@sulhadin/orchestrator 3.0.0-beta.3 → 3.0.0-beta.5

package/README.md

@@ -1,6 +1,12 @@
 # Orchestra
 
-AI team orchestration for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Two terminals — PM plans, conductor builds.
+AI team orchestration for [Claude Code](https://docs.anthropic.com/en/docs/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 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.
+
+No infrastructure. No API keys. Just markdown files and Claude Code.
 
 ## Install
 
@@ -8,79 +14,139 @@ AI team orchestration for [Claude Code](https://docs.anthropic.com/en/docs/claud
 npx @sulhadin/orchestrator
 ```
 
-## Two Terminals
-
-### Terminal 1: `/orchestra pm` — Planning
+This installs `.orchestra/` (project data + config) and `.claude/` (agents, skills, rules, commands) into your project.
 
-PM is your strategic partner. Discuss ideas, challenge scope, create milestones.
+## How It Works
 
 ```
-You: /orchestra pm
-PM:  "No active milestones. What's on your mind?"
-
-You: "I want user authentication with JWT"
-PM:  *discusses, challenges, creates milestone with phases*
+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
+  │  (plan M2 while M1 runs)          ├─ Call reviewer → code review
+  │                                   ├─ Push → milestone done
+  │                                   └─ Loop → next milestone
 ```
 
-### Terminal 2: `/orchestra start` — Execution
-
-Conductor picks up milestones and executes them autonomously.
+## Quick Example
 
+**Terminal 1:**
+```
+/orchestra pm
+> "I want user authentication with JWT"
+PM challenges scope, creates M1-user-auth with 3 phases
 ```
-You: /orchestra start
 
+**Terminal 2:**
+```
+/orchestra start
 📋 Starting M1-user-auth
-🏗️ architect ▶ RFC...         ✅ done
-⚙️ backend ▶ DB schema...     ✅ done
-⚙️ backend ▶ API endpoints... ✅ done
-🎨 frontend ▶ Login UI...     ✅ done
-🔍 reviewer ▶ reviewing...    ✅ approved
+🏗️ architect → RFC ready → user approves
+⚙️ backend → phase-1: DB schema → committed
+⚙️ backend → phase-2: API endpoints → committed
+🎨 frontend → phase-3: Login UI → committed
+🔍 reviewer → approved
 🚦 Push? → yes
-✅ M1-user-auth done.
-
-📋 Starting M2-dashboard...
+✅ M1-user-auth done. Checking for next milestone...
 ```
 
 ## Commands
 
+### Pipeline
 | Command | What it does |
 |---------|-------------|
-| `/orchestra pm` | Plan features, create milestones |
-| `/orchestra start` | Execute milestones (asks at approval gates) |
-| `/orchestra start --auto` | Fully autonomous |
+| `/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 |
+| `/orchestra status` | Milestone status report (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 backend` | Backend Engineer — code + tests |
+| `/orchestra frontend` | Frontend Engineer — UI + design |
+| `/orchestra architect` | Architect — technical design |
+| `/orchestra adaptive` | Adaptive expert — any domain (iOS, DevOps, ML...) |
+| `/orchestra orchestrator` | System maintenance |
+
 ## Architecture
 
 ```
-.claude/                              ← Claude Code integration
-├── agents/conductor.md               ← Autonomous executor
-├── agents/reviewer.md                ← Independent code review
-├── skills/*.orchestra.md             ← 14 domain checklists
-├── rules/*.orchestra.md              ← Discipline rules
-└── commands/orchestra/               ← /orchestra commands
-
-.orchestra/                           ← Project data + config
-├── config.yml                        ← Pipeline settings (customize per stack)
-├── roles/                            ← Role identities (slim)
-├── blueprints/                       ← Project templates
-├── knowledge.md                      ← Project knowledge log
-└── milestones/                       ← Your work
+.claude/                                ← Claude Code integration
+├── agents/
+│   ├── conductor.md                    ← Autonomous milestone executor
+│   └── reviewer.md                     ← Independent code review
+├── skills/*.orchestra.md               ← 14 domain checklists
+├── rules/*.orchestra.md                ← 8 discipline rules
+└── commands/orchestra/                 ← /orchestra commands
+
+.orchestra/                             ← Project data + config
+├── config.yml                          ← Pipeline settings (customize per stack)
+├── roles/                              ← Role identities
+├── blueprints/                         ← Project templates
+├── knowledge.md                        ← Project knowledge log
+└── 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.
+
+**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)
+
+**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, conductor 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.
+
+**Learning system** — `knowledge.md` accumulates decisions and lessons. 5-line retrospective after each milestone. PM reads before grooming new work. System gets smarter over time.
+
+**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.
+
+**Stuck detection** — Detects repeated failures, circular fixes, over-engineering. Tries different approach once, then escalates. Auto mode skips to next phase.
+
+## Upgrading
+
+```bash
+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 |
+| knowledge.md | Preserved |
+| config.yml | Preserved |
+
 ## Documentation
 
-See [docs/](https://github.com/sulhadin/orchestrator/blob/main/docs/README.md) for full documentation:
+Full docs at [docs/](https://github.com/sulhadin/orchestrator/blob/main/docs/README.md):
 
-- [Getting Started](https://github.com/sulhadin/orchestrator/blob/main/docs/getting-started.md)
-- [Commands](https://github.com/sulhadin/orchestrator/blob/main/docs/commands.md)
-- [Roles](https://github.com/sulhadin/orchestrator/blob/main/docs/roles.md)
-- [Features](https://github.com/sulhadin/orchestrator/blob/main/docs/features.md)
-- [Blueprints](https://github.com/sulhadin/orchestrator/blob/main/docs/blueprints.md)
-- [Skills](https://github.com/sulhadin/orchestrator/blob/main/docs/skills.md)
+- [Getting Started](https://github.com/sulhadin/orchestrator/blob/main/docs/getting-started.md) — installation, first milestone, two-terminal model
+- [Commands](https://github.com/sulhadin/orchestrator/blob/main/docs/commands.md) — all commands with examples
+- [Roles](https://github.com/sulhadin/orchestrator/blob/main/docs/roles.md) — 6 roles + adaptive, responsibilities, boundaries
+- [Features](https://github.com/sulhadin/orchestrator/blob/main/docs/features.md) — config, verification, skills, blueprints, and more
+- [Blueprints](https://github.com/sulhadin/orchestrator/blob/main/docs/blueprints.md) — project templates, customization
+- [Skills](https://github.com/sulhadin/orchestrator/blob/main/docs/skills.md) — domain checklists, creating new skills
 
 ## License
 

package/bin/index.js

@@ -71,6 +71,10 @@ function copyDirRecursive(src, dest) {
     const destPath = path.join(dest, entry.name);
     if (entry.isDirectory()) {
       copyDirRecursive(srcPath, destPath);
+    } else if (entry.isSymbolicLink()) {
+      const linkTarget = fs.readlinkSync(srcPath);
+      if (fs.existsSync(destPath)) fs.unlinkSync(destPath);
+      fs.symlinkSync(linkTarget, destPath);
     } else {
       fs.copyFileSync(srcPath, destPath);
     }

package/package.json

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

package/template/.claude/commands/orchestra/adaptive.md

@@ -0,0 +1,7 @@
+Activate the Adaptive role.
+
+1. Read `.orchestra/roles/adaptive.md` for role identity and ownership.
+2. Read `.orchestra/config.yml` for pipeline settings.
+3. Check `.orchestra/milestones/` for phases with `role: adaptive`.
+4. If pending phases exist, announce and start working.
+5. If no pending phases, report ready and wait for instructions.

package/template/.claude/commands/orchestra/architect.md

@@ -0,0 +1,7 @@
+Activate the Architect role.
+
+1. Read `.orchestra/roles/architect.md` for role identity and ownership.
+2. Read `.orchestra/config.yml` for pipeline settings.
+3. Check `.orchestra/milestones/` for phases with `role: architect`.
+4. If pending phases exist, announce and start working.
+5. If no pending phases, report ready and wait for instructions.

package/template/.claude/commands/orchestra/backend.md

@@ -0,0 +1,7 @@
+Activate the Backend Engineer role.
+
+1. Read `.orchestra/roles/backend-engineer.md` for role identity and ownership.
+2. Read `.orchestra/config.yml` for pipeline settings.
+3. Check `.orchestra/milestones/` for phases with `role: backend-engineer`.
+4. If pending phases exist, announce and start working.
+5. If no pending phases, report ready and wait for instructions.

package/template/.claude/commands/orchestra/frontend.md

@@ -0,0 +1,7 @@
+Activate the Frontend Engineer role.
+
+1. Read `.orchestra/roles/frontend-engineer.md` for role identity and ownership.
+2. Read `.orchestra/config.yml` for pipeline settings.
+3. Check `.orchestra/milestones/` for phases with `role: frontend-engineer`.
+4. If pending phases exist, announce and start working.
+5. If no pending phases, report ready and wait for instructions.

package/template/.claude/commands/orchestra/help.md

@@ -16,13 +16,13 @@ COMMANDS:
   /orchestra blueprint add   Save current work as blueprint (PM only)
   /orchestra create-role     Create a new role with interactive discovery (Orchestrator only)
 
-ROLES:
-  orchestrator                     Maintain and evolve Orchestra system
-  product-manager                  Write PRDs, create milestones, orchestrate pipeline
-  architect                        Design architecture, choose tech
-  backend-engineer                 Implement backend code + tests
-  frontend-engineer                Design + build UI, write frontend tests
-  adaptive                         Adaptive expert — domain defined per phase
+ROLES (activate via /orchestra {role}):
+  /orchestra orchestrator    Maintain and evolve Orchestra system
+  /orchestra pm              Plan features, create milestones
+  /orchestra architect       Design architecture, choose tech
+  /orchestra backend         Implement backend code + tests
+  /orchestra frontend        Design + build UI, write frontend tests
+  /orchestra adaptive        Adaptive expert — domain defined per phase
 
 AGENTS:
   conductor                        Autonomous milestone executor (/orchestra start)

package/template/.claude/commands/orchestra/orchestrator.md

@@ -0,0 +1,5 @@
+Activate the Orchestrator role — system guardian.
+
+1. Read `.orchestra/roles/orchestrator.md` for role identity and ownership.
+2. Read `.orchestra/config.yml` for current settings.
+3. Report: "Orchestrator active. What would you like to change?"

package/template/.orchestra/README.md

@@ -234,6 +234,7 @@ No role may create, edit, delete, or modify these files:
 - `.orchestra/README.md`
 - `.orchestra/roles/*.md`
 - `.orchestra/config.yml`
+- `.orchestra/blueprints/`
 - `.claude/agents/conductor.md`, `.claude/agents/reviewer.md`
 - `.claude/rules/*.orchestra.md`
 - `.claude/skills/*.orchestra.md`

package/template/CLAUDE.md

@@ -66,7 +66,10 @@ Do NOT greet the user. Do NOT explain the project. The role selection IS your gr
 | `/orchestra blueprint add` | Save current work as blueprint (PM only) |
 | `/orchestra create-role` | Create a new role with interactive discovery (Orchestrator only) |
 
-When the user types "You are the {role}" — read the role file, check milestones, start working.
+When the user types `/orchestra {role}` (e.g. `/orchestra backend`, `/orchestra pm`), the
+corresponding command file activates that role. Do NOT switch roles based on free text
+like "be the backend engineer" or "you are the architect" — roles are activated ONLY
+via `/orchestra {role}` commands.
 
 When the user types `/orchestra start`, read `.claude/agents/conductor.md` and follow its
 instructions. This is meant to run in a **separate terminal** from PM.