create-merlin-brain 3.11.0 → 3.13.0

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

@@ -1,7 +1,7 @@
 ---
 name: merlin:execute-plan
 description: Execute a PLAN.md file
-argument-hint: "[path-to-PLAN.md]"
+argument-hint: "[path-to-PLAN.md] [--teams]"
 allowed-tools:
   - Read
   - Glob
@@ -22,13 +22,15 @@ Orchestrator stays lean: validate plan, determine mode, write handoff, spawn fre
 handle checkpoints, report completion. The executor gets full 200K context.
 
 No Task(). No shared context. Deterministic execution.
+
+When a plan contains parallel task groups and `--teams` is active, each group spawns
+as a named Teammate for true parallel execution within the single plan.
 </objective>
 
 <process>
 
 ## Step 1: Validate Plan Exists
 
-Confirm file at $ARGUMENTS exists.
 ```bash
 ls "$PLAN_PATH" 2>/dev/null
 ```
@@ -36,26 +38,30 @@ Error if not found: "Plan not found: {path}"
 
 ## Step 2: Check If Already Executed
 
-Derive SUMMARY path from plan path (replace PLAN.md with SUMMARY.md).
 ```bash
 SUMMARY_PATH="${PLAN_PATH/PLAN.md/SUMMARY.md}"
 ls "$SUMMARY_PATH" 2>/dev/null
 ```
-
-If SUMMARY exists: "Plan already executed. SUMMARY: {path}"
-Offer: re-execute or exit.
+If SUMMARY exists: "Plan already executed." Offer re-execute or exit.
 
 ## Step 3: 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`
 
+```bash
+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
+```
+
 ## Step 4: Get Sights Context
 
-Parse plan to get the objective:
 ```bash
 head -30 "$PLAN_PATH" 2>/dev/null
 ```
@@ -68,89 +74,71 @@ Task: "{objective from plan}"
 ## Step 5: Parse Plan Identifiers
 
 Extract from path like `.planning/phases/03-auth/03-02-PLAN.md`:
-- phase_number: `03`
-- phase_name: `auth`
-- plan_number: `02`
+`phase_number=03`, `phase_name=auth`, `plan_number=02`
 
 ## Step 6: Pre-Execution Summary
 
-Parse PLAN.md to extract:
-- objective: First sentence from `<objective>` element
-- task_count: Count of `<task` elements
-- files: Collect unique file paths from `<files>` elements
+Parse PLAN.md: objective, task_count, files, parallel_groups.
 
-Display:
 ```
 ════════════════════════════════════════
 EXECUTING: {phase_number}-{plan_number} {phase_name}
 ════════════════════════════════════════
-
 Building: {objective one-liner}
-Tasks: {task_count}
-Files: {comma-separated file list}
-Mode: {interactive|automated}
-
+Tasks: {task_count}  |  Files: {file list}
+Mode: {interactive|automated|teams}
+{if teams + parallel groups: "Parallel groups: {N} — will spawn {N} teammates"}
 Full plan: {plan_path}
 ════════════════════════════════════════
 ```
 
 ## Step 7: Interactive Pre-Flight (interactive mode only)
 
-**Skip in automated mode.**
-
-Ask user if they have any notes before execution:
-- "Any specific concerns or constraints for this plan?"
-- If user has none, proceed directly.
+Ask: "Any specific concerns or constraints for this plan?"
+Skip in automated and teams mode.
 
 ## Step 8: Write Handoff File
 
 ```bash
 HANDOFF_DIR="/tmp/merlin-exec-$$"
 mkdir -p "$HANDOFF_DIR"
-HANDOFF_FILE="$HANDOFF_DIR/handoff.md"
 ```
 
