Agent Coordination

Agent Coordination Protocol

Core Principle

Build on existing work. Never recreate.

Two Registries

The system maintains two distinct registries:

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:

1. Always: Add report to _registry.md

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

2. 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]/:

Naming convention: [category]-[topic]-YYYYMMDD.md

Agent Reference

When to Update Tech Debt

Tech debt entries are created when:

Format in _tech-debt.md:

- [ ] **TD-NNN**: Brief description
  - **Impact:** Critical | High | Medium | Low
  - **Source:** [link to originating report]
  - **Created:** YYYY-MM-DD

Commands

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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.