create-merlin-brain 3.10.0 → 3.12.0

package/files/commands/merlin/promote.md

@@ -0,0 +1,176 @@
+---
+name: merlin:promote
+description: Promote a high-confidence learned behavior into a permanent reusable skill or agent
+argument-hint: "[behavior-id or keyword]"
+allowed-tools:
+  - mcp__merlin__merlin_get_behaviors
+  - mcp__merlin__merlin_list_promotion_candidates
+  - mcp__merlin__merlin_promote_behavior
+  - AskUserQuestion
+---
+
+<objective>
+Turn proven learned behaviors into first-class, permanent skills.
+
+Behaviors with confidence >= 0.85 have been validated enough to be formalized. This command
+walks you through selecting candidates, reviewing auto-generated skill drafts, editing them,
+and saving them to the project's Sights catalog — where they become discoverable by all agents.
+</objective>
+
+<process>
+
+## Step 1: Parse Arguments
+
+Extract from $ARGUMENTS (optional):
+- **behavior-id**: A specific behavior UUID to promote directly
+- **keyword**: A word/phrase to filter candidates by pattern text
+
+If no argument is given, proceed to list all candidates.
+
+## Step 2: Load Promotion Candidates
+
+Call `merlin_list_promotion_candidates` with no filters.
+
+If the result says there are no candidates yet:
+```
+No behaviors are ready for promotion yet.
+Confidence >= 0.85 is required. Keep applying behaviors — each successful
+application adds +0.05 confidence.
+
+Use /merlin:check-behaviors to see current confidence levels.
+```
+Then stop.
+
+## Step 3: Display Candidates
+
+Present the candidates in a numbered list:
+
+```
+Promotion Candidates  ({N} behaviors ready)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[1] {pattern}
+    Action: {action}
+    Confidence: {confidence} | Applied: {timesApplied}x
+    ID: {id}
+
+[2] ...
+
+[A] Promote ALL candidates
+[Q] Quit
+```
+
+## Step 4: Ask User to Select
+
+Ask the user which behavior(s) to promote. Accept:
+- A single number (promote that one)
+- Multiple numbers comma-separated ("1,3")
+- "A" to promote all
+- "Q" to quit
+
+If $ARGUMENTS had a valid behavior-id or keyword, auto-select matching candidates
+and skip the question (just confirm: "Found behavior matching '{keyword}' — promoting it.").
+
+## Step 5: Generate Skill Draft(s)
+
+For the selected behaviors, call:
+
+```
+merlin_promote_behavior(
+  behaviorId: "{id}",  // or omit and use patternKeyword if multi-select
+  repoUrl: optional
+)
+```
+
+If multiple behaviors selected, call once with no behaviorId to get all clustered:
+```
+merlin_promote_behavior()  // clusters ALL candidates automatically
+```
+
+## Step 6: Present Draft for Review
+
+Show each draft inside a code block. Then ask:
+
+```
+Review the skill draft above.
+
+[A] Approve and save as-is
+[E] Edit then save  (paste your edited version)
+[S] Skip this skill
+[Q] Quit without saving
+```
+
+If the user chooses **E**:
+- Ask them to paste their edited SKILL.md content
+- Use their version as the skillDraft
+
+## Step 7: Save Approved Draft
+
+When user approves (A or E):
+
+```
+merlin_promote_behavior(
+  approved: true,
+  skillDraft: "{draft content}",
+  repoUrl: optional
+)
+```
+
+Show the confirmation message returned by the tool.
+
+## Step 8: Handle Multiple Drafts
+
+If there were multiple skill drafts, loop through each (Step 6-7) before finishing.
+
+## Step 9: Summary
+
+After all drafts are handled:
+
+```
+Promotion complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Saved: {N} skill(s)
+Skipped: {M} skill(s)
+
+Saved skills are now in the Sights index and discoverable by:
+  merlin_get_context("skill: {name}")
+
+Next: Reference these skills in agent prompts or route tasks to them
+      via /merlin:route.
+```
+
+</process>
+
+<behavior_clustering>
+
+When multiple behaviors share overlapping trigger keywords (Jaccard similarity >= 0.3),
+the promotion tool automatically clusters them into a single skill with multiple actions.
+This keeps the agent catalog focused rather than fragmenting related patterns.
+
+Example: "always run tests after editing src/" and "always run lint on TypeScript files"
+would cluster into a "QualityGates" skill with two actions.
+
+The draft shows which behaviors were merged and preserves their individual trigger conditions.
+
+</behavior_clustering>
+
+<error_handling>
+
+| Condition | Action |
+|-----------|--------|
+| No candidates yet | Explain threshold, show path to get there |
+| Behavior ID not found | Show available IDs, ask user to re-select |
+| API unavailable | Inform user, suggest trying again later |
+| User skips all drafts | Exit cleanly with "Nothing saved" message |
+| Draft edit is empty | Ask again, do not save empty skill |
+
+</error_handling>
+
+<design_notes>
+- This command is a guided UX wrapper around merlin_promote_behavior and merlin_list_promotion_candidates
+- The tools do the heavy lifting (clustering, draft generation, saving)
+- Always show the draft BEFORE saving — never auto-save without user review
+- Skill drafts are saved to the Sights catalog as discoveries, not as local files
+- Skills are retrievable with merlin_get_context("skill: {name}")
+</design_notes>

