create-merlin-brain 4.0.0 → 5.0.0

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

@@ -0,0 +1,95 @@
+# duo/status — report current duo state
+
+## Steps
+
+**Step 1 — Parse duo-mode.json with 24h expiry logic.**
+```bash
+python3 - <<'PYEOF'
+import json, os, sys
+from datetime import datetime, timezone, timedelta
+
+state_path = os.path.expanduser("~/.claude/merlin-state/duo-mode.json")
+try:
+    data = json.load(open(state_path))
+except:
+    data = {"enabled": False, "sinceISO": None, "lastToggleReason": None}
+
+enabled = data.get("enabled", False)
+since_iso = data.get("sinceISO")
+reason = data.get("lastToggleReason") or "never enabled"
+
+age_str = ""
+status_label = "OFF"
+expired = False
+
+if enabled and since_iso:
+    try:
+        since_dt = datetime.fromisoformat(since_iso.replace("Z", "+00:00"))
+        now_dt = datetime.now(timezone.utc)
+        delta = now_dt - since_dt
+        if delta > timedelta(hours=24):
+            expired = True
+            status_label = "AUTO-EXPIRED"
+        else:
+            status_label = "ON"
+            total_s = int(delta.total_seconds())
+            age_str = f"{total_s // 3600:02d}:{(total_s % 3600) // 60:02d}"
+    except:
+        expired = True
+        status_label = "AUTO-EXPIRED"
+
+print(f"status={status_label}")
+print(f"since={since_iso or 'n/a'}")
+print(f"age={age_str or 'n/a'}")
+print(f"reason={reason}")
+print(f"expired={expired}")
+PYEOF
+```
+
+**Step 2 — Check Codex install gate.**
+```bash
+~/.claude/scripts/duo-installed.sh 2>/dev/null && echo "gate=pass" || echo "gate=fail"
+```
+
+**Step 3 — Parse duo-suppress.json.**
+```bash
+python3 - <<'PYEOF'
+import json, os
+f = os.path.expanduser("~/.claude/merlin-state/duo-suppress.json")
+try:
+    d = json.load(open(f))
+except:
+    d = {"session_skip": False, "never_for_intents": [], "task_hashes_declined": []}
+
+print(f"session_skip={d.get('session_skip', False)}")
+print(f"intents_count={len(d.get('never_for_intents', []))}")
+print(f"hashes_count={len(d.get('task_hashes_declined', []))}")
+PYEOF
+```
+
+**Step 4 — Emit status output.**
+
+Use the values above to emit ONE of these formats:
+
+If status=ON:
+```
+⟡🔮↔🔮 MERLIN·DUO › Duo: ON · since {sinceISO} · age {hh:mm} · reason: {lastToggleReason}
+```
+
+If status=OFF:
+```
+⟡🔮 MERLIN › Duo: OFF (last reason: {lastToggleReason})
+```
+
+If status=AUTO-EXPIRED:
+```
+⟡🔮 MERLIN › Duo: AUTO-EXPIRED (was on since {sinceISO}, exceeded 24h). Treating as off.
+```
+
+Then append install gate and suppression lines:
+```
+Codex install gate: ✓ pass   (or ✗ fail — duo would silent-fallback to solo)
+Session skip: {true|false}
+Suppressed intents: {N}   (if N > 0, add: — run Skill("merlin:duo", args="unsuppress") to clear)
+Recently declined task hashes: {N}
+```

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

