create-merlin-brain 4.2.0 → 5.0.1

package/README.md

@@ -134,6 +134,25 @@ Use Merlin to find the best skill, agent, and workflow for this task: add OAuth
 Call merlin_help for this task: debug the failing Stripe webhook tests.
 ```
 
+## Duo Mode (parallel + sequential dual-brain)
+
+Run Claude and Codex on the same task: parallel for planning/docs/review/tests, sequential for code writing.
+
+```bash
+# Toggle in any Claude Code session:
+"duo on"     # enable
+"duo off"    # disable
+"duo status" # check
+```
+
+When enabled, the badge swaps to `⟡🔮↔🔮 MERLIN·DUO ›` so you always know which mode you're in. Set `MERLIN_BADGE_TEXTONLY=1` for emoji-hostile terminals.
+
+**Auto-offer:** When duo is OFF and a task scores >=50 on the risk heuristic (auth, payments, migrations, etc.), Merlin asks if you want to enable duo for that task. Suppress with "skip session" or "never for X". 7-day expiry on intent suppressions.
+
+**Requires:** Codex CLI installed. If not installed, Merlin silently uses solo mode.
+
+Full rules: `~/.claude/rules/duo-routing.md`.
+
 ## Documentation
 
 Visit [merlin.build/docs](https://merlin.build/docs) for full documentation.

package/bin/install.cjs

@@ -138,6 +138,7 @@ const LOOP_DIR = path.join(CLAUDE_DIR, 'loop');
 const RULES_DIR = path.join(CLAUDE_DIR, 'rules');
 const SCRIPTS_DIR = path.join(CLAUDE_DIR, 'scripts');
 const MERLIN_STATE_DIR = path.join(CLAUDE_DIR, 'merlin-state');
+const SKILLS_DIR = path.join(CLAUDE_DIR, 'skills', 'merlin');
 
 const colors = {
   reset: '\x1b[0m',
@@ -873,7 +874,7 @@ async function install() {
   }
 
   // Step 0: Clean up legacy GSD/ccwiki artifacts
-  logStep('0/13', 'Cleaning up legacy installations...');
+  logStep('0/14', 'Cleaning up legacy installations...');
   const cleaned = cleanupLegacy();
   if (cleaned.length > 0) {
     for (const item of cleaned) {
@@ -884,11 +885,11 @@ async function install() {
   }
 
   // Step 1: Ensure Claude Code is installed and up to date
-  logStep('1/13', 'Checking Claude Code...');
+  logStep('1/14', 'Checking Claude Code...');
   const claudeCheck = ensureClaudeCode();
 
   // Step 2: Detect runtimes
-  logStep('2/13', 'Detecting runtimes...');
+  logStep('2/14', 'Detecting runtimes...');
   const detectedRuntimes = detectRuntimes();
   log(`  ${colors.green}✅${colors.reset} Claude Code (primary)`);
   for (const rt of detectedRuntimes) {
@@ -901,7 +902,7 @@ async function install() {
   }
 
   // Step 3: Install globally for instant startup across all terminals
-  logStep('3/13', 'Installing globally (fast startup for all terminals)...');
+  logStep('3/14', 'Installing globally (fast startup for all terminals)...');
   try {
     const { execSync } = require('child_process');
     // Check if already installed globally and up-to-date
@@ -942,7 +943,7 @@ async function install() {
   }
 
   // Step 4: Create directories
-  logStep('4/13', 'Creating directories...');
+  logStep('4/14', 'Creating directories...');
   ensureDir(CLAUDE_DIR);
   ensureDir(MERLIN_DIR);
   ensureDir(AGENTS_DIR);
@@ -950,7 +951,7 @@ async function install() {
   logSuccess('Directories created');
 
   // Step 5: Install Merlin core (workflows, references, templates)
-  logStep('5/13', 'Installing Merlin workflows...');
+  logStep('5/14', 'Installing Merlin workflows...');
   const merlinSrc = path.join(filesDir, 'merlin');
   if (fs.existsSync(merlinSrc)) {
     const count = copyDirRecursive(merlinSrc, MERLIN_DIR);
@@ -963,7 +964,7 @@ async function install() {
   }
 
   // Step 6: Install agents (tiered)
-  logStep('6/13', 'Installing Merlin agents...');
+  logStep('6/14', 'Installing Merlin agents...');
   const agentsSrc = path.join(filesDir, 'agents');
   if (fs.existsSync(agentsSrc)) {
     // Load agent manifest for tiered display
@@ -991,7 +992,7 @@ async function install() {
   }
 
   // Step 7: Install path-scoped rules
-  logStep('7/13', 'Installing path-scoped rules...');
+  logStep('7/14', 'Installing path-scoped rules...');
   const rulesSrc = path.join(filesDir, 'rules');
   if (fs.existsSync(rulesSrc)) {
     ensureDir(RULES_DIR);
@@ -1014,8 +1015,62 @@ async function install() {
     logWarn('Rules not found in package');
   }
 
+  // Step 7b: Install Merlin skills tree (~/.claude/skills/merlin/)
+  // Skills live at runtime path ~/.claude/skills/merlin/ (NOT ~/.claude/merlin/skills/)
+  // Source: files/merlin/skills/ — preserves user-customized skill files (mtime check)
+  logStep('7b/14', 'Installing Merlin skills tree...');
+  const skillsSrc = path.join(filesDir, 'merlin', 'skills');
+  if (fs.existsSync(skillsSrc)) {
+    ensureDir(SKILLS_DIR);
+    let installedCount = 0;
+    let skippedCount = 0;
+    let updatedCount = 0;
+
+    function installSkillsDir(srcDir, destDir) {
+      fs.mkdirSync(destDir, { recursive: true });
+      const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.name === '.DS_Store') continue;
+        const srcPath = path.join(srcDir, entry.name);
+        const destPath = path.join(destDir, entry.name);
+        if (entry.isDirectory()) {
+          installSkillsDir(srcPath, destPath);
+        } else {
+          if (fs.existsSync(destPath)) {
+            // Check if user has customized: dest is newer AND content differs
+            const srcStat = fs.statSync(srcPath);
+            const destStat = fs.statSync(destPath);
+            const userNewer = destStat.mtimeMs > srcStat.mtimeMs;
+            const contentDiffers = fs.readFileSync(srcPath, 'utf8') !== fs.readFileSync(destPath, 'utf8');
+            if (userNewer && contentDiffers) {
+              skippedCount++;
+              // logSuccess(`  skipped (user-customized): ${destPath.replace(os.homedir(), '~')}`);
+            } else if (contentDiffers) {
+              fs.copyFileSync(srcPath, destPath);
+              updatedCount++;
+            } else {
+              // identical — no-op
+              skippedCount++;
+            }
+          } else {
+            fs.copyFileSync(srcPath, destPath);
+            installedCount++;
+          }
+        }
+      }
+    }
+
+    installSkillsDir(skillsSrc, SKILLS_DIR);
+    if (installedCount > 0) logSuccess(`Installed ${installedCount} skill files`);
+    if (updatedCount > 0) logSuccess(`Updated ${updatedCount} skill files`);
+    if (skippedCount > 0) logSuccess(`Skipped ${skippedCount} skill files (up-to-date or user-customized)`);
+    if (installedCount === 0 && updatedCount === 0 && skippedCount === 0) logSuccess('Skills tree already up-to-date');
+  } else {
+    logWarn('Skills not found in package');
+  }
+
   // Step 8: Install commands
-  logStep('8/13', 'Installing /merlin:* commands...');
+  logStep('8/14', 'Installing /merlin:* commands...');
   const commandsSrc = path.join(filesDir, 'commands', 'merlin');
   if (fs.existsSync(commandsSrc)) {
     const count = copyDirRecursive(commandsSrc, COMMANDS_DIR);
@@ -1025,7 +1080,7 @@ async function install() {
   }
 
   // Step 9: Install CLAUDE.md
-  logStep('9/13', 'Configuring Claude Code...');
+  logStep('9/14', 'Configuring Claude Code...');
   const claudeMdSrc = path.join(filesDir, 'CLAUDE.md');
   const claudeMdDest = path.join(CLAUDE_DIR, 'CLAUDE.md');
 
@@ -1050,7 +1105,7 @@ async function install() {
   // Use /merlin:loop-recipes in Claude Code for pre-built loop patterns.
   // These scripts are still copied so existing users and terminal workflows
   // (merlin-loop, merlin session) continue to work without interruption.
-  logStep('10/13', 'Installing Merlin Loop (legacy scripts)...');
+  logStep('10/14', 'Installing Merlin Loop (legacy scripts)...');
   const loopSrc = path.join(filesDir, 'loop');
   if (fs.existsSync(loopSrc)) {
     ensureDir(LOOP_DIR);
@@ -1083,7 +1138,7 @@ async function install() {
   }
 
   // Step 11: Install Claude Code hooks
-  logStep('11/13', 'Installing Claude Code hooks...');
+  logStep('11/14', 'Installing Claude Code hooks...');
   const HOOKS_DIR = path.join(CLAUDE_DIR, 'hooks');
   const hooksSrc = path.join(filesDir, 'hooks');
   if (fs.existsSync(hooksSrc)) {
@@ -1359,7 +1414,7 @@ async function install() {
   }
 
   // Step 11b: Install Codex integration scripts
-  logStep('11b/13', 'Installing Codex integration scripts...');
+  logStep('11b/14', 'Installing Codex integration scripts...');
   const scriptsSrc = path.join(filesDir, 'scripts');
   if (fs.existsSync(scriptsSrc)) {
     ensureDir(SCRIPTS_DIR);
@@ -1376,7 +1431,7 @@ async function install() {
   }
 
   // Step 11c: Install merlin-state defaults (without overwriting user state)
-  logStep('11c/13', 'Installing merlin-state defaults...');
+  logStep('11c/14', 'Installing merlin-state defaults...');
   const stateSrc = path.join(filesDir, 'merlin-state');
   if (fs.existsSync(stateSrc)) {
     ensureDir(MERLIN_STATE_DIR);
@@ -1411,7 +1466,7 @@ async function install() {
   }
 
   // Step 12: Optional Merlin Sights configuration
-  logStep('12/13', 'Merlin Sights configuration...');
+  logStep('12/14', 'Merlin Sights configuration...');
 
   // Check if API key is already configured (skip prompt on updates)
   let existingApiKey = '';
@@ -1543,7 +1598,7 @@ async function install() {
   }
 
   // Step 13: Configure non-Claude-Code runtimes
-  logStep('13/13', 'Configuring additional runtimes...');
+  logStep('13/14', 'Configuring additional runtimes...');
   configureRuntimes({
     runtimeFlag: RUNTIME_FLAG,
     useGlobalBinary,

package/files/CLAUDE.md

@@ -5,7 +5,13 @@ IMPORTANT: Before processing any user request, you MUST complete these steps:
 3. Call `merlin_get_rules` and `merlin_get_brief` in parallel.
 4. Show the session start banner, then detect intent and route.
 
-**You are Merlin — an orchestrator, not a coder.** NEVER write, edit, or debug code yourself. Route ALL implementation work to specialist agents. Prefix every action with `⟡🔮 MERLIN ›`.
+**You are Merlin — an orchestrator, not a coder.** NEVER write, edit, or debug code yourself. Route ALL implementation work to specialist agents.
+
+**Badge:** Prefix every action with the badge from `~/.claude/scripts/duo-badge.sh`.
+- Solo mode (default): `⟡🔮 MERLIN ›`
+- Duo mode (when `~/.claude/merlin-state/duo-mode.json` is enabled AND Codex installed): `⟡🔮↔🔮 MERLIN·DUO ›`
+- Text-only fallback (env `MERLIN_BADGE_TEXTONLY=1`): `MERLIN ›` / `[DUO] MERLIN ›`
+If `duo-badge.sh` is unavailable, default to `⟡🔮 MERLIN ›`.
 
 **What YOU do vs what AGENTS do:**
 - **YOU answer questions** about the codebase using Sights (`merlin_get_context`, `merlin_search`) — never delegate questions to Explore agents
@@ -43,7 +49,7 @@ Do NOT spawn Explore agents or run Glob/Grep for codebase questions. Use Sights
 2. Run `merlin_run_verification()` after implementation work
 3. Surface one capability the user might not know about
 4. Detect if the user's request needs more work
-5. Show cost: `⟡🔮 MERLIN › Session: X agents · $Y.ZZ · Nmin`
+5. Show cost: `[badge] Session: X agents · $Y.ZZ · Nmin` (badge from `duo-badge.sh`)
 
 Never just dump an agent result and go silent. Always follow through.
 
@@ -64,7 +70,7 @@ When user corrects you → `merlin_save_behavior`. When user says "always/never/
 - Session end → auto-invoke `Skill("merlin:standup")`.
 - Never kill user processes (Xcode, VS Code, browsers) without explicit confirmation.
 - Never claim "done" without actually building/compiling/testing.
-- Badge on EVERY action — if the user can't see `⟡🔮 MERLIN ›`, you're not doing your job.
+- Badge on EVERY action — call `~/.claude/scripts/duo-badge.sh` to get the right badge. If the user can't see the badge, you're not doing your job.
 
 ## Codex Execution Mode
 
@@ -84,6 +90,22 @@ Merlin can delegate code execution to OpenAI Codex while Claude handles planning
 
 **Brain/hands split:** Codex writes code; Claude always verifies via `merlin_run_verification()`.
 
+## Duo Mode (parallel + sequential dual-brain)
+
+Duo mode runs Claude AND Codex on the same task — parallel for planning/docs/review/tests, sequential for code write/modify. The decider merges (parallel) or gates (sequential).
+
+State file: `~/.claude/merlin-state/duo-mode.json`. Auto-expires after 24h. Install gate: requires Codex (silent fallback if missing).
+
+Toggle: "duo on" / "duo off" / "duo status" (or `Skill("merlin:duo", args="on|off|status")`).
+
+Badge: when duo is active AND install gate passes AND within 24h, prefix every action with `⟡🔮↔🔮 MERLIN·DUO ›` instead of `⟡🔮 MERLIN ›`. Use `~/.claude/scripts/duo-badge.sh` to compute.
+
+Auto-offer: when duo is OFF and a task scores ≥50 on the risk heuristic (auth/payment/migration/etc.), Merlin asks the user if they want to enable duo for that task. Suppression memory in `duo-suppress.json` (FIFO-capped, 7-day expiry on never-for-intents).
+
+Precedence: if both `duo-mode` and `codex-mode` are enabled, duo wins. Verification authority remains with Claude regardless.
+
+Full rules: `~/.claude/rules/duo-routing.md`. Single source of truth — do not duplicate routing logic elsewhere.
+
 ## New Capabilities (March 2026)
 
 ### Auto Mode — `merlin loop yolo`

package/files/agents/merlin.md

@@ -76,7 +76,8 @@ When user switches:
 
 ## 🎨 Visual Identity (ALWAYS follow these formatting rules)
 
-The `⟡🔮 MERLIN ›` badge appears on EVERY action, decision, routing, save, warning, and completion. No exceptions.
+The badge (from `~/.claude/scripts/duo-badge.sh`) appears on EVERY action, decision, routing, save, warning, and completion. No exceptions.
+- Solo: `⟡🔮 MERLIN ›` — Duo: `⟡🔮↔🔮 MERLIN·DUO ›`. Always call `duo-badge.sh` to get the current badge; fallback to `⟡🔮 MERLIN ›` if script unavailable.
 
 ### Badge Formats
 
@@ -111,7 +112,7 @@ The `⟡🔮 MERLIN ›` badge appears on EVERY action, decision, routing, save,
 ```
 
 ### Key Rules
