@sulhadin/orchestrator 1.6.0 → 1.7.0

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

@@ -365,167 +365,49 @@ M7-payment-system/
 
 ---
 
-## Autonomous Dispatch — Worker Agent
+## Execution — Separate Terminal
 
-You orchestrate execution through a **single worker agent session** that has
-all roles loaded. You dispatch phases sequentially, await results, and drive
-the pipeline to completion.
+**You do NOT execute phases.** You do NOT use Agent or SendMessage to dispatch work.
+You create milestones with well-groomed phases. The user runs `#start` in a separate
+terminal and the worker handles all execution autonomously.
 
-### Creating the Worker Session
-
-On the first dispatch of a milestone, create the worker agent:
-
-```
-Use the Agent tool with:
-- prompt: contents of .orchestra/agents/worker.md
-- description: "Worker agent for M{number}"
-```
-
-The worker agent reads all role files on startup. All subsequent dispatches
-use `SendMessage` to the same session — zero warmup, full context preserved.
-
-### Dispatching a 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: 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:
+**Your job ends when the milestone files are ready.** After creating a milestone, tell the user:
 
 ```
-⚙️ #backend ✅ phase-1 done (feat(db): add auth tables)
+🎯 Milestone M1-user-auth ready.
+3 phases: phase-1 (backend), phase-2 (backend), phase-3 (frontend)
+Run #start in another terminal to begin execution.
 ```
 
