AI agent skill · by @bobmatnyc

Mpm Tool Usage Guide

Detailed tool usage patterns and examples for PM agents

Archived 2026-10-23 · Source updated 2026-08-31. Check the original repository for the latest version.

SKILL.md instructions

# MPM Tool Usage Guide

Detailed tool usage patterns and examples for PM agents.

## Task Tool - Detailed Examples

### Example 1: Delegating Implementation
```
Task:
  agent: "engineer"
  task: "Implement user authentication with OAuth2"
  context: |
    User requested secure login feature.
    Research agent identified Auth0 as recommended approach.
    Existing codebase uses Express.js for backend.
  acceptance_criteria:
    - User can log in with email/password
    - OAuth2 tokens stored securely
    - Session management implemented
```

### Example 2: Delegating Verification
```
Task:
  agent: "qa"
  task: "Verify deployment at https://app.example.com"
  acceptance_criteria:
    - Homepage loads successfully
    - Login form is accessible
    - No console errors in browser
    - API health endpoint returns 200
```

### Example 3: Delegating Investigation
```
Task:
  agent: "research"
  task: "Investigate authentication options for Express.js application"
  context: |
    User wants secure authentication.
    Codebase is Express.js + PostgreSQL.
  requirements:
    - Compare OAuth2 vs JWT approaches
    - Recommend specific libraries
    - Identify security best practices
```

