create-merlin-brain 5.0.2 → 5.3.2

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

@@ -1,6 +1,6 @@
 ---
 name: duo-offer
-description: Auto-offer prompt for enabling duo mode on risky tasks. Invoked by duo-pre-route.sh when risk score >= threshold and Codex is installed and duo is off and task is not suppressed.
+description: Auto-offer prompt for enabling duo mode on risky tasks. Invoked by duo-pre-route.sh when risk score >= threshold and duo is off and task is not suppressed.
 type: skill
 subcommand: offer
 ---
@@ -13,9 +13,10 @@ You are executing the duo auto-offer flow. Follow every step in sequence.
 
 Run `~/.claude/scripts/duo-mode-read.sh`. If output is `enabled`, exit silently — duo is already on, no offer needed.
 
-## Step 2 — Install gate
-
-Run `~/.claude/scripts/duo-installed.sh`. If exit code != 0, exit silently — do not mention duo or Codex.
+## Step 2 — Detect pair (informational only — never blocks the offer).
+Run `~/.claude/scripts/codex-installed.sh`. Capture exit code.
+If exit 0 → PAIR=claude+codex
+Else → PAIR=claude+claude
 
 ## Step 3 — Read context
 
@@ -95,8 +96,9 @@ Map reasons to human-readable category labels (never display raw file paths):
 - `keyword:ship`, `keyword:release`, `keyword:critical` → "release-critical"
 - `dep:package.json`, `dep:go.mod`, `dep:Cargo.toml`, `dep:requirements.txt` → "dependency changes"
 
-Display (show at most 3 categories, never raw paths):
+Display (show at most 3 categories, never raw paths). Tailor the pair line to PAIR:
 
+If PAIR == claude+codex:
 ```
 ⟡🔮 MERLIN › This task looks risky (score <SCORE>/100).
   • Areas: <comma-separated categories>
@@ -107,13 +109,24 @@ Reply: yes (enable duo) · no (solo) · skip session · never
 (default = solo if you don't reply explicitly)
 ```
 
+If PAIR == claude+claude:
+```
+⟡🔮 MERLIN › This task looks risky (score <SCORE>/100).
+  • Areas: <comma-separated categories>
+  • Workflow: <workflow or "general">
+  Twin-Claude pair would tag-team this (sequential write + review with decider gate).
+
+Reply: yes (enable duo) · no (solo) · skip session · never
+(default = solo if you don't reply explicitly)
+```
+
 ## Step 7 — Parse user reply (case-insensitive)
 
 Wait for the user's response, then:
 
 | Reply contains | Action |
 |---|---|
-| `yes` / `enable duo` / `do it` | Call `~/.claude/scripts/duo-mode-write.sh on "auto-offer accepted: <reasons>"` then set `DUO_OFFER_OUTCOME=yes` |
+| `yes` / `enable duo` / `do it` | Call `~/.claude/scripts/duo-mode-write.sh on "auto-offer accepted: <reasons>" "$PAIR"` then set `DUO_OFFER_OUTCOME=yes` |
 | `skip session` / `skip this session` | Set `session_skip:true` in duo-suppress.json (atomic, flock), set `DUO_OFFER_OUTCOME=skip-session` |
 | `never` | Add intent fingerprint to `never_for_intents` (FIFO cap 20, with timestamp), set `DUO_OFFER_OUTCOME=never` |
 | `no` / anything else / silence | Add task_hash to `task_hashes_declined` (FIFO cap 100), set `DUO_OFFER_OUTCOME=no` |
@@ -149,7 +162,7 @@ EOF
 Append to `~/.claude/merlin-state/duo-decisions.log` (create if missing, JSONL):
 
 ```json
-{"ts":"<ISO8601>","event":"offer","score":<N>,"reasons":[...],"response":"<yes|no|skip-session|never|silent>","action":"<enable|solo|suppress-session|suppress-intent|suppress-task>"}
+{"ts":"<ISO8601>","event":"offer","score":<N>,"reasons":[...],"response":"<yes|no|skip-session|never|silent>","action":"<enable|solo|suppress-session|suppress-intent|suppress-task>","pair":"<claude+codex|claude+claude>"}
 ```
 
 ## Step 9 — Continue

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

@@ -2,29 +2,23 @@
 
 ## Steps
 
