Orchestra

AI team orchestration for Claude Code. One terminal plans, another builds — from idea to production.

What is Orchestra?

Orchestra turns a single Claude Code session into a coordinated development team. A Product Manager plans features, a Lead assembles the right team — deriving sub-agent identity dynamically from phase content and delegating each phase. Sub-agents own implementation and verification; lead owns commits. Each role has strict boundaries, every commit passes verification, and the system learns from past milestones.

No infrastructure. No API keys. Just markdown files and Claude Code.

Install

As Claude Code Plugin (recommended)

/plugin install orchestra

No files copied into your project.

As Standalone (copies files into your project)

npx @sulhadin/orchestrator

Copies .orchestra/ (project data + config) and .claude/ (agents, skills, rules, commands) into your project.

Both options use the same commands: /orchestra:pm, /orchestra:start, etc.

How It Works

Terminal 1 (PM):                    Terminal 2 (Lead):
  /orchestra pm                       /orchestra start
  │                                   │
  ├─ Discuss features                 ├─ Scan milestones
  ├─ Create milestones                ├─ Design phase → RFC
  ├─ Groom phases                     ├─ Delegate to sub-agents → code + tests
  │                                   ├─ Call reviewer → code review
  │  (plan M2 while M1 runs)          ├─ Push → milestone done
  │                                   └─ Stop (inline) or next milestone (agent)

Quick Example

Terminal 1:

/orchestra pm
> "I want user authentication with JWT"
PM challenges scope, creates M1-user-auth with 3 phases

Terminal 2:

/orchestra start
📋 Starting M1-user-auth
🏗️ design → RFC ready → user approves
⚙️ phase-1: DB schema → committed
⚙️ phase-2: API endpoints → committed
⚙️ phase-3: Login UI → committed
🔍 reviewer → approved
✅ M1-user-auth done. Pushed to origin.

Commands

Pipeline

| Command | What it does | |---------|-------------| | /orchestra pm | Open PM terminal — plan features, create milestones | | /orchestra start | Execute milestones autonomously (asks at approval gates) | | /orchestra start --auto | Fully autonomous — warns once, then auto-push | | /orchestra hotfix {desc} | Ultra-fast fix: implement → verify → commit → push | | /orchestra status | Milestone status report (PM only) | | /orchestra verifier [N] | Verify milestones match PRD/RFC requirements (PM only) | | /orchestra rewind [N] | Review execution history: decisions, metrics, insights (PM only) | | /orchestra blueprint {name} | Generate milestones from template | | /orchestra blueprint add | Save current work as reusable template | | /orchestra create-role | Create a new role interactively (Orchestrator only) | | /orchestra help | Show all commands |

Roles

| Command | Role | |---------|------| | /orchestra pm | Product Manager — plan and orchestrate | | /orchestra orchestrator | System maintenance |

Architecture

.claude/                                ← Claude Code integration
├── agents/
│   ├── lead.md                         ← Autonomous milestone executor
│   └── reviewer.md                     ← Independent code review
├── skills/*.orchestra.md               ← 14 domain checklists
├── rules/*.orchestra.md                ← Discipline rules (auto-loaded)
└── commands/orchestra/                 ← /orchestra commands

.orchestra/                             ← Project data + config
├── config.yml                          ← Pipeline settings (customize per stack)
├── roles/                              ← Role identities (orchestrator, product-manager)
├── blueprints/                         ← Project templates
└── milestones/                         ← Your work

Key Features

Config-driven pipeline — .orchestra/config.yml controls everything: verification commands (customize for Go, Python, Rust), approval gates, thresholds, parallel execution. No hardcoded assumptions.

Four complexity levels with model tiering — PM sets per phase:

• trivial (haiku) → Config changes, version bumps
• quick (sonnet) → Single-file fixes, simple CRUD
• standard (sonnet) → Typical features (default)
• complex (opus) → New subsystems, architectural changes

Verification gate — Tests + lint must pass before every commit. Commands come from config. Fails 3 times → phase marked failed, escalated to user.

14 built-in skills — Domain checklists for auth, CRUD, deployment, accessibility, React, testing, debugging, and more. PM assigns to phases, lead loads them automatically.

Blueprints — Start from templates instead of scratch. saas-starter creates 5 milestones instantly. blueprint add saves your work as a reusable template.

Role boundaries — Enforced via .claude/rules/. PM cannot write code. Engineers cannot modify system files. Orchestrator cannot write features. Boundaries checked by file path, not by words.

Milestone isolation — Every milestone runs in its own sub-agent — context freed automatically, enabling 20+ milestones in a single session. Normal mode asks before continuing; --auto chains milestones automatically.

Stuck detection — Detects repeated failures, circular fixes, over-engineering. Tries different approach once, then escalates. Auto mode skips to next phase.

Upgrading

npx @sulhadin/orchestrator

Smart merge on upgrade:

| What | On upgrade | |------|-----------| | System files (roles, rules, agents, commands) | Updated to latest | | Skills (.orchestra.md) | Updated | | Skills (your custom .md) | Preserved | | Blueprints (template) | Updated | | Blueprints (your custom) | Preserved | | milestones/ | Untouched | | config.yml | Smart merged (user values preserved, new keys added) |

Documentation

Full docs at docs/:

• Getting Started — installation, first milestone, two-terminal model
• Commands — all commands with examples
• Roles — roles, responsibilities, boundaries
• Features — config, verification, skills, blueprints, and more
• Blueprints — project templates, customization
• Skills — domain checklists, creating new skills

License

MIT