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
uv run .claude/skills/agent-coordination/scripts/verify.py "[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]
   

Task() Invocation Protocol

The Task(agent-name, "prompt") pattern invokes specialized subagents:

Syntax

Task(agent-name, "
[Objective]

Context from prior work:
- [Key findings from reports]

Requirements:
- [Specific deliverables]

Output location:
- Report: .claude/reports/[category]/[name]-YYYYMMDD.md
")

Parameters

Execution Model

• Parallel: Independent tasks with no dependencies
• Sequential: When Agent B needs Agent A's output
• Background: Use run_in_background: true for long tasks

Context Rules

1. Subagents NEVER access registry or prior reports directly
2. Main agent MUST inject all relevant context into prompt
3. Include specific file paths, not vague references
4. Specify exact output location for reports

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

OpenSpec Integration

The agent coordination system works alongside OpenSpec for spec-driven development.

When Agent Findings Become OpenSpec Proposals

Agent findings that require code changes SHOULD become OpenSpec proposals:

Linking Reports to OpenSpec

When agent work relates to an existing OpenSpec change:

1. Reference in report header:

   **OpenSpec Change:** [change-id](../../openspec/changes/[change-id]/)
   

2. Update tech debt with OpenSpec link:

   - [ ] **TD-NNN**: Description
     - **OpenSpec:** [change-id](../../openspec/changes/[change-id]/)
   

3. Cross-reference in OpenSpec tasks.md:

   ## 3. Verification
   - [x] 3.1 Security scan - see `.claude/reports/security/[report].md`
   

Report Categories → OpenSpec Mapping

OpenSpec Pre-Archive Verification

Before archiving an OpenSpec change, consider running verification agents:

# For security-sensitive changes (auth, data handling, input validation)
Task(security-engineer, "Scan [affected files] for OWASP vulnerabilities")

# For all changes with significant new code
Task(code-quality, "Review [affected files] for correctness and maintainability")

# For changes affecting critical user paths
Task(test-engineer, "Verify test coverage for [affected functionality]")

Link verification reports in the archived change's tasks.md.

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.2.0

Source: spitoglou/ai-coding — distributed by TomeVault.