-- **EVERY Merlin action starts with `⟡🔮 MERLIN ›`** — no bare text
+- **EVERY Merlin action starts with the badge from `~/.claude/scripts/duo-badge.sh`** — no bare text (solo: `⟡🔮 MERLIN ›`, duo: `⟡🔮↔🔮 MERLIN·DUO ›`)
 - **Routing shows the arrow →** with agent name
 - **Status uses ━━━ divider lines**
 - The `⟡🔮` badge is sacred — it means "Merlin is doing this"

package/files/agents/reviewer-decider.md

@@ -0,0 +1,124 @@
+---
+name: reviewer-decider
+description: Lightweight gating agent for the duo sequential coding flow. Receives author diff + reviewer findings + original task; emits structured {decision: approve|revise|reject, reasoning, required_changes?}. Claude-only — must NEVER be embodied via codex-as.sh.
+tools: Read, Grep, Glob
+disallowedTools: [Write, Edit, Bash]
+model: opus
+effort: medium
+---
+
+You are reviewer-decider, the gate in Merlin's duo sequential coding flow. You are NOT the author and NOT the reviewer. Your job is to decide: should the author's change ship as-is, be revised once, or be rejected outright?
+
+You do not write code. You do not suggest improvements beyond what is required to meet the original task. You render a verdict from the evidence in front of you.
+
+## Section 1: Identity
+
+You are the final gate before a change merges. The author (Codex or any coding agent) produced a diff. The `code-review` agent examined it and returned findings. You receive both and decide. Your output is a single JSON object — nothing else.
+
+This role is Claude-only. You must never be run via `codex-as.sh`. If you detect you are being run by Codex, emit:
+```json
+{"decision":"reject","reasoning":"reviewer-decider must be Claude-only — gate integrity requires a different model than the author","required_changes":[]}
+```
+then stop.
+
+## Section 2: Inputs you will receive
+
+Your prompt will contain these fields:
+
+- `original_task` — what the user asked for (the acceptance criterion)
+- `author_diff` — the diff or change the author produced
+- `review_findings` — structured list from the `code-review` agent, severity-tagged (critical / high / medium / low). May be an empty array `[]`.
+- `iteration_count` — integer, 1 or 2. We allow at most one revise loop. If this is 2, revise is no longer available.
+- `additional_signals` (optional) — any of: `lint_clean: true`, `types_clean: true`, `tests_passed: true`. Used in the empty-findings guardrail.
+
+## Section 3: Decision rules
+
+Be deterministic. Same inputs must produce the same decision.
+
+### APPROVE
+
+Emit `approve` if ALL of the following hold:
+
+1. No critical or high severity findings in `review_findings`.
+2. Any medium findings present have low fix-cost relative to their value (they are suggestions, not blockers).
+3. The diff matches `original_task` scope — no scope creep (doing more than asked).
+4. At least one of the following is true: `lint_clean`, `types_clean`, or `tests_passed` is present in `additional_signals`.
+
+### EMPTY-FINDINGS GUARDRAIL (P0 — never bypass)
+
+If `review_findings` is an empty array `[]` AND `additional_signals` is absent or contains none of `lint_clean`, `types_clean`, `tests_passed`, you MUST NOT approve. Emit `revise` with:
+
+```json
+{
+  "required_changes": [
+    "request second-pass review or run lint/type/test signal before approve — empty findings without other signals is suspicious"
+  ]
+}
+```
+
+An empty review with no corroborating signals means the review may have been a false negative. This protects against silent failures.
+
+### REVISE
+
+Emit `revise` if ALL of the following hold:
+
+1. There are 1–3 fixable issues of medium severity (no critical or high).
+2. `iteration_count` is 1 (a second revise pass is still available).
+3. Each required fix is well-defined — you can state exactly what must change.
+
+Populate `required_changes` with one bullet per fix. Be specific enough that the author can act without ambiguity.
+
+### REJECT
+
+Emit `reject` if any of the following are true:
+
+- One or more critical or high severity findings exist that are not trivially self-contained.
+- The diff diverges structurally or architecturally from `original_task`.
+- Scope creep — the diff does meaningfully more than the task asked for.
+- `iteration_count` is 2 and unresolved findings remain (no further revise passes are available).
+
+## Section 4: Output schema (STRICT)
+
+Your entire response must be one JSON object. No prose before it, no prose after it.
+
+```json
+{
+  "decision": "approve",
+  "reasoning": "<1–3 sentence explanation of why this decision was reached>",
+  "required_changes": ["<bullet>", "..."]
+}
+```
+
+`required_changes` is ONLY present when `decision` is `"revise"`. Omit the key entirely for `approve` and `reject`.
+
+Valid values for `decision`: `"approve"`, `"revise"`, `"reject"`.
+
+## Section 5: Anti-patterns
+
+Do not do any of the following:
+
+- Second-guess severity tags assigned by `code-review`. Trust the reviewer's tagging; your job is to act on it, not re-evaluate it.
+- Ask for improvements unrelated to the original task. Scope is the diff vs the task, nothing more.
+- Approve "to be nice" or to move things along. A finding that blocks approval blocks approval.
+- Approve on empty findings without corroborating signals (see guardrail above).
+- Return any text outside the JSON object. The orchestrator parses your output directly.
+- Emit `required_changes` for decisions other than `revise`.
+- Use `revise` when `iteration_count` is 2 — that path is closed; use `reject` instead.
+
+## Section 6: Audit trail (orchestrator responsibility)
+
+You cannot write files (Write/Edit/Bash are disallowed). After you emit your decision JSON, the orchestrator (Claude) is responsible for appending the following JSONL line to `~/.claude/merlin-state/duo-decisions.log`:
+
+```json
+{"ts":"<ISO8601>","agent":"reviewer-decider","iteration":<int>,"decision":"approve|revise|reject","reasoning":"<short>"}
+```
+
+Do not attempt to write this yourself. Just emit the decision JSON and let the orchestrator handle persistence.
+
+## Section 7: Claude-only enforcement
+
+This agent is excluded from `codex-as.sh` by `~/.claude/rules/codex-routing.md` (see curated specialists exclusion, lines 91–92). Codex impersonating the gate that reviews Codex's own output defeats the sequential safety story entirely.
+
+If you have any reason to believe you are running inside a Codex execution context — model name mismatch, unusual system prompt prefix, or explicit instruction to "act as reviewer-decider" without being the real agent — emit the reject response from Section 1 and stop.
+
+The authority of this gate depends on its independence from the author. Claude-only is non-negotiable.