-**Step 1 — Check install gate.**
-```bash
-~/.claude/scripts/duo-installed.sh
-EXIT_CODE=$?
-```
+**Step 1 — Check current state.**
+Run `~/.claude/scripts/duo-mode-read.sh`. If output is `enabled`, duo is already on — skip to Step 4 to show current confirmation and stop.
 
-**Step 2 — Gate failed (Codex not installed).**
-If exit code != 0:
-```bash
-~/.claude/scripts/duo-mode-write.sh off "install gate failed (silent fallback)"
-```
-Do NOT mention duo mode, Codex, or this branch to the user. Continue with whatever
-the user originally requested as if this skill was never invoked. Stop here.
+**Step 2 — Detect pair.**
+Run `~/.claude/scripts/codex-installed.sh`. If exit 0 → PAIR=claude+codex. Else → PAIR=claude+claude.
 
-**Step 3 — Gate passed. Enable duo.**
+**Step 3 — Enable duo with pair.**
 ```bash
-~/.claude/scripts/duo-mode-write.sh on "<user's phrase that triggered enable>"
+~/.claude/scripts/duo-mode-write.sh on "<user's phrase that triggered enable>" "$PAIR"
 BADGE=$(~/.claude/scripts/duo-badge.sh)
 ```
 
-**Step 4 — Emit confirmation.**
+**Step 4 — Emit confirmation tailored to pair.**
+
+If PAIR == claude+codex:
 ```
-⟡🔮↔🔮 MERLIN·DUO › Duo mode enabled.
+⟡🔮↔🔮 MERLIN·DUO › Duo mode enabled (Claude + Codex).
 • Parallel: planning, docs, code review, tests
 • Sequential: code write/modify (codex writes → claude reviews → decider gates)
 • Verification stays with Claude
@@ -33,7 +27,22 @@ BADGE=$(~/.claude/scripts/duo-badge.sh)
 Try: "plan the next phase" to see dual-planning.
 ```
 
-**Step 5 — Codex-mode coexistence check.**
+If PAIR == claude+claude:
+```
+⟡🔮↔🔮 MERLIN·DUO › Duo mode enabled (twin-Claude — Codex not installed).
+Two Claude specialists tag-team your work:
+• Parallel planning: merlin-planner + challenger-academic → arbiter
+• Parallel review:   code-review + merlin-reviewer → arbiter
+• Parallel testing:  tests-qa + merlin-edge-case-hunter → arbiter
+• Sequential code:   implementation-dev writes → code-review reviews → decider gates
+• Verification stays with Claude
+• Auto-expires in 24h
+(Install Codex if you want claude+codex pairing instead.)
+```
+
+**Step 5 — Codex-mode coexistence check (claude+codex pair only).**
+Skip this step if PAIR == claude+claude.
+
 ```bash
 python3 -c "
 import json, os, sys

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

@@ -12,11 +12,13 @@ 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}
+    data = {"enabled": False, "sinceISO": None, "lastToggleReason": None, "pair": None}
 
 enabled = data.get("enabled", False)
 since_iso = data.get("sinceISO")
 reason = data.get("lastToggleReason") or "never enabled"
+# Legacy state: if enabled but no pair field, default to claude+codex
+pair = data.get("pair") or ("claude+codex" if enabled else None)
 
 age_str = ""
 status_label = "OFF"
@@ -30,6 +32,7 @@ if enabled and since_iso:
         if delta > timedelta(hours=24):
             expired = True
             status_label = "AUTO-EXPIRED"
+            pair = None
         else:
             status_label = "ON"
             total_s = int(delta.total_seconds())
@@ -37,18 +40,20 @@ if enabled and since_iso:
     except:
         expired = True
         status_label = "AUTO-EXPIRED"
+        pair = None
 
 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}")
+print(f"pair={pair or 'none'}")
 PYEOF
 ```
 
 **Step 2 — Check Codex install gate.**
 ```bash
-~/.claude/scripts/duo-installed.sh 2>/dev/null && echo "gate=pass" || echo "gate=fail"
+~/.claude/scripts/codex-installed.sh 2>/dev/null && echo "gate=pass" || echo "gate=fail"
 ```
 
 **Step 3 — Parse duo-suppress.json.**