@@ -0,0 +1,122 @@
+# duo/unsuppress — interactive suppression memory clearer
+
+## Steps
+
+**Step 1 — Read suppression state with exclusive lock.**
+```bash
+SUPPRESS_FILE="${HOME}/.claude/merlin-state/duo-suppress.json"
+LOCK_FILE="${HOME}/.claude/merlin-state/.duo-suppress.lock"
+
+flock -x "$LOCK_FILE" -c "python3 - '$SUPPRESS_FILE'" <<'PYEOF'
+import json, sys
+
+state_path = sys.argv[1]
+try:
+    data = json.load(open(state_path))
+except:
+    data = {"session_skip": False, "never_for_intents": [], "task_hashes_declined": []}
+
+session_skip = data.get("session_skip", False)
+intents = data.get("never_for_intents", [])
+hashes = data.get("task_hashes_declined", [])
+
+print(f"session_skip={session_skip}")
+print(f"intents_count={len(intents)}")
+print(f"hashes_count={len(hashes)}")
+for i, intent in enumerate(intents):
+    print(f"intent_{i}={intent}")
+PYEOF
+```
+
+**Step 2 — Check for empty state.**
+If `session_skip=false` AND `intents_count=0` AND `hashes_count=0`:
+```
+⟡🔮 MERLIN › Nothing suppressed. Duo offers fire on all qualifying tasks.
+```
+Stop here.
+
+**Step 3 — Display current suppression state.**
+```
+⟡🔮 MERLIN › Duo suppression memory:
+• Session skip: {true|false}
+• Never-for intents ({N}): [{list of intents, or "none"}]
+• Recently declined task hashes ({N}): [{first 5 hashes then "...and X more" if >5}]
+```
+
+**Step 4 — Ask user for choice.**
+```
+Reply with:
+• "clear all"       — wipe everything
+• "clear session"   — un-set session_skip only
+• "clear intents"   — wipe never_for_intents only
+• "clear hashes"    — wipe task_hashes_declined only
+• "clear <fingerprint>" — remove one specific never_for_intents entry (paste from list above)
+• "cancel"          — leave as-is
+```
+
+**Step 5 — Apply chosen change atomically.**
+After user replies, execute the matching branch with atomic write:
+
+```bash
+SUPPRESS_FILE="${HOME}/.claude/merlin-state/duo-suppress.json"
+LOCK_FILE="${HOME}/.claude/merlin-state/.duo-suppress.lock"
+USER_CHOICE="<user reply>"
+
+flock -x "$LOCK_FILE" -c "python3 - '$SUPPRESS_FILE' '$USER_CHOICE'" <<'PYEOF'
+import json, sys, os, tempfile
+
+state_path = sys.argv[1]
+choice = sys.argv[2].strip().lower()
+
+try:
+    data = json.load(open(state_path))
+except:
+    data = {"session_skip": False, "never_for_intents": [], "task_hashes_declined": []}
+
+cleared = []
+
+if choice == "clear all":
+    data = {"session_skip": False, "never_for_intents": [], "task_hashes_declined": []}
+    cleared = ["session_skip", "never_for_intents", "task_hashes_declined"]
+elif choice == "clear session":
+    data["session_skip"] = False
+    cleared = ["session_skip"]
+elif choice == "clear intents":
+    data["never_for_intents"] = []
+    cleared = ["never_for_intents"]
+elif choice == "clear hashes":
+    data["task_hashes_declined"] = []
+    cleared = ["task_hashes_declined"]
+elif choice.startswith("clear "):
+    fingerprint = sys.argv[2][6:].strip()
+    before = len(data.get("never_for_intents", []))
+    data["never_for_intents"] = [x for x in data.get("never_for_intents", []) if x != fingerprint]
+    after = len(data["never_for_intents"])
+    cleared = [f"intent:{fingerprint}"] if after < before else []
+elif choice == "cancel":
+    print("cancelled")
+    sys.exit(0)
+else:
+    print("unrecognized — no changes made")
+    sys.exit(0)
+
+tmp = tempfile.NamedTemporaryFile(
+    mode="w", dir=os.path.dirname(state_path), delete=False, suffix=".tmp"
+)
+json.dump(data, tmp, indent=2)
+tmp.close()
+os.replace(tmp.name, state_path)
+
+print(f"cleared={','.join(cleared) if cleared else 'nothing'}")
+PYEOF
+```
+
+**Step 6 — Emit confirmation.**
+Show what was cleared, e.g.:
+```
+⟡🔮 MERLIN › Cleared: {cleared list}. Duo offers will fire normally for affected tasks.
+```
+If user said "cancel":
+```
+⟡🔮 MERLIN › No changes made.
+```

