Claude Code Agents Coordination

Production-grade multi-agent coordination system with tiered delegation, institutional memory, and explicit tech-debt tracking.

This repository provides reusable configuration layers for Claude Code that enable sophisticated agent orchestration across projects—from solo development to enterprise-scale workflows.

What This Solves

Three critical problems in Claude Code agent usage:

1. Context Amnesia: Agents forget prior work within 15-20 minutes
2. Coordination Chaos: Multiple agents overwrite each other’s work
3. Delegation Limits: Manual oversight required for every decision

Solution: A tiered delegation architecture with persistent memory (registry + tech-debt tracking) that extends productive context windows to 2+ hours while enabling the Main Agent to consistently apply documented engineering criteria.

---

Core Architecture

Tiered Agent System

Tier 1: Workflow Orchestrators
├── code-quality      → Multi-level review chain (L1→L2→L3→L4)
├── test-engineer     → Test execution with failure triage
├── architect         → System design + ADRs + RFC lifecycle
└── ml-engineer       → End-to-end ML workflows

Tier 2: Specialized Execution
├── security-engineer → Threat modeling, OWASP scans
├── sre               → SLOs, postmortems, capacity planning
├── rfc               → Design document workflow
├── data-engineer     → Data pipelines + quality validation
├── frontend/backend  → Implementation work
├── devops            → CI/CD, infrastructure, git workflows
└── docs              → Technical documentation

Tier 3: On-Demand Specialists
├── lrl-nlp-expert        → Low-resource language NLP
├── data-viz-specialist   → Data storytelling + dashboards
└── ux-designer           → UX/design review + writing

Dual-Registry Model

_registry.md — What was done

• Tracks completed work, deliverables, and outcomes
• Main agent reads this for context before starting new tasks
• Updated after every significant task completion

_tech-debt.md — What was deferred

• Explicit tracking of shortcuts, workarounds, and deferred improvements
• Links each debt item to its source (commit, report, or incident)
• Prevents silent degradation of code quality

4-Step Coordination Protocol

1. Registry Check → Main agent reads prior work
2. Context Injection → Relevant context distributed to specialized agents
3. Sequencing → Sequential or parallel execution based on dependencies
4. Verification → Quality gates ensure standards are met

---

Quick Start

1. Install User-Level Configuration

mkdir -p ~/.claude
rsync -a claude-user/ ~/.claude/

This installs:

• Tiered agent set (orchestrators + specialists + on-demand experts)
• Standard workflows (/review-full, /ci, /debt, /postmortem, /rfc)
• Auto-invoked skills (agent-coordination protocol, design system, UX writing)

2. Install Project-Level Configuration

# In your project directory
mkdir -p .claude
rsync -a claude-project/ .claude/

This creates:

• CLAUDE.md project context file (edit with your project details)
• Institutional memory structure (registries + categorized report folders)
• Project-specific commands and skills

3. Start Using

# Multi-level code review
/review-full src/authentication/

# Local CI pipeline before pushing
/ci

# View and manage tech debt
/debt

# Create RFC for system design
/rfc authentication-system

# Incident postmortem with automatic debt logging
/postmortem login-timeout-2025-12-28

---

Key Features

Multi-Level Review Chain

The /review-full command implements graduated review escalation:

L1: Peer Review (code-quality agent)
    ↓ Triggers: Always runs
L2: Architecture Review (architect agent)
    ↓ Triggers: >200 lines, new APIs, schema changes, new modules
L3: Security Review (security-engineer agent)
    ↓ Triggers: Auth/authz, user input, external APIs, database queries, crypto
L4: Reliability Review (sre agent)
    ↓ Triggers: Infrastructure, service dependencies, error handling, caching

Why: Main Agent applies documented escalation criteria by reading code, ensuring consistent decisions without relying on memory.

Local CI Pipeline

The /ci command runs the full quality gate before pushing:

1. Lint → Check code style
2. Type-check → Verify type safety
3. Build → Ensure compilation succeeds
4. Test → Run test suite with coverage
5. Security scan → OWASP checks

Why: Catch issues locally before CI/CD, faster feedback cycles.

Explicit Tech-Debt Tracking

The _tech-debt.md registry captures:

• What shortcut was taken
• Why it was necessary (time pressure, missing info, external dependency)
• Where it lives (file paths, commit SHAs)
• Impact severity (cosmetic → critical)
• Remediation plan

Why: Prevents “just this once” from becoming permanent, maintains quality over time.

Protocol Efficiency Optimization

The agent-coordination protocol is split across multiple files:

• SKILL.md (core protocol, always loaded)
• templates.md (loaded only when creating reports)
• reference.md (loaded only for lookups)
• scripts/ (executable helpers for archiving, verification)

Why: Reduces per-task token consumption by 40-60% through selective loading.

---

