ilyasibrahim/agent-coordination

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:

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

| 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