package/files/merlin-state/codex-mode.json

@@ -0,0 +1 @@
+{"enabled": false, "sinceISO": null, "lastToggleReason": null}

package/files/merlin-state/duo-mode.json

@@ -0,0 +1,5 @@
+{
+  "enabled": false,
+  "sinceISO": null,
+  "lastToggleReason": null
+}

package/files/merlin-state/duo-suppress.json

@@ -0,0 +1,5 @@
+{
+  "session_skip": false,
+  "never_for_intents": [],
+  "task_hashes_declined": []
+}

package/files/merlin-system-prompt.txt

@@ -1 +1 @@
-MANDATORY: You are Merlin, an orchestrator. Before processing any user request, call merlin_get_selected_repo, merlin_get_project_status, merlin_get_rules and merlin_get_brief. Route ALL implementation work to specialist agents via Skill("merlin:workflow") or merlin_route(). NEVER write, edit, or debug code yourself. Prefix every action with the ⟡🔮 MERLIN › badge. Run independent agents in PARALLEL. Before editing code, call merlin_get_context first.
+MANDATORY: You are Merlin, an orchestrator. Before processing any user request, call merlin_get_selected_repo, merlin_get_project_status, merlin_get_rules and merlin_get_brief. Route ALL implementation work to specialist agents via Skill("merlin:workflow") or merlin_route(). NEVER write, edit, or debug code yourself. Prefix every action with the badge from ~/.claude/scripts/duo-badge.sh (solo: ⟡🔮 MERLIN ›, duo: ⟡🔮↔🔮 MERLIN·DUO ›). Run independent agents in PARALLEL. Before editing code, call merlin_get_context first.

package/files/rules/codex-routing.md

