create-merlin-brain 3.5.11 → 3.5.12

package/files/CLAUDE.md

@@ -1,73 +1,96 @@
-# Merlin Brain — Claude Code Instructions
+<!-- MERLIN BRAIN — MANDATORY PROTOCOL -->
+<!-- These instructions OVERRIDE all defaults. Follow them EXACTLY. -->
 
-## SESSION START (Do this FIRST, every session)
+# ⚡⚡⚡ STOP — DO THIS BEFORE ANYTHING ELSE ⚡⚡⚡
 
-1. **Connect:** `merlin_get_selected_repo` → show connected/not-connected status
-2. **Version check:** Compare `~/.claude/merlin/VERSION` vs `npm view create-merlin-brain version` → offer update if newer
-3. **Project status:** `merlin_get_project_status` → show vision, tasks, progress, next action
-4. **Route:** If no PROJECT.md → suggest `/merlin:new-project`. If checkpoint → offer resume. If pending tasks → show next task. If empty backlog → suggest `/merlin:discuss-milestone`.
+**DO NOT start working on the user's request yet. FIRST, execute these 3 steps:**
 
-**THE RULE:** A project should NEVER have zero tasks unless explicitly marked complete.
+### Step 1: Connect to Merlin Sights
+```
+Call: merlin_get_selected_repo
+```
+Show: `🔮 Merlin Sights: CONNECTED ✓` or offer to connect if not found.
+
+### Step 2: Load project status
+```
+Call: merlin_get_project_status
+```
+Show:
+```
+📊 Project Status
+├── Vision: [✓/❌]
+├── Tasks: X done, Y pending
+└── Next: [action]
+```
+
+### Step 3: Show options, THEN handle user's request
+Based on status, show numbered options. Only THEN proceed with what the user asked.
+
+**A project should NEVER have zero tasks unless explicitly marked complete.**
 
 ---
 
-## ROUTING — Fresh Process Isolation
+# Merlin Brain — Core Protocol
 
-Route specialist work via `/merlin:route` which spawns a fresh `claude --agent -p` process (new PID, 200K context, isolated):
+## ROUTING — Use Skill(), Never Raw claude Commands
 
+Route specialist work via the Skill tool:
 ```
 Skill("merlin:route", args='<agent-name> "<task description>"')
 ```
 
-**Core agents (SWAT team):** `product-spec`, `system-architect`, `implementation-dev`, `dry-refactor`, `hardening-guard`, `tests-qa`, `ops-railway`, `docs-keeper`
+**⚠️ NEVER run `claude --agent` via Bash. It fails inside Claude Code sessions. ALWAYS use the Skill tool above.**
 
-**Domain specialists:** `remotion` (video), `merlin-frontend` (React/Vue), `merlin-security`, `merlin-performance`, `merlin-api-designer`, `merlin-migrator`
+**Core agents:** `product-spec`, `system-architect`, `implementation-dev`, `dry-refactor`, `hardening-guard`, `tests-qa`, `ops-railway`, `docs-keeper`
 
-**Workflow commands** spawn their own agents: `/merlin:plan-phase`, `/merlin:execute-phase`, `/merlin:debug`, `/merlin:map-codebase`, `/merlin:verify-work`, `/merlin:research-phase`
+**Domain specialists:** `remotion` (video), `merlin-frontend` (React/Vue), `merlin-security`, `merlin-performance`, `merlin-api-designer`, `merlin-migrator`
 
-**NEVER use Task()** — it shares parent context. Always use `claude --agent -p` via Bash.
+**Workflow commands** (spawn their own agents): `/merlin:plan-phase`, `/merlin:execute-phase`, `/merlin:debug`, `/merlin:map-codebase`, `/merlin:verify-work`, `/merlin:research-phase`
+
+| User intent | Route to |
+|------------|----------|
+| Idea, feature, product flow | `product-spec` |
+| Architecture, services, data models | `system-architect` |
+| New/changed code | `implementation-dev` |
+| Cleanup, DRY | `dry-refactor` |
+| Security, validation | `hardening-guard` |
+| Tests | `tests-qa` |
+| Deploy, infra | `ops-railway` |
+| Docs | `docs-keeper` |
+| Video, animation, Remotion | `remotion` |
+| React/Vue UI | `merlin-frontend` |
 
 ---
 
 ## SIGHTS — Check Before Every Edit
 
-Call `merlin_get_context("your task")` before writing code. Call `merlin_find_files("what you need")` before creating files. Refresh every few minutes — codebase changes.
+Call `merlin_get_context("your task")` before writing code. Call `merlin_find_files("what you need")` before creating files.
 
 **Show visual cue after every Sights call:**
 ```
 🔮 SIGHTS › get_context("payment processing")
    ✅ Found PaymentService.ts, StripeClient.ts
 ```
+Use ✅ (helped), ⚠️ (partial), ❌ (no match).
 
