create-merlin-brain 3.11.0 → 3.13.0

package/files/commands/merlin/profiles.md

@@ -0,0 +1,215 @@
+---
+name: merlin:profiles
+description: Manage config profiles — snapshot and switch between agent/hook/rule configurations
+argument-hint: "list | create <name> | switch <name> | delete <name>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - AskUserQuestion
+---
+
+<objective>
+Manage Merlin config profiles. A profile is a named snapshot of your active agents, rules overrides, and hook overrides.
+
+Built-in profiles: default, security-audit, frontend, backend.
+Custom profiles are stored in `~/.claude/merlin/profiles/<name>/`.
+
+Subcommands:
+- `list` — Show available profiles (built-in + custom) and which is active
+- `create <name>` — Snapshot current config into a new profile
+- `switch <name>` — Apply a profile's overrides to the active config
+- `delete <name>` — Remove a custom profile (built-in profiles cannot be deleted)
+</objective>
+
+<context>
+Arguments: $ARGUMENTS
+Profiles root: ~/.claude/merlin/profiles/
+Active profile marker: ~/.claude/merlin/profiles/.active
+</context>
+
+<process>
+
+## Step 1: Parse subcommand
+
+```bash
+ARGS="$ARGUMENTS"
+SUBCMD=$(echo "$ARGS" | awk '{print $1}')
+PROFILE_NAME=$(echo "$ARGS" | awk '{print $2}')
+PROFILES_DIR="$HOME/.claude/merlin/profiles"
+ACTIVE_MARKER="$PROFILES_DIR/.active"
+```
+
+---
+
+## Subcommand: list
+
+Show all available profiles, marking which is currently active.
+
+```bash
+mkdir -p "$PROFILES_DIR"
+ACTIVE=$(cat "$ACTIVE_MARKER" 2>/dev/null || echo "default")
+
+echo "Available profiles:"
+echo ""
+
+# Built-in profiles
+for name in default security-audit frontend backend; do
+  if [ "$name" = "$ACTIVE" ]; then
+    echo "  * $name (active) [built-in]"
+  else
+    echo "    $name [built-in]"
+  fi
+done
+
+# Custom profiles
+for dir in "$PROFILES_DIR"/*/; do
+  name=$(basename "$dir")
+  # Skip built-in names
+  case "$name" in
+    default|security-audit|frontend|backend) continue ;;
+  esac
+  if [ "$name" = "$ACTIVE" ]; then
+    echo "  * $name (active)"
+  else
+    echo "    $name"
+  fi
+done
+```
+
+If no custom profiles exist, note: "No custom profiles yet. Use `/merlin:profiles create <name>` to snapshot your current config."
+
+---
+
+## Subcommand: create <name>
+
+Snapshot the current active config into a new profile.
+
+Validate name:
+- Must match `[a-zA-Z0-9_-]+`
+- Must not conflict with built-in names (default, security-audit, frontend, backend)
+- Must not already exist (if it does, ask user to confirm overwrite)
+
+Steps:
+```bash
+PROFILE_DIR="$PROFILES_DIR/$PROFILE_NAME"
+mkdir -p "$PROFILE_DIR"
+
+# Snapshot CLAUDE.md overrides if present in project
+[ -f ".claude/CLAUDE.md" ] && cp ".claude/CLAUDE.md" "$PROFILE_DIR/CLAUDE.md"
+
+# Snapshot local settings hooks section
+if [ -f ".claude/settings.local.json" ]; then
+  cp ".claude/settings.local.json" "$PROFILE_DIR/settings.local.json"
+fi
+
+# Write profile metadata
+cat > "$PROFILE_DIR/profile.json" << METAEOF
+{
+  "name": "$PROFILE_NAME",
+  "created": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "description": "Custom profile"
+}
+METAEOF
+```
+
+Report: "Profile '$PROFILE_NAME' created. Switch to it with `/merlin:profiles switch $PROFILE_NAME`."
+
+---
+
+## Subcommand: switch <name>
+
+Apply a profile's overrides to the active config.
+
+### Built-in profile definitions
+
+**default** — Standard balanced config. No overrides applied; restores baseline.
+
+**security-audit** — Security-focused overrides:
+- Activates agents: merlin-security, merlin-sast-reviewer, merlin-secret-scanner, merlin-access-control-reviewer, merlin-dependency-auditor, merlin-input-validator
+- Remind user to run `/merlin:route merlin-security "full audit"` after switching
+
+**frontend** — Frontend-focused overrides:
+- Activates agents: merlin-frontend, implementation-dev, tests-qa, dry-refactor
+- Suggest: "Pair with `/merlin:route merlin-frontend` for component work"
+
+**backend** — Backend-focused overrides:
+- Activates agents: implementation-dev, merlin-api-designer, merlin-migrator, hardening-guard, tests-qa
+- Suggest: "Pair with `/merlin:route merlin-api-designer` for API design"
+
+### Custom profile switch
+
+```bash
+PROFILE_DIR="$PROFILES_DIR/$PROFILE_NAME"
+
+if [ ! -d "$PROFILE_DIR" ]; then
+  echo "Profile '$PROFILE_NAME' not found. Run \`/merlin:profiles list\` to see available profiles."
+  exit 1
+fi
+
+# Restore settings if snapshot exists
+if [ -f "$PROFILE_DIR/settings.local.json" ]; then
+  cp "$PROFILE_DIR/settings.local.json" ".claude/settings.local.json"
+fi
+if [ -f "$PROFILE_DIR/CLAUDE.md" ]; then
+  cp "$PROFILE_DIR/CLAUDE.md" ".claude/CLAUDE.md"
+fi
+
+# Mark active
+echo "$PROFILE_NAME" > "$ACTIVE_MARKER"
+```
+
+Report: "Switched to profile '$PROFILE_NAME'. Active config updated."
+
+---
+
+## Subcommand: delete <name>
+
+Remove a custom profile.
+
+Validate:
+- Cannot delete built-in profiles (default, security-audit, frontend, backend) — explain why
+- Cannot delete the currently active profile — prompt user to switch first
+
+```bash
+PROFILE_DIR="$PROFILES_DIR/$PROFILE_NAME"
+
+case "$PROFILE_NAME" in
+  default|security-audit|frontend|backend)
+    echo "Cannot delete built-in profile '$PROFILE_NAME'."
+    exit 0
+    ;;
+esac
+
+ACTIVE=$(cat "$ACTIVE_MARKER" 2>/dev/null || echo "default")
+if [ "$PROFILE_NAME" = "$ACTIVE" ]; then
+  echo "Cannot delete the active profile. Switch to another profile first."
+  exit 0
+fi
+
+if [ ! -d "$PROFILE_DIR" ]; then
+  echo "Profile '$PROFILE_NAME' not found."
+  exit 0
+fi
+
+rm -rf "$PROFILE_DIR"
+echo "Profile '$PROFILE_NAME' deleted."
+```
+
+---
+
+## Step 2: Display results
+
+After each operation, confirm the result clearly. For `list`, display the full table. For `switch`, confirm the new active profile and suggest relevant next steps.
+
+</process>
+
+<success_criteria>
+- [ ] `list` shows built-in and custom profiles, marks active
+- [ ] `create` snapshots current settings.local.json and CLAUDE.md
+- [ ] `switch` applies profile overrides and updates active marker
+- [ ] `delete` prevents removing built-in or active profiles
+- [ ] Built-in profiles are described without needing files on disk
+- [ ] All operations are idempotent and safe to re-run
+</success_criteria>

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/resume-work.md