Releases

This repository maintains stable release versions to support documentation and article references:

• v1.0.0 — Initial “flat” coordination system (22 peer agents)

  • Referenced by Part 1 and Part 2 articles
  • Foundational 4-step protocol implementation
  • Proved agent coordination viability

• v2.0.0 — Tiered delegation system (current: v2.2.1)

  • Production-grade delegation with multi-level review chains
  • Dual-registry model (work done + tech debt)
  • Protocol optimization for token efficiency
  • Described in Part 3 article

Versioning approach: Major versions represent architectural shifts, minor versions add features, patches fix documentation/bugs.

---

Articles & Documentation

This system is documented through a three-part series on Medium:

1. How I Made Claude Code Agents Coordinate 100% (and Solved Context Amnesia)

   • The journey from 26-agent chaos to working coordination
   • 8x context window improvement (15 min → 2+ hours)

2. The 4-Step Protocol That Fixes Claude Code’s Context Amnesia

   • Deep dive into the coordination protocol
   • Registry-based institutional memory

3. How to Build Production-Grade Systems with Claude Code

   • Tiered delegation architecture
   • Multi-level review chains
   • Dual-registry model and workflow automation

In-repo documentation:

• claude-user/INDEX.md — User-level configuration guide
• claude-project/INDEX.md — Project-level setup and workflow

---

Repository Structure

claude-agents-coordination/
├── README.md                    # You are here
├── CHANGELOG.md                 # Version history
├── LICENSE                      # Unlicense (public domain)
│
├── claude-user/                 # User-level config (~/.claude/)
│   ├── INDEX.md                 # Detailed user-level guide
│   ├── agents/                  # Tiered agent definitions
│   ├── commands/                # Standard workflows (/review-full, /ci, etc.)
│   └── skills/                  # Auto-invoked knowledge + coordination protocol
│
└── claude-project/              # Project-level config (/.claude/)
    ├── INDEX.md                 # Detailed project-level guide
    ├── CLAUDE.md                # Project context template
    ├── commands/                # Project-specific workflows
    ├── skills/                  # Project domain knowledge
    └── reports/
        ├── _registry.md         # Work done (institutional memory)
        ├── _tech-debt.md        # Deferred work (explicit debt tracking)
        └── [categories]/        # Organized report folders

---

Performance Characteristics

---

Customization

Add Custom Agents

Create ~/.claude/agents/my-agent.md:

# My Agent

Specializes in [specific capability].

## Primary Responsibilities
- Responsibility 1
- Responsibility 2

## Available Tools
Read, Write, Bash, Grep, Glob

## Invocation Context
Use when [specific conditions].

Best practice: Keep agents focused (25-75 lines), single responsibility.

Add Project Skills

Create .claude/skills/my-domain/my-skill/SKILL.md:

# My Skill

Auto-invokes when task mentions: [trigger keywords]

## Domain Knowledge
[Specific domain expertise, patterns, conventions]

## Usage Guidelines
[When to apply this knowledge, examples]

Best practice: 200-400 lines, clear auto-invoke triggers.

Add Slash Commands

Create ~/.claude/commands/my-workflow.md:

Launch [agent-name] to [accomplish specific goal]

Provide context:
- [Detail 1]
- [Detail 2]

Expected deliverables:
- [Deliverable 1]
- [Deliverable 2]

Use: /my-workflow [arguments]

---

Real-World Usage

This system was developed for the Somali Dialect Classifier project—a low-resource language NLP initiative requiring:

• Multi-source data collection (BBC Somali, Wikipedia, HuggingFace, TikTok, Språkbanken)
• Quality-controlled preprocessing pipeline
• ML experimentation with persistent metrics tracking
• Static dashboard with Tableau-inspired design system
• All coordinated by a single developer

Results:

• 2+ hour productive sessions without context loss
• Main Agent consistently applied documented criteria to escalate security/architecture reviews
• Tech-debt registry prevented quality degradation
• 40% reduction in protocol overhead through optimization

---

Contributing

This repository documents a working system. Contributions welcome:

• Issues: Report bugs, suggest improvements
• Pull Requests: Enhancements to agents, protocols, documentation
• Discussions: Share your coordination patterns and lessons learned

Philosophy: Iterate, fail, learn, document. If you found a better approach, share it.

---

License

This is free and unencumbered software released into the public domain (Unlicense).

Use it however you want. No attribution required (though appreciated).

See LICENSE for full text.

---

Why This Exists

Built through systematic iteration on real production needs. Started with 26-agent chaos, refined to 22-agent flat coordination, evolved to tiered delegation for autonomous engineering judgment.

This repository shares the working solution so others can build sophisticated agent systems without repeating the same failures.

If this helped you: Star the repo, share your experiences, contribute improvements.

---

Questions? Open an issue or reach out via Medium.