@@ -0,0 +1,117 @@
+# Codex Execution Layer — Routing Rules
+
+This document defines how Merlin integrates with OpenAI Codex for code execution.
+
+## Install Gate (MANDATORY)
+
+Before ANY Codex routing, check if Codex is installed:
+
+```bash
+~/.claude/scripts/codex-installed.sh && echo installed || echo not-installed
+```
+
+- If the check FAILS (exit 1): silently fall back to Claude specialist — NO mention of Codex to the user
+- If the check PASSES (exit 0): proceed with Codex routing
+
+**Never skip the install gate. Never mention Codex if it's not installed.**
+
+## Scenarios
+
+| Scenario | Trigger | Action |
+|---|---|---|
+| **1. Failed-fix Escalation** | After `merlin_run_verification` fails OR user says "still broken" / "didn't work" / "same error" / "that didn't fix it" | Route to `codex-escalator` with bundle: {original_issue, claude_diagnosis, claude_diff, failure_evidence}. ONE attempt only — if Codex also fails, stop and report both attempts. |
+| **2. Big-feature Dual-plan** | `feature-dev` or `refactor` workflow starts (NOT bug-fix, NOT quick) | Run `merlin-planner` AND `codex-planner` in PARALLEL. Route both plans to `challenger-arbiter` for synthesis. Execute unified plan with `codex-implementer` for coding; Claude orchestrates and verifies. |
+| **3. Manual Codex Mode** | Natural language toggle (see phrases below) | While enabled, EVERY implementation/edit/refactor routes to `codex-implementer`. Planning, orchestration, and verification stay with Claude. |
+
+## Scenario 3: Manual Codex-Execution Mode
+
+### Turn-On Phrases
+- "use codex to code"
+- "let codex do the coding"
+- "code with codex"
+- "codex hands"
+- "switch to codex for this"
+- "codex execute"
+
+### Turn-Off Phrases
+- "back to claude"
+- "stop codex"
+- "claude does the coding"
+- "disable codex"
+
+### State Management
+
+When turned ON, write to `~/.claude/merlin-state/codex-mode.json`:
+```json
+{"enabled": true, "sinceISO": "<ISO timestamp>", "lastToggleReason": "user said X"}
+```
+
+When turned OFF:
+```json
+{"enabled": false, "sinceISO": null, "lastToggleReason": "user said X"}
+```
+
+### Auto-Expire
+
+If `sinceISO` is more than 24 hours old, treat as disabled. This approximates session-sticky behavior — mode resets between sessions.
+
+## Skill Injection Mechanism
+
+`codex-implementer` uses `codex-as.sh` which:
+1. Reads the Merlin specialist's `.md` file (e.g., `~/.claude/agents/implementation-dev.md`)
+2. Strips YAML frontmatter
+3. Extracts the prompt body
+4. Prepends it to the Codex invocation
+
+This gives Codex the SAME system prompt, instructions, and constraints that the Claude specialist would have. Same patterns, same guardrails, different brain.
+
+## Verification Authority
+
+**Claude ALWAYS verifies**, regardless of who wrote the code:
+- After `codex-escalator` completes → run `merlin_run_verification()`
+- After `codex-implementer` completes → run `merlin_run_verification()`
+- After dual-plan execution step → Claude verifies before proceeding
+
+This is the "brain/hands split" — Codex may execute, but Claude certifies.
+
+## Curated Specialists
+
+Codex can embody these roles via `codex-as.sh`:
+- `implementation-dev` — General implementation
+- `dry-refactor` — DRY cleanup and refactoring
+- `hardening-guard` — Security hardening
+- `ui-builder` — React/UI components
+- `android-expert` — Android/Kotlin
+- `apple-swift-expert` — iOS/macOS Swift
+- `desktop-app-expert` — Electron/Tauri
+- `merlin-frontend` — Frontend specialist
+- `animation-expert` — Motion/animation
+- `code-review` — Production-readiness code review
+
+**Excluded from codex-as.sh:**
+- `reviewer-decider` — Claude-only by design (sequential gate authority)
+
+Any other specialist stays with Claude.
+
+## Code Review Routing
+
+Natural language intent: "code review" / "production readiness review" / "review the codebase" / "check for AI smells" / "review this folder" / "do a full review"
+
+Routing logic:
+1. Check codex-mode.json state (enabled + within 24h) AND `codex-installed.sh` returns 0
+2. If both true → route to `codex-code-review` agent (Codex gpt-5.4)
+3. Otherwise → route to `code-review` agent (Claude Opus)
+
+Both produce the same CODE_REVIEW.md report format. User can override by saying "use claude for code review" or "use codex for code review".
+
+---
+
+## Duo Mode — see `duo-routing.md`
+
+When duo is enabled (`~/.claude/merlin-state/duo-mode.json: enabled=true`, within 24h, install gate passes), duo routing in `duo-routing.md` SUPERSEDES the rules in this file. Codex-mode does not need to be on for duo to work — duo manages its own state.
+
+When duo is OFF, the rules in this file (codex-mode escalation, dual-plan, manual codex hands) apply normally.
+
+### Curated specialists exclusion (P0 safety)
+
+`reviewer-decider` is **Claude-only** and MUST NOT be added to the curated specialists list for `codex-as.sh`. Codex impersonating the gate that checks Codex defeats the sequential safety story.

package/files/rules/duo-routing.md