### Common Mistakes to Avoid
- Not providing context (agent lacks background)
- Vague task description ("fix the thing")
- No acceptance criteria (agent doesn't know completion criteria)

## TodoWrite Tool - Progress Tracking

**Purpose**: Track delegated tasks during the current session

**When to Use**: After delegating work to maintain visibility of progress

**States**:
- `pending`: Task not yet started
- `in_progress`: Currently being worked on (max 1 at a time)
- `completed`: Finished successfully
- `ERROR - Attempt X/3`: Failed, attempting retry
- `BLOCKED`: Cannot proceed without user input

**Example**:
```
TodoWrite:
  todos:
    - content: "Research authentication approaches"
      status: "completed"
      activeForm: "Researching authentication approaches"
    - content: "Implement OAuth2 with Auth0"
      status: "in_progress"
      activeForm: "Implementing OAuth2 with Auth0"
    - content: "Verify authentication flow"
      status: "pending"
      activeForm: "Verifying authentication flow"
```

## Read Tool Usage - Strict Hierarchy

**ABSOLUTE PROHIBITION**: PM must NEVER read source code files directly.

**Source code extensions** (ALWAYS delegate to Research):
`.py`, `.js`, `.ts`, `.tsx`, `.jsx`, `.go`, `.rs`, `.java`, `.rb`, `.php`, `.swift`, `.kt`, `.c`, `.cpp`, `.h`

**SINGLE EXCEPTION**: ONE config/settings file for delegation context only.
- Allowed: `package.json`, `pyproject.toml`, `settings.json`, `.env.example`
- NOT allowed: Any file with source code extensions above

**Pre-Flight Check (MANDATORY before ANY Read call)**:
1. Is this a source code file? → STOP, delegate to Research
2. Have I already used Read once this session? → STOP, delegate to Research
3. Does my task contain investigation keywords? → STOP, delegate to Research

**Investigation Keywords** (trigger delegation, not Read):
- check, look, see, find, search, analyze, investigate, debug
- understand, explore, examine, review, inspect, trace
- "what does", "how does", "why does", "where is"

**Rules**:
- ✅ Allowed: ONE file (`package.json`, `pyproject.toml`, `settings.json`, `.env.example`)
- ❌ NEVER: Source code (`.py`, `.js`, `.ts`, `.tsx`, `.go`, `.rs`)
- ❌ NEVER: Multiple files OR investigation keywords ("check", "analyze", "debug", "investigate")
- **Rationale**: Reading leads to investigating. PM must delegate, not do.

## Bash Tool Usage

**Purpose**: Navigation and git file tracking ONLY

**Allowed Uses**:
- Navigation: `ls`, `pwd`, `cd` (understanding project structure)
- Git tracking: `git status`, `git add`, `git commit` (file management)

**FORBIDDEN Uses** (MUST delegate instead):
- ❌ **Verification commands** (`curl`, `lsof`, `ps`, `wget`, `nc`) → Delegate to local-ops or QA
- ❌ **Browser testing tools** → Delegate to web-qa (use Playwright via web-qa agent)
- ❌ **Implementation commands** (`npm start`, `docker run`, `pm2 start`) → Delegate to ops agent
- ❌ **File modification** (`sed`, `awk`, `echo >`, `>>`, `tee`) → Delegate to engineer
- ❌ **Investigation** (`grep`, `find`, `cat`, `head`, `tail`) → Delegate to research (or use vector search)

**Why File Modification is Forbidden:**
- `sed -i 's/old/new/' file` = Edit operation → Delegate to Engineer
- `echo "content" > file` = Write operation → Delegate to Engineer
- `awk '{print $1}' file > output` = File creation → Delegate to Engineer
- PM uses Edit/Write tools OR delegates, NEVER uses Bash for file changes

**Example Violation:**
```
❌ WRONG: PM uses Bash for version bump
PM: Bash(sed -i 's/version = "1.0"/version = "1.1"/' pyproject.toml)
PM: Bash(echo '1.1' > VERSION)
```

**Correct Pattern:**
```
✅ CORRECT: PM delegates to local-ops
Task:
  agent: "local-ops"
  task: "Bump version from 1.0 to 1.1"
  acceptance_criteria:
    - Update pyproject.toml version field
    - Update VERSION file
    - Commit version bump with standard message
```

**Enforcement:** Circuit Breaker #12 detects:
- PM using sed/awk/echo for file modification
- PM using Bash with redirect operators (>, >>)
- PM implementing changes via Bash instead of delegation

**Violation Levels:**
- Violation #1: ⚠️ WARNING - Must delegate implementation
- Violation #2: 🚨 ESCALATION - Session flagged for review
- Violation #3: ❌ FAILURE - Session non-compliant

**Example - Verification Delegation (CORRECT)**:
```
❌ WRONG: PM runs curl/lsof directly
PM: curl http://localhost:3000  # VIOLATION

✅ CORRECT: PM delegates to local-ops
Task:
  agent: "local-ops"
  task: "Verify app is running on localhost:3000"
  acceptance_criteria:
    - Check port is listening (lsof -i :3000)
    - Test HTTP endpoint (curl http://localhost:3000)
    - Check for errors in logs
    - Confirm expected response
```

**Example - Git File Tracking (After Engineer Creates Files)**:
```bash
# Check what files were created
git status

# Track the files
git add src/auth/oauth2.js src/routes/auth.js

# Commit with context
git commit -m "feat: add OAuth2 authentication

- Created OAuth2 authentication module
- Added authentication routes
- Part of user login feature

🤖👥 Generated with [Claude MPM](https://github.com/bobmatnyc/claude-mpm)

Co-Authored-By: Claude MPM <https://github.com/bobmatnyc/claude-mpm>"
```

**Implementation commands require delegation**:
- `npm start`, `docker run`, `pm2 start` → Delegate to ops agent
- `npm install`, `yarn add` → Delegate to engineer
- Investigation commands (`grep`, `find`, `cat`) → Delegate to research

## Context-First Protocol

**Purpose**: Query project memory and code search BEFORE delegating to Research or reading files.

**MANDATORY**: Before using Read or delegating to Research, PM MUST attempt memory recall and code search using whichever backends are installed.

**Why This Matters:**
- Memory recall surfaces previously-discovered project facts instantly
- Code search provides semantic context without file loading
- Together they reduce Research delegation in most cases
- Prevents premature Read/Grep usage

---

### Step 1: Memory (check in order, use first available)

```
1. mcp__trusty-memory__memory_recall  ← primary (use if available)
2. mcp__kuzu-memory__kuzu_recall      ← legacy fallback
3. Neither available → skip, proceed to Step 2
```

**Example:**
```
mcp__trusty-memory__memory_recall:
  palace: "claude-mpm"
  query: "authentication patterns"
```

---

### Step 2: Code Search (use if available)

```
1. mcp__trusty-search__search  ← use if available
2. Not available → skip, delegate to Research instead
```

**Example:**
```
mcp__trusty-search__search:
  query: "authentication login user session"
  index: "claude-mpm"
  limit: 5
```

---

### Step 3: Evaluate and Proceed

- If memory + search gave sufficient context → use for delegation instructions
- If insufficient → delegate to Research for deep investigation

**Correct Workflow:**

✅ STEP 1: Attempt memory recall (whichever backend is available)
✅ STEP 2: Attempt code search (if trusty-search available)
✅ STEP 3: Evaluate results — sufficient? Use them. Insufficient? Delegate to Research.
✅ STEP 4: Delegate with enhanced context

**Anti-Pattern (FORBIDDEN):**

❌ WRONG: PM delegates to Research or uses Grep/Read without first attempting memory+search
```
PM: *Uses Grep to find auth files*               # VIOLATION! No memory/search attempt
PM: *Reads 5 files to understand auth*           # VIOLATION! Skipped protocol
PM: *Immediately delegates to Research*          # VIOLATION! No prior memory/search
```

**Enforcement:** Circuit Breaker detects:
- Grep/Read usage without prior memory/search attempt (if tools available)
- Research delegation without prior memory/search attempt
- Multiple Read calls suggesting investigation (should use search OR delegate)

**Violation Levels:**
- Violation #1: ⚠️ WARNING - Must check memory and search first
- Violation #2: 🚨 ESCALATION - Session flagged for review
- Violation #3: ❌ FAILURE - Session non-compliant

## FORBIDDEN MCP Tools for PM (CRITICAL)

**PM MUST NEVER use these tools directly - ALWAYS delegate instead:**

| Tool Category | Forbidden Tools | Delegate To | Reason |
|---------------|----------------|-------------|---------|
| **Code Modification** | Edit, Write | engineer | Implementation is specialist domain |
| **Investigation** | Grep (>1 use), Glob (investigation) | research | Deep investigation requires specialist |
| **Ticketing** | `mcp__mcp-ticketer__*`, WebFetch on ticket URLs | ticketing | MCP-first routing, error handling |
| **Browser** | `mcp__chrome-devtools__*` (ALL browser tools) | web-qa | Playwright expertise, test patterns |

**Code Modification Enforcement:**
- Edit: PM NEVER modifies existing files → Delegate to Engineer
- Write: PM NEVER creates new files → Delegate to Engineer
- Exception: Git commit messages (allowed for file tracking)

See Circuit Breaker #1 for enforcement.

## Browser State Verification (MANDATORY)

**CRITICAL RULE**: PM MUST NOT assert browser/UI state without Chrome DevTools MCP evidence.

When verifying local server UI or browser state, PM MUST:
1. Delegate to web-qa agent
2. web-qa MUST use Chrome DevTools MCP tools (NOT assumptions)
3. Collect actual evidence (snapshots, screenshots, console logs)

**Chrome DevTools MCP Tools Available** (via web-qa agent only):
- `mcp__chrome-devtools__navigate_page` - Navigate to URL
- `mcp__chrome-devtools__take_snapshot` - Get page content/DOM state
- `mcp__chrome-devtools__take_screenshot` - Visual verification
- `mcp__chrome-devtools__list_console_messages` - Check for errors
- `mcp__chrome-devtools__list_network_requests` - Verify API calls

**Required Evidence for UI Verification**:
```
✅ CORRECT: web-qa verified with Chrome DevTools:
   - navigate_page: http://localhost:3000 → HTTP 200
   - take_snapshot: Page shows login form with email/password fields
   - take_screenshot: [screenshot shows rendered UI]
   - list_console_messages: No errors found
   - list_network_requests: GET /api/config → 200 OK

❌ WRONG: "The page loads correctly at localhost:3000"
   (No Chrome DevTools evidence - CIRCUIT BREAKER VIOLATION)
```

**Local Server UI Verification Template**:
```
Task:
  agent: "web-qa"
  task: "Verify local server UI at http://localhost:3000"
  acceptance_criteria:
    - Navigate to page (mcp__chrome-devtools__navigate_page)
    - Take page snapshot (mcp__chrome-devtools__take_snapshot)
    - Take screenshot (mcp__chrome-devtools__take_screenshot)
    - Check console for errors (mcp__chrome-devtools__list_console_messages)
    - Verify network requests (mcp__chrome-devtools__list_network_requests)
```

See Circuit Breaker #6 for enforcement on browser state claims without evidence.

## Localhost Deployment Verification (CRITICAL)

**ABSOLUTE RULE**: PM NEVER tells user to "go to", "open", "check", or "navigate to" a localhost URL.

**Anti-Pattern Examples (CIRCUIT BREAKER VIOLATION)**:
```
❌ "Go to http://localhost:3000/dashboard"
❌ "Open http://localhost:3300 in your browser"
❌ "Make sure you're accessing via http://localhost:3300"
❌ "Navigate to the dashboard at localhost:8080"
❌ "Check the page at http://localhost:5000"
```

**Correct Pattern - Always Delegate to web-qa**:
```
Task:
  agent: "web-qa"
  task: "Verify localhost deployment at http://localhost:3300/dashboard"
  acceptance_criteria:
    - Navigate to URL (mcp__chrome-devtools__navigate_page)
    - Take snapshot to verify content loads (mcp__chrome-devtools__take_snapshot)
    - Take screenshot as evidence (mcp__chrome-devtools__take_screenshot)
    - Check console for JavaScript errors (mcp__chrome-devtools__list_console_messages)
    - Report actual page content, not assumptions
```

**Evidence Required Before Claiming Deployment Success**:
- Actual page snapshot content (not "it should work")
- Screenshot showing rendered UI
- Console error check results
- HTTP response status codes

**Violation Consequences**:
- Telling user to check localhost = Circuit Breaker #9 violation
- Claiming deployment works without web-qa evidence = Circuit Breaker #3 violation (Unverified Assertions)