package/files/commands/merlin/quick.md

@@ -0,0 +1,229 @@
+---
+name: merlin:quick
+description: Run an ad-hoc task with Merlin guarantees but no ceremony — no plan files, no phase tracking
+argument-hint: "\"task description\""
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - Write
+  - AskUserQuestion
+  - mcp__merlin__merlin_get_context
+  - mcp__merlin__merlin_search
+  - mcp__merlin__merlin_find_files
+---
+
+<objective>
+Handle ad-hoc tasks fast — no PLAN.md, no STATE.md updates, no phase ceremony.
+
+Skips: research agents, discussion phase, plan-checking, post-execution verification.
+Provides: Sights context injection, specialist routing, fresh 200K process, git diff review.
+
+Perfect for: bug fixes, small features, one-off tasks, config changes, experiments.
+Use the full workflow (`/merlin:plan-phase` + `/merlin:execute-plan`) for anything that touches core architecture or spans multiple files significantly.
+
+Estimated 40-50% token reduction vs full workflow.
+</objective>
+
+<context>
+User's task: $ARGUMENTS
+</context>
+
+<process>
+
+## Step 1: Parse Task
+
+Extract task description from $ARGUMENTS (the quoted string).
+
+If no arguments provided:
+```
+Usage: /merlin:quick "task description"
+
+Examples:
+  /merlin:quick "add dark mode toggle to settings page"
+  /merlin:quick "fix the 404 on /api/users when id is missing"
+  /merlin:quick "write tests for the auth middleware"
+  /merlin:quick "update README with new env vars"
+```
+Exit.
+
+## Step 2: Get Sights Context
+
+```
+Call: merlin_get_context
+Task: "{task-description}"
+```
+
+Store as SIGHTS_CONTEXT. If unavailable, use Glob, Grep, and Read to discover relevant files manually.
+
+## Step 3: Determine Best Agent
+
+Route based on task description keywords:
+
+| Task type | Agent |
+|-----------|-------|
+| Code, feature, fix, refactor, implement, add, change, update (code) | `implementation-dev` |
+| Test, spec, coverage, unit, integration, e2e | `tests-qa` |
+| Docs, README, comment, document, explain | `docs-keeper` |
+| Debug, error, crash, broken, failing, investigate | `merlin-debugger` |
+| API design, endpoint, schema, contract | `merlin-api-designer` |
+| Performance, slow, optimize, bottleneck | `merlin-performance` |
+| Frontend, UI, component, styling, CSS | `merlin-frontend` |
+| Migration, schema change, data | `merlin-migrator` |
+| Security, vulnerability, auth, permissions | `merlin-security` |
+
+If unclear, default to `implementation-dev`.
+
+State the chosen agent and why, one line.
+
+## Step 4: Clarify If Needed
+
+If the task is ambiguous in a way that would cause the agent to make wrong assumptions, ask ONE focused question using AskUserQuestion.
+
+Examples of good clarifying questions:
+- "Should this update the existing endpoint or create a new one?"
+- "Is this for the frontend or backend auth layer?"
+
+If the task is clear, skip this step and note: "Task is clear — spawning {agent} directly."
+
+## Step 5: Spawn Fresh Agent
+
+Write a handoff file and spawn the specialist in a fresh 200K context.
+
+```bash
+HANDOFF_DIR="/tmp/merlin-quick-$$"
+mkdir -p "$HANDOFF_DIR"
+HANDOFF_FILE="$HANDOFF_DIR/handoff.md"
+RESULT_FILE="$HANDOFF_DIR/result.md"
+```
+
+Write handoff content:
+
+```markdown
+# Quick Task Handoff
+
+## Your Task
+{task-description}
+
+## Mode
+automated — make reasonable assumptions. Do NOT output CHECKPOINT_NEEDED.
+State any assumptions you made at the end.
+
+## Merlin Sights Context
+{SIGHTS_CONTEXT}
+
+## Constraints
+- This is a quick task — scope to what's described, no more
+- Prefer targeted changes over broad refactors
+- If you discover something bigger that needs attention, note it in Decisions but do NOT fix it
+- Commit your changes when done with a clear conventional commit message
+
+## Result Protocol
+When done, output this exact block at the END of your response:
+
+---QUICK_RESULT---
+Status: completed | error
+Summary: <2-3 sentence summary of what you did>
+Files-Changed: <comma-separated list of files modified>
+Decisions: <key decisions and assumptions, one per line>
+Follow-Up: <anything bigger discovered that needs attention, one per line>
+---END_QUICK_RESULT---
+
+Also write a detailed result to: {RESULT_FILE}
+```
+
+Spawn:
+
+```bash
+unset CLAUDECODE && cat "$HANDOFF_FILE" | claude \
+  --agent {agent-name} \
+  -p \
+  --permission-mode acceptEdits \
+  --output-format text \
+  2>&1
+```
+
+Use Bash tool with `timeout: 600000` (10 minutes max).
+
+## Step 6: Review Changes
+
+After the agent completes:
+
+1. Parse the `---QUICK_RESULT---` block from output.
+2. Run a quick git diff review:
+
+```bash
+git diff --stat HEAD 2>/dev/null
+git diff HEAD 2>/dev/null | head -100
+```
+
+3. Check exit code — non-zero means error; show output and offer retry.
+
+4. Clean up:
+```bash
+rm -rf "$HANDOFF_DIR"
+```
+
+## Step 7: Present Result
+
+```
+════════════════════════════════════════
+ Quick Task — {agent-name} completed
+════════════════════════════════════════
+
+{summary from result}
+
+Files changed:
+{files-changed list}
+
+Decisions / Assumptions:
+{decisions from result}
+
+{If follow-up items exist:}
+Noticed (not fixed):
+{follow-up items — these may warrant a full workflow}
+
+────────────────────────────────────────
+Looks good? Run: git add -p && git commit
+Or discard:    git checkout .
+────────────────────────────────────────
+```
+
+If any follow-up items were surfaced, suggest:
+```
+For larger work found above, consider:
+/merlin:plan-phase — full workflow with planning + execution
+```
+
+</process>
+
+<agent_selection_notes>
+- `implementation-dev` handles the vast majority of quick code tasks
+- Only switch to a specialist if the task is clearly domain-specific
+- When in doubt, `implementation-dev` is the right default — it knows to call other agents if needed
+- Never spawn `merlin-planner`, `system-architect`, or `product-spec` for quick tasks — those are for full workflow phases
+</agent_selection_notes>
+
+<error_handling>
+
+| Condition | Action |
+|-----------|--------|
+| No arguments | Show usage examples, exit |
+| Sights unavailable | Proceed with manual discovery via Glob/Grep |
+| Agent not found | Default to `implementation-dev` |
+| Spawn fails (exit != 0) | Show error output, offer retry or `/merlin:debug` |
+| Spawn times out (>10 min) | Warn: task too large for quick mode, suggest full workflow |
+| No result block in output | Treat full output as summary, still run git diff review |
+| Nothing changed in git | Note: agent may have analyzed only — confirm with user |
+
+</error_handling>
+
+<design_notes>
+- NEVER use Task() — it shares parent context, not true isolation
+- ALWAYS use `claude --agent <name> -p` via Bash — true fresh process
+- No PLAN.md written — that's the whole point of quick mode
+- No STATE.md update — quick tasks are ephemeral by design
+- The git diff IS the verification — no formal verify-work agent
+- For anything that feels like it needs a plan, redirect to the full workflow
+</design_notes>

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>