@@ -74,6 +79,7 @@ Use the values above to emit ONE of these formats:
 If status=ON:
 ```
 ⟡🔮↔🔮 MERLIN·DUO › Duo: ON · since {sinceISO} · age {hh:mm} · reason: {lastToggleReason}
+Pair: {claude+codex|claude+claude}
 ```
 
 If status=OFF:
@@ -88,7 +94,8 @@ If status=AUTO-EXPIRED:
 
 Then append install gate and suppression lines:
 ```
-Codex install gate: ✓ pass   (or ✗ fail — duo would silent-fallback to solo)
+Codex install gate: ✓ pass (claude+codex pair available)   [when gate=pass]
+Codex install gate: ✗ fail (duo runs as twin-Claude pair)  [when gate=fail]
 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/templates/DEBUG.md

@@ -1,3 +1,14 @@
+---
+provenance:
+  upstream: gsd-build/get-shit-done
+  upstream_path: templates/DEBUG.md
+  upstream_commit: 9045c81
+  license: MIT
+  license_verification: confirmed
+  adapted: "2026-03-14"
+  changes: adapted from GSD planning template
+---
+
 # Debug Template
 
 Template for `.planning/debug/[slug].md` — active debug session tracking.

package/files/merlin/templates/UAT.md

@@ -1,3 +1,14 @@
+---
+provenance:
+  upstream: gsd-build/get-shit-done
+  upstream_path: templates/UAT.md
+  upstream_commit: 9045c81
+  license: MIT
+  license_verification: confirmed
+  adapted: "2026-03-14"
+  changes: adapted from GSD planning template
+---
+
 # UAT Template
 
 Template for `.planning/phases/XX-name/{phase}-UAT.md` — persistent UAT session tracking.

package/files/merlin/templates/phase-prompt.md

@@ -1,3 +1,14 @@
+---
+provenance:
+  upstream: gsd-build/get-shit-done
+  upstream_path: templates/phase-prompt.md
+  upstream_commit: 9045c81
+  license: MIT
+  license_verification: confirmed
+  adapted: "2026-03-14"
+  changes: adapted from GSD planning template
+---
+
 # Phase Prompt Template
 
 Template for `.planning/phases/XX-name/{phase}-{plan}-PLAN.md` - executable phase plans optimized for parallel execution.

package/files/merlin/templates/project.md

@@ -1,3 +1,14 @@
+---
+provenance:
+  upstream: gsd-build/get-shit-done
+  upstream_path: templates/project.md
+  upstream_commit: 9045c81
+  license: MIT
+  license_verification: confirmed
+  adapted: "2026-03-14"
+  changes: adapted from GSD planning template
+---
+
 # PROJECT.md Template
 
 Template for `.planning/PROJECT.md` — the living project context document.

package/files/merlin/templates/requirements.md

@@ -1,3 +1,14 @@
+---
+provenance:
+  upstream: gsd-build/get-shit-done
+  upstream_path: templates/requirements.md
+  upstream_commit: 9045c81
+  license: MIT
+  license_verification: confirmed
+  adapted: "2026-03-14"
+  changes: adapted from GSD planning template
+---
+
 # Requirements Template
 
 Template for `.planning/REQUIREMENTS.md` — checkable requirements that define "done."

package/files/merlin/templates/roadmap.md

@@ -1,3 +1,14 @@
+---
+provenance:
+  upstream: gsd-build/get-shit-done
+  upstream_path: templates/roadmap.md
+  upstream_commit: 9045c81
+  license: MIT
+  license_verification: confirmed
+  adapted: "2026-03-14"
+  changes: adapted from GSD planning template
+---
+
 # Roadmap Template
 
 Template for `.planning/ROADMAP.md`.

package/files/merlin/templates/state.md

@@ -1,3 +1,14 @@
+---
+provenance:
+  upstream: gsd-build/get-shit-done
+  upstream_path: templates/state.md
+  upstream_commit: 9045c81
+  license: MIT
+  license_verification: confirmed
+  adapted: "2026-03-14"
+  changes: adapted from GSD planning template
+---
+
 # State Template
 
 Template for `.planning/STATE.md` — the project's living memory.

package/files/merlin/templates/verification-report.md

@@ -1,3 +1,14 @@
+---
+provenance:
+  upstream: gsd-build/get-shit-done
+  upstream_path: templates/verification-report.md
+  upstream_commit: 9045c81
+  license: MIT
+  license_verification: confirmed
+  adapted: "2026-03-14"
+  changes: adapted from GSD planning template
+---
+
 # Verification Report Template
 
 Template for `.planning/phases/XX-name/{phase}-VERIFICATION.md` — phase goal verification results.

package/files/merlin/workflows/execute-phase.md

@@ -1,3 +1,14 @@
+---
+provenance:
+  upstream: gsd-build/get-shit-done
+  upstream_path: workflows/execute-phase.md
+  upstream_commit: 9045c81
+  license: MIT
+  license_verification: confirmed
+  adapted: "2026-03-14"
+  changes: adapted from GSD workflow pattern
+---
+
 <purpose>
 Execute all plans in a phase using wave-based parallel execution. Orchestrator stays lean by delegating plan execution to subagents.
 </purpose>

package/files/merlin/workflows/plan-phase.md

@@ -1,3 +1,14 @@
+---
+provenance:
+  upstream: gsd-build/get-shit-done
+  upstream_path: workflows/plan-phase.md
+  upstream_commit: 9045c81
+  license: MIT
+  license_verification: confirmed
+  adapted: "2026-03-14"
+  changes: adapted from GSD workflow pattern
+---
+
 <decimal_phase_numbering>
 Decimal phases enable urgent work insertion without renumbering:
 

package/files/merlin/workflows/progress.md

@@ -1,3 +1,14 @@
+---
+provenance:
+  upstream: gsd-build/get-shit-done
+  upstream_path: workflows/progress.md
+  upstream_commit: 9045c81
+  license: MIT
+  license_verification: confirmed
+  adapted: "2026-03-14"
+  changes: adapted from GSD workflow pattern
+---
+
 <purpose>
 Check project progress, ensure backlog health, and route to next action.
 

package/files/merlin/workflows/resume-project.md

@@ -1,3 +1,14 @@
+---
+provenance:
+  upstream: gsd-build/get-shit-done
+  upstream_path: workflows/resume-project.md
+  upstream_commit: 9045c81
+  license: MIT
+  license_verification: confirmed
+  adapted: "2026-03-14"
+  changes: adapted from GSD workflow pattern
+---
+
 <trigger>
 Use this workflow when:
 - Starting a new session on an existing project

package/files/merlin/workflows/verify-phase.md

@@ -1,3 +1,14 @@
+---
+provenance:
+  upstream: gsd-build/get-shit-done
+  upstream_path: workflows/verify-phase.md
+  upstream_commit: 9045c81
+  license: MIT
+  license_verification: confirmed
+  adapted: "2026-03-14"
+  changes: adapted from GSD workflow pattern
+---
+
 <purpose>
 Verify phase goal achievement through goal-backward analysis. Check that the codebase actually delivers what the phase promised, not just that tasks were completed.
 

package/files/merlin/workflows/verify-work.md

@@ -1,3 +1,14 @@
+---
+provenance:
+  upstream: gsd-build/get-shit-done
+  upstream_path: workflows/verify-work.md
+  upstream_commit: 9045c81
+  license: MIT
+  license_verification: confirmed
+  adapted: "2026-03-14"
+  changes: adapted from GSD workflow pattern
+---
+
 <purpose>
 Validate built features through conversational testing with persistent state. Creates UAT.md that tracks test progress, survives /clear, and feeds gaps into /merlin:plan-phase --gaps.
 

package/files/merlin-system-prompt.txt

@@ -1 +1,35 @@
-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.
+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.
+
+## Duo mode (codex+codex)
+
+When `~/.claude/scripts/duo-mode-read.sh` outputs `enabled` AND `~/.claude/scripts/duo-mode-read.sh --pair` outputs `codex+codex`, you orchestrate two Codex instances per task instead of one.
+
+**Toggle from chat:**
+- "duo on" → run `~/.claude/scripts/duo-mode-write.sh on "<user phrase>"` (auto-detects codex+codex via MERLIN_RUNTIME), then announce: "⟡🔮↔🔮 MERLIN·DUO › Duo enabled (codex+codex). Two Codex specialists tag-team your work."
+- "duo off" → run `~/.claude/scripts/duo-mode-write.sh off "<reason>"`, announce: "⟡🔮 MERLIN › Duo off."
+- "duo status" → run `duo-mode-read.sh` and `--pair`, report state and pair.
+
+**Parallel tasks (planning, code review, tests, docs)** — spawn two `codex exec` subprocesses concurrently, then merge:
+- Planning: `codex exec ... codex-planner persona` and `~/.claude/scripts/codex-as.sh challenger-academic ...` in parallel. Each writes to its own file (`<phase-dir>/PLAN-CODEX-A.md` and `PLAN-CODEX-B.md`). Then `~/.claude/scripts/codex-as.sh challenger-arbiter` synthesizes to `PLAN-FINAL.md`.
+- Code review: `codex-code-review` and `codex-as.sh merlin-reviewer` in parallel; you merge their findings inline.
+- Testing: `codex-as.sh tests-qa` and `codex-as.sh merlin-edge-case-hunter` in parallel; merge inline.
+- Documentation: `codex-as.sh docs-keeper` solo — only one doc specialist exists.
+
+**Sequential tasks (code write/modify)** — strict author → reviewer → gate, but the gate is YOU (the orchestrator), not a separate agent:
+1. Author writes diff: `~/.claude/scripts/codex-as.sh implementation-dev "<task>"`
+2. Reviewer reviews: `~/.claude/scripts/codex-as.sh code-review "<diff or path>"`
+3. YOU consume the reviewer's findings and decide approve/revise/reject inline — do not delegate this gate to another spawn. (The dedicated `reviewer-decider` is Claude-only by safety design and isn't available to you.)
+4. On revise: re-run author once with required_changes, then re-review. Max 2 iterations. On second revise or reject, stop and report.
+
+**Run-parallel pattern (bash):**
+```
+( codex exec "..." > a.out 2>&1 ) &
+( codex exec "..." > b.out 2>&1 ) &
+wait
+```
+
+**Verification stays your job.** Codex specialists may execute, but you certify by running tests/builds yourself before declaring done.
+
+**Badge:** Always prefix every action with `⟡🔮↔🔮 MERLIN·DUO ›` when duo is on, `⟡🔮 MERLIN ›` when off.
+
+TASK OPTIMIZATION: Before EVERY routing decision (workflows, agents, specialists), run ~/.claude/scripts/task-optimize.sh --task "<user text>". It returns {intent, skills[], agent, score, matched_phrases}. If score>=25, ALWAYS announce "⟡🔮 MERLIN › Intent: <X>. Loading <skills> + routing to <agent>." then route with skills prepended to context. Registry: ~/.claude/merlin/skills/TASK-OPTIMIZER.json. Slash commands /merlin:optimize, /merlin:design-audit, /merlin:polish, /merlin:redesign wrap common flows.

package/files/rules/codex-routing.md

@@ -93,6 +93,25 @@ Codex can embody these roles via `codex-as.sh`:
 
 Any other specialist stays with Claude.
 
+## Universal Task Optimization (Codex)
+
+When dispatching to `codex-implementer` or any `codex-as.sh <specialist>`, ALSO run the universal optimizer first:
+
+```
+bash ~/.claude/scripts/task-optimize.sh --task "<text>"
+```
+
+If `score >= 25`:
+1. Read each matched skill file (`~/.claude/merlin/skills/<id>.md` or external path)
+2. PREPEND the skill bodies to the codex-as.sh prompt body (BEFORE the specialist's own system prompt)
+3. Optionally use the optimizer's recommended agent as the specialist (override caller's choice if not user-specified)
+
+This is the Codex-side mirror of the Claude-side `merlin-routing.md` § Universal Task Optimization.
+
+If skill files are missing locally, run `bash ~/.claude/scripts/install-design-skills.sh` first.
+
+The registry of all skill→agent pairings lives at `~/.claude/merlin/skills/TASK-OPTIMIZER.json`. When the optimizer returns skills for a task, `codex-as.sh` automatically prepends them to the specialist's system prompt.
+
 ## 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"

package/files/rules/duo-routing.md

@@ -14,23 +14,37 @@ Duo mode runs two brains on the same task: Claude and Codex. Tasks that produce
 
 **Schema:**
 ```json
