@sulhadin/orchestrator 1.13.0 → 1.15.0

package/README.md

@@ -77,7 +77,7 @@ Close the terminal, reopen, type `#start` — it resumes from where it left off.
 | **Fast Track** | `quick/standard/full` pipeline complexity — skip unnecessary steps for simple work |
 | **Verification Gate** | Tests + lint must pass before every commit — broken code can't be committed |
 | **Skills** | Domain checklists (auth, CRUD, deploy) assigned to phases |
-| **Blueprints** | Project templates — `blueprint saas-starter` creates 5 milestones instantly |
+| **Blueprints** | Project templates — `#blueprint saas-starter` creates 5 milestones instantly |
 | **Hotfix** | `#hotfix {desc}` — implement, verify, commit, push in one command |
 | **Learning** | knowledge.md accumulates decisions and lessons across milestones |
 | **Parallel Phases** | Independent phases run simultaneously via `depends_on` |
@@ -96,8 +96,8 @@ Close the terminal, reopen, type `#start` — it resumes from where it left off.
 | `#help` | Any | Show all commands |
 | `#help skills` | Any | List available skills |
 | `#help blueprints` | Any | List available blueprints |
-| `blueprint {name}` | Terminal 1 | Generate milestones from template |
-| `blueprint add` | Terminal 1 | Save current work as reusable template |
+| `#blueprint {name}` | Terminal 1 | Generate milestones from template |
+| `#blueprint add` | Terminal 1 | Save current work as reusable template |
 
 Manual roles (any terminal):
 
@@ -108,6 +108,7 @@ Manual roles (any terminal):
 | `#reviewer` | Code Reviewer |
 | `#architect` | Architect |
 | `#owner` | System maintenance |
+| `#adaptive` | Adaptive expert (iOS, DevOps, ML, etc.) |
 
 ## Documentation
 