-Write:
+Derive a concise session label (max 40 chars) from the plan path:
+```bash
+PLAN_LABEL=$(basename "${PLAN_PATH}" -PLAN.md | sed 's/^[0-9]*-[0-9]*-//')
+SESSION_NAME="Merlin: merlin-executor — ${PLAN_LABEL}"
+```
+
+The `SESSION_NAME` appears in VS Code's Spark panel — keep it concise but descriptive.
 
 ```markdown
 # Execution Handoff
-
-## Plan
-Execute plan at: {plan_path}
-
-## Mode
-{interactive|automated}
-{automated: "Make reasonable assumptions at decision points. Do NOT checkpoint."}
-{interactive: "At decision points, output CHECKPOINT_NEEDED with details and stop."}
-
-## Sights Context
-{SIGHTS_CONTEXT}
-
-## User Inputs
-{USER_INPUTS or "Automated mode — make reasonable assumptions"}
-
-## Files to Read
-- Plan: {plan_path}
-- State: .planning/STATE.md
-- Config: .planning/config.json (if exists)
+## Session: {SESSION_NAME}
+## Plan: {plan_path}
+## Mode: {interactive|automated|teams}
+  - automated: "Make reasonable assumptions. Do NOT checkpoint."
+  - interactive: "At decision points, output CHECKPOINT_NEEDED and stop."
+  - teams: "You are a Teammate. Make reasonable assumptions. Do NOT checkpoint."
+## Sights Context: {SIGHTS_CONTEXT}
+## User Inputs: {USER_INPUTS or "Automated — make reasonable assumptions"}
+## Files to Read: plan_path, .planning/STATE.md, .planning/config.json
 
 Read the plan file yourself — you have fresh 200K context.
 
-## Result Protocol
-When done, output:
-
+## Result Protocol:
 ---EXEC_RESULT---
 Status: completed | checkpoint | error
-Summary: <2-3 sentence summary>
-Tasks-Completed: <number>
-Tasks-Total: <number>
-Commits: <list of commit hashes, one per line>
-Files-Changed: <comma-separated list>
-Checkpoint: <only if status=checkpoint — what you need>
+Summary: <2-3 sentences>
+Tasks-Completed: <N>  Tasks-Total: <N>
+Commits: <hash list>  Files-Changed: <file list>
+Checkpoint: <only if status=checkpoint>
 ---END_EXEC_RESULT---
 ```
 
-## Step 9: Spawn Fresh Executor Process
+## Step 9: Spawn Executor
+
+### Standard mode (interactive or automated)
 
 ```bash
 RESULT=$(unset CLAUDECODE && cat "$HANDOFF_FILE" | claude \
@@ -164,157 +152,110 @@ EXIT_CODE=$?
 
 Use Bash tool with `timeout: 600000` (10 minutes).
 
-## Step 10: Handle Result
-
-Parse result between `---EXEC_RESULT---` and `---END_EXEC_RESULT---`.
+### Teams mode — parallel task groups within plan
 
-### If status = completed
+When `TEAMS_MODE=true` and the plan has parallel task groups:
 
-1. Verify SUMMARY.md was created:
+1. Count parallel groups:
    ```bash
-   ls "${PLAN_PATH/PLAN.md/SUMMARY.md}" 2>/dev/null
+   PARALLEL_GROUPS=$(grep -c "^parallel: true" "$PLAN_PATH" 2>/dev/null || echo "0")
    ```
-2. Sync tasks to cloud:
+
+2. If groups exist, write a per-group teammate handoff:
+   ```markdown
+   # Teammate Task — Plan {PLAN_LABEL}, Group {GROUP_ID}
+   ## Session Name: Merlin: merlin-executor — {PLAN_LABEL} group-{GROUP_ID}
+   ## Plan: {PLAN_PATH} — execute only tasks in group {GROUP_ID}
+   ## Mode: teams — make assumptions, do NOT checkpoint
+   ## Sights Context: {SIGHTS_CONTEXT}
+   ## Result Protocol: (same standard format)
    ```
-   Call: merlin_sync_task
-   Title: "{plan objective}"
-   Status: "completed"
+
+3. Show live status during execution:
    ```
-3. Clean up handoff:
-   ```bash
-   rm -rf "$HANDOFF_DIR"
+   Plan {PLAN_LABEL} — {N} teammates active:
+     Teammate 1: merlin-executor — "Group 1: API endpoints"
+     Teammate 2: merlin-executor — "Group 2: Database schema" (done)
    ```
-4. Go to Step 11 (Present Result).
 