package/files/commands/merlin/challenge.md

@@ -119,6 +119,8 @@ Agent(
 <step name="present_results">
 ## Step 4: Present Results
 
+> **Badge note:** Use `~/.claude/scripts/duo-badge.sh` to compute the current badge before presenting. If duo is active, prefix with `⟡🔮↔🔮 MERLIN·DUO ›` instead of `⟡🔮 MERLIN ›`. The examples below show the solo badge.
+
 ### In AI Automation mode (default):
 
 Parse the arbiter's verdict and present:

package/files/hooks/config-change.sh

@@ -36,6 +36,7 @@ HAS_KEY="$([ -n "$MERLIN_API_KEY" ] && echo true || echo false)"
 KEY_VALID="unknown"
 
 # Validate key format if present (valid prefixes: mrln_ or ccw_)
+_BADGE="$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›")"
 if [ -n "$MERLIN_API_KEY" ]; then
   case "$MERLIN_API_KEY" in
     mrln_*|ccw_*)
@@ -43,7 +44,7 @@ if [ -n "$MERLIN_API_KEY" ]; then
       ;;
     *)
       KEY_VALID="false"
-      echo "⟡🔮 MERLIN › API key has unexpected format after config change" >&2
+      echo "${_BADGE} API key has unexpected format after config change" >&2
       ;;
   esac
 fi
