create-merlin-brain 3.10.0 → 3.11.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-merlin-brain",
-  "version": "3.10.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",