@@ -0,0 +1,203 @@
+# Duo Mode — Routing Rules
+
+This document is the single source of truth for duo mode. Do not duplicate routing logic elsewhere — cross-reference this file instead.
+
+## What duo is
+
+Duo mode runs two brains on the same task: Claude and Codex. Tasks that produce independent artifacts (plans, reports, markdown, test files) run in **parallel** — both brains work simultaneously and an arbiter merges outputs. Tasks that write or modify source files run **sequentially** — one author at a time, followed by a Claude reviewer and a structured gate decision. This eliminates file-conflict risk while still getting two perspectives on every code change.
+
+---
+
+## Activation
+
+**State file:** `~/.claude/merlin-state/duo-mode.json`
+
+**Schema:**
+```json
+{"enabled": bool, "sinceISO": "ISO8601 | null", "lastToggleReason": "string | null"}
+```
+
+**Default (first install):**
+```json
+{"enabled": false, "sinceISO": null, "lastToggleReason": null}
+```
+
+**Auto-expire:** If `sinceISO` is more than 24 hours old at read time, treat as disabled. The file is NOT rewritten on read — expiry is a read-time interpretation. Approximately session-sticky.
+
+**Toggle:** `Skill("merlin:duo", args="on|off|status|unsuppress")` or natural language (see `merlin-routing.md` for intent triggers).
+
+**Install gate:** Run `~/.claude/scripts/duo-installed.sh` before any duo activation. If gate returns non-zero:
+- Silently fall back to solo routing for this task
+- Do NOT write `enabled: true` to the state file
+- Do NOT mention duo, Codex, or the gate failure to the user
+- Proceed as if duo was never considered
+
+---
+
+## Precedence
+
+When multiple modes are enabled simultaneously:
+
+1. **Duo active** (enabled=true, within 24h, gate passes) → duo rules in this file win
+2. **Codex-mode active** (enabled=true, within 24h, codex gate passes) → `codex-routing.md` rules apply
+3. **Neither** → solo routing (existing `merlin-routing.md` + `codex-routing.md` rules)
+
+Note: duo does NOT require `codex-mode.json` to be enabled. Duo manages its own state independently.
+
+---
+
+## Badge contract (UNMISSABLE)
+
+Compute the badge via `~/.claude/scripts/duo-badge.sh` before every action prefix.
+
+| Condition | Badge |
+|---|---|
+| Duo enabled + within 24h + gate passes | `⟡🔮↔🔮 MERLIN·DUO ›` |
+| Any other state | `⟡🔮 MERLIN ›` |
+
+**Text-only fallback:** If env `MERLIN_BADGE_TEXTONLY=1`, `duo-badge.sh` returns `[DUO] MERLIN ›` or `MERLIN ›` for terminals that mangle `↔` or emoji.
+
+Every Merlin action MUST prefix with the computed badge. If the badge is missing, the action is non-compliant. See badge audit: `.planning/duo/BADGE-AUDIT.md`.
+
+Special case — `duo off` when codex-mode is still active:
+```
+⟡🔮 MERLIN › Duo off. (codex-mode is still active.)
+```
+
+---
+
+## Routing Matrix — PARALLEL execution
+
+Both brains run independently on the same task. Results are routed to the arbiter for merging or deduplication. **Parallel tasks ONLY produce reports, plans, markdown, or test files — never edits to existing source code.** Source edits are always sequential (see below).
+
+| Task | Brain A | Brain B | Decider |
+|---|---|---|---|
+| Planning (feature-dev / refactor / product-dev) | `merlin-planner` | `codex-planner` | `challenger-arbiter` |
+| Documentation | `docs-keeper` (Claude) | `docs-keeper` via `codex-as.sh` | `challenger-arbiter` |
+| Code review | `code-review` | `codex-code-review` | merge + dedupe (in arbiter) |
+| Testing | `tests-qa` (Claude) | `tests-qa` via `codex-as.sh` | merge + dedupe (in arbiter) |
+
+**UX during parallel runs:**
+```
+⟡🔮↔🔮 MERLIN·DUO › Planning ×2 (claude + codex)…
+⟡🔮↔🔮 MERLIN·DUO › Arbiter merging plans…
+⟡🔮↔🔮 MERLIN·DUO › Plan ready.
+```
+
+---
+
+## Routing Matrix — SEQUENTIAL execution
+
+One author at a time to prevent file conflicts. Sequential only for tasks that write or modify source files.
+
+| Task | Author | Reviewer | Decider |
+|---|---|---|---|
+| Code write (new files) | `codex-implementer` | `code-review` (Claude) | `reviewer-decider` (Claude) |
+| Code modification | `codex-implementer` | `code-review` (Claude) | `reviewer-decider` (Claude) |
+
+**Sequential decision flow:**
+
+1. Author (`codex-implementer`) writes diff
+2. Reviewer (`code-review`, Claude) reviews diff
+3. `reviewer-decider` returns `{decision: approve|revise|reject, reasoning, required_changes?}`
+4. **On `approve`:** proceed to verification
+5. **On `revise`:** author iterates ONCE with `required_changes`. Re-review. If revise again → escalate to reject.
+6. **On `reject`** OR second revise without resolution: Claude reviewer takes over and writes the fix directly
+
+Maximum iterations per task: 2 (one initial pass + one revise loop). `reviewer-decider` enforces `iteration_count` ≤ 2.
+
+**UX during sequential runs:**
+```
+⟡🔮↔🔮 MERLIN·DUO › [1/3] Codex writing diff…
+⟡🔮↔🔮 MERLIN·DUO › [2/3] Claude reviewing…
+⟡🔮↔🔮 MERLIN·DUO › [3/3] Decision: approve · proceeding to verify
+```
+
+If decider returns `revise`:
+```
+⟡🔮↔🔮 MERLIN·DUO › Iteration 2/2: codex revising…
+```
+
+---
+
+## reviewer-decider is Claude-only (P0 safety)
+
+`reviewer-decider` MUST NOT be invoked via `codex-as.sh`. Codex impersonating the gate that checks Codex's own output destroys the sequential safety story. The curated specialists list in `codex-routing.md` explicitly excludes `reviewer-decider` — this exclusion is permanent and must not be removed.
+
+See also: `codex-routing.md` § "Curated specialists exclusion".
+
+---
+
+## Auto-offer for risky tasks
+
+When duo is OFF, Merlin runs a pre-route hook at the start of every routing decision:
+
+1. Call `~/.claude/scripts/duo-pre-route.sh --task "..." [--workflow X] [--files a,b] [--loc N]`
+2. Hook reads `duo-mode.json`, calls `duo-installed.sh`, calls `duo-risk-detect.sh`, checks `duo-suppress.json`
+3. Hook outputs exactly one of:
+   - `mode=duo` → proceed with duo routing (duo was already on)
+   - `mode=offer` → invoke `Skill("merlin:duo", args="offer")` first; user response determines mode
+   - `mode=solo` → fall through to existing solo/codex-mode rules
+
+**Risk threshold:** `duo-risk-detect.sh` scores the task 0–100. `suggest_duo: true` when score ≥ 50. Threshold tunable via env `MERLIN_DUO_OFFER_THRESHOLD`.
+
+**Offer fires only when ALL of the following are true:**
+- `duo-installed.sh` exits 0 (Codex installed)
+- Duo is currently OFF (or auto-expired)
+- Risk score ≥ threshold
+- Not suppressed (no `session_skip`, task hash not in `task_hashes_declined`, intent not in `never_for_intents`)
+
+**Offer is one-shot per task.** Never offer mid-flight. If `duo-pre-route.sh` errors or times out (>500ms), skip the offer silently and log to `duo-decisions.log`.
+
+**Suppression memory:** `~/.claude/merlin-state/duo-suppress.json`. Reset via `Skill("merlin:duo", args="unsuppress")`. `never_for_intents` entries auto-expire after 7 days. `session_skip` clears when file mtime is > 12h old.
+
+---
+
+## Codex-broken-runtime fallback (P0)
+
+`duo-installed.sh` only checks PATH presence. If Codex is on PATH but fails at runtime:
+
+1. Wrap all Codex invocations with a 60s timeout:
+   - With coreutils: `gtimeout 60s codex …`
+   - Without coreutils: `perl -e 'alarm 60; exec @ARGV' codex …`
+2. On Codex error or timeout: log to `~/.claude/merlin-state/duo-decisions.log` with severity `codex_runtime_failure`. Fall back to Claude for that step:
+   - Parallel branch: drop the codex result; arbiter receives one input
+   - Sequential branch: Claude takes the author role
+3. After 3 consecutive Codex failures in a session: surface the following message, write `enabled: false` to `duo-mode.json` with `lastToggleReason: "codex runtime failures"`, and revert to solo:
+
+```
+⟡🔮 MERLIN › Codex appears unhealthy. Reverting to solo for this session. Run 'codex doctor' to diagnose.
+```
+
+---
+
+## Verification authority (UNCHANGED)
+
+Claude ALWAYS runs `merlin_run_verification()` after a duo flow completes, regardless of who wrote the code. This is the brain/hands principle — Codex (or any specialist) may execute, but Claude certifies.
+
+---
+
+## Workflow integration
+
+| Workflow | When duo ON | When duo OFF |
+|---|---|---|
+| `feature-dev` | Parallel planning + sequential coding | Existing codex-mode dual-plan or solo |
+| `refactor` | Parallel planning + sequential coding | Existing codex-mode dual-plan or solo |
+| `product-dev` | Parallel planning + sequential coding | Solo |
+| `bug-fix` | Solo by default; opt-in via "duo this" | Solo |
+| `quick` | Solo by default; opt-in via "duo this" | Solo |
+| Code review intent | Parallel review pair | `code-review` or `codex-code-review` (codex-routing rules) |
+| Tests intent | Parallel test generation pair | Solo |
+| Docs intent | Parallel docs pair | Solo |
+
+---
+
+## Cross-references
+
+- Codex execution layer: `~/.claude/rules/codex-routing.md`
+- Intent triggers (toggle phrases, workflow routing): `~/.claude/rules/merlin-routing.md`
+- Skill prompts: `~/.claude/skills/merlin/duo/` (SKILL.md, on.md, off.md, status.md, offer.md)
+- Reviewer-decider agent: `~/.claude/agents/reviewer-decider.md`
+- Badge audit: `.planning/duo/BADGE-AUDIT.md`
+- State files: `~/.claude/merlin-state/duo-mode.json`, `~/.claude/merlin-state/duo-suppress.json`
+- Decision audit log: `~/.claude/merlin-state/duo-decisions.log` (JSONL, append-only)

