create-merlin-brain 3.10.0 → 3.11.0

package/files/commands/merlin/course-correct.md

@@ -0,0 +1,219 @@
+---
+name: merlin:course-correct
+description: Handle plan pivots — when implementation reveals the plan needs changing
+argument-hint: "\"description of what changed\""
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - AskUserQuestion
+  - mcp__merlin__merlin_get_context
+  - mcp__merlin__merlin_get_project_status
+  - mcp__merlin__merlin_search
+---
+
+<objective>
+Handle "the plan was wrong" — a dedicated workflow for pivots discovered during implementation.
+
+Most planning flows only handle the happy path. This command handles the other reality:
+a technical constraint appeared, a dependency changed, a requirement turned out to be wrong.
+
+It assesses impact across all phases, proposes a minimal change set, and applies changes
+only after the user approves. Nothing is modified until the user says go.
+</objective>
+
+<process>
+
+## Step 1: Parse Arguments
+
+Extract from $ARGUMENTS:
+- **change_description**: Free-text description of what went wrong or what changed
+  (e.g., "Auth provider changed from Auth0 to Clerk")
+
+If no argument provided, ask:
+
+```
+What changed or went wrong? Describe the situation briefly.
+(e.g., "We discovered the third-party API we planned to use requires a paid plan"
+ or "The database schema for users needs an extra field throughout the system")
+```
+
+## Step 2: Load Planning Context
+
+Read all planning state. This step is intentionally thorough — impact assessment requires full context.
+
+```bash
+cat .planning/PROJECT.md 2>/dev/null
+cat .planning/ROADMAP.md 2>/dev/null
+cat .planning/REQUIREMENTS.md 2>/dev/null
+cat .planning/STATE.md 2>/dev/null
+ls .planning/phases/ 2>/dev/null
+```
+
+For each phase directory found:
+
+```bash
+# Completed phases: read summaries
+ls .planning/phases/*/  *-SUMMARY.md 2>/dev/null
+
+# Active phase: read all plans
+ls .planning/phases/${CURRENT_PHASE_DIR}/*-PLAN.md 2>/dev/null
+
+# Upcoming phases: read any existing plans
+ls .planning/phases/*-PLAN.md 2>/dev/null
+```
+
+Get Sights context for the change topic:
+
+```
+Call: merlin_get_context
+Task: "course correction — {change_description}"
+```
+
+## Step 3: Impact Assessment
+
+Analyze the loaded context against the change description. Determine:
+
+**Completed work affected:**
+- Which SUMMARY.md phases/plans touched the area that changed?
+- What specifically needs to be revised in already-built work?
+- Is this a patch (small addition/change) or a rewrite (fundamental change)?
+
+**Active plans affected:**
+- Which PLAN.md files in the current phase directly address the changed area?
+- Classify each: rewrite needed, update needed, or unaffected.
+
+**Upcoming plans affected:**
+- Which future phases or plans will need to change based on the pivot?
+- Are any roadmap milestones invalidated?
+
+**Requirements affected:**
+- Which entries in REQUIREMENTS.md reference the changed component/decision?
+- Do any requirement acceptance criteria need updating?
+
+**New work required:**
+- Does the pivot introduce entirely new tasks (e.g., a migration helper, a new adapter)?
+
+## Step 4: Generate Change Proposal
+
+Produce a structured, numbered change proposal. Every entry must name the exact file.
+
+Classify each change as:
+- **Rewrite** — file needs to be replaced
+- **Update** — targeted edits to existing file
+- **Patch** — small addition to completed work
+- **New** — entirely new file needs to be created
+
+Compute scope impact:
+- Count rewrites, updates, patches, new files
+- Flag if any milestone-level changes are needed (i.e., ROADMAP.md phases added/removed)
+- Estimate net new plans required
+
+Present the full proposal before taking any action:
+
+```
+🔮 **Course Correction** · "{change_description}"
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+### Impact Assessment
+{bullet list of affected areas — completed, active, upcoming, requirements}
+
+### Change Proposal
+{numbered list, each entry: [TYPE] filename — reason}
+
+### Scope Impact
+- {X} rewrites, {Y} updates, {Z} patches, {W} new files
+- {milestone impact or "No milestone-level changes needed"}
+- {estimated net new plans}
+
+[1] Apply all changes
+[2] Apply selectively — I'll choose
+[3] Discuss first
+[4] Cancel
+```
+
+Wait for user response before proceeding.
+
+## Step 5: Apply Changes (with approval)
+
+**If user selects [1] — Apply all:**
+
+Execute the change proposal in this order:
+1. Update REQUIREMENTS.md (requirements changes first — they anchor everything else)
+2. Update ROADMAP.md (if milestone or phase structure changes)
+3. Update STATE.md — log the pivot under a "Course Corrections" section
+4. Rewrite or update active PLAN.md files
+5. Patch completed work notes (add patch notes to SUMMARY.md, do not delete history)
+6. Create any new PLAN.md files required
+
+**If user selects [2] — Apply selectively:**
+
+Present each proposed change as a y/n question using AskUserQuestion. Apply only approved changes.
+
+**After applying:**
+
+Update STATE.md with a course correction log entry:
+
+```markdown
+## Course Corrections
+
+### {date} — {change_description}
+- Trigger: {what the user described}
+- Changes applied: {count and summary}
+- Files modified: {list}
+```
+
+## Step 6: Present Completion Summary
+
+```
+Course correction applied.
+
+### Changes Made
+{list of files modified, created, or patched}
+
+### Updated State
+STATE.md updated with correction log.
+
+---
+
+Next:
+[1] Re-check readiness: /merlin:readiness-gate {phase}
+[2] Continue executing: /merlin:execute-phase {phase}
+[3] Review updated plans: /merlin:progress
+```
+
+</process>
+
+<critical_rules>
+
+**NEVER MODIFY BEFORE APPROVAL.** The full proposal must be presented and the user must
+select an action before any file is written or edited.
+
+**PRESERVE HISTORY.** Do not delete SUMMARY.md content from completed phases. Add patch
+notes as addenda. The record of what was built stays intact.
+
+**STATE.MD IS ALWAYS UPDATED.** Every course correction must be logged in STATE.md
+regardless of scope. Future agents need to know a pivot happened.
+
+**BE CONCRETE.** Every item in the change proposal names an exact file path, not a vague
+description like "update the auth files."
+
+**REQUIREMENTS FIRST.** If requirements change, update REQUIREMENTS.md before updating
+any PLAN.md. Plans derive from requirements, not the other way around.
+
+</critical_rules>
+
+<success_criteria>
+- [ ] Change description captured (from args or prompt)
+- [ ] Full planning context loaded
+- [ ] Sights context retrieved for the change area
+- [ ] Impact assessment covers completed, active, and upcoming work
+- [ ] Change proposal presented with exact file names before any edit
+- [ ] User approves before any modification
+- [ ] Changes applied in correct order (requirements → roadmap → plans → summaries)
+- [ ] STATE.md updated with course correction log
+- [ ] Next steps offered
+</success_criteria>

