@sulhadin/orchestrator 1.6.1 → 1.7.0

package/README.md

@@ -1,207 +1,120 @@
 # Orchestra
 
-A milestone-based orchestration system for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). One terminal, one PM, one worker agent — features built end-to-end without manual role switching.
+AI team orchestration for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Two terminals — PM plans, worker builds.
 
-## The Problem
-
-Building a feature with Claude Code typically looks like this:
+## Install
 
+```bash
+npx @sulhadin/orchestrator
 ```
-You: "Build user authentication"
-You: *opens terminal* "#architect — design the system"
-You: *reads RFC, approves*
-You: *opens terminal* "#backend — implement the API"
-You: *opens terminal* "#reviewer — review the code"
-You: *opens terminal* "#pm — close the feature"
-```
-
-You become the orchestrator. You carry context between sessions, sequence work in the right order, and manage the pipeline manually. This is tedious and error-prone.
 
-## The Solution
+Skip permission prompts:
 
-Orchestra turns Claude Code's PM role into an autonomous orchestrator. You describe what you want, PM handles the rest:
-
-```
-You: "#pm"
-You: "I want user authentication with JWT"
-PM:  creates milestone, grooms phases, dispatches worker agent
-     #architect writes RFC → you approve
-     #backend implements phase by phase → each phase = one commit
-     #frontend builds the UI → each phase = one commit
-     #reviewer reviews unpushed commits
-     you approve → PM pushes to origin
-     milestone closed.
+```bash
+npx @sulhadin/orchestrator --dangerously-skip-permissions
 ```
 
-One conversation. One terminal. PM drives everything.
-
-## How It Works
-
-```
-You ←→ PM (always-on orchestrator)
-        │
-        ├── Creates milestone with groomed phases
-        ├── Spawns one worker agent (all roles loaded)
-        │
-        ├── SendMessage("#architect: write RFC") → awaits
-        ├── SendMessage("#backend: phase-1")     → awaits → commit
-        ├── SendMessage("#backend: phase-2")     → awaits → commit
-        ├── SendMessage("#frontend: phase-3")    → awaits → commit
-        ├── SendMessage("#reviewer: review")     → awaits
-        │
-        ├── You approve → PM pushes to origin
-        └── Milestone closed
-```
+## Two Terminals
 
-### Key Concepts
+### Terminal 1: `#pm` — Planning
 
-**Milestones** — Each feature is a milestone. Everything lives in one directory:
+PM is your strategic partner. Discuss ideas, challenge scope, create milestones. PM never writes code — only plans.
 
 ```
-.orchestra/milestones/M1-user-auth/
-├── prd.md              PM writes (what + why)
-├── milestone.md        Status, acceptance criteria
-├── grooming.md         Discussion notes, decisions
-├── rfc.md              Architect writes (how)
-├── architecture.md     Architect writes (system design)
-├── design.md           Frontend engineer writes (UI/UX)
-├── adrs/               Architecture Decision Records
-└── phases/
-    ├── phase-1.md      backend: DB schema → commit
-    ├── phase-2.md      backend: API endpoints → commit
-    └── phase-3.md      frontend: login UI → commit
-```
-
-**Single Worker Session** — PM creates one agent with all roles loaded. No warmup on role switches. Architect decisions are in context when backend implements. Backend code is in context when reviewer reviews.
-
-**Await-Based** — PM dispatches via `SendMessage`, blocks until the worker returns. No polling, no signal files. Results flow directly through the return value.
-
-**Git-Native Review** — Reviewer doesn't need task files. Reviews unpushed commits on the current branch via `git diff origin/branch...HEAD`.
-
-### Roles
+You: #pm
+PM:  "No active milestones. Ready for instructions."
 
-| Role | What it does |
-|------|-------------|
-| **Product Manager** | Orchestrates everything. Creates milestones, dispatches worker, drives pipeline. |
-| **Architect** | Designs technical solutions. Writes RFCs, ADRs. |
-| **Backend Engineer** | Implements backend code + tests. One commit per phase. |
-| **Frontend Engineer** | Designs + implements UI. One commit per phase. |
-| **Code Reviewer** | Reviews unpushed commits. Returns approved or changes-requested. |
-| **Owner** | Maintains Orchestra system files (roles, rules, structure). |
+You: "I want user authentication with JWT"
+PM:  *discusses, challenges, refines scope*
 
