@sulhadin/orchestrator 3.0.0-beta.9 → 3.1.0

package/README.md

@@ -4,7 +4,7 @@ AI team orchestration for [Claude Code](https://docs.anthropic.com/en/docs/claud
 
 ## What is Orchestra?
 
-Orchestra turns a single Claude Code session into a coordinated development team. A Product Manager plans features, a Conductor executes them — switching between specialized roles (backend, frontend, architect) automatically. Each role has strict boundaries, every commit passes verification, and the system learns from past milestones.
+Orchestra turns a single Claude Code session into a coordinated development team. A Product Manager plans features, a Conductor orchestrates them — delegating each phase to a sub-agent with the right role (backend, frontend, architect). Sub-agents own implementation and verification; conductor 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.
 
@@ -23,12 +23,12 @@ Terminal 1 (PM):                    Terminal 2 (Conductor):
   /orchestra pm                       /orchestra start
   │                                   │
   ├─ Discuss features                 ├─ Scan milestones
-  ├─ Create milestones                ├─ Activate architect → RFC
-  ├─ Groom phases                     ├─ Activate backend → code + tests
-  │                                   ├─ Activate frontend → UI
+  ├─ Create milestones                ├─ Delegate to architect → RFC
+  ├─ Groom phases                     ├─ Delegate to backend → code + tests
+  │                                   ├─ Delegate to frontend → UI
   │  (plan M2 while M1 runs)          ├─ Call reviewer → code review
   │                                   ├─ Push → milestone done
-  │                                   └─ Loop → next milestone
+  │                                   └─ Stop (inline) or next milestone (agent)
 ```
 
 ## Quick Example
@@ -49,8 +49,7 @@ PM challenges scope, creates M1-user-auth with 3 phases
 ⚙️ backend → phase-2: API endpoints → committed
 🎨 frontend → phase-3: Login UI → committed
 🔍 reviewer → approved
-🚦 Push? → yes
-✅ M1-user-auth done. Checking for next milestone...
+✅ M1-user-auth done. Pushed to origin.
 ```
 
 ## Commands
@@ -63,6 +62,8 @@ PM challenges scope, creates M1-user-auth with 3 phases
 | `/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) |
@@ -86,7 +87,7 @@ PM challenges scope, creates M1-user-auth with 3 phases
 │   ├── conductor.md                    ← Autonomous milestone executor
 │   └── reviewer.md                     ← Independent code review
 ├── skills/*.orchestra.md               ← 14 domain checklists
-├── rules/*.orchestra.md                ← 8 discipline rules
+├── rules/*.orchestra.md                ← Discipline rules (auto-loaded)
 └── commands/orchestra/                 ← /orchestra commands
 
 .orchestra/                             ← Project data + config
@@ -101,10 +102,11 @@ PM challenges scope, creates M1-user-auth with 3 phases
 
 **Config-driven pipeline** — `.orchestra/config.yml` controls everything: verification commands (customize for Go, Python, Rust), approval gates, thresholds, parallel execution. No hardcoded assumptions.
 
-**Three complexity levels** — PM sets per milestone:
-- `quick` → Engineer → Commit → Push (trivial changes)
-- `standard` → Engineer → Review → Push (typical features)
-- `full` → Architect → Engineer → Review → Push (complex work)
+**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.
 
@@ -116,6 +118,8 @@ PM challenges scope, creates M1-user-auth with 3 phases
 
 **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** — `inline` mode stops after each milestone (user compacts manually). `agent` mode spawns each milestone in its own sub-agent — context freed automatically, enabling 20+ milestones in a single `--auto` session.
+
 **Stuck detection** — Detects repeated failures, circular fixes, over-engineering. Tries different approach once, then escalates. Auto mode skips to next phase.
 
 ## Upgrading
@@ -135,7 +139,7 @@ Smart merge on upgrade:
 | Blueprints (your custom) | Preserved |
 | milestones/ | Untouched |
 | knowledge.md | Preserved |
-| config.yml | Preserved |
+| config.yml | Smart merged (user values preserved, new keys added) |
 
 ## Documentation
 

package/bin/build-template.js

@@ -6,12 +6,32 @@ const path = require("path");
 const rootDir = process.cwd();
 const templateDir = path.join(rootDir, "template");
 
-// System files to include in the template
+// Dev-only agents that should NOT be published to users
+const DEV_ONLY_AGENTS = new Set([
+  "codebase-deep-analyzer.md",
+  "orchestra-analyzer.md",
+  "orchestra-reviewer.md",
+  "repo-deep-analyzer.md",
+]);
+
+// Plugin manifest
+const PLUGIN_MANIFEST = {
+  name: "orchestra",
+  description: "AI Team Orchestration — multi-role coordination with milestones, phases, and quality gates for Claude Code",
+  version: require("../package.json").version,
+  author: { name: "Sulhadin Öney" },
+  repository: "https://github.com/sulhadin/orchestrator",
+  license: "MIT",
+};
+
+// System files to include in the template (plugin-compatible structure)
+// Plugin dirs (agents/, commands/, skills/, rules/) go at root level
+// .orchestra/ and CLAUDE.md also go at root level
 const SYSTEM_PATHS = [
-  { src: ".claude/agents", dest: ".claude/agents" },
-  { src: ".claude/commands/orchestra", dest: ".claude/commands/orchestra" },
-  { src: ".claude/rules", dest: ".claude/rules", filter: (f) => f.endsWith(".orchestra.md") },
-  { src: ".claude/skills", dest: ".claude/skills", filter: (f) => f.endsWith(".orchestra.md") },
+  { src: ".claude/agents", dest: "agents", filter: (f) => !DEV_ONLY_AGENTS.has(f) },
+  { src: ".claude/commands/orchestra", dest: "commands" },
+  { src: ".claude/rules", dest: "rules", filter: (f) => f.endsWith(".orchestra.md") },
+  { src: ".claude/skills", dest: "skills", filter: (f) => f.endsWith(".orchestra.md") },
   { src: ".orchestra/roles", dest: ".orchestra/roles" },
   { src: ".orchestra/blueprints", dest: ".orchestra/blueprints" },
   { src: ".orchestra/config.yml", dest: ".orchestra/config.yml" },
@@ -74,5 +94,14 @@ for (const item of SYSTEM_PATHS) {
   console.log(`  [+] Packed: ${item.src}`);
 }
 
+// Write plugin manifest
+const pluginDir = path.join(templateDir, ".claude-plugin");
+ensureDir(pluginDir);
+fs.writeFileSync(
+  path.join(pluginDir, "plugin.json"),
+  JSON.stringify(PLUGIN_MANIFEST, null, 2) + "\n"
+);
+console.log("  [+] Generated .claude-plugin/plugin.json");
+
 console.log("\n  Done! Template is updated and ready for release.");
 console.log("  Run 'yarn build' to test the installation from this template.\n");

package/bin/index.js

@@ -6,6 +6,14 @@ const path = require("path");
 const targetDir = process.cwd();
 const templateDir = path.join(__dirname, "..", "template");
 
+// Plugin-to-standalone mapping: plugin root dirs → .claude/ subdirs
+const PLUGIN_TO_CLAUDE = {
+  agents: ".claude/agents",
+  commands: ".claude/commands/orchestra",
+  rules: ".claude/rules",
+  skills: ".claude/skills",
+};
+
 const ORCHESTRA_SECTION_START = "<!-- orchestra -->";
 const ORCHESTRA_SECTION_END = "<!-- /orchestra -->";
 
@@ -295,7 +303,6 @@ function run() {
   console.log("");
 
   const orchestraSrc = path.join(templateDir, ".orchestra");
-  const claudeSrc = path.join(templateDir, ".claude");
   const orchestraDest = path.join(targetDir, ".orchestra");
   const claudeDest = path.join(targetDir, ".claude");
   const isUpgrade = fs.existsSync(orchestraDest);
@@ -384,18 +391,24 @@ function run() {
     copyDirRecursive(orchestraSrc, orchestraDest);
     console.log("  [+] .orchestra/ installed");
 
-    if (fs.existsSync(claudeSrc)) {
-      copyDirRecursive(claudeSrc, claudeDest);
-      console.log("  [+] .claude/ orchestra files installed");
+    // Copy plugin dirs → .claude/ (plugin-to-standalone mapping)
+    for (const [pluginDir, claudeSubdir] of Object.entries(PLUGIN_TO_CLAUDE)) {
+      const src = path.join(templateDir, pluginDir);
+      if (fs.existsSync(src)) {
+        const dest = path.join(targetDir, claudeSubdir);
+        copyDirRecursive(src, dest);
+      }
     }
+    console.log("  [+] .claude/ orchestra files installed");
 
     // ── Restore user data ──
     for (const [key, { backupPath, type, dir }] of Object.entries(backups)) {
       const baseDest = type === "orchestra" ? orchestraDest : claudeDest;
       const restorePath = path.join(baseDest, dir);
+      // Plugin structure: claude dirs are at template root, orchestra dirs under .orchestra/
       const templateDirPath = type === "orchestra"
         ? path.join(orchestraSrc, dir)
-        : path.join(claudeSrc, dir);
+        : path.join(templateDir, dir);
 
       if (dir === "milestones") {
         if (fs.existsSync(restorePath)) rmDirRecursive(restorePath);
@@ -433,10 +446,15 @@ function run() {
     copyDirRecursive(orchestraSrc, orchestraDest);
     console.log("  [+] .orchestra/ installed");
 
-    if (fs.existsSync(claudeSrc)) {
-      copyDirRecursive(claudeSrc, claudeDest);
-      console.log("  [+] .claude/ installed");
+    // Copy plugin dirs → .claude/ (plugin-to-standalone mapping)
+    for (const [pluginDir, claudeSubdir] of Object.entries(PLUGIN_TO_CLAUDE)) {
+      const src = path.join(templateDir, pluginDir);
+      if (fs.existsSync(src)) {
+        const dest = path.join(targetDir, claudeSubdir);
+        copyDirRecursive(src, dest);
+      }
     }
+    console.log("  [+] .claude/ installed");
   }
 
   // ── Handle CLAUDE.md ──

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@sulhadin/orchestrator",
-  "version": "3.0.0-beta.9",
+  "version": "3.1.0",
   "description": "AI Team Orchestration System — multi-role coordination for Claude Code",
   "bin": "bin/index.js",
   "scripts": {
-    "test": "node --test bin/**/*.test.js",
+    "test": "node --test test/**/*.test.js",
     "template": "node bin/build-template.js",
     "prepare": "husky"
   },

package/template/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "orchestra",
+  "description": "AI Team Orchestration — multi-role coordination with milestones, phases, and quality gates for Claude Code",
+  "version": "3.1.0",
+  "author": {
+    "name": "Sulhadin Öney"
+  },
+  "repository": "https://github.com/sulhadin/orchestrator",
+  "license": "MIT"
+}

package/template/.orchestra/README.md

@@ -10,14 +10,13 @@ Terminal 1 (PM):                    Terminal 2 (Conductor):
   /orchestra pm                      /orchestra start
   │                                  │
   ├─ Discuss features with user      ├─ Scan milestones
-  ├─ Create milestones               ├─ 🏗️ architect → RFC
+  ├─ Create milestones               ├─ 🏗️ delegate to architect → RFC
   ├─ Groom phases                    ├─ 🚦 User approves RFC
-  ├─ Always available                ├─ ⚙️ backend → phase by phase
-  │                                  ├─ 🎨 frontend → phase by phase
+  ├─ Always available                ├─ ⚙️ delegate to backend → phase by phase
+  │                                  ├─ 🎨 delegate to frontend → phase by phase
   │  (can plan M2 while M1 runs)     ├─ 🔍 reviewer → review commits
-  │                                  ├─ 🚦 User approves push
   │                                  ├─ git push → milestone done
-  │                                  └─ Loop → next milestone
+  │                                  └─ Stop (inline) or next milestone (agent)
 ```
 
 ## Directory Structure
@@ -25,7 +24,7 @@ Terminal 1 (PM):                    Terminal 2 (Conductor):
 ```
 .orchestra/
 ├── README.md              # This file
-├── roles/                 # Role identities (slim, ~15 lines each)
+├── roles/                 # Role identities (one file per role)
 │   ├── product-manager.md
 │   ├── architect.md
 │   ├── backend-engineer.md
@@ -56,8 +55,10 @@ You can plan new milestones while the conductor is executing another one.
 
 ### Terminal 2: `/orchestra start` (Execution)
 
-Conductor reads milestones, executes phases autonomously. Activates roles per phase.
-Loops to the next milestone when done. Maintains `context.md` for resume capability.
+Conductor reads milestones, delegates each phase to a sub-agent with the right role.
+Sub-agents implement + verify; conductor commits. After milestone completion, behavior
+depends on `milestone_isolation` config: stops (inline) or continues to next (agent).
+Maintains `context.md` for resume capability.
 
 ```
 /orchestra start
@@ -81,7 +82,6 @@ PM discusses feature with user
   → Conductor executes frontend phases (sequential, each → commit)
   → Conductor calls reviewer agent (reviews unpushed commits)
   → FIX cycle if changes-requested (re-review if fix >= 30 lines)
-  → [USER APPROVAL GATE: Push to origin]
   → Conductor pushes, PM verifies acceptance criteria, closes milestone
   → Conductor appends 5-line retrospective to knowledge.md
 
@@ -94,19 +94,45 @@ Hotfix (production bugs):
 ### Milestone Lock
 
 Conductor claims a milestone by writing `Locked-By: {timestamp}` to milestone.md before execution.
-Other conductors skip locked milestones. Lock expires after 2 hours (stale protection).
+Other conductors skip locked milestones. Lock expires after config.yml `thresholds.milestone_lock_timeout` minutes (default 120).
 
 ### Pipeline Modes (Complexity)
 
-PM sets a `Complexity` level on each milestone that determines the pipeline:
+PM sets `Complexity` on milestone (pipeline) and `complexity` on each phase (model selection):
 
-| Complexity | Pipeline | Use when |
-|------------|----------|----------|
-| `quick` | Engineer → Commit → Push | Config tweaks, copy changes, trivial fixes |
-| `standard` | Engineer → Review → Push | Typical features, clear requirements |
-| `full` | Architect → Engineer → Review → Push | Complex features, new subsystems |
+| Complexity | Model | Pipeline | Use when |
+|------------|-------|----------|----------|
+| `trivial` | Haiku | Phases → Commit → Push | Version bumps, env vars, config changes |
+| `quick` | Sonnet | Phases → Commit → Push (skip review) | Single-file fixes, simple CRUD |
+| `standard` | Sonnet | Phases → Review → Push | Typical features, clear requirements |
+| `complex` | Opus | Architect → Phases → Review → Push | New subsystems, unfamiliar territory |
 
-Default is `full` if not specified. Conductor reads the `Complexity` field from `milestone.md`.
+Defaults: config.yml `pipeline.default_pipeline` and `pipeline.default_complexity`.
+
+### Milestone Isolation
+
+Config `pipeline.milestone_isolation` controls how the conductor handles multiple milestones:
+
+| Mode | Behavior | Best for |
+|------|----------|----------|
+| `inline` (default) | Conductor runs milestone directly, **stops** after completion. User runs `/compact` then `/orchestra start` for next milestone. | Manual sessions, PC-based work |
+| `agent` | Conductor spawns a sub-agent per milestone. Context freed automatically after each. Loops to next milestone. | `--auto` overnight batch runs |
+
+```
+Inline mode:                          Agent mode:
+  /orchestra start                      /orchestra start --auto
+  → M1 executes → done → STOP          → Spawn Agent(M1) → done → freed
+  user: /compact                        → Spawn Agent(M2) → done → freed
+  /orchestra start                      → Spawn Agent(M3) → done → freed
+  → M2 executes → done → STOP          → All done
+```
+
+In agent mode, the delegation is two-tier:
+```
+Conductor (lean dispatcher)
+  └── Milestone Agent (fresh context)
+        └── Phase Agent (unchanged)
+```
 
 ### Milestone Statuses
 
@@ -142,8 +168,8 @@ Within each domain (backend/frontend), phases run in order: phase-1 → phase-2
 **Parallel execution:** If PM sets `depends_on` in phase frontmatter, independent phases
 can run in parallel via subagent worktree isolation. No `depends_on` = sequential (default).
 
-**Verification Gate:** Before every commit, conductor MUST pass type check + tests + lint
-(commands from config.yml). Commit is blocked until all checks pass.
+**Verification Gate:** Sub-agents run typecheck + tests + lint (from config.yml) before reporting.
+Conductor NEVER commits unless verification passes.
 
 ---
 
@@ -151,7 +177,8 @@ can run in parallel via subagent worktree isolation. No `depends_on` = sequentia
 
 - Each phase completion → **one conventional commit** on the current branch
 - No branch creation or switching — work happens on whatever branch is checked out
-- Milestone completion → **push to origin** (after user approval)
+- Milestone completion → **push to origin** (automatic after review passes)
+- Commits stay local until milestone fully completes — no partial push on failure
 - Reviewer reviews unpushed commits: `git log origin/{branch}..HEAD`
 - Clean git history: each commit maps to a phase
 
@@ -185,16 +212,14 @@ Rules:
 
 The user must approve before these transitions:
 - **Milestone creation** — PM discusses and plans, but must get user approval before creating the milestone directory and files
-- **RFC → Implementation** — user reviews architect's RFC
-- **Push to origin** — user approves the final changeset
+- **RFC → Implementation** — user reviews architect's RFC (if `rfc_approval` is not `skip`)
 
-All other transitions are automatic.
+Push is automatic after review passes. All other transitions are automatic.
 
 ### Rejection Handling
 
 If the user says **no** at any gate:
-- **RFC rejected** → Architect revises based on feedback, re-submits (max 3 rounds)
-- **Push rejected** → Conductor creates fix phase, implements, re-submits push gate
+- **RFC rejected** → Architect revises based on feedback, re-submits (max config `pipeline.max_rfc_rounds`)
 - **Milestone rejected** → PM revises in PM terminal
 
 Rejections are normal. The system does not stall — it loops back with feedback.
@@ -213,12 +238,12 @@ Conductor calls reviewer agent
   → Returns: approved / approved-with-comments / changes-requested
 ```
 
-**If approved** → proceed to push gate.
+**If approved** → push immediately.
 
-**If approved-with-comments** → proceed to push gate. Comments are logged in context.md.
+**If approved-with-comments** → push immediately. Comments are logged in context.md.
 
-**If changes-requested** → Conductor switches to the relevant role, fixes
-and commits. Re-review triggered if fix >= config `re_review_lines` threshold.
+**If changes-requested** → Conductor continues the phase's sub-agent via SendMessage with
+reviewer findings. Re-review triggered if fix >= config `re_review_lines` threshold.
 
 ---
 
@@ -283,16 +308,21 @@ PM and conductor run in **separate terminals**. They communicate through milesto
 
 ### Context Persistence
 
-Conductor maintains `context.md` in each milestone directory. This allows:
-- Resume after terminal close/reopen
-- Track decisions made during implementation
-- Record what was committed in each phase
+Conductor maintains `context.md` in each milestone directory with a fixed structure:
+- `## Status` — milestone id, start date, pipeline type
+- `## Phases` — per-phase status, commit hash, files changed, errors
+- `## Codebase Map` — scout-generated file map (survives milestone clear)
+- `## Decisions` — key choices from each phase that affect later phases
+- `## Metrics` — phase duration and verification retries (used by `/orchestra status`)
+
+This enables resume after terminal close/reopen. On restart, conductor reads context.md and skips completed phases.
 
 ### Approval Gates (Conductor Terminal)
 
-Conductor asks the user directly (not PM) at these points:
-1. **RFC ready** — "Approve RFC to start implementation?"
-2. **Push to origin** — "All done. Push to origin?"
+Conductor asks the user directly (not PM) at this point:
+1. **RFC ready** — "Approve RFC to start implementation?" (if `rfc_approval` is not `skip`)
+
+Push is automatic after review passes — no approval needed.
 
 ---
 
@@ -330,16 +360,18 @@ sequenceDiagram
         C->>C: Fix → commit
     end
 
-    C->>U: Push to origin?
-    U->>C: Yes
     C->>C: git push → milestone done
 
-    C->>C: Next milestone? → loop or done
+    alt Inline mode (default)
+        C->>C: STOP — user compacts and restarts
+    else Agent mode
+        C->>C: Next milestone? → loop or done
+    end
 
     Note over PM: PM is free the entire time<br/>Can plan M2 while M1 executes
 ```
 
-### 2. Conductor Execution Loop
+### 2. Conductor Execution Loop (Inline Mode)
 
 ```mermaid
 sequenceDiagram
@@ -354,11 +386,27 @@ sequenceDiagram
     C->>C: reviewer → approved
     C->>C: Push → M1 done
 
-    C->>C: Start M2
-    C->>C: architect → RFC
-    C->>C: backend phase-1
-    C->>C: reviewer → approved
-    C->>C: Push → M2 done
+    Note over C: STOP. "Run /compact or /clear then /orchestra start"
+```
+
+### 3. Conductor Execution Loop (Agent Mode)
+
+```mermaid
+sequenceDiagram
+    participant C as Conductor
+    participant MA as Milestone Agent
+
+    C->>C: Scan milestones/
+
+    C->>MA: Spawn Agent(M1)
+    MA->>MA: phase-1 → phase-2 → review → push
+    MA-->>C: {status: done, retro: ...}
+    Note over C: Write retro, ~1-2k tokens retained
+
+    C->>MA: Spawn Agent(M2)
+    MA->>MA: phase-1 → phase-2 → review → push
+    MA-->>C: {status: done, retro: ...}
+    Note over C: Write retro, ~1-2k tokens retained
 
     C->>C: No more milestones
     Note over C: "All done. Waiting for new work."

package/template/.orchestra/config.yml

@@ -13,10 +13,7 @@ pipeline:
     standard: sonnet
     complex: opus
   # RFC approval gate: required | optional | skip
-  rfc_approval: required
-
-  # Push approval gate: required | auto
-  push_approval: required
+  rfc_approval: skip
 
   # Code review: required | optional | skip
   review: required
@@ -25,6 +22,11 @@ pipeline:
   # When enabled, phases with depends_on: [] run in parallel
   parallel: disabled
 
+  # Milestone isolation mode: inline | agent
+  # inline: conductor runs milestones directly, stops after each. User compacts manually. (default)
+  # agent: each milestone runs in its own sub-agent. Context freed automatically. Best for --auto.
+  milestone_isolation: inline
+
   # Default pipeline when milestone Complexity is missing
   default_pipeline: full  # quick | standard | full
 
@@ -34,6 +36,9 @@ pipeline:
   # Max RFC rejection rounds before escalating to user
   max_rfc_rounds: 3
 
+  # Max milestone review rounds before proceeding anyway with warnings
+  max_milestone_review_rounds: 3
+
 thresholds:
   # Milestone lock timeout in minutes (stale locks are ignored)
   milestone_lock_timeout: 120

package/template/.orchestra/knowledge.md

@@ -69,7 +69,7 @@ Last 5 milestones. Conductor reads before every milestone start. PM reads before
 
 ### Decisions
 - Skill System (markdown-only): Lightweight `.orchestra/skills/` with domain checklists (auth, CRUD, deployment). No registry, no keyword matching — PM manually assigns via `skills:` frontmatter in phase files. Preserves zero-infrastructure philosophy.
-- Cost Awareness: Track duration + verification retries per phase in context.md Cost Tracking table. PM sees this in #status. No token counting (unreliable from prompt), focus on observable metrics.
+- Cost Awareness: Track duration + verification retries per phase in context.md `## Metrics` section. PM sees this in `/orchestra status`. No token counting (unreliable from prompt), focus on observable metrics.
 - Re-review Threshold: Fix < 30 lines → no re-review. Fix >= 30 lines → abbreviated re-review (only the fix commit). Balances quality vs speed.
 - Rejection Flow: RFC rejected → architect revises (max 3 rounds). Push rejected → create fix phase. System no longer stalls on "no".
 

package/template/.orchestra/roles/product-manager.md

@@ -42,13 +42,44 @@ Cannot write: feature code, RFCs, architecture docs, review findings, system fil
     └── phase-2.md
 ```
 
-### Pre-flight Checklist
+### Milestone Review Loop
 
+After creating milestone files, launch a milestone-reviewer sub-agent before
+marking the milestone as ready. This catches planning errors before conductor executes.
+
+**Flow:** PM creates → reviewer sub-agent → PM fixes → reviewer again → max `pipeline.max_milestone_review_rounds`
+
+Launch sub-agent (general-purpose, model: sonnet) with this prompt:
+
+```
+You are reviewing a milestone for quality before execution. Read these files
+in {milestone_path}/: prd.md, milestone.md, grooming.md, and all files in phases/.
+(rfc.md and context.md don't exist yet — don't flag them as missing.)
+
+## Checklist
 1. Every phase has `role:` set?
-2. Every phase has `skills:` reviewed?
-3. Every phase has clear, testable acceptance criteria?
-4. `milestone.md` has `Complexity:` set?
-5. Phase order and dependencies correct?
+2. Every phase has `complexity:` set?
+3. Every phase has `skills:` appropriate for the role and task?
+4. Every phase has `scope:` defining which files/dirs to touch?
+5. Acceptance criteria are testable? (not vague like "works well" — specific like "returns 200")
+6. `milestone.md` has `Complexity:` set?
+7. Phase order and `depends_on` are correct? (frontend depends on backend, etc.)
+8. No overlapping scope between phases? (two phases writing same files)
+9. PRD explains WHY, not just WHAT?
+
+## Return Format
+verdict: approved | changes-requested
+issues:
+- [severity: blocking|suggestion] {description} — {file}
+summary: {2-3 sentences}
+```
+
+**Process:**
+1. If **approved** → proceed, milestone is ready for conductor
+2. If **changes-requested** → PM reads issues, fixes milestone files, re-launches reviewer
+3. After max rounds with no blocking issues → proceed with suggestions logged in grooming.md
+4. After max rounds with blocking issues still open → escalate to user, do NOT proceed
+5. Present verdict to user before finalizing
 
 ### milestone.md Format
 
@@ -59,7 +90,7 @@ Cannot write: feature code, RFCs, architecture docs, review findings, system fil
 |-------|-------|
 | Status | planning / in-progress / review / done |
 | Priority | P0 / P1 / P2 |
-| Complexity | quick / standard / full |
+| Complexity | trivial / quick / standard / complex |
 | PRD | prd.md |
 | Created | {date} |
 ```
@@ -85,11 +116,12 @@ depends_on: []
 
 ### Complexity Levels
 
-| Level | Pipeline | When |
-|-------|----------|------|
-| `quick` | Engineer → Commit → Push | Trivial: config, copy, single-file fix |
-| `standard` | Engineer → Review → Push | Typical features, clear requirements |
-| `full` | Architect → Engineer → Review → Push | Complex: new subsystems, unfamiliar territory |
+| Level | Model | Pipeline | When |
+|-------|-------|----------|------|
+| `trivial` | Haiku | Phases → Commit → Push | Version bumps, env vars, config changes |
+| `quick` | Sonnet | Phases → Commit → Push (skip review) | Single-file fixes, simple CRUD |
+| `standard` | Sonnet | Phases → Review → Push | Typical features (default) |
+| `complex` | Opus | Architect → Phases → Review → Push | New subsystems, unfamiliar territory |
 
 ### Blueprint Command
 

package/template/CLAUDE.md

@@ -1,6 +1,6 @@
-# CLAUDE.md — Orchestra Setup Instructions
+# CLAUDE.md
 
-This file is automatically read by Claude at the start of every session.
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
 <!-- orchestra -->
 ## Orchestra — AI Team Orchestration System
@@ -46,6 +46,22 @@ Role IDs: orchestrator, product-manager, architect, backend-engineer, frontend-e
 - Rules (`.claude/rules/*.orchestra.md`) auto-loaded. Skills loaded per phase.
 - **PROTECTED:** Non-Orchestrator roles NEVER modify `.orchestra/roles/`, `.orchestra/config.yml`, `.orchestra/README.md`, `.orchestra/blueprints/`, `.claude/agents/`, `.claude/rules/*.orchestra.md`, `.claude/skills/*.orchestra.md`, `.claude/commands/orchestra/`, `CLAUDE.md`, or `docs/`.
 
+## Development
+
+This is an npm package (`@sulhadin/orchestrator`) — a CLI installer that copies Orchestra template files into user projects.
+
+```bash
+yarn test              # Run tests (node:test, test/**/*.test.js)
+yarn template          # Rebuild template/ from source files (bin/build-template.js)
+yarn build             # Full build (defined in lint-staged)
+```
+
+**Architecture:** `bin/index.js` is the CLI entry point (runs via `npx`). It copies files from `template/` into the user's project, with smart YAML merge for `config.yml` (preserves user values, adds new keys). `bin/build-template.js` generates the `template/` directory from the source `.orchestra/` and `.claude/` files.
+
+**npm publishes:** Only `bin/` and `template/` directories (see `package.json` `files` field). Tests, docs, and source orchestra files are excluded.
+
+**Pre-commit:** Husky + lint-staged runs `yarn template && yarn build` on staged `.js`, `.md`, `.yml`, `.json` files.
+
 ## Installation
 
 See `docs/getting-started.md` for setup instructions.