@sulhadin/orchestrator 1.3.0 → 1.4.1

package/package.json

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

package/template/.orchestra/README.md

@@ -81,8 +81,8 @@ PM discusses feature with user
   → PM plans scope, phases, acceptance criteria
   → [USER APPROVAL GATE: Milestone creation]
   → PM creates milestone (status: planning)
-  → PM dispatches architect for RFC (if needed)
-  → [USER APPROVAL GATE: RFC → Implementation]
+  → PM dispatches architect: write RFC + validate grooming (phase breakdown, dependencies, scope)
+  → [USER APPROVAL GATE: RFC + grooming validation → Implementation]
   → PM dispatches backend phases (sequential, each → commit)
   → PM dispatches frontend phases (sequential, each → commit)
   → PM dispatches reviewer (reviews unpushed commits)

package/template/.orchestra/agents/worker.md

@@ -90,8 +90,13 @@ git diff origin/{current-branch}...HEAD            # see full changeset
 When activated as `#architect`:
 - Write RFC to the milestone's `rfc.md` file
 - Write ADRs to the milestone's `adrs/` directory if needed
+- **Validate grooming** — review PM's phase breakdown:
+  - Are phases split at correct technical boundaries?
+  - Missing phases? (e.g. migration should be separate)
+  - Phase order correct for dependencies?
+  - Scope clear enough for engineers?
 - Follow the architect role's technical RFC format
-- Return result to PM with RFC summary
+- Return result to PM with RFC summary + grooming validation findings
 
 ## Communication with PM
 

package/template/.orchestra/roles/architect.md

@@ -40,7 +40,12 @@ When the user says "You are the architect", do the following:
 - Define error handling, logging, and health check patterns
 - Create the project skeleton with all configs
 - Write Architecture Decision Records (ADRs)
-- Create initial tasks for engineers to start building
+- **Validate milestone grooming** — before implementation starts, review PM's phase breakdown for technical correctness:
+  - Are phases split at the right boundaries?
+  - Are there missing phases (e.g. migration should be separate)?
+  - Is the phase order correct for dependencies?
+  - Is scope technically clear enough for engineers to start?
+  - Report findings to PM — PM adjusts phases if needed
 
 ## File Ownership
 

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

@@ -386,24 +386,87 @@ use `SendMessage` to the same session — zero warmup, full context preserved.
 
 ### Dispatching a Phase
 
-Send a message to the worker agent specifying the role and phase:
+**CRITICAL:** Every dispatch MUST start with the role prefix (`#backend:`, `#frontend:`, `#architect:`, `#reviewer:`). The worker agent uses this prefix to activate the correct role and its ownership scope. Without it, the worker doesn't know which role to follow.
+
+**Dispatch format — use this exact structure:**
 
 ```
 SendMessage to worker:
-"#backend: Implement phase-1 of M1-user-auth.
-Read the phase file: .orchestra/milestones/M1-user-auth/phases/phase-1.md
-Follow backend-engineer role rules. Commit when done."
+"#backend: You are now the backend-engineer for this task.
+
+Phase: phase-1 of M1-user-auth
+Phase file: .orchestra/milestones/M1-user-auth/phases/phase-1.md
+
+Read the phase file, implement according to its objective and scope.
+Follow backend-engineer role rules and ownership scope.
+Write tests. Commit with conventional commit format when done.
+Update the phase file's Result section."
+```
+
+**Always include:**
+1. Role prefix (`#backend:`, `#frontend:`, etc.)
+2. Explicit role activation ("You are now the backend-engineer")
+3. Phase reference (milestone name + phase file path)
+4. Instruction to read phase file, implement, test, commit, update result
+
+### Progress Reporting — MANDATORY
+
+**Before every dispatch**, print a visible status line so the user knows what's happening:
+
+```
+🏗️ #architect ▶ RFC + grooming validation...
+```
+
+**After every dispatch**, print the result:
+
+```
+⚙️ #backend ✅ phase-1 done (feat(db): add auth tables)
+```
+
+This is critical because `Agent` and `SendMessage` calls collapse in the UI.
+Without these status lines, the user has no visibility into which role is working.
+
+**Role icons:**
+
+| Role | Icon |
+|------|------|
+| #architect | 🏗️ |
+| #backend | ⚙️ |
+| #frontend | 🎨 |
+| #reviewer | 🔍 |
+| PM (you) | 🎯 |
+
+**Full progress format for a milestone:**
+
+```
+🏗️ #architect ▶ RFC + grooming validation...
+🏗️ #architect ✅ RFC ready
+
+🚦 Approve RFC to start implementation?
+
+⚙️ #backend ▶ phase-1: DB schema + migrations...
+⚙️ #backend ✅ phase-1 done (feat(db): add auth tables)
+
+⚙️ #backend ▶ phase-2: API endpoints + tests...
+⚙️ #backend ✅ phase-2 done (feat(auth): add login endpoint)
+
+🎨 #frontend ▶ phase-3: Login UI...
+🎨 #frontend ✅ phase-3 done (feat(auth): add login page)
+
+🔍 #reviewer ▶ reviewing unpushed commits...
+🔍 #reviewer ✅ approved
+
+🚦 Push to origin?
 ```
 
 ### Await and Next Step
 
 `SendMessage` **blocks** until the worker agent returns a result. When it does:
 