-{"enabled": bool, "sinceISO": "ISO8601 | null", "lastToggleReason": "string | null"}
+{"enabled": bool, "sinceISO": "ISO8601 | null", "lastToggleReason": "string | null", "pair": "claude+codex" | "claude+claude" | "codex+codex" | null}
 ```
 
 **Default (first install):**
 ```json
-{"enabled": false, "sinceISO": null, "lastToggleReason": null}
+{"enabled": false, "sinceISO": null, "lastToggleReason": null, "pair": 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
+**Install gate:** `duo-installed.sh` is always-pass — duo is always available. Pair selection (which specialists are used) is determined separately at toggle time via `codex-installed.sh`.
+
+---
+
+## Pair selection
+
+Duo runs as one of two pairs, selected at toggle-on time and persisted in `duo-mode.json` under the `pair` field:
+
+| Pair | When selected | Behavior |
+|---|---|---|
+| `claude+codex` | Codex installed (`codex-installed.sh` exits 0) at toggle time | Claude + Codex collaboration. Existing duo behavior. |
+| `claude+claude` | Codex not installed at toggle time | Twin-Claude — two different Claude specialists tag-team each task. |
+| `codex+codex` | Running under merlin-codex (`MERLIN_RUNTIME=codex`) | Codex-only — Codex orchestrator + two Codex specialists per task. Used when Claude Code isn't available. |
+
+Pair auto-detection at toggle-on time: `MERLIN_RUNTIME=codex` → `codex+codex`; else `codex-installed.sh` exit 0 → `claude+codex`; else → `claude+claude`.
+
+Pair is fixed for the life of the duo session (24h auto-expire). Disable + re-enable to re-detect.
+
+The `duo-installed.sh` gate is always-pass now — duo is always available. `codex-installed.sh` is what determines pair for claude-orchestrated sessions.
 
 ---
 
@@ -38,7 +52,7 @@ Duo mode runs two brains on the same task: Claude and Codex. Tasks that produce
 
 When multiple modes are enabled simultaneously:
 
-1. **Duo active** (enabled=true, within 24h, gate passes) → duo rules in this file win
+1. **Duo active** (enabled=true, within 24h) → 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)
 
