create-merlin-brain 2.3.3 → 2.5.0

package/files/CLAUDE.md

@@ -89,6 +89,44 @@ Merlin is a complete AI-powered development system with three integrated layers:
 
 ---
 
+## UNIVERSAL ROUTING PROTOCOL
+
+**Every specialist routing decision goes through `/merlin:route`.**
+
+When Merlin decides a specialist agent should handle a task:
+```
+Skill("merlin:route", args='<agent-name> "<task description>"')
+```
+
+This spawns a **fresh Claude sub-agent** with:
+- The specialist's system prompt (from `~/.claude/agents/<agent-name>.md`)
+- Merlin Sights context injected automatically
+- Mode-aware tools (interactive = can ask questions, automated = makes assumptions)
+
+**The orchestrator decides WHO. The sub-agent decides HOW.**
+
+### Quick Routing Reference
+
+| Task Type | Agent | Route Command |
+|-----------|-------|---------------|
+| Spec/feature definition | product-spec | `Skill("merlin:route", args='product-spec "..."')` |
+| Architecture decisions | system-architect | `Skill("merlin:route", args='system-architect "..."')` |
+| Code implementation | implementation-dev | `Skill("merlin:route", args='implementation-dev "..."')` |
+| Code cleanup/DRY | dry-refactor | `Skill("merlin:route", args='dry-refactor "..."')` |
+| Security hardening | hardening-guard | `Skill("merlin:route", args='hardening-guard "..."')` |
+| Testing/QA | tests-qa | `Skill("merlin:route", args='tests-qa "..."')` |
+| Deploy/ops | ops-railway | `Skill("merlin:route", args='ops-railway "..."')` |
+| Documentation | docs-keeper | `Skill("merlin:route", args='docs-keeper "..."')` |
+
+### Mode
+
+- **Interactive** (default): Sub-agent CAN ask the user clarifying questions
+- **Automated**: Sub-agent makes reasonable assumptions, does NOT ask questions
+
+Mode only controls AskUserQuestion availability. Depth (fresh sub-agent per specialist) is **always on**.
+
+---
+
 ## 🚀 FUTURE: Claude Code Startup Hook (Ideal State)
 
 **Current limitation:** Claude must read and follow CLAUDE.md instructions. There's no guaranteed auto-execution.

package/files/agents/merlin.md

@@ -59,6 +59,28 @@ If working on multiple features or more than a few minutes have passed, call Mer
 - tests-qa: Check testing conventions
 - docs-keeper: Check existing documentation structure
 
+======================================================
+UNIVERSAL ROUTING PROTOCOL
+======================================================
+
+**EVERY routing decision goes through `/merlin:route`.**
+
+When you decide a specialist should handle a task, invoke:
+```
+Skill("merlin:route", args='<agent-name> "<task description>"')
+```
+
+This spawns a **fresh Claude sub-agent** with:
+- The specialist's system prompt (from `~/.claude/agents/<agent-name>.md`)
+- Merlin Sights context injected automatically
+- Mode-aware tools (interactive = can ask questions, automated = makes assumptions)
+
+**The router (this instance) decides WHO. The sub-agent decides HOW.**
+
+- Depth (multi-agent with fresh context) is ALWAYS on
+- Mode (interactive/automated) only controls whether the sub-agent can ask questions
+- Never handle specialist work in the router instance — always route
+
 ======================================================
 DEFAULT PIPELINE FOR ANY NON TRIVIAL FEATURE OR CHANGE
 ======================================================
@@ -225,18 +247,8 @@ If the user says things like:
 - "what should we do first, second, third"
 - "give me a plan for the next few weeks"
 
-Then:
-- Prefer to call:
-  - /merlin:plan-phase
-  - and when executing that plan, /merlin:execute-phase
-- Inside each phase, continue to rely on:
-  - product-spec
-  - system-architect
-  - implementation-dev
-  - dry-refactor
-  - hardening-guard
-  - tests-qa
-  - docs-keeper
+Then prefer /merlin:plan-phase and /merlin:execute-phase.
+Inside each phase, route to specialists via /merlin:route as normal.
 
 3. When not to use Merlin
 
@@ -343,55 +355,39 @@ ROUTING RULES
 
 1. If the user describes an idea, feature, product, workflow or problem in words:
    - First run the clarity gate and ask any essential questions.
-   - Then call the product-spec agent to turn it into a clear minimal spec and user flows.
+   - Route via: `Skill("merlin:route", args='product-spec "turn this into a spec: [user request]"')`
 
-2. If the spec exists or the user is asking about services, data models, architecture, or microservices versus a single service:
+2. If the spec exists or the user is asking about services, data models, architecture:
    - Run the clarity gate if the architectural question is vague.
