create-merlin-brain 3.11.0 → 3.13.0

package/files/commands/merlin/execute-phase.md

@@ -1,7 +1,7 @@
 ---
 name: merlin:execute-phase
 description: Execute all plans in a phase with wave-based parallelization
-argument-hint: "<phase-number>"
+argument-hint: "<phase-number> [--teams] [--automated]"
 allowed-tools:
   - Read
   - Write
@@ -14,15 +14,13 @@ allowed-tools:
 
 <objective>
 Execute all plans in a phase using wave-based parallel execution with FRESH processes.
-
 Each plan gets its own fresh `claude --agent merlin-executor -p` process with 200K context.
-Parallel plans run in separate git worktrees for file isolation.
-
-No Task(). No shared context. Deterministic wave execution.
+Parallel plans use git worktrees for file isolation, or Agent Teams when available.
 
-Two modes:
-- **Interactive**: Orchestrator asks user before each wave, handles checkpoints between waves
-- **Automated**: Waves run sequentially without user input, agents make assumptions
+Three modes:
+- **Interactive**: Ask user before each wave, handle checkpoints
+- **Automated**: Sequential without user input, agents make assumptions
+- **Teams**: Lead + teammates for true parallel execution (experimental, additive)
 </objective>
 
 <process>
@@ -30,12 +28,7 @@ Two modes:
 ## Step 1: Validate Phase Exists
 
 ```bash
-# Find phase directory
 ls -d .planning/phases/${PHASE_NUM}*/ 2>/dev/null
-```
-
-Count PLAN.md files:
-```bash
 ls -1 .planning/phases/${PHASE_DIR}/*-PLAN.md 2>/dev/null | wc -l
 ```
 
@@ -43,219 +36,162 @@ Error if no plans found.
 
 ## Step 2: Determine Mode
 
-Same mode detection as `/merlin:route`:
-1. Check arguments for `--automated` or `--interactive`
-2. Check `.planning/config.json`
-3. Check `~/.claude/merlin/settings.local.json`
+1. Check args for `--teams`, `--automated`, `--interactive`
+2. If no `--teams` flag, check env: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`
+3. Check `.planning/config.json`, then `~/.claude/merlin/settings.local.json`
 4. Default: `interactive`
 
-## Step 3: Discover Plans
-
-List all *-PLAN.md files in phase directory.
-Check which have *-SUMMARY.md (already complete).
-Build list of incomplete plans.
-
 ```bash