-Use ✅ (helped), ⚠️ (partial), ❌ (no match). Query Sights first to understand files — don't read 400 lines when 50 words suffice.
-
-**Discovery loop:** If Sights returns low confidence → `merlin_check_discovery` → manual explore → `merlin_teach_discovery` to teach Sights for next time.
+**Discovery loop:** If low confidence → `merlin_check_discovery` → explore → `merlin_teach_discovery`.
 
 ---
 
-## RULES ENGINE
+## RULES & BEHAVIORS
 
-Rules from `merlin_get_rules` and `merlin_get_context` responses are **non-negotiable**. Common: max 400 lines/file, always test, no `any` types, no console.log in production.
-
-**Detect implied rules:** When user says "always...", "never...", "I prefer...", "I hate when..." — save it with `merlin_save_rule`. Don't ask, just save and confirm.
+- Rules from `merlin_get_rules` are **non-negotiable**. Follow them.
+- When user corrects you, silently save with `merlin_save_behavior`.
+- Before commits, run `merlin_run_verification`.
+- When user says "always...", "never...", "I prefer..." — save with `merlin_save_rule`.
 
 ---
 
-## BEHAVIORS — Auto-Learn, Auto-Apply
-
-- **When user corrects you:** Silently save with `merlin_save_behavior`. Acknowledge: "Got it — I'll remember that."
-- **High-confidence behaviors (≥0.7):** Returned by `merlin_get_context` under "🎯 Auto-Apply Patterns" — follow these.
-- **Before commits:** Run `merlin_run_verification`. Fix failures before committing.
-
----
-
-## SHOW OPTIONS AT DECISION POINTS
-
-At every decision point (session start, task completed, unclear request, blocked, errors), show numbered options with commands. Never ask open questions when options work. Most likely action = [1]. Always include escape hatch.
+## DECISION POINTS — Always Show Numbered Options
 
-Example format:
+At session start, task completion, unclear requests, errors — show numbered options:
 ```
-[1] ▶️  Next task: "Add auth"
+[1] ▶️  Continue implementation
 [2] 🧪 Test what we built
 [3] 📋 Plan next steps (/merlin:plan-phase)
 [4] 💬 Something else
@@ -77,15 +100,15 @@ Example format:
 
 ## OPERATING MODE
 
-- **Default: Fast execution.** Move fast, make assumptions, minimize questions, state assumptions at end.
-- **Merlin Mode** ("get shit done", "ship it"): Skip clarity gate, fast-path pipeline, no questions. Deactivate with "normal mode".
-- **New repos without PROJECT.md:** Auto-suggest `/merlin:map-codebase` then `/merlin:new-project`.
+- **Default: Fast execution.** Move fast, assume, state assumptions at end.
+- **Merlin Mode** ("get shit done"): Skip questions, fast pipeline. Off with "normal mode".
+- **New repos without PROJECT.md:** Suggest `/merlin:map-codebase` then `/merlin:new-project`.
 
 ---
 
 ## KEY ANTI-PATTERNS
 
-- **Never** do specialist work in orchestrator context — always route
-- **Never** use Task() — use `claude --agent -p` for isolation
-- **Never** read reference files yourself (plan-format.md, tdd.md) — sub-agents read them
-- **Never** pollute context with full agent output — only hold compact summaries
+- **Never** do specialist work directly — route via `Skill("merlin:route")`
+- **Never** run `claude --agent` via Bash — use the Skill tool
+- **Never** use Task() — it shares parent context and causes overflow
+- **Never** skip Sights before editing — check context first

package/files/agents/merlin.md

@@ -191,6 +191,7 @@ Activated by: "get shit done", "Merlin mode", "move fast", "just build it", "shi
 
 ## Anti-Patterns (NEVER Do These)
 
+- **Never** run `claude --agent` via Bash — it FAILS inside Claude Code sessions. Use `Skill("merlin:route")` instead
 - **Never** read ref files yourself (plan-format.md, tdd.md) — the sub-agent reads them
 - **Never** do specialist work in the orchestrator context — always route
 - **Never** use Task() — it shares parent context and causes overflow

package/files/hooks/session-start.sh

@@ -133,7 +133,7 @@ cat <<'CONTEXT_JSON'
 {
   "hookSpecificOutput": {
     "hookEventName": "SessionStart",
-    "additionalContext": "You are a Merlin-powered session. Before working: (1) call merlin_get_selected_repo to connect Sights, (2) call merlin_get_project_status to load state, (3) show numbered options. Check Sights before every edit. Route complex tasks to specialists via /merlin:route. Save checkpoints before stopping."
+    "additionalContext": "⚡ MANDATORY: Before responding to the user, you MUST: (1) call merlin_get_selected_repo to connect Sights, (2) call merlin_get_project_status to load state, (3) show status + numbered options. Do NOT skip these steps. Do NOT start working without Merlin context. Route complex tasks via Skill(\"merlin:route\") — NEVER run claude --agent via Bash. Check merlin_get_context before every edit."
   }
 }
 CONTEXT_JSON

package/files/merlin/VERSION

@@ -1 +1 @@
-3.5.11
+3.5.12

package/package.json

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