Research-mind mpm-tool-usage-guide

MPM Tool Usage Guide

install

source · Clone the upstream repo

git clone https://github.com/MacPhobos/research-mind

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/MacPhobos/research-mind "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.claude/skills/mpm-tool-usage-guide" ~/.claude/skills/macphobos-research-mind-mpm-tool-usage-guide && rm -rf "$T"

manifest: .claude/skills/mpm-tool-usage-guide/SKILL.md

source content

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):

Is this a source code file? → STOP, delegate to Research
Have I already used Read once this session? → STOP, delegate to Research
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):

# 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 <noreply@anthropic.com>"

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

Vector Search Tools

Purpose: Quick semantic code search BEFORE delegation (helps provide better context)

When to Use: Need to identify relevant code areas before delegating to Engineer

MANDATORY: Before using Read or delegating to Research, PM MUST attempt mcp-vector-search if available.

Detection Priority:

Check if mcp-vector-search tools available (look for mcp__mcp-vector-search__*)
If available: Use semantic search FIRST
If unavailable OR insufficient results: THEN delegate to Research
Read tool limited to ONE config file only (existing rule)

Why This Matters:

Vector search provides instant semantic context without file loading
Reduces need for Research delegation in simple cases
PM gets quick context for better delegation instructions
Prevents premature Read/Grep usage

Correct Workflow:

✅ STEP 1: Check vector search availability

available_tools = [check for mcp__mcp-vector-search__* tools]
if vector_search_available:
    # Attempt vector search first

✅ STEP 2: Use vector search for quick context

mcp__mcp-vector-search__search_code:
  query: "authentication login user session"
  file_extensions: [".js", ".ts"]
  limit: 5

✅ STEP 3: Evaluate results

If sufficient context found: Use for delegation instructions
If insufficient: Delegate to Research for deep investigation

✅ STEP 4: Delegate with enhanced context

Task:
  agent: "engineer"
  task: "Add OAuth2 authentication"
  context: |
    Vector search found existing auth in src/auth/local.js.
    Session management in src/middleware/session.js.
    Add OAuth2 as alternative method.

Anti-Pattern (FORBIDDEN):

❌ WRONG: PM uses Grep/Read without checking vector search

PM: *Uses Grep to find auth files*           # VIOLATION! No vector search attempt
PM: *Reads 5 files to understand auth*       # VIOLATION! Skipped vector search
PM: *Delegates to Engineer with manual findings* # VIOLATION! Manual investigation

Enforcement: Circuit Breaker #10 detects:

Grep/Read usage without prior mcp-vector-search attempt (if tools available)
Multiple Read calls suggesting investigation (should use vector search OR delegate)
Investigation keywords ("check", "find", "analyze") without vector search

Violation Levels:

Violation #1: ⚠️ WARNING - Must use vector search first
Violation #2: 🚨 ESCALATION - Session flagged for review
Violation #3: ❌ FAILURE - Session non-compliant

Example - Using Vector Search Before Delegation:

# Before delegating OAuth2 implementation, find existing auth code:
mcp__mcp-vector-search__search_code:
  query: "authentication login user session"
  file_extensions: [".js", ".ts"]
  limit: 5

# Results show existing auth files, then delegate with better context:
Task:
  agent: "engineer"
  task: "Add OAuth2 authentication alongside existing local auth"
  context: |
    Existing authentication in src/auth/local.js (email/password).
    Session management in src/middleware/session.js.
    Add OAuth2 as alternative auth method, integrate with existing session.

When NOT to Use: Deep investigation requires Research agent delegation.

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:

Delegate to web-qa agent
web-qa MUST use Chrome DevTools MCP tools (NOT assumptions)
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)