package/files/rules/merlin-routing.md

@@ -38,6 +38,7 @@ Call `merlin_smart_route(task="...")` FIRST (searches 500+ community agents). Th
 | Database migrations | `merlin-migrator` |
 | API design | `merlin-api-designer` |
 | Code review | `merlin-reviewer` |
+| Production code review / AI-smell audit | `code-review` (or `codex-code-review` in Codex mode) |
 | Performance | `merlin-performance` |
 
 ## Collaborative Intents — Auto-Detect from Natural Language
@@ -57,6 +58,10 @@ Call `merlin_smart_route(task="...")` FIRST (searches 500+ community agents). Th
 | "remind me" / "add a todo" | `Skill("merlin:add-todo")` |
 | "check todos" / "pending items" | `Skill("merlin:check-todos")` |
 | New project, no PROJECT.md | `Skill("merlin:map-codebase")` then `Skill("merlin:new-project")` |
+| "duo on" / "enable duo" / "go duo" | `Skill("merlin:duo", args="on")` |
+| "duo off" / "disable duo" / "back to solo" | `Skill("merlin:duo", args="off")` |
+| "duo status" / "am I in duo" / "is duo on" | `Skill("merlin:duo", args="status")` |
+| "stop duo for this kind of task" / "never duo for X" | `Skill("merlin:duo", args="unsuppress")` |
 
 ## Planning Intents
 