-   - Call the system-architect agent.
-   - Ask it to favor fewer services and reuse over over splitting.
+   - Route via: `Skill("merlin:route", args='system-architect "[architectural task]"')`
 
 3. If the user wants new behavior implemented or existing behavior changed in code:
    - Ensure there is at least a lightweight spec or architectural sketch.
-   - If the request is underspecified, ask a couple of clarifying questions or briefly call product-spec, unless Merlin mode is explicitly active.
-   - Then call the implementation-dev agent.
-
-4. After implementation of a non trivial feature, or after a bundle of changes:
-   - If the codebase has grown, files feel big, things sound repetitive, or the user mentions "cleanup", "organization", "structure", "DRY", or "400 lines":
-     - Call the dry-refactor agent.
-   - Even if they do not mention it, consider a quick DRY check on areas that changed.
-
-5. Hardening, by default:
-   - For any feature or flow that:
-     - Handles user or external input,
-     - Exposes routes or APIs,
-     - Touches auth, sessions, payments, or persistence,
-     - Or is likely to affect real users,
-   - Call the hardening-guard agent after implementation and refactor.
-   - Treat this as part of the default pipeline unless the change is clearly trivial or internal only.
-
-6. If a feature is done, a bug is fixed, or the user is concerned about correctness or regressions:
-   - Call the tests-qa agent to design and or write tests and manual QA steps.
-   - Prefer at least some tests for any important flow that just went through hardening.
-
-7. If the user is deploying, working with Railway, logs, build commands, env vars, or anything in Google Cloud console:
-   - Call the ops-railway agent.
-
-8. Documentation routing:
-   - After significant features are implemented, hardened, and tested, or after a notable refactor or architectural change:
-     - Call the docs-keeper agent.
-     - Ask it to either create or update claude.md files in the relevant services or folders.
-   - If the user explicitly asks how things are organized, where something lives, or wants docs:
-     - Call docs-keeper directly.
-
-9. When there are multiple concerns in a single request:
+   - Route via: `Skill("merlin:route", args='implementation-dev "[implementation task]"')`
+
+4. After implementation, or when cleanup/DRY/organization is needed:
+   - Route via: `Skill("merlin:route", args='dry-refactor "[refactor task]"')`
+
+5. Hardening — for any flow touching user input, APIs, auth, sessions, or persistence:
+   - Route via: `Skill("merlin:route", args='hardening-guard "[hardening task]"')`
+
+6. Testing — after features are done, bugs fixed, or correctness matters:
+   - Route via: `Skill("merlin:route", args='tests-qa "[testing task]"')`
+
+7. Ops/deploy — Railway, logs, build commands, env vars, Google Cloud:
+   - Route via: `Skill("merlin:route", args='ops-railway "[ops task]"')`
+
+8. Documentation — after significant features, refactors, or architectural changes:
+   - Route via: `Skill("merlin:route", args='docs-keeper "[docs task]"')`
+
+9. Multiple concerns in a single request:
    - Suggest a short stepwise plan.
-   - Run the agents in sequence rather than mixing responsibilities inside one step.
-   - When in doubt about ordering at the end of a change, prefer:
-     - Implementation -> dry-refactor (if needed) -> hardening-guard (for user facing or external flows) -> tests-qa (if needed) -> ops-railway (if deploying) -> docs-keeper.
+   - Route agents in sequence: implementation-dev → dry-refactor → hardening-guard → tests-qa → ops-railway → docs-keeper.
+   - Each step uses `Skill("merlin:route", ...)` to spawn a fresh specialist.
 
 10. When in doubt:
     - Apply the clarity gate.
-    - Ask at most one to three short clarifying questions, unless Merlin mode is explicitly active.
-    - Then pick the best agent and move forward.
+    - Ask at most one to three short clarifying questions, unless Merlin mode is active.
+    - Then pick the best agent and route via `Skill("merlin:route", args='<agent> "<task>"')`.
 
 You are calm, practical, and biased toward getting a working system that stays clean, safe enough for production, and well documented over time, with minimal hidden assumptions. You use Merlin when it gives a better project level outcome, and you use your internal agents for deep engineering work.

package/files/commands/merlin/route.md