-### Pipeline
+You: "Create the milestone"
+PM:  *creates prd.md, grooming.md, milestone.md, phases/*
+     "🎯 M1-user-auth ready. Run #start in another terminal."
 
+You: "Let's also plan a dashboard"
+PM:  *plans M2 while worker executes M1*
 ```
-PM creates milestone
-  → Architect writes RFC
-  → [You approve RFC]
-  → Backend phases (sequential, each → commit)
-  → Frontend phases (sequential, each → commit)
-  → Reviewer reviews unpushed commits
-  → Fix cycle if needed (one round, no re-review)
-  → [You approve push]
-  → PM pushes to origin, closes milestone
-```
-
-### Approval Gates
 
-You only need to approve twice:
+PM is always available. Plan ahead while work runs in the other terminal.
 
-1. **RFC → Implementation** — after architect writes the technical design
-2. **Push to origin** — after reviewer approves
+### Terminal 2: `#start` — Execution
 
-Everything else is automatic.
+Worker picks up milestones and executes them autonomously. Loops to the next when done.
 
-## Install
-
-```bash
-npx @sulhadin/orchestrator
 ```
+You: #start
 
-This will:
+📋 Starting M1-user-auth
 
-- Copy `.orchestra/` directory to your project root
-- Create `CLAUDE.md` if it doesn't exist, or append Orchestra instructions to your existing one
+🏗️ #architect ▶ RFC + grooming validation...
+🏗️ #architect ✅ RFC ready
+🚦 Approve RFC? → yes
 
-### What Gets Installed
+⚙️ #backend ▶ phase-1: DB schema + migrations...
+⚙️ #backend ✅ phase-1 done (feat(db): add auth tables)
 
-```
-your-project/
-├── .orchestra/
-│   ├── README.md              Orchestration rules
-│   ├── agents/worker.md       Worker agent prompt
-│   ├── roles/                 6 role definitions
-│   ├── milestones/            Feature work (empty)
-
-└── CLAUDE.md                  Orchestra instructions for Claude
-```
+⚙️ #backend ▶ phase-2: API endpoints + tests...
+⚙️ #backend ✅ phase-2 done (feat(auth): add login endpoint)
 
-## Usage
+🎨 #frontend ▶ phase-3: Login UI...
+🎨 #frontend ✅ phase-3 done (feat(auth): add login page)
 
-Open Claude Code in your project and say `#pm`:
+🔍 #reviewer ▶ reviewing unpushed commits...
+🔍 #reviewer ✅ approved
 
-```
-You: #pm
-PM:  "No active milestones. Ready for instructions."
+🚦 Push to origin? → yes
+✅ M1-user-auth done.
 
-You: "I want to add a health check endpoint"
-PM:  *discusses scope, challenges assumptions, proposes approach*
-
-You: "Let's build it"
-PM:  *creates milestone, grooms phases, dispatches worker*
-     *reports progress after each phase*
-     *asks for approval at gates*
-     *pushes and closes milestone*
+📋 Starting M2-dashboard...
 ```
 
-### Commands
-
-| Command | Description |
-|---------|------------|
-| `#pm` | Activate Product Manager |
-| `#backend` | Activate Backend Engineer (manual mode) |
-| `#frontend` | Activate Frontend Engineer (manual mode) |
-| `#reviewer` | Activate Code Reviewer (manual mode) |
-| `#architect` | Activate Architect (manual mode) |
-| `#owner` | Activate Owner (system maintenance) |
-| `status` | Pipeline status report (PM only) |
-| `orc help` | Show all commands |
+Close the terminal, reopen, type `#start` — it resumes from where it left off.
 
-### Manual Mode
+## Milestones
 
-You can still use roles directly without PM orchestration:
+Everything for a feature lives in one directory:
 
 ```
-You: #backend
-BE:  *checks milestones for pending backend phases*
-     *starts working*
+.orchestra/milestones/M1-user-auth/
+├── prd.md              What + why (PM writes)
+├── milestone.md        Status, acceptance criteria
+├── grooming.md         Discussion notes, scope decisions
+├── rfc.md              Technical design (architect writes)
+├── context.md          Running log (worker maintains for resume)
+└── phases/
+    ├── phase-1.md      backend: DB schema → commit
+    ├── phase-2.md      backend: API endpoints → commit
+    └── phase-3.md      frontend: login UI → commit
 ```
 
-Autonomous and manual modes work side by side.
+## Approval Gates
 
-## Engineering Standards
+Worker asks you at two points:
 
-Orchestra enforces these through role definitions and code review:
+1. **RFC ready** — approve before implementation starts
+2. **Push to origin** — approve before code is pushed
 
-- **SOLID, KISS, YAGNI, DRY** — enforced by reviewer
-- **Code without tests is not done** — backend and frontend engineers write tests as part of implementation
-- **Conventional commits** — one commit per phase (`feat`, `fix`, `refactor`, etc.)
-- **No `any` types, no unused code, no workarounds** — zero-tolerance rules
-- **Design before code** — frontend engineer writes design specs before implementing
-- **Grooming before implementation** — detailed phase planning before any code is written
-- **Current library versions** — always verify with docs, never rely on memory
+PM asks you before creating a milestone. Everything else is automatic.
 
-## Configuration
+## Commands
 
-Customize roles by editing files in `.orchestra/roles/`. Each role file defines:
+| Command | Where | What it does |
+|---------|-------|-------------|
+| `#pm` | Terminal 1 | Plan features, create milestones |
+| `#start` | Terminal 2 | Execute milestones, asks at approval gates |
+| `#start --auto` | Terminal 2 | Fully autonomous — no questions asked |
+| `#status` | Terminal 1 | Milestone status report |
+| `#help` | Any | Show all commands |
 
-- Identity and boundaries
-- File ownership (what it can/cannot write)
-- Workflow steps
-- Engineering principles
-- Review checklists (for code-reviewer)
+Manual mode (any terminal):
 
-The worker agent prompt (`.orchestra/agents/worker.md`) controls how the subagent behaves when PM dispatches it.
+| Command | Role |
+|---------|------|
+| `#backend` | Backend Engineer |
+| `#frontend` | Frontend Engineer |
+| `#reviewer` | Code Reviewer |
+| `#architect` | Architect |
+| `#owner` | System maintenance |
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sulhadin/orchestrator",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "AI Team Orchestration System — multi-role coordination for Claude Code",
   "bin": {
     "orchestrator": "bin/index.js"

package/template/.orchestra/README.md

@@ -1,26 +1,23 @@
 # Orchestra — AI Team Orchestration
 
 A milestone-based orchestration system for coordinating AI agent sessions
-working on the same codebase. The Product Manager acts as the orchestrator,
-dispatching work to a single worker agent that switches between roles.
+working on the same codebase. Two terminals: PM plans, worker executes.
 
 ## How It Works
 
 ```
-You (User)
-  │
-  └─ Open Terminal → "You are the product-manager"
-      → PM reads role file + orchestration rules
-      → PM checks .orchestra/milestones/ for active work
-      → PM discusses features with you, creates milestones
-      → PM creates a worker agent session (all roles loaded)
-      → PM dispatches phases sequentially:
-          #architect → writes RFC
-          #backend   → implements backend phases (each → commit)
-          #frontend  → implements frontend phases (each → commit)
-          #reviewer  → reviews unpushed commits
-      → PM pushes to origin after approval
-      → PM closes milestone
+Terminal 1 (PM):                    Terminal 2 (Worker):
+  #pm                                #start
+  │                                  │
+  ├─ Discuss features with user      ├─ Scan milestones
+  ├─ Create milestones               ├─ 🏗️ #architect → RFC
+  ├─ Groom phases                    ├─ 🚦 User approves RFC
+  ├─ Always available                ├─ ⚙️ #backend → phase by phase
+  │                                  ├─ 🎨 #frontend → phase by phase
+  │  (can plan M2 while M1 runs)     ├─ 🔍 #reviewer → review commits
+  │                                  ├─ 🚦 User approves push
+  │                                  ├─ git push → milestone done
+  │                                  └─ Loop → next milestone
 ```
 
 ## Directory Structure
@@ -42,35 +39,42 @@ You (User)
 │       ├── milestone.md   # Summary, acceptance criteria, status
 │       ├── grooming.md    # Discussion, scope, decisions
 │       ├── rfc.md         # Technical design (architect fills)
+│       ├── architecture.md # System design (architect fills, if needed)
+│       ├── design.md      # UI/UX design (frontend fills, if needed)
+│       ├── context.md     # Running log (worker maintains for resume)
+│       ├── adrs/          # Architecture Decision Records (if needed)
 │       └── phases/        # Sequential units of work
 │           ├── phase-1.md # role + objective + scope + result
 │           ├── phase-2.md
 │           └── ...
 ```
 
-## Two Modes of Operation
+## Two Terminals
 
-### Autonomous Mode (recommended)
+### Terminal 1: `#pm` (Planning)
 
-User talks only to PM. PM dispatches a worker agent to execute all roles:
+PM is always available for discussion. Creates milestones, never writes code.
+You can plan new milestones while the worker is executing another one.
 
-1. PM creates milestone with groomed phases
-2. PM creates worker agent session (via `Agent` tool — all roles loaded once)
-3. PM dispatches phases via `SendMessage` → awaits result → dispatches next
-4. Worker switches roles as PM instructs (`#architect`, `#backend`, `#frontend`, `#reviewer`)
-5. Each phase → one commit. Milestone done → push to origin.
+### Terminal 2: `#start` (Execution)
 
-### Manual Mode
-
-User switches roles directly — same as before:
+Worker reads milestones, executes phases autonomously. Switches roles per phase.
+Loops to the next milestone when done. Maintains `context.md` for resume capability.
 
 ```
-User → #backend (implement)
-User → #reviewer (review)
+#start
+  → finds M1-user-auth (status: in-progress) → resumes
+  → finds M2-dashboard (status: planning) → starts after M1
+  → no more milestones → "All done. Waiting for new work."
 ```
 
-Roles check `.orchestra/milestones/` for phases assigned to them. Manual mode
-works alongside autonomous mode — user can mix both.
+### Manual Mode
+
+You can still use roles directly in any terminal:
+```
+#backend  → checks milestones for pending backend phases
+#reviewer → checks for unpushed commits to review
+```
 
 ---
 
@@ -243,38 +247,31 @@ Each role has exclusive write access to specific directories:
 | product-manager | `.orchestra/milestones/*` (prd.md, milestone.md, grooming.md, phases) | Everything |
 | architect | `.orchestra/milestones/*/rfc.md`, `.orchestra/milestones/*/architecture.md`, `.orchestra/milestones/*/adrs/*`, project configs (initial setup) | Everything |
 | backend-engineer | `src/`, `tests/`, `src/**/__tests__/*`, `migrations/`, `package.json`, `tsconfig.json` | `.orchestra/milestones/*/phases/*` |
-| code-reviewer | Review findings only (returned to PM via await) | `src/`, `tests/`, `frontend/` |
+| code-reviewer | Review findings only — never modifies source code | `src/`, `tests/`, `frontend/` |
 | frontend-engineer | `frontend/`, `frontend/**/__tests__/*`, `frontend/**/e2e/*`, `.orchestra/milestones/*/design.md` | `.orchestra/milestones/*/phases/*` |
 
 ---
 
-## Worker Agent Communication
-
-### PM → Worker (via SendMessage)
-
-PM dispatches tasks by specifying the role and the work:
+## PM ↔ Worker Communication
 
-```
-"#backend: Implement phase-1 of M1-user-auth.
-Read: .orchestra/milestones/M1-user-auth/phases/phase-1.md"
-```
+PM and worker run in **separate terminals**. They communicate through milestone files:
 
-### Worker → PM (via await return)
+- **PM writes:** prd.md, grooming.md, milestone.md, phase files
+- **Worker reads:** milestone files → executes phases → updates results + context.md
+- **No direct messaging** between PM and worker — file system is the interface
 
-Worker returns results directly. PM reads the return value — no polling needed.
+### Context Persistence
 
-Possible return types:
-- **Done** — work completed, committed, phase result updated
-- **QUESTION** — worker needs clarification, PM asks user and re-dispatches
-- **CONCERN** — worker spotted an issue, PM evaluates
-- **NEEDS** — worker needs work outside current role's scope, PM dispatches appropriate role
-- **Error** — worker failed, PM reports to user
+Worker 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
 
-### No Polling, No Signals
+### Approval Gates (Worker Terminal)
 
-`SendMessage` blocks until the worker returns. PM gets results directly.
-Signal files and queues are **not used**. Milestone/phase files provide
-persistence if PM session dies.
+Worker 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?"
 
 ---
 
@@ -285,85 +282,63 @@ persistence if PM session dies.
 ```mermaid
 sequenceDiagram
     actor U as User
-    participant PM as Product Manager
-    participant W as Worker Agent
+    participant PM as Terminal 1: PM
+    participant W as Terminal 2: Worker
 
-    U->>PM: Describe feature
-    PM->>PM: Create milestone + groom phases
-    PM->>W: Agent(worker.md) — create session
+    U->>PM: "I want user auth"
+    PM->>PM: Discuss, plan, create milestone
 
-    PM->>W: SendMessage(#architect: write RFC)
-    W-->>PM: RFC result
-    PM->>U: RFC ready — approve?
-    U->>PM: Approved
+    U->>W: #start
+    W->>W: Read milestone files
+
+    W->>W: 🏗️ #architect → write RFC
+    W->>U: 🚦 Approve RFC?
+    U->>W: Yes
 
     loop Each backend phase
-        PM->>W: SendMessage(#backend: phase-N)
-        W-->>PM: Phase result + commit
-        PM->>U: Progress: phase-N done
+        W->>W: ⚙️ #backend → phase-N → commit
     end
 
     loop Each frontend phase
-        PM->>W: SendMessage(#frontend: phase-N)
-        W-->>PM: Phase result + commit
-        PM->>U: Progress: phase-N done
+        W->>W: 🎨 #frontend → phase-N → commit
     end
 
-    PM->>W: SendMessage(#reviewer: review)
-    W-->>PM: Review verdict
+    W->>W: 🔍 #reviewer → review commits
 
     alt Changes requested
-        PM->>W: SendMessage(#backend/#frontend: fix)
-        W-->>PM: Fix result + commit
+        W->>W: Fix → commit
     end
 
-    PM->>U: Review done — push to origin?
-    U->>PM: Approved
-    PM->>PM: Push + close milestone
+    W->>U: 🚦 Push to origin?
+    U->>W: Yes
+    W->>W: git push → milestone done
+
+    W->>W: Next milestone? → loop or done
+
+    Note over PM: PM is free the entire time<br/>Can plan M2 while M1 executes
 ```
 
-### 2. Phase Execution
+### 2. Worker Execution Loop
 
 ```mermaid
 sequenceDiagram
-    participant PM as Product Manager
-    participant W as Worker Agent
-
-    PM->>W: "#backend: implement phase-1"
-    Note over W: Read phase file<br/>Activate backend role<br/>Implement + test<br/>Commit
-    W-->>PM: Result: done, committed abc123
-
-    PM->>W: "#backend: implement phase-2"
-    Note over W: Same session<br/>Full context preserved<br/>Implement + test<br/>Commit
-    W-->>PM: Result: done, committed def456
+    participant W as Worker
 
-    PM->>W: "#frontend: implement phase-3"
-    Note over W: Role switch<br/>Architect + backend context available<br/>Implement + test<br/>Commit
-    W-->>PM: Result: done, committed ghi789
-```
+    W->>W: Scan milestones/
+    Note over W: M1: in-progress<br/>M2: planning<br/>M3: done
 
-### 3. Review Flow
+    W->>W: Resume M1 (read context.md)
+    W->>W: ⚙️ phase-2 (resuming)
+    W->>W: ⚙️ phase-3
+    W->>W: 🔍 review → approved
+    W->>W: Push → M1 done
 
-```mermaid
-sequenceDiagram
-    participant PM as Product Manager
-    participant W as Worker Agent
-    actor U as User
+    W->>W: Start M2
+    W->>W: 🏗️ architect → RFC
+    W->>W: ⚙️ phase-1
+    W->>W: 🔍 review → approved
+    W->>W: Push → M2 done
 
-    PM->>W: "#reviewer: review M1-user-auth"
-    Note over W: git log origin/branch..HEAD<br/>git diff origin/branch...HEAD<br/>Apply review checklist
-
-    alt Approved
-        W-->>PM: verdict: approved
-        PM->>U: Review passed. Push?
-        U->>PM: Yes
-        PM->>PM: git push + close milestone
-    else Changes Requested
-        W-->>PM: verdict: changes-requested + issues
-        PM->>W: "#backend: fix issues in phase-2"
-        W-->>PM: Fixed + committed
-        PM->>U: Fixes applied. Push?
-        U->>PM: Yes
-        PM->>PM: git push + close milestone
-    end
+    W->>W: No more milestones
+    Note over W: "All done. Waiting for new work."
 ```