Skip to content

v2.0.0: Production-Grade Delegation System

Choose a tag to compare

View all tags
@ilyasibrahim ilyasibrahim released this 28 Dec 09:59
· 9 commits to main since this release
v2.0.0
640e8a2

Release v2.0.0: Production-Grade Delegation System

Released: December 28, 2025

Overview

Major architectural evolution from task coordination to production-grade delegation. This release transforms Claude Code agents from task executors into autonomous decision-makers with embedded engineering judgment.

Upgrade from v1.0.0: Tiered agent hierarchy, multi-level review chains, explicit tech-debt tracking, and 40-60% protocol optimization.

What's New

Tiered Agent Architecture

Restructured from 22 flat peers to a three-tier delegation model:

Tier 1: Workflow Orchestrators (4 agents)

  • code-quality — Multi-level review chain (L1→L2→L3→L4)
  • test-engineer — Test execution with failure triage and flaky test detection
  • architect — System design, ADRs, RFC lifecycle
  • ml-engineer — End-to-end ML workflows with experiment tracking

Tier 2: Specialized Execution (8 agents)

  • security-engineer — OWASP scanning, threat modeling, compliance
  • sre — SLO definition, postmortems, capacity planning, reliability reviews
  • rfc — RFC authoring, review, and decision capture
  • data-engineer — Data pipelines, quality validation, ETL patterns
  • frontend / backend — Implementation work
  • devops — CI/CD, infrastructure, git workflows
  • docs — Technical documentation and handoffs

Tier 3: On-Demand Specialists (remaining agents)

  • lrl-nlp-expert — Low-resource language NLP techniques
  • data-viz-specialist — Data storytelling, dashboards
  • ux-designer — UX/design review and writing

Multi-Level Review Chain

The /review-full command implements graduated escalation:

L1: Peer Review (code-quality agent)
    ↓ Always runs
L2: Architecture Review (architect agent)
    ↓ Triggers: New APIs, schema changes, >500 lines, new dependencies
L3: Security Review (security-engineer agent)
    ↓ Triggers: Auth/authz, user input, external APIs, cryptography
L4: Reliability Review (sre agent)
    ↓ Triggers: Infrastructure changes, deployment configs, perf-critical paths

Key Innovation: Escalation happens automatically based on code characteristics, not manual judgment. Agents decide which reviews are needed.

Dual-Registry Model

_registry.md (What was done)

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

_tech-debt.md (What was deferred)

  • Explicit tracking of shortcuts, workarounds, deferred improvements
  • Links each debt item to source (commit, report, incident)
  • Severity levels (cosmetic → critical) with remediation plans
  • Prevents silent quality degradation

Standard Workflow Commands

New slash commands for common engineering workflows:

  • /review-full [path] — L1→L2→L3→L4 review chain with auto-escalation
  • /ci — Local CI pipeline: lint → type-check → build → test → security
  • /debt — Tech-debt registry management (add/resolve/list)
  • /postmortem [incident] — Incident learning + automatic debt logging
  • /rfc [topic] — RFC workflow (author → review → decision)

Protocol Optimization

Split coordination protocol across multiple files for 40-60% token reduction:

  • SKILL.md (150-200 lines) — Core protocol, always loaded
  • templates.md (100-150 lines) — Loaded only when creating reports
  • reference.md (100-200 lines) — Loaded only for lookups
  • scripts/ — Executable helpers for archiving, verification

Before (v1.0.0): 370 lines loaded every time
After (v2.0.0): 150-250 lines loaded selectively

Breaking Changes from v1.0.0

Agent Definitions

  • Some v1.0.0 agents merged or reorganized into tiers
  • Agent invocation patterns changed (orchestrators now delegate to specialists)
  • Agent definitions updated to include delegation capabilities

Registry Structure

  • Added _tech-debt.md alongside _registry.md
  • Report categories expanded (added: sre/, rfc/, ci/)
  • Archive structure standardized

Skills Organization

  • agent-coordination skill split into multiple files
  • New skills: design/, enhanced ux-writing/
  • Trigger keywords updated for v2 tiered model

Migration Path

See CHANGELOG.md for detailed migration guidance from v1.0.0 to v2.0.0.

Performance Comparison

Metric v1.0.0 v2.0.0 Change
Context window duration 2 hours 2+ hours Maintained
Protocol token cost 370 lines (always) 150-250 lines (selective) 40-60% reduction
Review depth Single-level Multi-level (L1→L4) Graduated escalation
Tech-debt visibility None Explicit tracking New capability
Delegation capability Task execution Engineering judgment Autonomous decisions
Agent tiers Flat (1 tier) Hierarchical (3 tiers) Structured delegation

Installation

Fresh Installation

git clone https://github.com/ilyasibrahim/claude-agents-coordination.git
cd claude-agents-coordination
git checkout v2.0.0

# User-level config
mkdir -p ~/.claude
rsync -a claude-user/ ~/.claude/

# Project-level config (in your project)
mkdir -p .claude
rsync -a claude-project/ .claude/

Upgrade from v1.0.0

cd claude-agents-coordination
git fetch
git checkout v2.0.0

# Backup existing config
cp -r ~/.claude ~/.claude.v1-backup

# Install v2.0.0 user-level config
rsync -a claude-user/ ~/.claude/

# Project-level: manually merge changes or fresh install
# Review differences in INDEX.md files before overwriting

What's Included