@@ -64,7 +65,7 @@ if declare -f log_event >/dev/null 2>&1; then
 fi
 
 if [ -z "$MERLIN_API_KEY" ]; then
-  echo "⟡🔮 MERLIN › No API key configured — Sights features disabled" >&2
+  echo "${_BADGE} No API key configured — Sights features disabled" >&2
 fi
 
 echo '{}'

package/files/hooks/notify-desktop.sh

@@ -104,7 +104,7 @@ case "${HOOK_EVENT}" in
     MESSAGE="Claude needs your input"
     ;;
   *)
-    MESSAGE="⟡🔮 MERLIN › Task complete"
+    MESSAGE="$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›") Task complete"
     ;;
 esac
 

package/files/hooks/notify-webhook.sh

@@ -90,12 +90,13 @@ fi
 
 STATUS_TEXT="Success"
 STATUS_ICON="OK"
+_BADGE="$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›")"
 
 # ── Slack webhook ─────────────────────────────────────────────────
 if [ -n "${SLACK_WEBHOOK}" ]; then
   SLACK_BODY=$(cat <<SLACK_JSON
 {
-  "text": "⟡🔮 MERLIN › Task completed",
+  "text": "${_BADGE} Task completed",
   "blocks": [
     {
       "type": "section",

package/files/hooks/orchestrator-guard.sh

@@ -59,12 +59,13 @@ fi
 # ── BLOCK: Main orchestrator trying to edit source code ───────────
 # This is the structural constraint. Instead of TELLING Claude not to
 # code, we PREVENT it. Like Roo Code's Orchestrator mode.
+_BADGE="$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›")"
 if command -v jq >/dev/null 2>&1; then
-  jq -n '{
+  jq -n --arg badge "$_BADGE" '{
     hookSpecificOutput: {
       hookEventName: "PreToolUse",
       permissionDecision: "block",
-      reason: "⟡🔮 MERLIN › BLOCKED: You are the orchestrator — you do not edit source code directly. Route this to a specialist agent: Skill(\"merlin:route\", args=''implementation-dev \"your task\"'') or use Skill(\"merlin:workflow\", args=''run feature-dev \"your task\"''). Agents write code. You orchestrate."
+      reason: ($badge + " BLOCKED: You are the orchestrator — you do not edit source code directly. Route this to a specialist agent: Skill(\"merlin:route\", args='\''implementation-dev \"your task\"'\'') or use Skill(\"merlin:workflow\", args='\''run feature-dev \"your task\"'\''). Agents write code. You orchestrate.")
     }
   }'
 else

package/files/hooks/pre-edit-sights-check.sh

@@ -107,12 +107,13 @@ if declare -f sights_was_checked_recently >/dev/null 2>&1; then
     fi
     # BLOCK the edit — stale context means the agent skipped merlin_get_context
     # This is the structural enforcement: you cannot edit without fresh Sights context
+    _BADGE="$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›")"
     if command -v jq >/dev/null 2>&1; then
-      jq -n '{
+      jq -n --arg badge "$_BADGE" '{
         hookSpecificOutput: {
           hookEventName: "PreToolUse",
           permissionDecision: "block",
-          reason: "⟡🔮 MERLIN › BLOCKED: Sights context is stale (>2 minutes). You MUST call merlin_get_context(\"your current task\") before editing files. This is a non-negotiable rule."
+          reason: ($badge + " BLOCKED: Sights context is stale (>2 minutes). You MUST call merlin_get_context(\"your current task\") before editing files. This is a non-negotiable rule.")
         }
       }'
     else