@@ -115,9 +116,9 @@ See [docs/](https://github.com/sulhadin/orchestrator/blob/main/docs/README.md) f
 
 - [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, responsibilities, boundaries
+- [Roles](https://github.com/sulhadin/orchestrator/blob/main/docs/roles.md) — 7 roles, responsibilities, boundaries
 - [Features](https://github.com/sulhadin/orchestrator/blob/main/docs/features.md) — verification gate, fast track, parallel, hotfix, and more
-- [Blueprints](https://github.com/sulhadin/orchestrator/blob/main/docs/blueprints.md) — project templates, `blueprint add`
+- [Blueprints](https://github.com/sulhadin/orchestrator/blob/main/docs/blueprints.md) — project templates, `#blueprint add`
 - [Skills](https://github.com/sulhadin/orchestrator/blob/main/docs/skills.md) — domain checklists, creating new skills
 
 ## License

package/package.json

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

package/template/.orchestra/README.md

@@ -30,9 +30,13 @@ Terminal 1 (PM):                    Terminal 2 (Worker):
 │   ├── architect.md
 │   ├── backend-engineer.md
 │   ├── code-reviewer.md
-│   └── frontend-engineer.md
+│   ├── frontend-engineer.md
+│   └── owner.md
 ├── agents/                # Worker agent definitions
 │   └── worker.md          # Multi-role execution agent prompt
+├── skills/                # Domain-specific checklists (auth, CRUD, deploy)
+├── blueprints/            # Project/component milestone templates
+├── knowledge.md           # Append-only project knowledge log
 ├── milestones/            # Feature work (one dir per feature)
 │   └── M1-feature-name/
 │       ├── prd.md         # Product requirements (PM writes)
@@ -90,11 +94,34 @@ PM discusses feature with user
   → Worker executes backend phases (sequential, each → commit)
   → Worker executes frontend phases (sequential, each → commit)
   → Worker activates #reviewer (reviews unpushed commits)
-  → FIX cycle if changes-requested (one round, no re-review)
+  → FIX cycle if changes-requested (re-review if fix >= 30 lines)
   → [USER APPROVAL GATE: Push to origin]
-  → PM pushes, verifies acceptance criteria, closes milestone
+  → Worker pushes, PM verifies acceptance criteria, closes milestone
+  → Worker appends 5-line retrospective to knowledge.md
+
+Hotfix (production bugs):
+  #hotfix {description}
+  → Auto-create milestone + phase → Implement → Verify → Commit → Push
+  → No RFC, no review, no approval gates (except verification)
 ```
 
+### Milestone Lock
+
+Worker claims a milestone by writing `Locked-By: {timestamp}` to milestone.md before execution.
+Other workers skip locked milestones. Lock expires after 2 hours (stale protection).
+
+### Pipeline Modes (Complexity)
+
+PM sets a `Complexity` level on each milestone that determines the pipeline:
+
+| Complexity | Pipeline | Use when |
+|------------|----------|----------|
+| `quick` | Engineer → Commit → Push | Config tweaks, copy changes, trivial fixes |
+| `standard` | Engineer → Review → Push | Typical features, clear requirements |
+| `full` | Architect → Engineer → Review → Push | Complex features, new subsystems |
+
+Default is `full` if not specified. Worker reads the `Complexity` field from `milestone.md`.
+
 ### Milestone Statuses
 
 | Status | Meaning |
@@ -126,6 +153,12 @@ Phases always execute in this order:
 
 Within each domain (backend/frontend), phases run in order: phase-1 → phase-2 → phase-3.
 
+**Parallel execution:** If PM sets `depends_on` in phase frontmatter, independent phases
+can run in parallel via subagent worktree isolation. No `depends_on` = sequential (default).
+
+**Verification Gate:** Before every commit, worker MUST pass type check + tests + lint.
+Commit is blocked until all checks pass (max 3 retries, then phase fails).
+
 ---
 
 ## Git Boundaries
@@ -158,7 +191,7 @@ Rules:
 - Breaking changes add `!` after type
 - Body explains WHY, not WHAT
 - Subject line ≤ 72 characters
-- **No `Co-Authored-By` trailers** — never add co-author lines to commit messages
+- **No `Co-Authored-By` trailers** — NEVER add co-author lines to commit messages. This applies to ALL commits in ALL repositories using Orchestra. No exceptions.
 
 ---
 
@@ -171,6 +204,15 @@ The user must approve before these transitions:
 
 All other transitions are automatic.
 
+### Rejection Handling
+
+If the user says **no** at any gate:
+- **RFC rejected** → Architect revises based on feedback, re-submits (max 3 rounds)
+- **Push rejected** → Worker creates fix phase, implements, re-submits push gate
+- **Milestone rejected** → PM revises in PM terminal
+
+Rejections are normal. The system does not stall — it loops back with feedback.
+
 ---
 
 ## Review Flow (Git-Native)
@@ -182,13 +224,15 @@ Worker activates #reviewer
   → Reviewer runs: git log origin/{branch}..HEAD
   → Reviewer runs: git diff origin/{branch}...HEAD
   → Reviewer applies full checklist (backend or frontend mode)
-  → Returns: approved OR changes-requested (with specific issues)
+  → Returns: approved / approved-with-comments / changes-requested
 ```
 
-**If approved** → PM proceeds to push gate.
+**If approved** → proceed to push gate.
+
+**If approved-with-comments** → proceed to push gate. Comments are logged in context.md for future reference.
 
 **If changes-requested** → Worker switches to the relevant role, fixes
-and commits. Pipeline proceeds — **no re-review** (single review round).
+and commits. Re-review triggered if fix >= 30 lines changed.
 
 ---
 
@@ -244,12 +288,14 @@ Each role has exclusive write access to specific directories:
 
 | Role | Owns (can write) | Reads |
 |------|-------------------|-------|
-| owner | `.orchestra/roles/*`, `.orchestra/README.md`, `CLAUDE.md` | Everything |
+| owner | `.orchestra/roles/*`, `.orchestra/README.md`, `CLAUDE.md`, `.orchestra/agents/*`, `.orchestra/skills/*`, `.orchestra/blueprints/*`, `.orchestra/knowledge.md` | Everything |
 | 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 — never modifies source code | `src/`, `tests/`, `frontend/` |
 | frontend-engineer | `frontend/`, `frontend/**/__tests__/*`, `frontend/**/e2e/*`, `.orchestra/milestones/*/design.md` | `.orchestra/milestones/*/phases/*` |
+| adaptive | Defined by `scope:` field in phase file — dynamic per phase | `.orchestra/milestones/*/phases/*` |
+| worker (all roles) | `.orchestra/milestones/*/context.md`, `.orchestra/knowledge.md` (append only) | Everything in active milestone |
 
 ---
 

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

@@ -11,13 +11,22 @@ Two modes:
 | Command | Behavior |
 |---------|----------|
 | `#start` | Asks user at approval gates (RFC, push) |
-| `#start --auto` | Fully autonomous — no questions, auto-approves everything |
+| `#start --auto` | Fully autonomous — confirms once, then auto-approves all gates |
 
 When the user types `#start` or `#start --auto`:
 
-1. Detect mode: if `--auto` was specified, set **auto mode** (skip all approval gates)
+1. Detect mode: if `--auto` was specified, show a one-time warning before proceeding:
+   ```
+   ⚠️ Auto mode: ALL approval gates will be skipped (RFC, push). Code will be pushed without confirmation.
+   Type "confirm" to proceed, or switch to #start for manual gates.
+   ```
+   Wait for user to type "confirm". Then set **auto mode** (skip all approval gates).
 2. Read `.orchestra/README.md` for orchestration rules
-3. Read all role files in `.orchestra/roles/` (architect, backend, frontend, reviewer)
+3. Do NOT read all role files upfront — only read the role file needed for each phase:
+   - At startup: read NO role files yet (wait until first phase determines the role)
+   - At each phase: read `.orchestra/roles/{role-from-phase}.md` for the active role only
+   - When switching roles between phases: read the new role file, previous role context is no longer needed
+   - Also read `.orchestra/knowledge.md` once at milestone start (if it exists)
 4. Scan `.orchestra/milestones/` for work:
    - Find milestones with `status: in-progress` → resume from last incomplete phase
    - If none, find milestones with `status: planning` → start from the beginning
@@ -26,6 +35,37 @@ When the user types `#start` or `#start --auto`:
 
 ## Execution Loop
 
+### Pipeline Selection — Based on Complexity
+
+Before starting a milestone, read the `Complexity` field from `milestone.md`:
+
+| Complexity | Pipeline | What to skip |
+|------------|----------|-------------|
+| `quick` | Phases → Commit → Push | Skip architect phase, skip review phase |
+| `standard` | Phases → Review → Push | Skip architect phase (unless a phase has `role: architect`) |
+| `full` | Architect → Phases → Review → Push | Nothing skipped — full pipeline |
+
+**Rules:**
+- If `Complexity` is missing, treat as `full` (safe default)
+- `quick` mode still requires Verification Gate (test + lint) before commit
+- `quick` mode still requires push approval gate (unless `--auto`)
+- If a `quick` milestone fails verification, escalate to `standard` automatically:
+  "⚠️ Escalating from quick to standard — verification failed, adding review phase"
+
+### Milestone Lock — Prevent Concurrent Execution
+
+Before starting a milestone, check for concurrent workers:
+
+1. Read `milestone.md` — check for `Locked-By` field
+2. If `Locked-By` exists and timestamp is less than 2 hours old → **skip this milestone**:
+   "⚠️ Skipping {milestone}: locked by another worker since {timestamp}"
+3. If no lock or lock is stale (>2 hours) → **claim it**: add `Locked-By: {timestamp}` to milestone.md
+4. On milestone completion or failure → remove the `Locked-By` field
+
+This prevents two `#start` terminals from executing the same milestone simultaneously.
+
+### Milestone Execution
+
 For each milestone (in order: in-progress first, then planning):
 
 ```
@@ -99,6 +139,7 @@ Role mapping:
 | `#backend` | backend-engineer | ⚙️ |
 | `#frontend` | frontend-engineer | 🎨 |
 | `#reviewer` | code-reviewer | 🔍 |
+| `#adaptive` | adaptive | 🔧 |
 
 ### Active Role Enforcement
 
@@ -110,6 +151,7 @@ You can only write to files owned by the **currently active** role:
 | `#backend` | `src/*`, `tests/*`, `migrations/*`, `package.json`, `tsconfig.json` |
 | `#frontend` | `frontend/*`, `.orchestra/milestones/*/design.md` |
 | `#reviewer` | Review findings only — never modify source code |
+| `#adaptive` | Defined by `scope:` field in phase file — dynamic per phase |
 
 If you need to write outside your active role's scope, **do not do it**. Note it
 as a CONCERN in context.md and continue.
@@ -157,8 +199,35 @@ to update; write incrementally as you work.
 
 ## Concerns
 - (any issues spotted during implementation)
+
+## Cost Tracking
+| Phase | Duration | Verification Retries |
+|-------|----------|---------------------|
+| phase-1 | ~3min | 0 |
+| phase-2 | ~7min | 1 (lint fix) |
 ```
 
+### Learning System — Knowledge Persistence
+
+The file `.orchestra/knowledge.md` is a project-wide, append-only knowledge log.
+
+**Before starting a milestone:**
+- Read ONLY the **Active Knowledge** section of `.orchestra/knowledge.md` (skip Archive)
+- Check for relevant lessons, patterns, or decisions that apply to the current work
+- If a previous lesson says "use X instead of Y" — follow it
+
+**After completing a milestone (before push gate):**
+- Append a new entry to `.orchestra/knowledge.md` with:
+  - Key technical decisions made during this milestone and WHY
+  - Lessons learned (anything harder than expected, any mistakes corrected)
+  - Reusable patterns discovered or established
+- Keep entries concise — 3-5 bullet points per section, skip empty sections
+
+**Rules:**
+- NEVER edit previous entries — append only
+- If a previous entry is wrong, add a correction entry
+- Read knowledge.md at milestone start, write to it at milestone end
+
 ### Resuming from context.md
 
 When `#start` is called and a milestone has `status: in-progress`:
@@ -169,17 +238,105 @@ When `#start` is called and a milestone has `status: in-progress`:
 
 ## Phase Execution
 
-For each phase:
+### Parallel Execution — Based on `depends_on`
+
+Before executing phases sequentially, check if parallel execution is possible:
+
+1. Read all phase files and their `depends_on` frontmatter
+2. Build a dependency graph:
+   - Phase with `depends_on: []` or no `depends_on` field → can run immediately
+   - Phase with `depends_on: [phase-1]` → must wait for phase-1 to complete
+3. Identify independent phases — phases that have no unmet dependencies at the same time
+4. If 2+ phases can run simultaneously:
+   - Launch each independent phase as a **subagent with worktree isolation** (`isolation: "worktree"`)
+   - Each subagent gets its own git worktree — no conflicts
+   - Wait for all parallel phases to complete
+5. **Merge parallel results** back to the main branch (in phase order: phase-2 before phase-3):
+   - Merge one worktree at a time, in ascending phase order
+   - After each merge, run verification gate (tsc + test + lint) to confirm no integration issues
+   - **If merge conflict occurs:**
+     - Conflicts in different files → auto-resolve (accept both changes)
+     - Conflicts in same file → STOP, report to user with both versions, ask which to keep
+     - In `--auto` mode: attempt auto-resolve. If same-file conflict → set both phases to `failed`, log details, move on
+   - **If verification fails after merge** → the last merged phase likely broke integration. Revert that merge, set its phase to `failed`, continue with remaining phases
+6. Continue with the next group of phases whose dependencies are now met
+
+**Example:**
+```
+phase-1 (backend: DB migration)     depends_on: []
+phase-2 (backend: Auth endpoints)   depends_on: [phase-1]
+phase-3 (backend: User endpoints)   depends_on: [phase-1]
+phase-4 (frontend: Auth UI)         depends_on: [phase-2]
+phase-5 (frontend: User UI)         depends_on: [phase-3]
+
+Execution:
+  Round 1: phase-1 (sequential — only one ready)
+  Round 2: phase-2 + phase-3 (parallel — both depend only on phase-1 which is done)
+  Round 3: phase-4 + phase-5 (parallel — each dependency is met)
+```
+
+**Rules:**
+- If NO `depends_on` fields exist in any phase → fall back to sequential order (backward compatible)
+- Parallel execution requires `depends_on` to be explicitly set by PM
+- Each parallel subagent follows the same phase execution steps below
+- Verification Gate runs independently in each subagent's worktree
+- Commits happen in each worktree, then merge to main branch in order
+
+### Sequential Execution (default)
+
+For each phase (in order, or when parallel is not applicable):
 
 1. **Read the phase file** — check `role:` field, objective, scope, acceptance criteria
 2. **Activate the role from `role:` field** — read the corresponding role file in `.orchestra/roles/`, follow its rules, principles, ownership scope
-3. **Print start status** — `{icon} #role ▶ phase-N: description...`
-4. **Implement** — write code, tests, following the role's engineering standards
-5. **Verify** — `npx tsc --noEmit`, run tests (if applicable)
-6. **Commit** — one conventional commit per phase on current branch
-7. **Update phase file** — set `status: done`, fill `## Result`
-8. **Update context.md** — append what was done, decisions made, files touched
-9. **Print completion status** — `{icon} #role ✅ phase-N done (commit message)`
+3. **Load Skills (if specified)** — check the phase file for a `skills:` field in frontmatter:
+   - If present (e.g. `skills: [auth-setup, crud-api]`), read each skill file from `.orchestra/skills/{name}.md`
+   - Follow the skill's checklist alongside the role's engineering standards
+   - If a skill file doesn't exist, skip it and log: "⚠️ Skill '{name}' not found — skipping"
+   - Skills are supplementary — they don't override role rules, they add domain-specific checklists
+4. **Research (before writing code)** — understand the codebase before making changes:
+   - Read existing files in the directories the phase will modify
+   - Check current dependency versions in `package.json` — do NOT assume versions from memory
+   - If the phase references an external library, verify its current API
+   - Identify potential conflicts: are other phases modifying the same files?
+   - If the phase builds on a previous phase's output, verify that output exists
+   - Time-box research to ~2 minutes. Note what's unclear and proceed with best knowledge
+   - Record key findings in context.md under current phase before starting implementation
+5. **Print start status** — `{icon} #role ▶ phase-N: description...`
+6. **Implement** — write code, tests, following the role's engineering standards + loaded skills
+
+   **Phase Limits (enforced during implementation):**
+   - **Time limit:** If a phase exceeds ~15 minutes, pause and report:
+     "⏰ Phase-{N} exceeded 15min. Continue or stop?"
+     In `--auto` mode: continue but log the overage in context.md
+   - **Scope guard:** If you find yourself working on something NOT listed in the phase's
+     acceptance criteria → STOP. Note it as a concern in context.md, don't implement it.
+     The phase scope is defined by PM — don't expand it.
+   - **Tool call guard:** If you've made 40+ tool calls in one phase without committing,
+     you're likely over-engineering or stuck. Pause, assess: commit what you have or escalate.
+7. **Verification Gate (MANDATORY before commit)** — you MUST pass ALL checks:
+   - Run type check: `npx tsc --noEmit` → must exit 0
+   - Run tests: `npm test` / `npx vitest run` → must exit 0
+   - Run lint: `npm run lint` → must exit 0 (if configured)
+   - Run checks in order. Stop at first failure. Fix and re-run ALL from step 1.
+   - Max 3 fix attempts per check. After 3 failures → set phase `failed`, report to user.
+   - **NEVER commit if verification fails.**
+   - If a check command doesn't exist, skip it but log: "⚠️ No {check} command found — skipping"
+8. **Acceptance Check (after verification, before commit)** — verify you built the right thing:
+   - Re-read the phase file's acceptance criteria
+   - For EACH criterion, ask: "Does my implementation satisfy this?"
+   - If YES → proceed
+   - If NO → fix it, re-run verification gate
+   - If UNCERTAIN → flag in context.md: "Unverified: {criterion} — {reason}"
+   - This catches "code works but doesn't do what was asked" — verification gate only checks if code compiles and tests pass
+9. **Commit** — one conventional commit per phase on current branch (only after verification + acceptance check pass)
+10. **Update phase file** — set `status: done`, fill `## Result`
+11. **Update context.md** — append what was done, decisions made, files touched
+12. **Update Cost Tracking** — append a row to the Cost Tracking table in context.md:
+    - Phase name
+    - Approximate duration (time from phase start to commit)
+    - Number of verification retries (0 if passed first try)
+    - This helps PM identify which phases are expensive and improve future grooming
+13. **Print completion status** — `{icon} #role ✅ phase-N done (commit message)`
 
 ## Architect Phase
 
@@ -197,7 +354,25 @@ Always runs last, after all implementation phases:
 - Full changeset: `git diff origin/{branch}...HEAD`
 - Apply the full review checklist (detect backend or frontend mode)
 - If **approved** → proceed to push gate
-- If **changes-requested** → switch to the relevant role (#backend or #frontend), fix issues, commit, then proceed (no re-review)
+- If **approved with comments** → proceed to push gate, but log comments in context.md for future reference
+- If **changes-requested** → fix cycle (see below)
+
+### Fix Cycle with Conditional Re-review
+
+When reviewer returns `changes-requested`:
+
+1. Switch to the relevant role (`#backend` or `#frontend`)
+2. Fix the issues identified in the review
+3. Run Verification Gate (test + lint must pass)
+4. Commit the fix
+5. **Check fix size:** count changed lines in the fix commit (`git diff HEAD~1 --stat`)
+   - **Fix < 30 lines** → proceed to push gate (no re-review needed)
+   - **Fix >= 30 lines** → trigger **abbreviated re-review**:
+     - Switch to `#reviewer`
+     - Review ONLY the fix commit (`git diff HEAD~1`), not the entire codebase
+     - If approved → proceed to push gate
+     - If changes-requested again → one more fix round, then proceed regardless
+6. Update context.md: "Fix cycle: {N} lines changed, re-review: {yes/no}"
 
 ## Approval Gates
 
@@ -214,7 +389,36 @@ Print the gate status but don't wait:
 🚦 Push to origin — auto-pushing
 ```
 
-## Error Handling
+### Rejection Flow — When the User Says "No"
+
+Gates are not just "yes" checkpoints — the user can reject. Handle each case:
+
+**RFC Rejected:**
+1. Ask: "What would you like changed in the RFC?"
+2. Collect specific feedback from the user
+3. Switch back to `#architect` role
+4. Revise the RFC based on feedback — don't start from scratch, amend the existing RFC
+5. Update context.md: "RFC revision round {N}: {what changed}"
+6. Re-submit for approval: "🚦 RFC revised. Approve to start implementation?"
+7. Max 3 revision rounds. After 3 rejections → report: "RFC rejected 3 times. Please clarify the requirements or adjust the PRD."
+
+**Push Rejected:**
+1. Ask: "What needs to change before pushing?"
+2. Collect specific feedback
+3. Based on feedback:
+   - If code changes needed → create a fix phase, switch to relevant engineer role, implement fix, commit
+   - If review concerns → re-trigger abbreviated review (reviewer only checks the fix, not entire codebase)
+   - If scope change → report to PM terminal: "User wants scope change — PM should update milestone"
+4. After fix is done → re-submit push gate: "🚦 Fix applied. Push to origin?"
+
+**Milestone Rejected (PM terminal):**
+- PM revises the milestone based on user feedback
+- Re-present for approval
+- This is handled in the PM terminal, not the worker terminal
+
+## Error Handling & Stuck Detection
+
+### Basic Error Handling
 
 If something fails mid-phase:
 1. Set phase status to `failed`
@@ -222,6 +426,86 @@ If something fails mid-phase:
 3. Report to user: what failed, why, options (retry / skip / stop)
 4. Wait for user input before proceeding
 
+### Stuck Detection
+
+You are **stuck** when any of these happen:
+- **Same error 3 times** — you've attempted the same fix 3 times and it still fails
+- **Circular fix** — fixing issue A creates issue B, fixing B recreates A
+- **Verification loop** — verification gate fails 3 times on the same check
+- **No progress** — you're reading files and running commands but not making meaningful code changes after 5+ tool calls
+
+### Recovery Protocol
+
+When stuck is detected:
+
+1. **STOP immediately.** Do not attempt another fix.
+2. **Log the stuck state** in context.md:
+   ```
+   ## Stuck — {timestamp}
+   - Phase: {phase-name}
+   - Symptom: {what's failing}
+   - Attempts: {what you tried, numbered}
+   - Root cause hypothesis: {your best guess}
+   ```
+3. **Try a different approach** (ONE attempt):
+   - If the same code fix failed 3x → try an entirely different implementation strategy
+   - If a dependency is broken → check if an alternative library solves the problem
+   - If tests fail due to environment → try isolating the test
+4. **If the different approach also fails** → escalate to user:
+   ```
+   🚨 Stuck on phase-{N}: {description}
+   Tried: {numbered list of approaches}
+   Root cause: {hypothesis}
+   Options:
+   1. I'll try {specific alternative} — say "try"
+   2. Skip this phase and continue — say "skip"
+   3. Stop execution — say "stop"
+   ```
+5. **Wait for user input.** Do NOT auto-retry indefinitely.
+
+### Auto-Recovery (--auto mode)
+
+In `--auto` mode, stuck detection still applies but recovery changes:
+- Try the different approach (step 3) automatically
+- If that also fails → set phase to `failed`, log everything to context.md, **move to the next phase**
+- Report the failure in the milestone completion summary
+
+## Hotfix Pipeline — `#hotfix {description}`
+
+When the user types `#hotfix {description}`, execute an ultra-fast fix pipeline:
+
+```
+#hotfix fix login 500 error on invalid email
+```
+
+**Pipeline (single flow, no gates except verification):**
+
+1. **Create hotfix milestone** automatically:
+   - Directory: `.orchestra/milestones/HF-{timestamp}-{slug}/`
+   - `milestone.md` with `Complexity: quick`, `Status: in-progress`
+   - Single phase file: `phase-1.md` with `role: backend-engineer` (or frontend if user specifies)
+2. **Read relevant code** — based on description, identify likely files
+3. **Implement the fix** — focused, minimal change
+4. **Verification Gate** — test + lint MUST pass (this is the only gate)
+5. **Commit** — `fix({scope}): {description}`
+6. **Push immediately** — no push approval gate for hotfixes
+7. **Update knowledge.md** — append a one-liner:
+   `- Hotfix {date}: {description} → {root cause} → {fix applied}`
+8. **Print summary:**
+   ```
+   🚑 Hotfix complete: fix({scope}): {description}
+   Commit: {hash}
+   Pushed to: {branch}
+   ```
+
+**Rules:**
+- Hotfix NEVER skips verification gate — broken fix is worse than slow fix
+- Hotfix NEVER creates an RFC or triggers review — speed is the priority
+- If verification fails after 3 attempts → STOP, report to user, do NOT push
+- Hotfix works on current branch — no branch creation
+- If `--auto` is active, hotfix runs without any prompts
+- After hotfix, worker returns to normal milestone execution (if `#start` was active)
+
 ## User Interruptions
 
 The user can talk to you at any time during execution. When the user sends a
@@ -237,6 +521,27 @@ message while you're working:
 
 The user is the boss. Their input always takes priority over the current phase.
 
+## Milestone Retrospective — Auto-Generated After Completion
+
+After a milestone is pushed (or after push gate in `--auto` mode), **before moving to the next milestone**, generate a concise retrospective and append it to `.orchestra/knowledge.md`.
+
+**Format — exactly 5 lines, no more:**
+
+```
+## Retro: {milestone-id} — {milestone-title} ({date})
+- Longest phase: {phase-name} (~{duration}) — {why it was slow}
+- Verification retries: {total count} — {which phases had retries}
+- Stuck: {yes/no} — {if yes, on which phase and root cause}
+- Review findings: {N blocking, N non-blocking} — {top issue if any}
+- Missing skill: {skill name that would have helped, or "none"}
+```
+
+**Rules:**
+- Pull data from context.md Cost Tracking table + review results
+- Keep it factual, not narrative — numbers and short labels only
+- If a field has nothing notable, write "none" — don't skip the line
+- This retrospective feeds future grooming: PM reads it before creating similar milestones
+
 ## What You Do NOT Do
 
 - You do NOT create milestones (PM does that)

package/template/.orchestra/blueprints/README.md

@@ -0,0 +1,87 @@
+# Blueprints — Pre-Built Milestone Templates
+
+Blueprints are ready-made milestone sets for common project types. Instead of
+PM writing every milestone from scratch, say `#blueprint{name}` and get a full
+set of milestones pre-groomed with phases, skills, and acceptance criteria.
+
+## How to Use
+
+1. PM activates: `#blueprintsaas-starter`
+2. PM reviews the generated milestones — customize as needed
+3. PM approves → milestones are created in `.orchestra/milestones/`
+4. Worker executes with `#start`
+
+## How to Customize
+
+Blueprints are starting points, not rigid templates:
+- **Add phases** — need an extra API endpoint? Add a phase to the relevant milestone
+- **Remove phases** — no mobile? Remove React Native phases
+- **Change skills** — using Clerk instead of custom auth? Swap skill references
+- **Reorder milestones** — want CI/CD first? Move it up
+- **Adjust complexity** — blueprint says `full` but you know the domain? Change to `standard`
+
+## How to Create a New Blueprint
+
+Create a new `.md` file in this directory. Follow the format:
+
+```markdown
+# Blueprint: {name}
+
+## Description
+What this blueprint is for, what it produces.
+
+## Milestones
+
+### M1 — {title}
+- Complexity: {quick/standard/full}
+- Phases:
+  1. (backend) {description} [skills: {skill-list}]
+  2. (backend) {description}
+  3. (frontend) {description}
+- Acceptance Criteria:
+  - [ ] {criterion}
+
+### M2 — {title}
+...
+```
+
+## How to Add a Component Template
+
+If you have a recurring component (e.g. "add a new CRUD resource", "add OAuth provider"),
+create it as a **component blueprint** — a single milestone that can be mixed into any project:
+
+```markdown
+# Blueprint: component-crud-resource
+
+## Description
+Adds a complete CRUD resource: DB table, API endpoints, validation, tests.
+Use this whenever you need a new entity in your API.
+
+## Parameters
+- RESOURCE_NAME: The name of the resource (e.g. "product", "order")
+- FIELDS: List of fields (e.g. "name:string, price:number, active:boolean")
+
+## Milestones
+
+### M{N} — {RESOURCE_NAME} CRUD
+- Complexity: standard
+- Phases:
+  1. (backend) DB schema + migration for {RESOURCE_NAME} [skills: crud-api]
+  2. (backend) CRUD endpoints + validation + tests [skills: crud-api]
+  3. (frontend) {RESOURCE_NAME} list + detail + form UI
+- Acceptance Criteria:
+  - [ ] All CRUD operations work
+  - [ ] Input validation on all mutations
+  - [ ] Pagination on list endpoint
+  - [ ] Tests cover happy path + edge cases
+```
+
+PM uses it: `#blueprintcomponent-crud-resource` with `RESOURCE_NAME=product`.
+
+## Available Blueprints
+
+| Name | Type | Description |
+|------|------|-------------|
+| `saas-starter` | Full project | Auth + DB + API + Dashboard + Deploy |
+| `api-only` | Full project | DB + API + Auth + CI/CD (no frontend) |
+| `component-crud-resource` | Component | Single CRUD entity (reusable) |