@@ -52,7 +66,7 @@ Compute the badge via `~/.claude/scripts/duo-badge.sh` before every action prefi
 
 | Condition | Badge |
 |---|---|
-| Duo enabled + within 24h + gate passes | `⟡🔮↔🔮 MERLIN·DUO ›` |
+| Duo enabled + within 24h | `⟡🔮↔🔮 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.
@@ -86,6 +100,30 @@ Both brains run independently on the same task. Results are routed to the arbite
 
 ---
 
+## Parallel Planning Artifacts
+
+Both planners and the arbiter write to canonical paths inside the phase directory. The orchestrator MUST pass these absolute paths in each agent's prompt.
+
+| Agent | Writes to | Required prompt args |
+|---|---|---|
+| `merlin-planner` | `<phase-dir>/PLAN-CLAUDE.md` | `output_path` |
+| `codex-planner` | `<phase-dir>/PLAN-CODEX.md` | `output_path` |
+| `challenger-arbiter` | `<phase-dir>/PLAN-FINAL.md` | `output_path`, `claude_plan_path`, `codex_plan_path` |
+
+`<phase-dir>` resolution:
+- Numbered phases → `.planning/phases/<NN-slug>/`
+- Ad-hoc duo workflows → `.planning/duo/<slug>/`
+
+The orchestrator MUST `mkdir -p <phase-dir>` before spawning the agents.
+
+**Contract for planning agents:**
+- The file on disk at `output_path` is the canonical artifact for any agent that receives `output_path` in its prompt. Such agents MUST write the file themselves and MUST NOT return inline content as a fallback.
+- Agents that are part of a parallel pair but do NOT receive `output_path` (e.g. `challenger-academic` in twin-Claude planning, whose frontmatter forbids Write) MAY return inline content; the orchestrator captures and writes the file in that case.
+- If an agent cannot write `output_path` (tool denied, disk error, missing arg), it MUST return a structured error and stop. The orchestrator never reconstructs plans from stdout.
+- If `output_path` is missing or not absolute, the agent MUST refuse with a clear error.
+
+---
+
 ## Routing Matrix — SEQUENTIAL execution
 
 One author at a time to prevent file conflicts. Sequential only for tasks that write or modify source files.
@@ -120,12 +158,74 @@ If decider returns `revise`:
 
 ---
 
+## Twin-Claude pair (claude+claude) routing
+
+When `pair == claude+claude`, the parallel and sequential matrices use these specialist pairings instead:
+
+**PARALLEL:**
+
+| Task | Brain A | Brain B | Decider |
+|---|---|---|---|
+| Planning (feature-dev / refactor / product-dev) | `merlin-planner` | `challenger-academic` | `challenger-arbiter` |
+| Code review | `code-review` | `merlin-reviewer` | `challenger-arbiter` (merge + dedupe) |
+| Testing | `tests-qa` | `merlin-edge-case-hunter` | `challenger-arbiter` (merge + dedupe) |
+| Documentation | `docs-keeper` | — | falls back to solo (no second doc specialist available) |
+
+**SEQUENTIAL (code write/modify):**
+
+| Author | Reviewer | Decider |
+|---|---|---|
+| `implementation-dev` | `code-review` | `reviewer-decider` |
+
+**Twin-Claude planning artifact paths:**
+
+- `<phase-dir>/PLAN-CLAUDE.md` — written by `merlin-planner` (uses output_path arg).
+- `<phase-dir>/PLAN-CHALLENGE.md` — challenger-academic does NOT receive output_path (its frontmatter forbids Write). The orchestrator captures the agent's returned content and writes the file.
+- `<phase-dir>/PLAN-FINAL.md` — written by `challenger-arbiter`. In claude+claude, the arbiter's prompt receives `claude_plan_path` and `challenge_plan_path` instead of `codex_plan_path`.
+
+`reviewer-decider` remains Claude-only — even in claude+claude where the author is also Claude. The gate authority is intentionally separated by being a fresh agent spawn with its own context, not by brain identity.
+
+---
+
+## Codex-only pair (codex+codex) routing
+
+When `pair == codex+codex` (orchestrator is `merlin-codex`, no Claude available), the orchestrator drives duo via bash and `codex-as.sh`. Specialists are invoked as `codex exec`/`codex-as.sh <agent>` instead of as Skill/Agent calls.
+
+**PARALLEL:**
+
+| Task | Brain A | Brain B | Decider |
+|---|---|---|---|
+| Planning (feature-dev / refactor / product-dev) | `codex-planner` | `codex-as.sh challenger-academic` | `codex-as.sh challenger-arbiter` |
+| Code review | `codex-code-review` | `codex-as.sh merlin-reviewer` | merge + dedupe inline (orchestrator) |
+| Testing | `codex-as.sh tests-qa` | `codex-as.sh merlin-edge-case-hunter` | merge + dedupe inline (orchestrator) |
+| Documentation | `codex-as.sh docs-keeper` | — | solo (single specialist) |
+
+**SEQUENTIAL (code write/modify):**
+
+| Author | Reviewer | Gate |
+|---|---|---|
+| `codex-as.sh implementation-dev` | `codex-as.sh code-review` | **inline orchestrator judgment** — no `reviewer-decider` (Claude-only by P0) |
+
+**Codex-only planning artifact paths:**
+
+- `<phase-dir>/PLAN-CODEX-A.md` — written by `codex-planner` (receives `output_path`).
+- `<phase-dir>/PLAN-CODEX-B.md` — challenger-academic via `codex-as.sh` does NOT receive `output_path` (its frontmatter forbids Write). Orchestrator captures the agent's stdout and writes the file.
+- `<phase-dir>/PLAN-FINAL.md` — written by `codex-as.sh challenger-arbiter` (receives `output_path` plus both A and B paths).
+
+**Safety degradation (documented honestly):**
+
+Sequential code in `codex+codex` has a weaker gate than `claude+codex` or `claude+claude`. In those pairs, `reviewer-decider` is a separate fresh-context Claude spawn that gates the author's diff. In `codex+codex`, no separate gate spawn is available — the orchestrator (Codex) consumes the reviewer's findings and decides approve/revise/reject inline within its own context. This is acceptable for non-critical changes but users should consider installing Claude Code for higher-stakes work.
+
+---
+
 ## 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".
 
+In `codex+codex` pair, no `reviewer-decider` invocation occurs — the orchestrator handles gate logic inline. This is the only pair where the gate is not a separate spawn, and it's a documented safety degradation, not an oversight.
+
 ---
 
 ## Auto-offer for risky tasks
@@ -142,7 +242,6 @@ When duo is OFF, Merlin runs a pre-route hook at the start of every routing deci
 **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`)