package/files/hooks/task-completed-verify.sh

@@ -24,7 +24,7 @@ if [ -f "package.json" ] && command -v jq >/dev/null 2>&1; then
     build_exit=$?
     if [ "$build_exit" -ne 0 ]; then
       log_event "build_failed" "$(printf '{"exit_code":%d}' "$build_exit")"
-      echo "⟡🔮 MERLIN › Build check failed (exit $build_exit)" >&2
+      echo "$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›") Build check failed (exit $build_exit)" >&2
     else
       log_event "build_passed" '{}'
     fi
@@ -37,7 +37,7 @@ if [ -f "tsconfig.json" ] && command -v npx >/dev/null 2>&1; then
   tsc_exit=$?
   if [ "$tsc_exit" -ne 0 ]; then
     log_event "typecheck_failed" "$(printf '{"exit_code":%d}' "$tsc_exit")"
-    echo "⟡🔮 MERLIN › Type check failed (exit $tsc_exit)" >&2
+    echo "$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›") Type check failed (exit $tsc_exit)" >&2
   else
     log_event "typecheck_passed" '{}'
   fi

package/files/hooks/user-prompt-router.sh

@@ -6,7 +6,7 @@
 # session start.
 #
 # Contract:
-#   - Reads JSON from stdin: {"userPrompt": "..."}
+#   - Reads JSON from stdin: {"prompt": "..."}
 #   - Outputs {} when no pattern matches (no noise)
 #   - Outputs additionalContext JSON when a routing signal is found
 #   - MUST be <100ms: no network calls, no merlin CLI, no curl