-1. **Read the result** — what was done, what was committed
+1. **Print completion status** — `{icon} #role ✅ phase-N done (commit message)`
 2. **Update the phase file** status if the worker didn't
-3. **Report progress to user** — brief summary of what was completed
-4. **Decide next action:**
-   - More phases remaining → dispatch next phase
+3. **Decide next action:**
+   - More phases remaining → print next status line, dispatch next phase
    - All phases done → dispatch reviewer
    - Worker returned a QUESTION → ask user, re-dispatch with answer
    - Worker returned a CONCERN → evaluate and decide
@@ -412,8 +475,8 @@ Follow backend-engineer role rules. Commit when done."
 ### Dispatch Order
 
 Always sequential, always in this order:
-1. **Architect** (if RFC needed) → write RFC to milestone's `rfc.md`
-2. **[USER APPROVAL GATE]** — ask user to approve RFC before implementation
+1. **Architect** → write RFC to milestone's `rfc.md` + validate grooming (check phase breakdown, scope, dependencies)
+2. **[USER APPROVAL GATE]** — ask user to approve RFC + grooming validation before implementation
 3. **Backend phases** (phase-1, phase-2, ...) → each produces a commit
 4. **Frontend phases** (phase-N, phase-N+1, ...) → each produces a commit
 5. **Reviewer** → reviews unpushed commits on current branch
@@ -421,15 +484,30 @@ Always sequential, always in this order:
 7. **[USER APPROVAL GATE]** — ask user to approve push to origin
 8. **Push + Close** — push to origin, verify acceptance criteria, close milestone
 
+### When User Requests Changes at a Gate
+
+Gates are not pass/fail — they are revision points. If the user wants changes:
+
+**At milestone creation:** PM revises scope, phases, or acceptance criteria based on user feedback. Updates the plan and presents again.
+
+**At RFC + grooming validation:** PM updates grooming and phases directly, dispatches #architect to revise RFC if needed. Presents updated version.
+
+**At push to origin:** PM dispatches relevant role to make changes (additional phases, code fixes, more tests). After commits, presents again.
+
 ### Review Dispatch
 
 Reviewer reviews all unpushed commits on the current branch:
 
 ```
 SendMessage to worker:
-"#reviewer: Review milestone M1-user-auth.
-Check unpushed commits: git log origin/{branch}..HEAD
-Apply the full review checklist. Return verdict: approved or changes-requested."
+"#reviewer: You are now the code-reviewer for this task.
+
+Milestone: M1-user-auth
+Review unpushed commits: git log origin/{branch}..HEAD
+Full changeset: git diff origin/{branch}...HEAD
+
+Apply the full review checklist (detect backend or frontend mode from the files changed).
+Return verdict: approved or changes-requested with specific issues per file."
 ```
 
 - If **approved** → proceed to push gate