create-merlin-brain 3.9.0 → 3.11.0

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 \

package/files/commands/merlin/readiness-gate.md

@@ -0,0 +1,208 @@
+---
+name: merlin:readiness-gate
+description: Validate planning completeness before implementation begins
+argument-hint: "<phase-number>"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - mcp__merlin__merlin_get_context
+  - mcp__merlin__merlin_get_project_status
+---
+
+<objective>
+Validate that planning artifacts are complete and coherent before any implementation begins.
+
+Prevents the #1 failure mode: starting to code with incomplete, ambiguous, or uncovered specs.
+
+Runs 6 checks and returns a READY / NEEDS WORK / NOT READY verdict with specific issues to fix.
+</objective>
+
+<process>
+
+## Step 1: Parse Arguments
+
+Extract from $ARGUMENTS:
+- **phase**: Phase number (e.g., "4", "2.1") — or "current" to auto-detect from STATE.md
+
+```bash
+# If "current" or empty, read current phase from STATE
+head -30 .planning/STATE.md 2>/dev/null
+```
+
+Resolve phase name from ROADMAP.md:
+
+```bash
+grep -A 5 "Phase ${PHASE_NUM}" .planning/ROADMAP.md 2>/dev/null | head -6
+```
+
+## Step 2: Document Discovery
+
+Check that required planning documents exist. Record each as present (✅) or missing (❌).
+
+```bash
+ls .planning/PROJECT.md 2>/dev/null
+ls .planning/ROADMAP.md 2>/dev/null
+ls .planning/REQUIREMENTS.md 2>/dev/null
+ls .planning/phases/${PHASE_DIR}/*-PLAN.md 2>/dev/null
+```
+
+Track:
+- `doc_project`: present or missing
+- `doc_roadmap`: present or missing
+- `doc_requirements`: present or missing
+- `plan_count`: number of PLAN.md files found for the phase
+
+If `doc_project`, `doc_roadmap`, and `doc_requirements` are all missing: emit **NOT READY** immediately — planning has not started. Skip remaining steps.
+
+## Step 3: Requirements Analysis
+
+Read `.planning/REQUIREMENTS.md`. For each requirement, check:
+
+1. Has at least one explicit acceptance criterion (a testable condition — not a vague goal)
+2. Does not contain ambiguous modal verbs: "should", "might", "could", "may"
+3. Is expressed as a testable condition (something that can pass or fail a test)
+
+```bash
+grep -n "should\|might\|could\| may " .planning/REQUIREMENTS.md 2>/dev/null
+```
+
+Track:
+- `req_total`: total requirements found
+- `req_testable`: requirements that meet all three conditions
+- `req_ambiguous`: list of requirement IDs / lines with vague language
+
+Result label: `{req_testable}/{req_total} requirements are testable`
+
+## Step 4: Plan Coverage
+
+Cross-reference PLAN.md task descriptions against requirement IDs in REQUIREMENTS.md.
+
+For each requirement ID (e.g., R-4.1, R-4.2), check whether at least one PLAN.md file references or addresses it — either by ID or by matching keyword.
+
+```bash
+# List requirement IDs
+grep -E "^R-[0-9]" .planning/REQUIREMENTS.md 2>/dev/null
+
+# Check plan files for coverage
+grep -l "${REQ_ID}" .planning/phases/${PHASE_DIR}/*-PLAN.md 2>/dev/null
+```
+
+Track:
+- `covered_reqs`: requirements mentioned in at least one plan
+- `uncovered_reqs`: requirements with no matching plan task (list them)
+
+Result label: flag each uncovered requirement by ID.
+
+## Step 5: Dependency Check
+
+Verify upstream phases are complete and external dependencies are documented.
+
+```bash
+# Check that all prior phases have SUMMARY.md
+for prev_phase in all phases numbered below current; do
+  ls .planning/phases/${prev_phase_dir}/*-SUMMARY.md 2>/dev/null
+done
+
+# Check STATE.md for documented external dependencies
+grep -i "depend\|external\|blocker\|prerequisite" .planning/STATE.md 2>/dev/null
+```
+
+Track:
+- `prior_phases_complete`: all prior phases have at least one SUMMARY.md (true/false)
+- `missing_summaries`: list of prior phase directories with no SUMMARY.md
+- `external_deps_noted`: whether dependencies section exists in STATE.md
+
+## Step 6: Plan Quality
+
+For each PLAN.md in the phase, check:
+
+1. Has a non-empty `<objective>` section
+2. Has at least one explicit success criterion
+3. References specific file paths (not just vague descriptions like "update the code")
+4. Scope is reasonable — fewer than 15 distinct tasks in one plan
+
+```bash
+# Read each PLAN.md for the phase
+for plan in .planning/phases/${PHASE_DIR}/*-PLAN.md; do
+  grep -c "<objective>" "$plan" 2>/dev/null
+  grep -i "success.criteria\|acceptance\|done when" "$plan" 2>/dev/null
+  grep -E "\.(ts|js|py|go|md|json|yaml|sh)" "$plan" 2>/dev/null | wc -l
+done
+```
+
+Track per plan:
+- `has_objective`: true/false
+- `has_success_criteria`: true/false
+- `has_file_refs`: true/false
+- `quality_issues`: list of specific deficiencies per plan name
+
+## Step 7: Final Assessment
+
+Compute verdict:
+
+| Condition | Verdict |
+|-----------|---------|
+| Any required doc missing | NOT READY |
+| Prior phases incomplete | NOT READY |
+| req_testable < 50% of req_total | NOT READY |
+| 1–2 uncovered requirements OR plan quality issues | NEEDS WORK |
+| All checks pass | READY |
+
+Collect all issues into a numbered list.
+
+Present the full report:
+
+```
+🔮 **Readiness Gate** · Phase {N}: {Phase Name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+{icon} Document Discovery      — {summary}
+{icon} Requirements Analysis   — {req_testable}/{req_total} requirements are testable
+{icon} Plan Coverage           — {covered}/{total} requirements addressed
+{icon} Dependency Check        — {prior phases summary}
+{icon} Plan Quality            — {plan_count} plans, {quality_summary}
+{icon} Final Assessment        — {READY | NEEDS WORK | NOT READY}
+
+### Issues to Address:
+{numbered list of specific issues — omit if READY}
+
+### Verdict: {icon} {READY | NEEDS WORK | NOT READY}
+{one-line action — e.g., "Fix 2 issues before executing." or "You're clear to start."}
+
+[1] Fix issues and re-check
+[2] Execute anyway (not recommended — only shown for NEEDS WORK)
+[3] See per-plan detail
+```
+
+Icons: ✅ pass · ⚠️ warn · ❌ fail
+
+For READY: do not show options [1] and [2]. Offer only:
+
+```
+[1] Execute phase: /merlin:execute-phase {N}
+[2] See per-plan detail
+```
+
+</process>
+
+<critical_rules>
+
+**READ, DO NOT MODIFY.** This command never writes or edits planning files. It reports only.
+
+**BE SPECIFIC.** Every issue in the Issues list must name the exact file, requirement ID, or plan that needs attention.
+
+**FAIL FAST.** If all required docs are missing, emit NOT READY after Step 2 and stop.
+
+**DO NOT BLOCK UNCONDITIONALLY.** NEEDS WORK means improvable — still offer an override path. Only NOT READY hard-stops execution.
+
+</critical_rules>
+
+<success_criteria>
+- [ ] Phase resolved from args or STATE.md
+- [ ] All 6 checks executed and reported
+- [ ] Specific issues listed by file/ID (no vague feedback)
+- [ ] Correct verdict emitted (READY / NEEDS WORK / NOT READY)
+- [ ] Next steps offered based on verdict
+</success_criteria>

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