-# All plans
-ls -1 .planning/phases/${PHASE_DIR}/*-PLAN.md 2>/dev/null
+TEAMS_MODE=false
+if echo "${ARGUMENTS}" | grep -q '\-\-teams'; then
+  TEAMS_MODE=true
+elif [ "${CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS:-0}" = "1" ]; then
+  TEAMS_MODE=true
+fi
+```
 
-# Completed plans (have SUMMARY)
-ls -1 .planning/phases/${PHASE_DIR}/*-SUMMARY.md 2>/dev/null
+## Step 3: Discover Plans
+
+List all `*-PLAN.md` files. Check which have matching `*-SUMMARY.md` (complete).
+Report wave structure:
 
-# Incomplete = plans without matching summary
+```
+Phase {N}: {name}  |  Mode: {interactive|automated|teams}
+Wave 1: plan-01, plan-02 (parallel)
+Wave 2: plan-03 (sequential)
+{X} plans total, {Y} incomplete, {Z} waves
 ```
 
 ## Step 4: Group by Wave
 
-Read `wave` from each plan's frontmatter:
 ```bash
 head -10 .planning/phases/${PHASE_DIR}/*-PLAN.md 2>/dev/null | grep -i "wave"
 ```
 
-Group plans by wave number. Report wave structure:
+## Step 5: Interactive Wave Confirmation (interactive + teams only)
+
+Before each wave show:
+```
+Wave {W}: Ready to execute — {list of plans}
+[1] Execute  [2] Skip  [3] Single plan  [4] Stop
 ```
-Phase {N}: {name}
-Mode: {interactive|automated}
 
-Wave 1: plan-01, plan-02 (parallel)
-Wave 2: plan-03 (sequential, depends on wave 1)
+## Step 6: Execute Waves
 
-{X} plans total, {Y} incomplete, {Z} waves
-```
+### Teams Mode (TEAMS_MODE=true)
 
-## Step 5: Interactive Wave Confirmation (interactive mode only)
+Orchestrator is the Lead. Each plan in a wave becomes a named Teammate.
 
-**Skip in automated mode.**
+Write per-plan handoffs, spawn teammates.
 
-Before each wave, show user what's about to run:
+**Session naming (required — shows in VS Code Spark panel):**
 ```
-## Wave {W}: Ready to execute
-
-Plans: {list of plans in this wave}
-Parallel: {yes if >1 plan, no if single}
+Merlin: {agent-name} — {plan-label}
+```
+Where `plan-label` is the plan filename without the path and `-PLAN.md` suffix,
+truncated to 40 chars. Example: `Merlin: merlin-executor — build-auth-middleware`
 
-[1] Execute wave
-[2] Skip this wave
-[3] Execute single plan from this wave
-[4] Stop here
+Show live progress during execution:
+```
+Wave {W} — {N} teammates active:
+  Teammate 1: implementation-dev — "Build auth middleware"
+  Teammate 2: tests-qa — "Write auth tests"
+  Teammate 3: docs-keeper — "Update API docs" (done)
 ```
 
-## Step 6: Execute Waves
+Cross-agent context: when Wave N completes, append upstream SUMMARY findings
+to Wave N+1 teammate handoffs (enables architect → impl-dev → tests-qa pipeline).
 
-For each wave in order:
+**Fallback:** If Agent Teams unavailable or spawn fails, log:
+`[merlin] Agent Teams unavailable — falling back to worktree parallel mode`
+then continue with the worktree strategy below.
 
-### Single Plan in Wave (sequential)
+Teammates never checkpoint — they make reasonable assumptions.
 
-Write handoff and spawn single fresh process:
+### Single Plan in Wave
 
 ```bash
 HANDOFF_DIR="/tmp/merlin-phase-$$-wave-${W}"
 mkdir -p "$HANDOFF_DIR"
 
-# Write handoff for this plan
 cat > "$HANDOFF_DIR/handoff.md" << EOF
 # Execution Handoff
-
-## Plan
-Execute plan at: ${plan_path}
-
-## Mode
-${MODE}
-${MODE_INSTRUCTION}
-
-## Instructions
-Read the plan file yourself. You have fresh 200K context.
-Execute all tasks, make per-task commits, create SUMMARY.md.
-
-## Result Protocol
+## Plan: ${plan_path}
+## Mode: ${MODE} — ${MODE_INSTRUCTION}
+## Instructions: Read the plan file. Execute all tasks. Create SUMMARY.md.
+## Result Protocol:
 ---EXEC_RESULT---
 Status: completed | checkpoint | error
 Summary: <2-3 sentences>
-Tasks-Completed: <N>
-Tasks-Total: <N>
-Commits: <hash list>
-Files-Changed: <file list>
+Tasks-Completed: <N>  Tasks-Total: <N>
+Commits: <hash list>  Files-Changed: <file list>
 Checkpoint: <if needed>
 ---END_EXEC_RESULT---
 EOF
 
-# Spawn fresh executor
 RESULT=$(unset CLAUDECODE && cat "$HANDOFF_DIR/handoff.md" | claude \
-  --agent merlin-executor \
-  -p \
-  --permission-mode acceptEdits \
-  --output-format text \
-  2>&1)
+  --agent merlin-executor -p --permission-mode acceptEdits \
+  --output-format text 2>&1)
 ```
 
-### Multiple Plans in Wave (parallel with worktrees)
-
-Create git worktree per plan for file isolation:
+### Multiple Plans in Wave (worktrees)
 
 ```bash
 REPO_ROOT=$(git rev-parse --show-toplevel)
 REPO_NAME=$(basename "$REPO_ROOT")
-CURRENT_BRANCH=$(git branch --show-current)
 
-# Create worktree for each plan
 git worktree add "${REPO_ROOT}/../${REPO_NAME}-worktree-01" -b merlin/worktree-01
 git worktree add "${REPO_ROOT}/../${REPO_NAME}-worktree-02" -b merlin/worktree-02
-```
-
-Spawn parallel fresh processes (use `&` and `wait`):
 
-```bash
-# Plan 1 in worktree 1
-(cd "${REPO_ROOT}/../${REPO_NAME}-worktree-01" && \
-  unset CLAUDECODE && cat "$HANDOFF_DIR/plan-01.md" | claude \
-  --agent merlin-executor \
-  -p \
-  --permission-mode acceptEdits \
-  --output-format text \
+(cd "${REPO_ROOT}/../${REPO_NAME}-worktree-01" && unset CLAUDECODE && \
+  cat "$HANDOFF_DIR/plan-01.md" | claude --agent merlin-executor -p \
+  --permission-mode acceptEdits --output-format text \
   > "$HANDOFF_DIR/result-01.txt" 2>&1) &
 PID1=$!
 
-# Plan 2 in worktree 2
-(cd "${REPO_ROOT}/../${REPO_NAME}-worktree-02" && \
-  unset CLAUDECODE && cat "$HANDOFF_DIR/plan-02.md" | claude \
-  --agent merlin-executor \
-  -p \
-  --permission-mode acceptEdits \
-  --output-format text \
+(cd "${REPO_ROOT}/../${REPO_NAME}-worktree-02" && unset CLAUDECODE && \
+  cat "$HANDOFF_DIR/plan-02.md" | claude --agent merlin-executor -p \
+  --permission-mode acceptEdits --output-format text \
   > "$HANDOFF_DIR/result-02.txt" 2>&1) &
 PID2=$!
 
-# Wait for all to complete
 wait $PID1 $PID2
-```
 
-**After wave completes, merge back:**
-
-```bash
 cd "$REPO_ROOT"
 git merge merlin/worktree-01 --no-edit
 git merge merlin/worktree-02 --no-edit
-
-# Clean up
 git worktree remove "${REPO_ROOT}/../${REPO_NAME}-worktree-01" --force
 git worktree remove "${REPO_ROOT}/../${REPO_NAME}-worktree-02" --force
 git branch -d merlin/worktree-01 merlin/worktree-02
 ```
 
-**If merge conflicts:** Abort merge, report conflicting files, offer user resolution.
-
-**Fallback (worktree fails):** Run plans sequentially in main repo.
+If merge conflicts: abort, report files, offer resolution.
+Fallback if worktree fails: run plans sequentially.
 
-### Checkpoint Handling Within Waves (interactive mode)
+### Checkpoint Handling (interactive mode only)
 
-If any plan in a wave returns `status: checkpoint`:
-1. Present all checkpoints from the wave
-2. Collect user responses
-3. Spawn NEW fresh processes for each checkpointed plan with continuation handoffs
-4. Wait for completion before proceeding to next wave
+If a plan returns `status: checkpoint`:
+1. Present checkpoint, collect user response
+2. Spawn NEW fresh process with continuation handoff
+3. Wait for completion before next wave
 
-In automated mode: agents should not checkpoint (they make assumptions).
+Automated and teams mode: agents make assumptions, no checkpoints expected.
 
 ## Step 7: Verify Phase Goal
 
-After all plans complete, spawn merlin-verifier as fresh process:
-
 ```bash
-cat > "/tmp/merlin-verify-$$/handoff.md" << EOF
-Verify phase ${PHASE_NUM} goal achievement.
-
-Phase: ${PHASE_NUM} - ${PHASE_NAME}
-Phase goal: ${PHASE_GOAL}
-Phase directory: ${PHASE_DIR}
-
-Check must_haves against actual codebase.
-Create VERIFICATION.md in the phase directory.
-
----VERIFY_RESULT---
-Status: passed | gaps_found | human_needed
-Score: X/Y must-haves verified
-Summary: <verification summary>
----END_VERIFY_RESULT---
-EOF
-
 VERIFY_RESULT=$(unset CLAUDECODE && cat "/tmp/merlin-verify-$$/handoff.md" | claude \
-  --agent merlin-verifier \
-  -p \
-  --permission-mode acceptEdits \
-  --output-format text \
-  2>&1)
+  --agent merlin-verifier -p --permission-mode acceptEdits \
+  --output-format text 2>&1)
 ```
 
-Route by verification status:
-- `passed` → Step 8
-- `human_needed` → Present items, get approval
-- `gaps_found` → Present gaps, offer `/merlin:plan-phase {X} --gaps`
+Handoff asks verifier to check must_haves against codebase and create VERIFICATION.md.
+
+Route: `passed` → Step 8 | `human_needed` → present items | `gaps_found` → offer `--gaps`
 
 ## Step 8: Update Roadmap, State, and Requirements
 
-Update ROADMAP.md phase status to complete.
-Update STATE.md with new position.
-Update REQUIREMENTS.md — mark phase requirements as "Complete".
+Update ROADMAP.md phase status, STATE.md position, REQUIREMENTS.md phase items to "Complete".
 
 ## Step 9: Commit Phase Completion
 
@@ -268,75 +204,36 @@ git commit -m "docs(${PHASE_NUM}): complete ${PHASE_NAME} phase"
 
 ## Step 10: Offer Next Steps
 
-Route based on verification and milestone status:
-
-**Phase verified, more phases remain:**
-```
-## Phase {Z}: {Name} Complete
-
-All {Y} plans finished. Phase goal verified.
-
----
-
-## Next Up
-
-**Phase {Z+1}: {Name}** — {Goal}
-
-`/merlin:plan-phase {Z+1}`
-```
-
-**Phase verified, milestone complete:**
-```
-ALL PHASES COMPLETE!
-
-`/merlin:audit-milestone`
-```
-
-**Gaps found:**
-```
-## Phase {Z}: {Name} — Gaps Found
-
-Score: {N}/{M} must-haves verified
-
-`/merlin:plan-phase {Z} --gaps`
-```
+- More phases remain: suggest `/merlin:plan-phase {Z+1}`
+- Milestone complete: suggest `/merlin:audit-milestone`
+- Gaps found: suggest `/merlin:plan-phase {Z} --gaps`
 
 </process>
 
 <deviation_rules>
-Deviations are handled by the executor processes, not this orchestrator.
-- Auto-fix bugs: Executor handles, documents in Summary
-- Auto-add critical: Executor handles, documents in Summary
-- Auto-fix blockers: Executor handles, documents in Summary
-- Architectural changes: Executor checkpoints (interactive) or makes decision (automated)
+Deviations handled by executor processes, not this orchestrator.
+- Auto-fix bugs / critical additions / blockers: executor handles, documents in Summary
+- Architectural changes: executor checkpoints (interactive) or decides (automated/teams)
 </deviation_rules>
 
 <critical_rules>
-
 **NEVER USE Task().** All execution uses `claude --agent -p` via Bash.
-
 **EVERY PLAN = FRESH PROCESS.** Each plan in a wave gets its own 200K context.
-
-**PARALLEL = WORKTREES.** Multiple plans in a wave use git worktrees for file isolation.
-
+**PARALLEL = WORKTREES OR TEAMS.** Never share file state between parallel plans.
 **ALWAYS CLEAN UP.** Remove worktrees and /tmp files after processing.
-
 **CHECKPOINT = NEW PROCESS.** After checkpoints, spawn fresh continuation processes.
-
 **ORCHESTRATOR STAYS LEAN.** Only reads wave structure and result summaries.
-Never reads full plan content or codebase files.
-
+**TEAMS MODE IS ADDITIVE.** Worktree and sequential modes always work as fallback.
 </critical_rules>
 
 <success_criteria>
-- [ ] All incomplete plans in phase executed via fresh processes
+- [ ] All incomplete plans executed via fresh processes
 - [ ] Each plan has SUMMARY.md
-- [ ] Parallel plans used worktrees for isolation
+- [ ] Parallel plans used worktrees or Agent Teams for isolation
 - [ ] Phase goal verified (fresh verifier process)
 - [ ] VERIFICATION.md created in phase directory
-- [ ] STATE.md reflects phase completion
-- [ ] ROADMAP.md updated
-- [ ] REQUIREMENTS.md updated
+- [ ] STATE.md, ROADMAP.md, REQUIREMENTS.md updated
 - [ ] All worktrees and temp files cleaned up
 - [ ] User informed of next steps
+- [ ] Teams: teammate names displayed, cross-agent context passed between waves
 </success_criteria>