@@ -98,3 +103,30 @@ At natural moments, surface ONE relevant capability:
 - Session end → auto-invoke `Skill("merlin:standup")`.
 - After implementation → auto-run `merlin_run_verification()`.
 - Agent failure → diagnose, retry with different config, NEVER fall back to coding yourself.
+
+## Codex Execution Layer
+
+See `~/.claude/rules/codex-routing.md` for full details.
+
+**Install Gate:** Before any Codex routing, run `~/.claude/scripts/codex-installed.sh`. If it fails, silently fall back to Claude.
+
+**Scenarios:**
+1. **Failed-fix escalation** — after verification fails, escalate to `codex-escalator`
+2. **Big-feature dual-plan** — feature-dev/refactor workflows run `merlin-planner` + `codex-planner` in parallel, then `challenger-arbiter` synthesizes
+3. **Manual Codex mode** — user toggles with natural language, all implementation routes to `codex-implementer`
+
+**State file:** `~/.claude/merlin-state/codex-mode.json`
+
+### Additional Collaborative Intents
+
+| User says | Action |
+|---|---|
+| "use codex to code" / "let codex do the coding" / "code with codex" / "codex hands" / "switch to codex for this" / "codex execute" | Write `{"enabled": true, "sinceISO": "<now>", "lastToggleReason": "user said X"}` to `~/.claude/merlin-state/codex-mode.json`. Route implementation to `codex-implementer`. |
+| "back to claude" / "stop codex" / "claude does the coding" / "disable codex" | Write `{"enabled": false, ...}` to `~/.claude/merlin-state/codex-mode.json`. Resume normal Claude routing. |
+
+### Additional Workflow Routing Notes
+
+- `feature-dev` and `refactor` workflows: If Codex installed, use dual-plan flow (merlin-planner + codex-planner → challenger-arbiter → codex-implementer execution)
+- `bug-fix` and `quick`: No dual-plan — normal flow, but failed-fix escalation to codex-escalator is available
+
+> When duo mode is active, `feature-dev`, `refactor`, and `product-dev` workflows automatically use parallel planning + sequential coding. See `duo-routing.md`.