@@ -12,7 +12,8 @@ allowed-tools:
 <objective>
 Restore complete project context and resume work seamlessly from previous session.
 
-Routes to the resume-project workflow which handles:
+First restores the last session snapshot (files changed, commits, agents used),
+then routes to the resume-project workflow which handles:
 
 - STATE.md loading (or reconstruction if missing)
 - Checkpoint detection (.continue-here files)
@@ -26,6 +27,25 @@ Routes to the resume-project workflow which handles:
 </execution_context>
 
 <process>
+## Step 1 — Restore last session context
+
+Call `merlin_session_restore` to load the previous session snapshot before
+opening any PLAN files. This gives immediate visibility into what was worked
+on, which files were modified, and which agents were used last time.
+
+If `merlin_session_restore` returns a session, show a brief summary:
+
+```
+## Last Session
+<timestamp> — <duration>
+<summary text>
+Files: <count> modified | Commits: <count> | Agents: <list>
+```
+
+If no session is found, note it and continue to Step 2.
+
+## Step 2 — Follow the resume-project workflow
+
 **Follow the resume-project workflow** from `@~/.claude/merlin/workflows/resume-project.md`.
 
 The workflow handles all resumption logic including:
@@ -37,4 +57,10 @@ The workflow handles all resumption logic including:
 5. Context-aware option offering (checks CONTEXT.md before suggesting plan vs discuss)
 6. Routing to appropriate next command
 7. Session continuity updates
+
+## Tips
+
+- Use `merlin_session_search(query="...")` to find a specific past session
+  (e.g., `merlin_session_search(query="OAuth login")`)
+- Use `merlin_session_restore(count=3)` to see the last 3 sessions at once
    </process>