claude-agents-coordination/
├── README.md (363 lines)           # Comprehensive architecture guide
├── CHANGELOG.md (96 lines)         # Keep a Changelog format
├── LICENSE                         # Unlicense (public domain)
│
├── claude-user/                    # User-level config
│   ├── INDEX.md (72 lines)         # Concise setup guide
│   ├── agents/                     # Tiered agent definitions
│   ├── commands/                   # Standard workflows
│   └── skills/                     # Optimized protocol + skills
│
└── claude-project/                 # Project-level config
    ├── INDEX.md (52 lines)         # Project setup guide
    ├── CLAUDE.md                   # Project context template
    ├── commands/                   # Project workflows
    ├── skills/                     # Project domain knowledge
    └── reports/
        ├── _registry.md            # Work done
        ├── _tech-debt.md           # Deferred work
        └── [categories]/           # analysis/, arch/, bugs/, commits/,
                                    # design/, exec/, handoff/, implementation/,
                                    # review/, security/, sre/, rfc/, ci/, tests/,
                                    # archive/

Use Cases

Solo Developer Building Complex System

Scenario: Building ML-powered application solo, need to maintain quality across data, backend, frontend, and ML components.

How v2.0.0 helps:

  • /review-full automatically escalates security and architecture reviews
  • /ci catches issues locally before CI/CD
  • /debt tracks shortcuts taken during rapid development
  • Multi-agent coordination handles cross-domain complexity

Team Onboarding with Institutional Memory

Scenario: New team member needs to understand what's been built and why.

How v2.0.0 helps:

  • _registry.md provides chronological work history with deliverables
  • _tech-debt.md shows known shortcuts and their remediation plans
  • RFC and ADR records capture architectural decisions
  • Postmortem reports document incidents and lessons learned

Quality-Conscious Development

Scenario: Maintaining high quality bar while moving quickly.

How v2.0.0 helps:

  • Multi-level review chain enforces graduated quality gates
  • SRE agent enforces reliability standards for production changes
  • Security-engineer agent catches OWASP vulnerabilities
  • Explicit tech-debt tracking prevents "temporary" from becoming permanent

Real-World Validation

Developed for the Somali Dialect Classifier project during transition from testing to active development:

Requirements:

  • Solo engineer coordinating data (5 sources), ML pipeline, dashboard, backend
  • Need for autonomous quality decisions without manual oversight
  • Explicit tracking of shortcuts taken under time pressure
  • Protocol efficiency to support 2+ hour sessions with complex work

Results:

  • 2+ hour productive sessions maintained (context window held)
  • Agents autonomously escalated architecture/security reviews
  • Tech-debt registry captured all shortcuts with remediation plans
  • 40% reduction in protocol overhead through optimization
  • Zero quality incidents from autonomous delegation

Documentation

In-repository:

  • README.md — Comprehensive v2.0.0 architecture guide
  • claude-user/INDEX.md — User-level setup and workflows
  • claude-project/INDEX.md — Project-level configuration
  • CHANGELOG.md — Detailed version history

Articles (Medium):

  1. Part 1: Solving Context Amnesia — v1.0.0 foundation
  2. Part 2: The 4-Step Protocol — v1.0.0 deep dive
  3. Part 3: Scaling to Enterprise-Grade Delegation (Coming Soon) — v2.0.0 evolution

Migration from v1.0.0

What Still Works

  • Four-step coordination protocol (Registry → Context → Sequencing → Verification)
  • Flat agent invocation for simple tasks
  • Registry-based institutional memory
  • Auto-invoked skills system
  • Slash command structure

What Changed

  • Agent hierarchy (flat → tiered)
  • Protocol file structure (single → split)
  • Review process (single → multi-level)
  • Registry model (single → dual)
  • Commands (basic → workflow-oriented)

Migration Checklist

  1. Backup existing ~/.claude and .claude/ directories
  2. Review new tiered agent definitions
  3. Update project CLAUDE.md with v2.0.0 context structure
  4. Migrate registry entries to new format (if needed)
  5. Initialize _tech-debt.md in existing projects
  6. Test /review-full, /ci, /debt commands
  7. Update any custom agents to reference new tiers

Key Principles (Updated for v2.0.0)

  1. Orchestrators delegate, specialists execute — Tier 1 agents make decisions, Tier 2/3 execute
  2. Multi-level quality gates — Graduated escalation based on code characteristics
  3. Explicit over implicit — Tech-debt tracked, not hidden; decisions captured, not forgotten
  4. Selective loading — Load only what's needed when needed (40-60% token savings)
  5. Autonomous judgment — Agents decide escalation, not humans

Contributing

This repository documents a working production system. Contributions welcome:

  • Issues: Report bugs, request features, suggest improvements
  • Pull Requests: Agent enhancements, protocol optimizations, documentation improvements
  • Discussions: Share your delegation patterns, lessons learned, alternative approaches

Philosophy: Iterate, fail, learn, document. Better approaches exist—help find them.

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.

Acknowledgments

Built through systematic iteration on real production needs:

  • v0.x: 26-agent chaos (failed)
  • v1.0.0: 22-agent flat coordination (worked for testing)
  • v2.0.0: Tiered delegation (works for production)

This release shares the working production solution so others can skip the failed iterations and build sophisticated agent systems from a proven foundation.

If v2.0.0 helped you: Star the repo, open issues with feedback, share your delegation patterns, contribute improvements.

Questions? Open an issue or reach out via Medium.

Assets 2
Loading