@@ -117,7 +117,7 @@ Write to: .planning/phases/{phase}-{slug}/{phase}-RESEARCH.md
 
 ```
 ## Spawn fresh researcher process via Bash:
-cat "$HANDOFF_DIR/handoff.md" | claude \
+unset CLAUDECODE && cat "$HANDOFF_DIR/handoff.md" | claude \
   --agent merlin-researcher \
   -p \
   --permission-mode acceptEdits \
@@ -152,7 +152,7 @@ Research file: @.planning/phases/{phase}-{slug}/{phase}-RESEARCH.md
 
 ```
 ## Spawn fresh continuation process via Bash:
-cat "$HANDOFF_DIR/continuation.md" | claude \
+unset CLAUDECODE && cat "$HANDOFF_DIR/continuation.md" | claude \
   --agent merlin-researcher \
   -p \
   --permission-mode acceptEdits \

package/files/commands/merlin/research-project.md

@@ -71,7 +71,7 @@ Spawn all 4 in parallel with rich context:
 
 ```
 ## Spawn fresh researcher via Bash:
-## Write the following to a handoff file, then: cat handoff.md | claude --agent merlin-researcher -p --permission-mode acceptEdits --output-format text
+## Write the following to a handoff file, then: unset CLAUDECODE && cat handoff.md | claude --agent merlin-researcher -p --permission-mode acceptEdits --output-format text
 ## Handoff content:
 # "
 <research_type>
@@ -113,7 +113,7 @@ Use template: ~/.claude/merlin/templates/research-project/STACK.md
 ## End of Stack research handoff
 
 ## Spawn fresh researcher via Bash:
-## Write the following to a handoff file, then: cat handoff.md | claude --agent merlin-researcher -p --permission-mode acceptEdits --output-format text
+## Write the following to a handoff file, then: unset CLAUDECODE && cat handoff.md | claude --agent merlin-researcher -p --permission-mode acceptEdits --output-format text
 ## Handoff content:
 # "
 <research_type>
@@ -155,7 +155,7 @@ Use template: ~/.claude/merlin/templates/research-project/FEATURES.md
 ## End of Features research handoff
 
 ## Spawn fresh researcher via Bash:
-## Write the following to a handoff file, then: cat handoff.md | claude --agent merlin-researcher -p --permission-mode acceptEdits --output-format text
+## Write the following to a handoff file, then: unset CLAUDECODE && cat handoff.md | claude --agent merlin-researcher -p --permission-mode acceptEdits --output-format text
 ## Handoff content:
 # "
 <research_type>
@@ -197,7 +197,7 @@ Use template: ~/.claude/merlin/templates/research-project/ARCHITECTURE.md
 ## End of Architecture research handoff
 
 ## Spawn fresh researcher via Bash:
-## Write the following to a handoff file, then: cat handoff.md | claude --agent merlin-researcher -p --permission-mode acceptEdits --output-format text
+## Write the following to a handoff file, then: unset CLAUDECODE && cat handoff.md | claude --agent merlin-researcher -p --permission-mode acceptEdits --output-format text
 ## Handoff content:
 # "
 <research_type>

package/files/commands/merlin/verify-work.md

@@ -83,7 +83,7 @@ Summary: <verification summary>
 ---END_VERIFY_RESULT---
 EOF
 
-RESULT=$(cat "$HANDOFF_DIR/handoff.md" | claude \
+RESULT=$(unset CLAUDECODE && cat "$HANDOFF_DIR/handoff.md" | claude \
   --agent merlin-work-verifier \
   -p \
   --permission-mode acceptEdits \

package/files/hooks/session-start.sh

@@ -1,9 +1,10 @@
 #!/usr/bin/env bash
 #
 # Merlin Hook: SessionStart (consolidated)
-# Does three things in a single hook (avoids 3x "success" messages):
+# Does four things in a single hook (avoids multiple "success" messages):
 #   1. Analytics: initialize session, log start event
 #   2. Agent sync: refresh agent files from cloud (background, max once/hour)
+#   2.5. Auto-update: check npm for new Merlin version (background, max once/24h)
 #   3. Context injection: output additionalContext for the session
 #
 # Always exits 0 — never blocks Claude Code startup.
@@ -130,6 +131,51 @@ _merlin_sync_agents() {
 }
 _merlin_sync_agents &
 
+# ── 2.5. Auto-update check (background, max once/24h) ─────────
+# Proactively upgrades Merlin when a new version is published.
+# Runs silently in background — never blocks session startup.
+_merlin_auto_update() {
+  local merlin_dir="${HOME}/.claude/merlin"
+  local last_check="${merlin_dir}/.last-update-check"
+  local version_file="${merlin_dir}/VERSION"
+  local check_interval=86400  # 24 hours
+
+  [ -d "${merlin_dir}" ] || return 0
+
+  # Skip if checked within the last 24 hours
+  if [ -f "${last_check}" ]; then
+    local last
+    last=$(cat "${last_check}" 2>/dev/null || echo "0")
+    [ $(($(date +%s) - last)) -lt ${check_interval} ] && return 0
+  fi
+
+  # Record check time immediately (prevents parallel checks)
+  date +%s > "${last_check}"
+
+  # Read installed version
+  local installed="0.0.0"
+  [ -f "${version_file}" ] && installed=$(cat "${version_file}" 2>/dev/null || echo "0.0.0")
+
+  # Determine channel from version string
+  local channel="latest"
+  echo "${installed}" | grep -q "beta" && channel="beta"
+
+  # Check npm for latest version (5s timeout)
+  local available
+  available=$(npm view "create-merlin-brain@${channel}" version 2>/dev/null) || return 0
+  [ -z "${available}" ] && return 0
+
+  # Compare versions (simple: if they differ and available is newer)
+  [ "${installed}" = "${available}" ] && return 0
+
+  # Version differs — run the upgrade
+  echo "merlin: updating ${installed} → ${available} ..." >&2
+  if npx "create-merlin-brain@${channel}" --yes 2>/dev/null; then
+    echo "merlin: updated to v${available}. Restart Claude Code for full effect." >&2
+  fi
+}
+_merlin_auto_update &
+
 # ── 3. Context injection (the only stdout output) ──────────────
 # Output additionalContext JSON for Claude to see at session start.
 # Full boot instructions are in CLAUDE.md — this is a lightweight nudge.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-merlin-brain",
-  "version": "3.9.0",
+  "version": "3.11.0",
   "description": "Merlin - The Ultimate AI Brain for Claude Code. One install: workflows, agents, loop, and Sights MCP server.",
   "type": "module",
   "main": "./dist/server/index.js",