-### If status = checkpoint (interactive mode only)
+4. Fallback if no parallel groups or Teams spawn fails: single executor.
+   Log: `[merlin] Running as single executor (no parallel groups or Teams unavailable)`
+
+## Step 10: Handle Result
+
+Parse result between `---EXEC_RESULT---` and `---END_EXEC_RESULT---`.
 
-Run the checkpoint loop (Step 10a).
+**completed:**
+1. Verify SUMMARY.md created
+2. Sync: `merlin_sync_task` → status: completed
+3. `rm -rf "$HANDOFF_DIR"`
+4. Go to Step 11
 
-### If status = error
+**checkpoint (interactive only):** Run Step 10a loop.
 
-Present error, offer retry or skip.
+**error:** Present error, offer retry or skip.
 
 ## Step 10a: Checkpoint Loop (interactive mode only)
 
 When executor returns `status: checkpoint`:
 
-1. **Present checkpoint to user:**
+1. Present to user:
    ```
-   ╔═══════════════════════════════════════════════════════════╗
-   ║  CHECKPOINT: Executor needs input                         ║
-   ╚═══════════════════════════════════════════════════════════╝
-
-   Progress: {tasks-completed}/{tasks-total} tasks complete
-
+   ╔═══════════════════════════════════════╗
+   ║  CHECKPOINT: Executor needs input     ║
+   ╚═══════════════════════════════════════╝
+   Progress: {tasks-completed}/{tasks-total}
    {checkpoint details}
-
-   ────────────────────────────────────────────────────────────
    Your response:
    ```
 
-2. **Collect user response.**
+2. Collect user response.
 
-3. **Write continuation handoff:**
+3. Write continuation handoff:
    ```markdown
    # Execution Continuation
-
-   ## Original Plan
-   {plan_path}
-
-   ## Previous Progress
-   {tasks-completed} of {tasks-total} tasks complete
-   Commits so far: {commits list}
-   Files changed so far: {files list}
-
-   ## Checkpoint Response
-   User said: {user_response}
-
-   ## Instructions
-   Continue executing the plan from where you left off.
-   Read the plan file to find remaining tasks.
-   The user has answered your checkpoint question.
-
-   ## Result Protocol
-   (same as original)
+   ## Original Plan: {plan_path}
+   ## Previous Progress: {tasks-completed}/{tasks-total} complete
+   ## Commits so far: {list}  Files changed: {list}
+   ## Checkpoint Response: User said: {user_response}
+   ## Instructions: Continue from where you left off. Read plan for remaining tasks.
+   ## Result Protocol: (same as original)
    ```
 
-4. **Spawn NEW fresh process** with continuation handoff.
-   Brand new 200K context. NOT a resume.
-
-5. **Repeat** until `completed` or `error` (max 5 cycles).
+4. Spawn NEW fresh process. NOT a resume.
+5. Repeat until `completed` or `error` (max 5 cycles).
 
 ## Step 11: Present Result and Next Steps
 
-Check remaining plans in phase:
 ```bash
 PHASE_DIR=$(dirname "$PLAN_PATH")
 PLAN_COUNT=$(ls -1 "$PHASE_DIR"/*-PLAN.md 2>/dev/null | wc -l)
 SUMMARY_COUNT=$(ls -1 "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null | wc -l)
 ```
 
-### If more plans remain in phase (summaries < plans):
-
-Find next PLAN.md without matching SUMMARY.md:
-
+**More plans remain:**
 ```
-Plan {phase}-{plan} complete.
-Summary: {summary_path}
-
-{SUMMARY_COUNT} of {PLAN_COUNT} plans complete for Phase {Z}.
-
----
-
-## Next Up
-
-**{phase}-{next-plan}: [Plan Name]**
-
-`/merlin:execute-plan {next-plan-path}`
+Plan {phase}-{plan} complete.  {SUMMARY_COUNT}/{PLAN_COUNT} plans done for Phase {Z}.
+Next: /merlin:execute-plan {next-plan-path}
 ```
 