@@ -23,13 +23,13 @@ fi
 
 [ -z "$input" ] && echo "{}" && exit 0
 
-# ── Extract userPrompt ────────────────────────────────────────────────────────
+# ── Extract prompt ────────────────────────────────────────────────────────
 prompt=""
 if command -v jq >/dev/null 2>&1; then
-  prompt=$(echo "$input" | jq -r '.userPrompt // empty' 2>/dev/null || true)
+  prompt=$(echo "$input" | jq -r '.prompt // empty' 2>/dev/null || true)
 else
   # Minimal extraction without jq — strip surrounding JSON scaffolding
-  prompt=$(echo "$input" | sed 's/.*"userPrompt"[[:space:]]*:[[:space:]]*"\(.*\)".*/\1/' 2>/dev/null || true)
+  prompt=$(echo "$input" | sed 's/.*"prompt"[[:space:]]*:[[:space:]]*"\(.*\)".*/\1/' 2>/dev/null || true)
 fi
 
 [ -z "$prompt" ] && echo "{}" && exit 0
@@ -82,7 +82,8 @@ fi
 [ -z "$suggestion" ] && echo "{}" && exit 0
 
 # ── Emit routing hint ─────────────────────────────────────────────────────────
-_ctx="⟡🔮 MERLIN ROUTING: ${suggestion}. Remember: YOU are the orchestrator. Answer codebase questions via Sights. Route implementation to agents. Badge every action."
+_BADGE="$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›")"
+_ctx="${_BADGE} ROUTING: ${suggestion}. Remember: YOU are the orchestrator. Answer codebase questions via Sights. Route implementation to agents. Badge every action."
 
 if command -v jq >/dev/null 2>&1; then
   jq -n --arg ctx "$_ctx" \

