AGENTS.md — Subagent Orchestration Protocol

Claude Code reads this automatically for multi-agent tasks.

Agent Registry

Parallelization Rules

PARALLEL OK:
  db-agent + rag-agent          (schema + retriever, no shared files)
  api-agent + frontend-agent    (endpoint + UI, API contract must be locked first)
  bot-agent + api-agent         (adapter + endpoint)
  rag-agent + frontend-agent    (no shared files)

SEQUENTIAL REQUIRED:
  auth-agent → everything else  (auth changes are foundational)
  db migration → db models      (migration first, then ORM)
  /specify → /plan → /tasks     (SDD phases are sequential)
  any two agents touching same file

Compact Handoff Template

Orchestrator MUST use this format when dispatching. No prose. No full file contents.

## DISPATCH: <agent-id> | Task: <T-id>
CONTEXT: <2 sentences max about feature>
CONSTRAINT: <2-3 HARD rules relevant to this task, from rules/HARD.md>
TASK: <exact task title and definition, 3-5 lines>
TOUCH: [backend/path/file.py, backend/path/other.py]
NO_TOUCH: [backend/auth/, backend/api/routes/]
TEST_CMD: pytest tests/<path>/<test_file.py>::<test_name> -v
MEMORY: .claude/memory/WARM/<feature>.mem.md
RETURN: diff + test_result + memory_update_block

Return Format (subagent must use)

## RESULT: <agent-id> | Task: <T-id>
STATUS: DONE | BLOCKED | PARTIAL
TEST: PASS ✅ | FAIL ❌ — <error summary if fail>
FILES_CHANGED: [list]
DECISIONS: [any new decisions made, for memory update]
BLOCKERS: [list, empty if none]
MEMORY_UPDATE:
  status: <new status>
  decisions: [list]
  files_touched: [list]

Memory Sync on Dispatch

Before dispatching ANY subagent:

1. Run /sync to flush session → HOT.md + WARM/<feature>.mem.md
2. Include MEMORY: line in handoff pointing to WARM file
3. Subagent reads WARM file, NOT full conversation

After subagent returns:

1. Orchestrator reads RESULT block only (not full subagent output)
2. Updates HOT.md status
3. Merges MEMORY_UPDATE into WARM/<feature>.mem.md
4. Does NOT re-read all changed files (trusts test result)

Token Budget for Orchestration

• Dispatch package: max 500 tokens
• Subagent context: max 6k tokens (per CLAUDE.md budget)
• Result package: max 300 tokens
• Cross-agent communication: via files only, never via conversation relay

Model Assignment Rationale