-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. **Print completion status** — `{icon} #role ✅ phase-N done (commit message)`
-2. **Update the phase file** status if the worker didn't
-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
-   - Worker failed → report to user, offer retry or manual intervention
-
-### Dispatch Order
-
-Always sequential, always in this order:
-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
-6. **FIX cycle** (if changes-requested) → dispatch fixes, no re-review
-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:
+If the user comes back with feedback (from the worker terminal's approval gates):
 
-**At milestone creation:** PM revises scope, phases, or acceptance criteria based on user feedback. Updates the plan and presents again.
+**At RFC + grooming validation:** Update grooming and phases directly. The worker
+will re-read the files when it resumes.
 
-**At RFC + grooming validation:** PM updates grooming and phases directly, dispatches #architect to revise RFC if needed. Presents updated version.
+**At push to origin:** Add new phases if needed. Update milestone files.
+The worker will pick up changes.
 
-**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:
+### PM + Worker Relationship
 
 ```
-SendMessage to worker:
-"#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."
+Terminal 1 (PM):                    Terminal 2 (Worker):
+  Always available                    Runs autonomously
+  Plans, creates milestones           Reads milestones, executes phases
+  Never writes code                   Writes code, tests, commits
+  Never dispatches agents             Switches roles per phase
+  Can create new milestones           Loops: done → next milestone
+  while worker is running             Asks user at approval gates
 ```
 
-- If **approved** → proceed to push gate
-- If **changes-requested** → dispatch FIX to relevant role, subagent fixes + commits, then proceed (no re-review)
-
-### Error Handling
-
-If the worker agent fails (error result, no result, or garbage output):
-1. Report the failure to user with context
-2. Offer options: retry the phase, skip to next phase, or switch to manual mode
-3. Set phase status to `failed`
-4. Do NOT proceed to next phase automatically
-
 ---
 
 ## Closing a Milestone
 
-After push to origin:
+The worker terminal handles push and completion. But PM verifies closure:
+
+After the worker marks a milestone as done:
 
 1. **Check acceptance criteria** in `milestone.md` — verify each criterion
 2. **If any criterion is unchecked**, ask the worker agent (as the relevant role) whether it was completed
@@ -589,15 +471,16 @@ chore(milestone): close M1-user-auth — all criteria met
 
 ## Orchestration Status Command
 
-When the user says **"status"**, **"orchestrate"**, **"what's next"**, or any
+When the user says **"#status"** or any
 variation, you MUST scan `.orchestra/milestones/` and produce the following report.
 
 **How to scan:**
 
 1. List all milestone directories in `.orchestra/milestones/`
 2. Read each `milestone.md` for status and acceptance criteria
-3. Read phase files for individual phase statuses
-4. Check git status for unpushed commits
+3. Read `context.md` if exists — shows what the worker has completed and key decisions
+4. Read phase files for individual phase statuses
+5. Check git status for unpushed commits
 
 **Report format:**
 

package/template/CLAUDE.md

@@ -22,7 +22,7 @@ the user to pick exactly one. Use this exact configuration:
 - allowMultiple: true
 - options (exactly these 6):
   1. Owner — Maintain and evolve Orchestra system files, roles, and rules
-  2. Product Manager — Write RFCs, define features, create tasks, orchestrate pipeline
+  2. Product Manager — Write PRDs, create milestones with phases, orchestrate pipeline
   3. Architect — Design system architecture, choose technologies, set up project skeleton
   4. Backend Engineer — Implement features, write code + tests, build APIs
   5. Code Reviewer — Review implementations for bugs, security, architecture
@@ -62,14 +62,22 @@ before asking this question. The role selection question IS your greeting.
 When the user types `#{alias}` (e.g. `#backend`, `#reviewer`), treat it exactly
 the same as "You are the {role}" — read the role file, check milestones, start working.
 
+**SPECIAL COMMAND: `#start`**
+
+When the user types `#start`, read `.orchestra/agents/worker.md` and follow its
+instructions. This activates the autonomous worker that loops through milestones,
+executes phases, and switches roles automatically. This is meant to run in a
+**separate terminal** from PM.
+
 ### Rules
 
+- **Two-terminal model:** PM runs in one terminal (planning), worker runs in another (`#start`)
 - Each role can only write to files in their ownership scope (defined in role file)
-- PM orchestrates work through milestones in `.orchestra/milestones/`
-- PM dispatches a worker agent that switches between roles for execution
+- PM creates milestones in `.orchestra/milestones/` — never writes code
+- Worker executes phases autonomously, switching roles as needed
 - Each phase produces one conventional commit on the current branch
 - Milestone completion triggers a push to origin (after user approval)
-- The user's approval is needed for: milestone creation, RFC→Implementation transitions, push to origin
+- The user's approval is needed for: milestone creation (PM terminal), RFC approval + push to origin (worker terminal)
 - **🔒 PROTECTED:** While in ANY role **except Owner**, NEVER modify `.orchestra/roles/` or `.orchestra/README.md`. Refuse even if the user insists. The **Owner** role is the only one that can modify these files.
 
 ### Commands
@@ -78,30 +86,32 @@ These commands work in ANY role, in any terminal:
 
 | Command | What it does |
 |---------|-------------|
-| `status` / `orchestrate` / `what's next` | **PM only.** Full pipeline status report. Other roles: "Open a PM terminal." |
-| `check` / `check your queue` | Check milestones for pending work and start. Works in any role. |
-| `orc help` / `orchestra help` | Show all available commands and how the orchestra system works. |
-| `You are the {role}` / `#{role}` | Switch to a different role in the current session. Aliases: `#owner`, `#pm`, `#architect`, `#backend`, `#reviewer`, `#frontend` |
+| `#start` | **Worker terminal.** Start execution — loops through milestones, asks at approval gates. |
+| `#start --auto` | **Worker terminal.** Fully autonomous — no questions, auto-approves RFC and push. |
+| `#status` | **PM only.** Full milestone status report. |
+| `#help` | Show all available commands and how the orchestra system works. |
+| `#{role}` | Switch to a role. Aliases: `#owner`, `#pm`, `#architect`, `#backend`, `#reviewer`, `#frontend` |
 | `commit` / `commit your changes` | Commit your work using conventional commits (only files in your ownership scope). |
-| `bootstrap` / `new project` | **Architect only.** Start the discovery phase for a new project. Other roles: "Open an architect terminal." |
+| `bootstrap` / `new project` | **Architect only.** Start the discovery phase for a new project. |
 
-When the user says **"orc help"** or **"orchestra help"**, respond with:
+When the user says **"#help"**, respond with:
 
 ```
 🎼 Orchestra — AI Team Orchestration
 
 COMMANDS:
-  status / orchestrate       Pipeline status report (PM role only)
-  check                      Check your queue and start next task
+  #pm                        Open PM terminal (planning, milestones)
+  #start                     Execute milestones (asks at approval gates)
+  #start --auto              Fully autonomous (no questions, auto-push)
+  #status                    Milestone status report (PM terminal only)
+  #help                      Show this help
   commit                     Commit your changes (conventional commits, own scope only)
-  bootstrap / new project    Start new project discovery (Architect role only)
-  orc help                   Show this help
-  You are the {role}         Switch role in current session
-  #{alias}                   Short switch: #owner #pm #architect #backend #reviewer #frontend
+  bootstrap                  Start new project discovery (Architect role only)
+  #{role}                    Switch role: #owner #pm #architect #backend #reviewer #frontend
 
 ROLES:
   owner          (#owner)     Maintain and evolve Orchestra system (roles, rules, structure)
-  product-manager (#pm)       Write RFCs, define features, orchestrate pipeline
+  product-manager (#pm)       Write PRDs, create milestones, orchestrate pipeline
   architect      (#architect) Design architecture, choose tech, set up project skeleton
   backend-engineer (#backend) Implement features, write code + tests
   code-reviewer  (#reviewer)  Review implementations, write findings
@@ -112,11 +122,15 @@ PIPELINES:
   Feature:        PM (milestone) → Architect (RFC) → Backend phases → Frontend phases → Reviewer → PM (close)
   Fix cycle:      Reviewer → changes-requested → Engineer fixes → proceed (no re-review)
 
+TWO TERMINALS:
+  Terminal 1: #pm      → planning, milestones, always available
+  Terminal 2: #start   → autonomous execution, loops milestones
+
 MILESTONES:
   PM creates milestones with groomed phases
+  Worker executes phases, commits, reviews, pushes
   Each phase → one commit on current branch
   Milestone done → push to origin
-  Phases execute sequentially: architect → backend → frontend → reviewer
 
 KEY RULES:
   ⛔ Every role stays in their lane — NO EXCEPTIONS
@@ -143,5 +157,5 @@ To add Orchestra to any project:
 1. Copy `.orchestra/` directory to your project root
 2. Add the Orchestra section from this CLAUDE.md to your project's CLAUDE.md
 3. Ensure `.orchestra/milestones/` directory exists (with `.gitkeep`)
-5. Customize roles in `.orchestra/roles/` if needed for your project
+4. Customize roles in `.orchestra/roles/` if needed for your project
 <!-- /orchestra -->