| name | agent-coordination |
| description | Coordination protocol for main Claude Code agent. Explicit user invocation required ("mobilize agents", "coordinate", "check registry"). Provides agent orchestration, registry management, and handoff protocols. Subagents never access this - main agent provides context in task prompts. |
| allowed-tools | Read, Write, Edit, Grep, Glob, Bash, TodoWrite |
Agent Coordination Protocol
Core Principle
Build on existing work. Never recreate.
Two Registries
The system maintains two distinct registries:
| Registry | Purpose | Updated When |
|---|---|---|
_registry.md |
Index of completed work (reports) | After each agent produces a report |
_tech-debt.md |
Tracked improvements to address later | When issues are deferred, incidents occur |
Decision rule:
- Registry → "What work has been done?" (past/present state)
- Tech Debt → "What do we need to fix later?" (future work)
4-Step Workflow
Step 1: Check Prior Work
Before invoking any agent, check what already exists:
# Check registry for recent reports
cat .claude/reports/_registry.md | head -50
# Check if archiving needed (>50 entries)
ENTRIES=$(grep -c "^- .*|.*|" .claude/reports/_registry.md 2>/dev/null || echo 0)
[ "$ENTRIES" -gt 50 ] && echo "⚠️ Registry has $ENTRIES entries - suggest /archive"
# Check relevant tech debt (if working on that area)
grep -i "[area-keyword]" .claude/reports/_tech-debt.md
Read relevant reports before proceeding to understand current state.
Step 2: Context Injection
Subagents NEVER read registry or reports directly. Main agent provides ALL context:
Task(agent-name, "
[Objective]
Context from prior work:
- [Report X]: [key decisions/findings]
- [Tech debt TD-NNN]: [relevant constraint]
- Current state: [what exists now]
Requirements:
- [Specific deliverables]
Output location:
- Report: .claude/reports/[category]/[name]-YYYYMMDD.md
")
Step 3: Sequencing
Rule: Will Agent B need Agent A's output?
- YES → Sequential (verify between each)
- NO → Parallel
Step 4: Verify and Update
After each agent completes:
# Verify deliverables exist
.claude/skills/agent-coordination/scripts/verify.sh "[category]" "[name]" "[date]"
Then update registries:
Always: Add report to
_registry.md- [report-name] | [Status] | [1-line summary]If issues deferred: Add to
_tech-debt.md- [ ] **TD-NNN**: [Description] - **Impact:** [Critical|High|Medium|Low] - **Source:** [report-name or postmortem-name]
Report Categories
All reports go to .claude/reports/[category]/:
| Category | Folder | Use For | Typical Agents |
|---|---|---|---|
| analysis | analysis/ |
Research, EDA, data exploration | data-engineer, data-viz |
| arch | arch/ |
Architecture decisions, ADRs, system design | architect, rfc |
| bugs | bugs/ |
Bug reports, root cause analysis | code-quality (debug) |
| commits | commits/ |
Commit summaries, changelog entries | devops (git) |
| design | design/ |
UI/UX reviews, design specs | ux-designer |
| exec | exec/ |
Execution logs, command outputs | devops |
| handoff | handoff/ |
Agent coordination, context transfers | (main agent) |
| implementation | implementation/ |
Implementation plans, code specs | backend, frontend |
| review | review/ |
Code reviews, PR reviews | code-quality (review) |
| tests | tests/ |
Test plans, test results, coverage | test-engineer, qa |
| security | security/ |
Security scans, threat models, compliance | security-engineer |
| sre | sre/ |
SLOs, postmortems, capacity plans | sre |
| rfc | rfc/ |
Design proposals, RFCs | rfc |
| ci | ci/ |
CI pipeline results | (bash/devops) |
| archive | archive/ |
Old reports (moved, not deleted) | (archive script) |
Naming convention: [category]-[topic]-YYYYMMDD.md
Agent Reference
| Agent | Modes | Primary Output Category |
|---|---|---|
| code-quality | review, debug, qa-strategy | review/, bugs/, tests/ |
| test-engineer | - | tests/ |
| architect | system, pipeline | arch/ |
| security-engineer | scan, threat-model, compliance | security/ |
| sre | reliability-review, incident, capacity | sre/ |
| rfc | author, review, decision | rfc/ |
| data-engineer | collect, analyze, preprocess | analysis/ |
| data-viz-specialist | - | analysis/, design/ |
| devops | infra, git | exec/, commits/, ci/ |
| docs | general, webdev | (documentation files) |
| frontend | - | implementation/ |
| backend | - | implementation/ |
| ml-engineer | train, evaluate, deploy | analysis/, implementation/ |
| lrl-nlp-expert | - | analysis/ |
| ux-designer | design, copy | design/ |
When to Update Tech Debt
Tech debt entries are created when:
| Situation | Action |
|---|---|
| Code review finds issue, won't fix now | Add as Medium/Low priority |
| Postmortem identifies prevention action | Add as Critical/High priority |
| RFC defers a requirement | Add as Medium priority |
| Security scan finds non-blocking issue | Add as High priority |
| Manual identification | Use /debt add |
Format in _tech-debt.md:
- [ ] **TD-NNN**: Brief description
- **Impact:** Critical | High | Medium | Low
- **Source:** [link to originating report]
- **Created:** YYYY-MM-DD
Commands
| Command | Purpose |
|---|---|
| /review-full | Multi-level review (L1: peer → L2: arch → L3: security → L4: reliability) |
| /ci | Local CI pipeline (lint → build → test → security) |
| /security | Security vulnerability scan |
| /rfc | Create/review design documents |
| /slo | Define service level objectives |
| /postmortem | Incident analysis and learning |
| /debt | View and manage tech debt |
| /archive | Move old registry entries to archive |
Skill Resources
skills/agent-coordination/
├── SKILL.md # This file
├── templates.md # Report templates
├── reference.md # Verification details, retry logic
└── scripts/
├── verify.sh # Deliverable verification
└── archive_reports.py # Registry archiving (dated snapshots)
Version: 5.1.0