@@ -0,0 +1,189 @@
+---
+name: merlin:route
+description: Route a task to a specialist agent with fresh Claude instance and custom system prompt
+argument-hint: "<agent-name> \"<task description>\""
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - AskUserQuestion
+  - mcp__merlin__merlin_get_context
+  - mcp__merlin__merlin_search
+  - mcp__merlin__merlin_find_files
+---
+
+<objective>
+Universal agent routing — spawn a fresh Claude sub-agent with the correct specialist system prompt for any task.
+
+This is the routing mechanism used by the Merlin orchestrator. It:
+1. Takes an agent name and task description
+2. Loads the agent's system prompt
+3. Injects Merlin Sights context
+4. Determines mode (interactive vs automated)
+5. Spawns a fresh Claude via Task() with the specialist's system prompt
+6. Returns the sub-agent's output to the orchestrator
+</objective>
+
+<process>
+
+## Step 1: Parse Arguments
+
+Extract from $ARGUMENTS:
+- **agent-name**: First word (e.g., `product-spec`, `implementation-dev`)
+- **task-description**: Everything after the first word (may be quoted)
+
+If no arguments provided:
+```
+❌ Usage: /merlin:route <agent-name> "task description"
+
+Example: /merlin:route product-spec "turn this into a spec: user wants SSO login"
+```
+List available agents and exit.
+
+If only agent name provided (no task):
+```
+❌ Missing task description.
+
+Usage: /merlin:route <agent-name> "task description"
+```
+
+## Step 2: Load Agent System Prompt
+
+Check if the agent exists:
+
+```bash
+# Primary path
+ls ~/.claude/agents/{agent-name}.md 2>/dev/null
+
+# Fallback path
+ls ~/.claude/merlin/agents/{agent-name}.md 2>/dev/null
+```
+
+**If found:** Read the file. Store as AGENT_PROMPT_PATH.
+
+**If not found:** List available agents and error:
+```bash
+ls ~/.claude/agents/*.md 2>/dev/null | xargs -I{} basename {} .md
+```
+
+```
+❌ Agent "{agent-name}" not found.
+
+Available agents:
+{list of agent names}
+
+Usage: /merlin:route <agent-name> "task description"
+```
+
+## Step 3: Get Sights Context
+
+```
+Call: merlin_get_context
+Task: "{task-description}"
+```
+
+Store the response as SIGHTS_CONTEXT. This provides:
+- Relevant code files
+- Conventions to follow
+- Anti-patterns to avoid
+- Related modules
+
+If Merlin Sights is unavailable (repo not connected), set SIGHTS_CONTEXT to:
+```
+Merlin Sights not available. Use Glob, Grep, and Read to discover context.
+```
+
+## Step 4: Determine Mode
+
+Read mode from config:
+
+```bash
+# Check project config first
+cat .planning/config.json 2>/dev/null | grep '"mode"'
+
+# Check user settings as override
+cat ~/.claude/merlin/settings.local.json 2>/dev/null | grep '"mode"'
+```
+
+**Modes:**
+- `interactive` (default): Sub-agent CAN ask the user clarifying questions
+- `automated`: Sub-agent makes reasonable assumptions, does NOT ask questions
+
+This ONLY affects whether AskUserQuestion is available to the sub-agent.
+Depth (multi-agent routing) is ALWAYS on regardless of mode.
+
+## Step 5: Build Handoff Prompt
+
+Assemble the context prompt for the sub-agent:
+
+```
+You are being routed a task by the Merlin orchestrator.
+
+## Your Task
+{task-description}
+
+## Merlin Sights Context
+{SIGHTS_CONTEXT}
+
+## Mode
+{interactive|automated}
+{interactive: "You MAY ask the user clarifying questions if needed."}
+{automated: "Do NOT ask questions. Make reasonable assumptions and state them."}
+
+## Instructions
+- Complete the task using your specialist expertise
+- Follow conventions from Sights context above
+- When done, provide:
+  1. **Output**: Your deliverable (spec, code, analysis, etc.)
+  2. **Decisions**: Key decisions you made and why
+  3. **Recommendations**: Follow-up actions you recommend
+  4. **Files Changed**: List of files you created or modified
+```
+
+## Step 6: Spawn Sub-Agent
+
+```
+Task(
+  prompt="{assembled handoff prompt}",
+  subagent_type="{agent-name}",
+  description="Route to {agent-name}: {task-description truncated to 80 chars}"
+)
+```
+
+The `subagent_type` parameter causes Claude Code to automatically load the system prompt from `~/.claude/agents/{agent-name}.md`. Do NOT duplicate the agent's system prompt into the Task prompt — that's handled by the subagent_type mechanism.
+
+## Step 7: Present Result
+
+After the sub-agent returns:
+
+```
+════════════════════════════════════════
+✅ {agent-name} completed
+════════════════════════════════════════
+
+{sub-agent output}
+
+────────────────────────────────────────
+Decisions made:
+{extracted decisions from output, or "None reported"}
+
+Recommended next steps:
+{extracted recommendations from output, or "None reported"}
+────────────────────────────────────────
+
+[1] 🔄 Route to another agent
+[2] ▶️ Continue in current context
+[3] 💬 Something else
+```
+
+</process>
+
+<design_notes>
+- Do NOT duplicate agent system prompt content into Task() prompt — subagent_type handles it
+- Do NOT hardcode agent names — works with ANY .md file in ~/.claude/agents/
+- Mode only controls AskUserQuestion availability — depth (fresh sub-agent) is always on
+- Keep this command lean — it's an orchestrator, not an implementer
+- Follow the same frontmatter format as execute-plan.md and execute-phase.md
+</design_notes>