cc-orchestrate

A multi-agent orchestration framework for managing software portfolios with Claude Code. It provides the specification patterns, feedback loops, and coordination protocols that make autonomous AI agents productive across multiple concurrent projects.

Core Thesis

The highest-leverage optimization in agentic engineering is not optimizing agents -- it's optimizing specifications. When the inputs are right, capable agents produce excellent outputs with near-zero friction. cc-orchestrate creates a closed-loop feedback mechanism where specification quality is continuously measured, reported, and improved, producing compounding returns on execution quality across an entire portfolio of projects.

Key Concepts

The Charter Model

Each project gets an autonomous orchestrator with a charter -- a persistent mandate that defines ownership, goals across multiple time horizons (immediate, medium-term, long-term, perpetual), autonomy boundaries, quality infrastructure, and cross-project interfaces. Unlike task lists that get completed and closed, a charter represents ongoing stewardship. The orchestrator continuously cycles through its goal horizons, always moving to the next highest-leverage work.

The Gardener Pattern

The meta-orchestrator's role shifts from dispatcher (decompose goals, assign tasks, wait, repeat) to gardener (compose initial conditions, observe outcomes, prune drift, fertilize with cross-project insights, intervene only when needed). The human-AI dyad's highest-leverage activity is composing and refining charters, not dispatching work.

5-5-5 Scoring

Every completed unit of work receives a three-dimensional feedback score where 5 is optimal (not average -- optimal), 0 means insufficient, and 9 means excessive:

1. Scope -- task size relative to context budget
2. Detail -- specificity of the specification and context provided
3. Practices -- tooling and process friction

Scores flow bidirectionally: workers score their specs, orchestrators score their workers, and the system scores the human's orchestration quality. This feedback loop drives continuous improvement of specification quality -- the actual bottleneck in agentic systems.

Continuous Iteration

Chartered orchestrators do not go idle after completing a batch. They cycle continuously through their goal horizons: immediate goals first, then medium-term, then long-term, then perpetual maintenance. The objective function is not "complete tasks" -- it is "the project thrives."

Quality Infrastructure as Prerequisite

The entire charter model -- standing push authority, autonomous decision-making, no human in the critical path -- is predicated on quality infrastructure being complete and enforced before any orchestrator is chartered. CI/CD, branch protections, linting, test coverage, and automated dependency management must be in place first. This is what makes autonomy safe rather than reckless.

Directory Structure

cc-orchestrate/
├── CLAUDE.md              # Full specification (the authoritative reference)
├── BOOTSTRAP.md           # Session initialization guide
├── agent-teams.md         # Claude Code agent teams implementation notes
├── modules/               # Shared specification components
│   ├── identity.md        # Orchestrator identity boilerplate
│   ├── workflow.md        # Continuous iteration loop
│   ├── auth.md            # GitHub multi-account auth patterns
│   └── communication.md   # Reporting protocol, 5-5-5 scoring
├── orchestrators/         # YOUR project charters go here
│   └── README.md
├── templates/             # Charter template with guidance
│   └── charter-template.md
└── examples/              # Real charters from a production deployment
    └── disentangle-network/

Quick Start

1. Fork this repository.

2. Set up your GitHub auth. If you manage repos across multiple GitHub accounts, set up isolated GH_CONFIG_DIR configs per account (see modules/auth.md and BOOTSTRAP.md).

3. Write your first charter. Copy templates/charter-template.md to orchestrators/{your-project}/charter.md. Fill in your project's specifics. Review examples/ for real-world reference.

4. Customize shared modules. Edit modules/identity.md to reference your ecosystem. Update modules/auth.md with your GitHub accounts. modules/workflow.md and modules/communication.md are generic and likely need no changes.

5. Ensure quality infrastructure. Before chartering an orchestrator, your project must have: CI with all gates enforced, linting, test coverage, and automated dependency management. This is non-negotiable -- see the Quality Infrastructure section in CLAUDE.md.

6. Spawn your orchestrator. Use the bootstrap protocol in BOOTSTRAP.md. The meta-orchestrator assembles shared modules + charter into the spawn prompt, and the orchestrator begins autonomous operation.

Specification Reference

The full specification lives in CLAUDE.md (~480 lines). It covers:

• Architecture and role assignments (meta-orchestrator, project orchestrators, workers)
• The specification engine (modules system, feedback loops, prompt composition)
• 5-5-5 scoring system with formulas and flow diagrams
• Parallel execution model (race protocol, split option)
• Token budget discipline (150k target, retry circuit breaker)
• Quality infrastructure requirements
• Memory hierarchy and temporal rot prevention
• The charter model and gardener pattern
• Session crystallization and knowledge preservation

Read CLAUDE.md for the complete methodology. Read BOOTSTRAP.md for session initialization. Read agent-teams.md for Claude Code agent teams implementation notes.

License

MIT. See LICENSE.