package/files/commands/merlin/debug.md

@@ -80,7 +80,7 @@ Create: .planning/debug/{slug}.md
 
 ```
 ## Spawn fresh debugger process via Bash:
-cat "$HANDOFF_DIR/handoff.md" | claude \
+unset CLAUDECODE && cat "$HANDOFF_DIR/handoff.md" | claude \
   --agent merlin-debugger \
   -p \
   --permission-mode acceptEdits \
@@ -134,7 +134,7 @@ goal: find_and_fix
 
 ```
 ## Spawn fresh continuation process via Bash:
-cat "$HANDOFF_DIR/continuation.md" | claude \
+unset CLAUDECODE && cat "$HANDOFF_DIR/continuation.md" | claude \
   --agent merlin-debugger \
   -p \
   --permission-mode acceptEdits \

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

@@ -140,7 +140,7 @@ Checkpoint: <if needed>
 EOF
 
 # Spawn fresh executor
-RESULT=$(cat "$HANDOFF_DIR/handoff.md" | claude \
+RESULT=$(unset CLAUDECODE && cat "$HANDOFF_DIR/handoff.md" | claude \
   --agent merlin-executor \
   -p \
   --permission-mode acceptEdits \
@@ -167,7 +167,7 @@ Spawn parallel fresh processes (use `&` and `wait`):
 ```bash
 # Plan 1 in worktree 1
 (cd "${REPO_ROOT}/../${REPO_NAME}-worktree-01" && \
-  cat "$HANDOFF_DIR/plan-01.md" | claude \
+  unset CLAUDECODE && cat "$HANDOFF_DIR/plan-01.md" | claude \
   --agent merlin-executor \
   -p \
   --permission-mode acceptEdits \
@@ -177,7 +177,7 @@ PID1=$!
 
 # Plan 2 in worktree 2
 (cd "${REPO_ROOT}/../${REPO_NAME}-worktree-02" && \
-  cat "$HANDOFF_DIR/plan-02.md" | claude \
+  unset CLAUDECODE && cat "$HANDOFF_DIR/plan-02.md" | claude \
   --agent merlin-executor \
   -p \
   --permission-mode acceptEdits \
@@ -238,7 +238,7 @@ Summary: <verification summary>
 ---END_VERIFY_RESULT---
 EOF
 
-VERIFY_RESULT=$(cat "/tmp/merlin-verify-$$/handoff.md" | claude \
+VERIFY_RESULT=$(unset CLAUDECODE && cat "/tmp/merlin-verify-$$/handoff.md" | claude \
   --agent merlin-verifier \
   -p \
   --permission-mode acceptEdits \

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

@@ -153,7 +153,7 @@ Checkpoint: <only if status=checkpoint — what you need>
 ## Step 9: Spawn Fresh Executor Process
 
 ```bash
-RESULT=$(cat "$HANDOFF_FILE" | claude \
+RESULT=$(unset CLAUDECODE && cat "$HANDOFF_FILE" | claude \
   --agent merlin-executor \
   -p \
   --permission-mode acceptEdits \
@@ -295,7 +295,7 @@ Summary: <what was verified>
 VERIFY
 
 # Spawn fresh verifier
-VERIFY_RESULT=$(cat "/tmp/merlin-verify-$$/handoff.md" | claude \
+VERIFY_RESULT=$(unset CLAUDECODE && cat "/tmp/merlin-verify-$$/handoff.md" | claude \
   --agent merlin-verifier \
   -p \
   --permission-mode acceptEdits \

package/files/commands/merlin/map-codebase.md

@@ -89,22 +89,22 @@ Focus area: ${FOCUS_AREA}
 EOF
 
 # Spawn all 4 in parallel as fresh processes
-(cat "$HANDOFF_DIR/tech.md" | claude --agent merlin-codebase-mapper -p \
+(unset CLAUDECODE && cat "$HANDOFF_DIR/tech.md" | claude --agent merlin-codebase-mapper -p \
   --permission-mode acceptEdits --output-format text \
   > "$HANDOFF_DIR/result-tech.txt" 2>&1) &
 PID1=$!
 
-(cat "$HANDOFF_DIR/arch.md" | claude --agent merlin-codebase-mapper -p \
+(unset CLAUDECODE && cat "$HANDOFF_DIR/arch.md" | claude --agent merlin-codebase-mapper -p \
   --permission-mode acceptEdits --output-format text \
   > "$HANDOFF_DIR/result-arch.txt" 2>&1) &
 PID2=$!
 
-(cat "$HANDOFF_DIR/quality.md" | claude --agent merlin-codebase-mapper -p \
+(unset CLAUDECODE && cat "$HANDOFF_DIR/quality.md" | claude --agent merlin-codebase-mapper -p \
   --permission-mode acceptEdits --output-format text \
   > "$HANDOFF_DIR/result-quality.txt" 2>&1) &
 PID3=$!
 
-(cat "$HANDOFF_DIR/concerns.md" | claude --agent merlin-codebase-mapper -p \
+(unset CLAUDECODE && cat "$HANDOFF_DIR/concerns.md" | claude --agent merlin-codebase-mapper -p \
   --permission-mode acceptEdits --output-format text \
   > "$HANDOFF_DIR/result-concerns.txt" 2>&1) &
 PID4=$!

package/files/commands/merlin/next.md

@@ -0,0 +1,240 @@
+---
+name: merlin:next
+description: Smart navigator — detects state and recommends the single best next action
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - mcp__merlin__merlin_get_project_status
+  - mcp__merlin__merlin_get_context
+  - mcp__merlin__merlin_get_next_task
+  - mcp__merlin__merlin_ensure_tasks
+---
+
+<objective>
+Answer one question: what should you do RIGHT NOW?
+
+This is the "I just opened my laptop" command. No long reports. No history.
+One recommended action, instantly. Merlin Sights powers the detection so the
+answer reflects real project state, not guesswork.
+</objective>
+
+
+<process>
+
+<step name="status">
+**Get project status from Merlin Cloud.**
+
+```
+Call: merlin_get_project_status
+```
+
+Note: checkpoint existence, blocker flags, task counts, recommended_action.
+</step>
+
+<step name="detect">
+**Detect state in priority order. Stop at the first match.**
+
+**P1 — Active checkpoint**
+
+If `merlin_get_project_status` reports a checkpoint, or if
+`.planning/HANDOFF.md` exists → go to **Route: Resume**.
+
+**P2 — Blockers**
+
+If STATE.md contains lines under a "Blockers" heading with content →
+go to **Route: Blocker**.
+
+**P3 — UAT gaps**
+
+```bash
+grep -rl "status: diagnosed" .planning/phases/ 2>/dev/null | head -1
+```
+
+If any file found → go to **Route: UAT Gaps**.
+
+**P4 — Unexecuted plans**
+
+```bash
+ls -1 .planning/phases/*/*.planning*-PLAN.md 2>/dev/null
+ls -1 .planning/phases/*/*-PLAN.md 2>/dev/null
+ls -1 .planning/phases/*/*-SUMMARY.md 2>/dev/null
+```
+
+Compare plan count vs summary count per phase directory.
+If any phase has more PLANs than SUMMARYs → go to **Route: Execute Plan**.
+
+**P5 — Unplanned phase**
+
+Read ROADMAP.md. Check current phase number from STATE.md.
+If the current phase directory has 0 PLAN.md files → go to **Route: Plan Phase**.
+If the next phase directory does not exist yet → go to **Route: Plan Phase** (next N).
+
+**P6 — Pending todos**
+
+```bash
+ls .planning/todos/pending/*.md 2>/dev/null | wc -l
+```
+
+If count > 0 → go to **Route: Todos**.
+
+**P7 — Milestone complete**
+
+If all phases in current milestone have matching PLAN+SUMMARY counts and
+no ROADMAP.md exists but PROJECT.md does → go to **Route: Between Milestones**.
+
+If ROADMAP.md exists and current phase = highest phase number in milestone
+and all plans have summaries → go to **Route: Complete Milestone**.
+
+**P8 — No planning structure**
+
+If no `.planning/` directory → go to **Route: No Project**.
+If no ROADMAP.md and no PROJECT.md → go to **Route: No Project**.
+If PROJECT.md exists but no ROADMAP.md → go to **Route: New Roadmap**.
+</step>
+
+<step name="output">
+**Output exactly one recommendation. Be brief.**
+
+---
+
+**Route: Resume**
+
+```
+Next  ->  /merlin:resume-work
+         Checkpoint found: [description from HANDOFF.md or status]
+
+[1] Resume from checkpoint
+[2] See full status  (/merlin:progress)
+[3] Do something else
+```
+
+---
+
+**Route: Blocker**
+
+```
+Next  ->  Address blocker first
+         [blocker description from STATE.md]
+
+Resolve the blocker, then re-run /merlin:next.
+
+[1] See full status  (/merlin:progress)
+```
+
+---
+
+**Route: UAT Gaps**
+
+```
+Next  ->  /merlin:plan-phase [N] --gaps
+         [N] gap(s) found in [phase-name] UAT
+
+[1] Plan gap fixes
+[2] See full status  (/merlin:progress)
+[3] Skip and continue
+```
+
+---
+
+**Route: Execute Plan**
+
+Find the first PLAN.md without a matching SUMMARY.md. Read its `<objective>`.
+
+```
+Next  ->  /merlin:execute-plan [full-path-to-PLAN.md]
+         [Phase N, Plan M]: [one-line objective]
+
+[1] Execute this plan
+[2] See full status  (/merlin:progress)
+[3] Do something else
+```
+
+---
+
+**Route: Plan Phase**
+
+```
+Next  ->  /merlin:plan-phase [N]
+         Phase [N]: [phase name from ROADMAP.md]
+
+[1] Plan this phase
+[2] Gather context first  (/merlin:discuss-phase [N])
+[3] See full status  (/merlin:progress)
+```
+
+---
+
+**Route: Todos**
+
+```
+Next  ->  /merlin:check-todos
+         [count] pending todo(s) need review
+
+[1] Review todos
+[2] See full status  (/merlin:progress)
+[3] Skip for now
+```
+
+---
+
+**Route: Complete Milestone**
+
+```
+Next  ->  /merlin:complete-milestone
+         All phases done — milestone ready to close
+
+[1] Complete milestone
+[2] Verify first  (/merlin:verify-work)
+[3] See full status  (/merlin:progress)
+```
+
+---
+
+**Route: Between Milestones**
+
+```
+Next  ->  /merlin:discuss-milestone
+         Last milestone complete — ready to plan what's next
+
+[1] Discuss next milestone
+[2] See full status  (/merlin:progress)
+```
+
+---
+
+**Route: New Roadmap**
+
+```
+Next  ->  /merlin:create-roadmap
+         PROJECT.md exists but no roadmap yet
+
+[1] Create roadmap
+[2] See full status  (/merlin:progress)
+```
+
+---
+
+**Route: No Project**
+
+```
+Next  ->  /merlin:new-project
+         No planning structure found
+
+[1] Start a new project
+```
+
+---
+
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Responds in under 10 lines of output
+- [ ] One clear action recommended
+- [ ] Priority order respected (checkpoint > blockers > UAT > execute > plan)
+- [ ] Numbered options always present
+- [ ] Full status always available as an option
+</success_criteria>

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

@@ -149,7 +149,7 @@ Summary: <2-3 sentence summary>
 ## Step 8: Spawn Fresh Planner Process
 
 ```bash
-RESULT=$(cat "$HANDOFF_FILE" | claude \
+RESULT=$(unset CLAUDECODE && cat "$HANDOFF_FILE" | claude \
   --agent merlin-planner \
   -p \
   --permission-mode acceptEdits \