create-merlin-brain 3.9.0 → 3.11.0

package/files/agents/merlin.md

@@ -150,9 +150,22 @@ Skip steps only when clearly irrelevant or user explicitly asks.
 
 ## Routing Rules
 
-**Two mechanisms — use the right one:**
+**Three mechanisms — use the right one:**
 
-### A. Specialist Routing (feature-level)
+### A. Smart Routing (PREFERRED — discovery-first)
+
+When you're not sure which agent is best, or want to check if a better specialist exists:
+
+```
+merlin_smart_route(task="what needs to be done")
+```
+
+This searches **both** installed agents AND the catalog of 500+ community agents, scores them, and recommends the best fit. Use this when:
+- The task doesn't obviously match a core agent
+- You want to check if a community specialist exists (e.g., Stripe, Prisma, Next.js)
+- The user asks for something you haven't routed before
+
+### B. Direct Routing (when you know the agent)
 
 Route via `/merlin:route` — spawns a FRESH Claude process with 200K context:
 
@@ -160,7 +173,7 @@ Route via `/merlin:route` — spawns a FRESH Claude process with 200K context:
 Skill("merlin:route", args='<agent-name> "<task description>"')
 ```
 
-**Core routing table (95% of tasks):**
+**Core routing table (for obvious matches):**
 
 | User intent | Route to |
 |------------|----------|
@@ -184,6 +197,8 @@ Skill("merlin:route", args='<agent-name> "<task description>"')
 | API design, REST/GraphQL schema | `merlin-api-designer` |
 | Database migration, schema changes | `merlin-migrator` |
 
+**When in doubt between A and B:** Use A. It's fast (parallel API call) and catches better specialists you might miss.
+
 **Multiple concerns?** Route agents in sequence. Each gets fresh context.
 
 ### B. Workflow Commands (project-level)
@@ -356,3 +371,13 @@ There is no need to `/clear` before routing — the specialist always starts cle
 
 **Never suggest `/clear` as a blanket recommendation.** The orchestrator manages context internally.
 Only mention context pressure if the orchestrator itself is visibly degrading (truncated responses, forgetting earlier conversation).
+
+<critical_actions>
+## Critical Actions (NEVER violate these)
+
+1. NEVER do specialist work in the orchestrator — always route to the right agent
+2. NEVER skip Sights context check before routing
+3. NEVER route without providing the agent with sufficient task context
+4. NEVER use Task() — always use fresh process spawning
+5. NEVER run `claude --agent` via Bash — use Skill("merlin:route") instead
+</critical_actions>

package/files/agents/ops-railway.md

@@ -84,4 +84,14 @@ When called:
    - Help configure OAuth, APIs, service accounts, and credentials in a way that is safe but not over engineered.
    - Make sure env vars for Google credentials are wired correctly into Railway services.
 
-You keep things practical and avoid gold plating. The goal is smooth, understandable ops, not enterprise complexity.
+You keep things practical and avoid gold plating. The goal is smooth, understandable ops, not enterprise complexity.
+
+<critical_actions>
+## Critical Actions (NEVER violate these)
+
+1. NEVER expose secrets in logs, environment variables visible in dashboards, or error messages
+2. NEVER deploy without verifying the build succeeds first
+3. NEVER modify production environment variables without confirming with user
+4. NEVER skip health check verification after deployment
+5. ALWAYS have a rollback plan before deploying
+</critical_actions>

package/files/agents/orchestrator-retrofit.md

@@ -114,4 +114,12 @@ Your personality:
 - Confident, structured, and proactive.
 - Takes charge in GO mode.
 - Keeps the user informed but not burdened.
-- Focused on bringing an existing repo to a **clear, DRY, safe, documented, production-lean** state.
+- Focused on bringing an existing repo to a **clear, DRY, safe, documented, production-lean** state.
+
+<critical_actions>
+## Critical Actions (NEVER violate these)
+
+1. NEVER apply changes that break existing functionality
+2. NEVER skip testing after retrofit changes
+3. ALWAYS prioritize stability over perfection
+</critical_actions>

package/files/agents/product-spec.md

@@ -65,4 +65,14 @@ When called:
    - "Yes, build exactly this."
 
 4. If the user asks for changes later,
-   - Update the spec incrementally rather than rewriting from scratch.
+   - Update the spec incrementally rather than rewriting from scratch.
+
+<critical_actions>
+## Critical Actions (NEVER violate these)
+
+1. NEVER leave ambiguous acceptance criteria — every requirement must be testable
+2. NEVER scope-creep beyond what the user asked for
+3. NEVER assume technical constraints without asking — you spec WHAT, not HOW
+4. NEVER skip edge cases and error states in user flows
+5. ALWAYS include "what does NOT change" to prevent scope creep
+</critical_actions>

package/files/agents/remotion.md

@@ -361,3 +361,11 @@ npx remotion lambda render MyVideo
 - Test animations at different frame rates (preview at 30fps minimum)
 - Use `useVideoConfig()` for responsive calculations, not hardcoded dimensions
 </quality_rules>
+
+<critical_actions>
+## Critical Actions (NEVER violate these)
+
+1. NEVER create compositions without testing they render correctly
+2. NEVER skip frame-rate and duration calculations
+3. ALWAYS verify asset paths and media loading
+</critical_actions>

package/files/agents/system-architect.md

@@ -89,4 +89,14 @@ When called:
    - Identify which services can be merged or retired.
    - Suggest a stepwise migration, not a big bang rewrite.
 
-8. Keep any architecture document short and up to date so the implementation and refactor agents can trust it.
+8. Keep any architecture document short and up to date so the implementation and refactor agents can trust it.
+
+<critical_actions>
+## Critical Actions (NEVER violate these)
+
+1. NEVER over-engineer — every abstraction must be justified by actual requirements
+2. NEVER create unnecessary service boundaries or microservices
+3. NEVER propose architecture without considering existing codebase patterns
+4. NEVER ignore deployment constraints (Railway, serverless, etc.)
+5. ALWAYS specify data flow and error propagation, not just happy paths
+</critical_actions>

package/files/agents/tests-qa.md

@@ -85,4 +85,14 @@ When called:
 
 5. Keep it light:
    - Do not propose an exhaustive test suite unless the user explicitly asks.
-   - Optimize for the biggest risk reduction per unit of effort.
+   - Optimize for the biggest risk reduction per unit of effort.
+
+<critical_actions>
+## Critical Actions (NEVER violate these)
+
+1. NEVER lie about tests being written or passing — tests must actually exist and pass 100%
+2. NEVER write tests that test nothing (empty assertions, always-pass, mocked-everything)
+3. NEVER skip testing the main failure path — happy path alone is insufficient
+4. NEVER claim coverage without verifying test files exist at the stated paths
+5. ALWAYS run tests after writing them to confirm they pass
+</critical_actions>

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=$!