package/files/scripts/codex-as.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# codex-as.sh — invoke Codex as a Merlin specialist agent
+# Usage: codex-as.sh <agent-name> <task-text> [--model <model-name>]
+
+set -euo pipefail
+
+# Install gate: if codex is not installed, exit silently
+command -v codex >/dev/null 2>&1 || exit 0
+
+AGENT_NAME=""
+TASK_TEXT=""
+MODEL_FLAG=""
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --model)
+            if [[ -n "${2:-}" ]]; then
+                MODEL_FLAG="--model $2"
+                shift 2
+            else
+                echo "Error: --model requires a value" >&2
+                exit 1
+            fi
+            ;;
+        *)
+            if [[ -z "$AGENT_NAME" ]]; then
+                AGENT_NAME="$1"
+            elif [[ -z "$TASK_TEXT" ]]; then
+                TASK_TEXT="$1"
+            fi
+            shift
+            ;;
+    esac
+done
+
+if [[ -z "$AGENT_NAME" ]]; then
+    echo "Usage: codex-as.sh <agent-name> <task-text> [--model <model-name>]" >&2
+    exit 1
+fi
+
+AGENT_FILE="$HOME/.claude/agents/${AGENT_NAME}.md"
+
+if [[ ! -f "$AGENT_FILE" ]]; then
+    echo "Error: Agent file not found: $AGENT_FILE" >&2
+    exit 1
+fi
+
+# Extract prompt body by stripping YAML frontmatter
+# Frontmatter is between --- lines at the start of the file
+PROMPT_BODY=$(awk '
+    BEGIN { in_frontmatter = 0; past_frontmatter = 0 }
+    /^---$/ {
+        if (!past_frontmatter) {
+            in_frontmatter = !in_frontmatter
+            if (!in_frontmatter) past_frontmatter = 1
+            next
+        }
+    }
+    past_frontmatter { print }
+' "$AGENT_FILE")
+
+# Build the full prompt: agent system prompt + separator + task
+FULL_PROMPT="${PROMPT_BODY}
+
+---
+
+## Task
+
+${TASK_TEXT}"
+
+# Invoke codex with --write to allow file modifications
+# shellcheck disable=SC2086
+exec codex exec --write --cd "$PWD" $MODEL_FLAG "$FULL_PROMPT"