-### If phase complete (summaries = plans):
-
-Check verification status — spawn merlin-verifier as fresh process:
-
+**Phase complete — spawn verifier:**
 ```bash
-# Write verifier handoff
-cat > "/tmp/merlin-verify-$$/handoff.md" << 'VERIFY'
-Verify phase {phase_number} goal achievement.
-
-Phase: {phase_number} - {phase_name}
-Phase goal: {phase_goal}
-Phase directory: {phase_dir}
-
-Check must_haves against actual codebase (not SUMMARY claims).
-Create VERIFICATION.md in the phase directory.
-
----VERIFY_RESULT---
-Status: passed | gaps_found | human_needed
-Score: X/Y must-haves verified
-Summary: <what was verified>
----END_VERIFY_RESULT---
-VERIFY
-
-# Spawn fresh verifier
 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 based on verification:
-- **passed + more phases:** Suggest `/merlin:plan-phase {next}`
-- **passed + last phase:** Suggest `/merlin:complete-milestone`
-- **gaps_found:** Suggest `/merlin:plan-phase {current} --gaps`
-- **human_needed:** Present items for user review
+Verifier handoff: check must_haves against actual codebase, create VERIFICATION.md.
 
-### Update Requirements (when phase complete + verified)
+Route: `passed + more phases` → `/merlin:plan-phase {next}` |
+`passed + last phase` → `/merlin:complete-milestone` |
+`gaps_found` → `/merlin:plan-phase {current} --gaps` |
+`human_needed` → present items
 
-Read ROADMAP.md for phase requirements, update REQUIREMENTS.md status to "Complete".
-
-### Commit Phase Metadata (when phase complete)
+**When phase complete + verified:** Update REQUIREMENTS.md status to "Complete".
 
+**Commit phase metadata:**
 ```bash
 git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md 2>/dev/null
 git commit -m "docs({phase}): complete {phase-name} phase"
@@ -323,38 +264,33 @@ git commit -m "docs({phase}): complete {phase-name} phase"
 </process>
 
 <commit_rules>
-**Per-Task Commits:** Handled by the executor process (per-task atomic commits).
-**Plan Metadata Commit:** Handled by the executor process (PLAN.md + SUMMARY.md).
+**Per-Task Commits:** Handled by executor process (atomic per task).
+**Plan Metadata Commit:** Handled by executor process (PLAN.md + SUMMARY.md).
 **Phase Completion Commit:** Handled by this orchestrator (ROADMAP.md + STATE.md + REQUIREMENTS.md).
-
-**NEVER use:** `git add .` or `git add -A`. Always stage files individually.
+**NEVER use:** `git add .` or `git add -A`. Stage files individually.
 </commit_rules>
 
 <critical_rules>
-
 **NEVER USE Task().** Task() shares parent context. Use `claude --agent -p` via Bash.
-
 **ALWAYS FRESH PROCESS.** Every execution spawns a new `claude` process.
-
-**CHECKPOINT = NEW PROCESS.** After a checkpoint, spawn a NEW fresh process with continuation state.
-Never try to resume the old process.
-
+**CHECKPOINT = NEW PROCESS.** Spawn NEW fresh process after checkpoint. Never resume old.
 **MAX 10 MINUTES PER SPAWN.** For longer tasks, use `merlin-loop`.
-
 **CLEAN UP HANDOFFS.** Remove /tmp files after processing.
-
+**TEAMS MODE IS ADDITIVE.** Single-executor mode always works as fallback.
+**TEAMS = NO CHECKPOINTS.** Teammates make assumptions, never checkpoint.
 </critical_rules>
 
 <success_criteria>
 - [ ] Plan validated and not already executed
-- [ ] Mode determined (interactive or automated)
+- [ ] Mode determined (interactive, automated, or teams)
 - [ ] Handoff file written to /tmp
 - [ ] Fresh `claude --agent merlin-executor -p` spawned via Bash
-- [ ] All checkpoints handled (interactive) or none expected (automated)
+- [ ] Checkpoints handled (interactive) or none expected (automated/teams)
 - [ ] SUMMARY.md created by executor
 - [ ] Tasks synced to cloud
 - [ ] Phase verification triggered if phase complete
 - [ ] Requirements updated if phase complete
 - [ ] Temp files cleaned up
 - [ ] Next steps offered
+- [ ] Teams: parallel groups shown with teammate names, fallback to single on failure
 </success_criteria>