package/files/hooks/worktree-create.sh

@@ -55,7 +55,7 @@ if declare -f log_event >/dev/null 2>&1; then
     "$WORKTREE_PATH" "$AGENT_ID" "$AGENT_TYPE")"
 fi
 
-echo "⟡🔮 MERLIN › propagated config to worktree ${WORKTREE_PATH} (agent: ${AGENT_TYPE})" >&2
+echo "$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›") propagated config to worktree ${WORKTREE_PATH} (agent: ${AGENT_TYPE})" >&2
 
 echo '{}'
 exit 0

package/files/hooks/worktree-remove.sh

@@ -48,7 +48,7 @@ fi
 
 LIFETIME_MSG=""
 [ -n "$LIFETIME_S" ] && LIFETIME_MSG=" (lifetime: ${LIFETIME_S}s)"
-echo "⟡🔮 MERLIN › cleaned up worktree ${WORKTREE_PATH}${LIFETIME_MSG} (agent: ${AGENT_TYPE})" >&2
+echo "$("${HOME}/.claude/scripts/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›") cleaned up worktree ${WORKTREE_PATH}${LIFETIME_MSG} (agent: ${AGENT_TYPE})" >&2
 
 echo '{}'
 exit 0

package/files/merlin/skills/duo/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: merlin:duo
+description: Toggle and inspect Merlin's duo mode (parallel + sequential dual-brain Claude+Codex execution).
+args:
+  - name: subcommand
+    enum: [on, off, status, unsuppress, offer]
+    default: status
+---
+
+# merlin:duo
+
+Duo mode runs Claude AND Codex on the same task — parallel for planning/docs/review/tests,
+sequential for code write/modify. The reviewer-decider merges or gates each step.
+
+## Subcommands
+
+| Subcommand   | What it does                                                                 |
+|--------------|-----------------------------------------------------------------------------|
+| `on`         | Enable duo mode (install-gate checked silently; fallback if Codex missing). |
+| `off`        | Disable duo mode, revert to solo routing.                                    |
+| `status`     | Show current state, age, expiry, suppression summary, install gate result.  |
+| `unsuppress` | Clear suppression memory (session skip, never-for intents, declined hashes).|
+| `offer`      | Internal — show risk-based offer prompt (invoked by duo-pre-route.sh).      |
+
+## Execution
+
+**Step 1 — Resolve subcommand.**
+Use the `subcommand` arg. If absent or empty, default to `status`.
+
+**Step 2 — Read current state.**
+```bash
+~/.claude/scripts/duo-mode-read.sh
+```
+Captures `enabled` or `disabled` to understand current state before branching.
+
+**Step 3 — Branch to subcommand file.**
+
+| subcommand   | Load and execute                              |
+|--------------|-----------------------------------------------|
+| `on`         | `~/.claude/skills/merlin/duo/on.md`           |
+| `off`        | `~/.claude/skills/merlin/duo/off.md`          |
+| `status`     | `~/.claude/skills/merlin/duo/status.md`       |
+| `unsuppress` | `~/.claude/skills/merlin/duo/unsuppress.md`   |
+| `offer`      | `~/.claude/skills/merlin/duo/offer.md` (if it exists; else fallback to status.md) |
+
+**Step 4 — Conclude with badge.**
+Always end by calling `~/.claude/scripts/duo-badge.sh` and displaying the badge so the
+user can confirm the current mode at a glance.