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:

bash

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

code

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:

bash

# Verify deliverables exist
.claude/skills/agent-coordination/scripts/verify.sh "[category]" "[name]" "[date]"

Then update registries:

•

Always: Add report to _registry.md

code

- [report-name] | [Status] | [1-line summary]

•

If issues deferred: Add to _tech-debt.md

code

- [ ] **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:

markdown

- [ ] **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

code

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