subagent-reuse: Instructions file for Claude Code

Subagent Reuse Protocol

Rule

BEFORE spawning any subagent, call route_task first. Always.

Workflow

Before any subagent work

route_task(task, files?, directory?)

• REUSE → Call get_context(agent_id) to load what the agent knows. Check stale_files — re-read any files that changed.
• CREATE_NEW → Spawn a new subagent. If tip says to recall(), do that too.

Agent context is auto-discovered from Claude Code's native session storage. No manual registration needed.

Optional: augment auto-discovered context

log_work(agent_id, summary, files_read?, files_modified?, learnings?, output?)

Only needed if you want to add extra annotations beyond what the auto-scanner extracts.

When done

mark_done(agent_id)

Agent won't receive new routing but its logs remain searchable.

Example

User: "Fix the login redirect bug"

→ route_task("Fix login redirect bug after OAuth callback",
    ["src/auth/callback.ts", "src/middleware/session.ts"])
→ CREATE_NEW (no agent has context for these files)

→ ... agent reads files, fixes the bug ...
→ (context auto-extracted from native JSONL — no log_work needed)

User: "Now add refresh token rotation to the auth flow"

→ route_task("Add refresh token rotation to auth flow",
    ["src/auth/callback.ts", "src/auth/tokens.ts"])
→ REUSE agent_id (file overlap: callback.ts + same directory)
→ stale_files: [] (nothing changed)

→ get_context(agent_id)
→ Agent already knows the auth flow. No re-reading needed.

User: (edits callback.ts manually, then asks)
"Now fix the error handling in the callback"

→ route_task("Fix error handling in auth callback",
    ["src/auth/callback.ts"])
→ REUSE agent_id
→ stale_warning: "callback.ts changed since agent last read it. Re-read before modifying."

Staleness Detection

Each agent's known files are tracked via Merkle tree (SHA-256 content hashes). At routing time:

• Fresh files → full score weight
• Stale files (modified since agent read them) → half score weight
• Stale modifications (agent edited the file, but it changed after) → zero bonus