@sulhadin/orchestrator 3.0.0-beta.10 → 3.0.0-beta.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +11 -10
  2. package/package.json +1 -1
  3. package/template/.orchestra/README.md +20 -18
  4. package/template/.orchestra/config.yml +3 -0
  5. package/template/.orchestra/roles/product-manager.md +43 -11
package/README.md CHANGED
@@ -4,7 +4,7 @@ AI team orchestration for [Claude Code](https://docs.anthropic.com/en/docs/claud
4
4
 
5
5
  ## What is Orchestra?
6
6
 
7
- 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.
7
+ 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.
8
8
 
9
9
  No infrastructure. No API keys. Just markdown files and Claude Code.
10
10
 
@@ -23,9 +23,9 @@ Terminal 1 (PM): Terminal 2 (Conductor):
23
23
  /orchestra pm /orchestra start
24
24
  │ │
25
25
  ├─ Discuss features ├─ Scan milestones
26
- ├─ Create milestones ├─ Activate architect → RFC
27
- ├─ Groom phases ├─ Activate backend → code + tests
28
- │ ├─ Activate frontend → UI
26
+ ├─ Create milestones ├─ Delegate to architect → RFC
27
+ ├─ Groom phases ├─ Delegate to backend → code + tests
28
+ │ ├─ Delegate to frontend → UI
29
29
  │ (plan M2 while M1 runs) ├─ Call reviewer → code review
30
30
  │ ├─ Push → milestone done
31
31
  │ └─ Loop → next milestone
@@ -86,7 +86,7 @@ PM challenges scope, creates M1-user-auth with 3 phases
86
86
  │ ├── conductor.md ← Autonomous milestone executor
87
87
  │ └── reviewer.md ← Independent code review
88
88
  ├── skills/*.orchestra.md ← 14 domain checklists
89
- ├── rules/*.orchestra.md ← 8 discipline rules
89
+ ├── rules/*.orchestra.md ← Discipline rules (auto-loaded)
90
90
  └── commands/orchestra/ ← /orchestra commands
91
91
 
92
92
  .orchestra/ ← Project data + config
@@ -101,10 +101,11 @@ PM challenges scope, creates M1-user-auth with 3 phases
101
101
 
102
102
  **Config-driven pipeline** — `.orchestra/config.yml` controls everything: verification commands (customize for Go, Python, Rust), approval gates, thresholds, parallel execution. No hardcoded assumptions.
103
103
 
104
- **Three complexity levels** — PM sets per milestone:
105
- - `quick` → Engineer → Commit → Push (trivial changes)
106
- - `standard` → Engineer → Review → Push (typical features)
107
- - `full` → Architect → Engineer → Review → Push (complex work)
104
+ **Four complexity levels with model tiering** — PM sets per phase:
105
+ - `trivial` (haiku) → Config changes, version bumps
106
+ - `quick` (sonnet) → Single-file fixes, simple CRUD
107
+ - `standard` (sonnet) → Typical features (default)
108
+ - `complex` (opus) → New subsystems, architectural changes
108
109
 
109
110
  **Verification gate** — Tests + lint must pass before every commit. Commands come from config. Fails 3 times → phase marked failed, escalated to user.
110
111
 
@@ -135,7 +136,7 @@ Smart merge on upgrade:
135
136
  | Blueprints (your custom) | Preserved |
136
137
  | milestones/ | Untouched |
137
138
  | knowledge.md | Preserved |
138
- | config.yml | Preserved |
139
+ | config.yml | Smart merged (user values preserved, new keys added) |
139
140
 
140
141
  ## Documentation
141
142
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sulhadin/orchestrator",
3
- "version": "3.0.0-beta.10",
3
+ "version": "3.0.0-beta.11",
4
4
  "description": "AI Team Orchestration System — multi-role coordination for Claude Code",
5
5
  "bin": "bin/index.js",
6
6
  "scripts": {
package/template/.orchestra/README.md CHANGED
@@ -10,10 +10,10 @@ Terminal 1 (PM): Terminal 2 (Conductor):
10
10
  /orchestra pm /orchestra start
11
11
  │ │
12
12
  ├─ Discuss features with user ├─ Scan milestones
13
- ├─ Create milestones ├─ 🏗️ architect → RFC
13
+ ├─ Create milestones ├─ 🏗️ delegate to architect → RFC
14
14
  ├─ Groom phases ├─ 🚦 User approves RFC
15
- ├─ Always available ├─ ⚙️ backend → phase by phase
16
- │ ├─ 🎨 frontend → phase by phase
15
+ ├─ Always available ├─ ⚙️ delegate to backend → phase by phase
16
+ │ ├─ 🎨 delegate to frontend → phase by phase
17
17
  │ (can plan M2 while M1 runs) ├─ 🔍 reviewer → review commits
18
18
  │ ├─ 🚦 User approves push
19
19
  │ ├─ git push → milestone done
@@ -56,8 +56,9 @@ You can plan new milestones while the conductor is executing another one.
56
56
 
57
57
  ### Terminal 2: `/orchestra start` (Execution)
58
58
 
59
- Conductor reads milestones, executes phases autonomously. Activates roles per phase.
60
- Loops to the next milestone when done. Maintains `context.md` for resume capability.
59
+ Conductor reads milestones, delegates each phase to a sub-agent with the right role.
60
+ Sub-agents implement + verify; conductor commits. Loops to next milestone when done.
61
+ Maintains `context.md` for resume capability.
61
62
 
62
63
  ```
63
64
  /orchestra start
@@ -94,19 +95,20 @@ Hotfix (production bugs):
94
95
  ### Milestone Lock
95
96
 
96
97
  Conductor claims a milestone by writing `Locked-By: {timestamp}` to milestone.md before execution.
97
- Other conductors skip locked milestones. Lock expires after 2 hours (stale protection).
98
+ Other conductors skip locked milestones. Lock expires after config.yml `thresholds.milestone_lock_timeout` minutes (default 120).
98
99
 
99
100
  ### Pipeline Modes (Complexity)
100
101
 
101
- PM sets a `Complexity` level on each milestone that determines the pipeline:
102
+ PM sets `Complexity` on milestone (pipeline) and `complexity` on each phase (model selection):
102
103
 
103
- | Complexity | Pipeline | Use when |
104
- |------------|----------|----------|
105
- | `quick` | Engineer → Commit → Push | Config tweaks, copy changes, trivial fixes |
106
- | `standard` | Engineer → Review → Push | Typical features, clear requirements |
107
- | `full` | Architect → Engineer → Review → Push | Complex features, new subsystems |
104
+ | Complexity | Model | Pipeline | Use when |
105
+ |------------|-------|----------|----------|
106
+ | `trivial` | Haiku | Phases → Commit → Push | Version bumps, env vars, config changes |
107
+ | `quick` | Sonnet | Phases → Commit → Push (skip review) | Single-file fixes, simple CRUD |
108
+ | `standard` | Sonnet | Phases → Review → Push | Typical features, clear requirements |
109
+ | `complex` | Opus | Architect → Phases → Review → Push | New subsystems, unfamiliar territory |
108
110
 
109
- Default is `full` if not specified. Conductor reads the `Complexity` field from `milestone.md`.
111
+ Defaults: config.yml `pipeline.default_pipeline` and `pipeline.default_complexity`.
110
112
 
111
113
  ### Milestone Statuses
112
114
 
@@ -142,8 +144,8 @@ Within each domain (backend/frontend), phases run in order: phase-1 → phase-2
142
144
  **Parallel execution:** If PM sets `depends_on` in phase frontmatter, independent phases
143
145
  can run in parallel via subagent worktree isolation. No `depends_on` = sequential (default).
144
146
 
145
- **Verification Gate:** Before every commit, conductor MUST pass type check + tests + lint
146
- (commands from config.yml). Commit is blocked until all checks pass.
147
+ **Verification Gate:** Sub-agents run typecheck + tests + lint (from config.yml) before reporting.
148
+ Conductor NEVER commits unless verification passes.
147
149
 
148
150
  ---
149
151
 
@@ -193,7 +195,7 @@ All other transitions are automatic.
193
195
  ### Rejection Handling
194
196
 
195
197
  If the user says **no** at any gate:
196
- - **RFC rejected** → Architect revises based on feedback, re-submits (max 3 rounds)
198
+ - **RFC rejected** → Architect revises based on feedback, re-submits (max config `pipeline.max_rfc_rounds`)
197
199
  - **Push rejected** → Conductor creates fix phase, implements, re-submits push gate
198
200
  - **Milestone rejected** → PM revises in PM terminal
199
201
 
@@ -217,8 +219,8 @@ Conductor calls reviewer agent
217
219
 
218
220
  **If approved-with-comments** → proceed to push gate. Comments are logged in context.md.
219
221
 
220
- **If changes-requested** → Conductor switches to the relevant role, fixes
221
- and commits. Re-review triggered if fix >= config `re_review_lines` threshold.
222
+ **If changes-requested** → Conductor continues the phase's sub-agent via SendMessage with
223
+ reviewer findings. Re-review triggered if fix >= config `re_review_lines` threshold.
222
224
 
223
225
  ---
224
226
 
package/template/.orchestra/config.yml CHANGED
@@ -34,6 +34,9 @@ pipeline:
34
34
  # Max RFC rejection rounds before escalating to user
35
35
  max_rfc_rounds: 3
36
36
 
37
+ # Max milestone review rounds before proceeding anyway with warnings
38
+ max_milestone_review_rounds: 3
39
+
37
40
  thresholds:
38
41
  # Milestone lock timeout in minutes (stale locks are ignored)
39
42
  milestone_lock_timeout: 120
package/template/.orchestra/roles/product-manager.md CHANGED
@@ -42,13 +42,44 @@ Cannot write: feature code, RFCs, architecture docs, review findings, system fil
42
42
  └── phase-2.md
43
43
  ```
44
44
 
45
- ### Pre-flight Checklist
45
+ ### Milestone Review Loop
46
46
 
47
+ After creating milestone files, launch a milestone-reviewer sub-agent before
48
+ marking the milestone as ready. This catches planning errors before conductor executes.
49
+
50
+ **Flow:** PM creates → reviewer sub-agent → PM fixes → reviewer again → max `pipeline.max_milestone_review_rounds`
51
+
52
+ Launch sub-agent (general-purpose, model: sonnet) with this prompt:
53
+
54
+ ```
55
+ You are reviewing a milestone for quality before execution. Read these files
56
+ in {milestone_path}/: prd.md, milestone.md, grooming.md, and all files in phases/.
57
+ (rfc.md and context.md don't exist yet — don't flag them as missing.)
58
+
59
+ ## Checklist
47
60
  1. Every phase has `role:` set?
48
- 2. Every phase has `skills:` reviewed?
49
- 3. Every phase has clear, testable acceptance criteria?
50
- 4. `milestone.md` has `Complexity:` set?
51
- 5. Phase order and dependencies correct?
61
+ 2. Every phase has `complexity:` set?
62
+ 3. Every phase has `skills:` appropriate for the role and task?
63
+ 4. Every phase has `scope:` defining which files/dirs to touch?
64
+ 5. Acceptance criteria are testable? (not vague like "works well" — specific like "returns 200")
65
+ 6. `milestone.md` has `Complexity:` set?
66
+ 7. Phase order and `depends_on` are correct? (frontend depends on backend, etc.)
67
+ 8. No overlapping scope between phases? (two phases writing same files)
68
+ 9. PRD explains WHY, not just WHAT?
69
+
70
+ ## Return Format
71
+ verdict: approved | changes-requested
72
+ issues:
73
+ - [severity: blocking|suggestion] {description} — {file}
74
+ summary: {2-3 sentences}
75
+ ```
76
+
77
+ **Process:**
78
+ 1. If **approved** → proceed, milestone is ready for conductor
79
+ 2. If **changes-requested** → PM reads issues, fixes milestone files, re-launches reviewer
80
+ 3. After max rounds with no blocking issues → proceed with suggestions logged in grooming.md
81
+ 4. After max rounds with blocking issues still open → escalate to user, do NOT proceed
82
+ 5. Present verdict to user before finalizing
52
83
 
53
84
  ### milestone.md Format
54
85
 
@@ -59,7 +90,7 @@ Cannot write: feature code, RFCs, architecture docs, review findings, system fil
59
90
  |-------|-------|
60
91
  | Status | planning / in-progress / review / done |
61
92
  | Priority | P0 / P1 / P2 |
62
- | Complexity | quick / standard / full |
93
+ | Complexity | trivial / quick / standard / complex |
63
94
  | PRD | prd.md |
64
95
  | Created | {date} |
65
96
  ```
@@ -85,11 +116,12 @@ depends_on: []
85
116
 
86
117
  ### Complexity Levels
87
118
 
88
- | Level | Pipeline | When |
89
- |-------|----------|------|
90
- | `quick` | Engineer → Commit → Push | Trivial: config, copy, single-file fix |
91
- | `standard` | Engineer → Review → Push | Typical features, clear requirements |
92
- | `full` | Architect → Engineer → Review → Push | Complex: new subsystems, unfamiliar territory |
119
+ | Level | Model | Pipeline | When |
120
+ |-------|-------|----------|------|
121
+ | `trivial` | Haiku | Phases → Commit → Push | Version bumps, env vars, config changes |
122
+ | `quick` | Sonnet | Phases → Commit → Push (skip review) | Single-file fixes, simple CRUD |
123
+ | `standard` | Sonnet | Phases → Review → Push | Typical features (default) |
124
+ | `complex` | Opus | Architect → Phases → Review → Push | New subsystems, unfamiliar territory |
93
125
 
94
126
  ### Blueprint Command
95
127