create-merlin-brain 5.0.2 → 5.3.1

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`)

package/files/rules/merlin-routing.md

@@ -15,6 +15,46 @@ Route user intent to the matching workflow. Do not analyze or fix problems yours
 | "build API" / "backend" / "endpoint" | `Skill("merlin:workflow", args='run api-build "<task>"')` |
 | Small, isolated task | `merlin_smart_route(task="...")` then `merlin_route()` |
 
+## Universal Task Optimization (RUN FIRST on every routing decision)
+
+BEFORE every routing decision (workflow, agent, or specialist), run:
+
+```
+bash ~/.claude/scripts/task-optimize.sh --task "<full user task text>"
+```
+
+The optimizer returns single-line JSON: `{"score":<0-100>,"intent":"<id>","skills":[<ids>],"agent":"<name>","matched_phrases":[...]}`.
+
+If `score >= 25`:
+1. Read the matched skill files (`~/.claude/merlin/skills/<id>.md` or `~/.claude/skills/<external>/SKILL.md` for external skills).
+2. Announce the pairing: `⟡🔮 MERLIN › Intent: <intent>. Loading <skills> + routing to <agent>.` (use the duo badge variant if duo mode is on)
+3. Route to the optimizer-recommended `agent` with skill bodies prepended into context.
+
+If `score < 25`: fall through to the existing routing tables below.
+
+The registry of skill→agent pairings lives at `~/.claude/merlin/skills/TASK-OPTIMIZER.json`. To add a new skill, append an entry there — no code changes needed.
+
+### Common skill+agent pairings (reference; full registry in TASK-OPTIMIZER.json)
+
+| Task signal | Skills | Agent |
+|---|---|---|
+| Design / UI / typography / color / responsive | design/impeccable, design/emil-design-eng | ui-builder |
+| Animation / polish / micro-interactions | design/emil-design-eng | animation-expert |
+| Accessibility / WCAG / a11y | coding/accessibility | hardening-guard |
+| Auth / OWASP / CSRF / hardening | coding/security-hardening | hardening-guard |
+| API / REST / OpenAPI / GraphQL | coding/api-design | merlin-api-designer |
+| Performance / Core Web Vitals / bundle | coding/performance | merlin-performance |
+| Tests / TDD / Jest / Vitest | testing/tdd-workflow | tests-qa |
+| Docker / containers / CI | devops/docker-containers | ops-railway |
+| Bug / crash / error / debug | coding/debug-mode | merlin-debugger |
+| Stripe / billing / webhooks / email | automation/*, communication/* | implementation-dev |
+| Brainstorm / ideate / options | research/brainstorm | merlin-researcher |
+| React / hooks / Next.js / components | coding/react-patterns | merlin-frontend |
+
+Slash commands: `/merlin:optimize`, `/merlin:design-audit`, `/merlin:polish`, `/merlin:redesign`.
+
+The optimizer is the AUTHORITY. Don't override its recommendations unless the user explicitly asks for a different agent.
+
 ## Agent Routing
 
 Call `merlin_smart_route(task="...")` FIRST (searches 500+ community agents). Then:

package/files/scripts/codex-as.sh

@@ -69,6 +69,9 @@ FULL_PROMPT="${PROMPT_BODY}
 
 ${TASK_TEXT}"
 
-# Invoke codex with --write to allow file modifications
+# Invoke codex with workspace-write sandbox to allow file modifications inside cwd.
+# (The legacy --write flag was removed from `codex exec`; -s workspace-write is the
+#  current equivalent. Use --dangerously-bypass-approvals-and-sandbox only if you
+#  explicitly want to skip all prompts — workspace-write is the safer default.)
 # shellcheck disable=SC2086
-exec codex exec --write --cd "$PWD" $MODEL_FLAG "$FULL_PROMPT"
+exec codex exec -s workspace-write --cd "$PWD" $MODEL_FLAG "$FULL_PROMPT"

package/files/scripts/design-intent-detect.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# design-intent-detect.sh — thin wrapper around task-optimize.sh (v5.3+)
+# Preserves the v5.2.0 contract for slash commands that reference this script.
+# Usage: design-intent-detect.sh --task "<text>" [--self-test]
+# Output: same JSON as task-optimize.sh
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec "$SCRIPT_DIR/task-optimize.sh" "$@"

package/files/scripts/duo-badge.sh

@@ -8,12 +8,10 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 STEP_PHRASE="${1:-}"
 
-# Determine if duo is active: gate passes AND mode is enabled
+# Determine if duo is active: mode is enabled (duo-installed.sh is always-pass, no longer checked)
 DUO_ACTIVE=false
-if "${SCRIPT_DIR}/duo-installed.sh" 2>/dev/null; then
-    if [[ "$("${SCRIPT_DIR}/duo-mode-read.sh" 2>/dev/null)" == "enabled" ]]; then
-        DUO_ACTIVE=true
-    fi
+if [[ "$("${SCRIPT_DIR}/duo-mode-read.sh" 2>/dev/null)" == "enabled" ]]; then
+    DUO_ACTIVE=true
 fi
 
 # Build badge

package/files/scripts/duo-installed.sh

@@ -1,8 +1,8 @@
 #!/usr/bin/env bash
 # duo-installed.sh — composite install gate for duo mode
-# Returns 0 only if codex-installed.sh (sibling) returns 0
+# Always exits 0: duo is available regardless of Codex. Pair selection (claude+codex vs claude+claude)
+# is determined separately via codex-installed.sh at toggle time.
 
 set -euo pipefail
 
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-"${SCRIPT_DIR}/codex-installed.sh"
+exit 0

package/files/scripts/duo-mode-read.sh

@@ -1,51 +1,71 @@
 #!/usr/bin/env bash
 # duo-mode-read.sh — reads duo-mode.json, applies 24h auto-expire (read-time only, never modifies file)
-# Prints exactly "enabled" or "disabled" to stdout
+# Without --pair: prints exactly "enabled" or "disabled" to stdout
+# With --pair:    prints the pair value: "claude+codex", "claude+claude", or "none"
 
 set -euo pipefail
 
 STATE_FILE="${HOME}/.claude/merlin-state/duo-mode.json"
+PAIR_MODE=false
 
-# If state file missing, default to disabled
+for arg in "$@"; do
+    if [[ "$arg" == "--pair" ]]; then
+        PAIR_MODE=true
+    fi
+done
+
+# If state file missing, default to disabled / none
 if [[ ! -f "$STATE_FILE" ]]; then
-    echo "disabled"
+    if [[ "$PAIR_MODE" == "true" ]]; then
+        echo "none"
+    else
+        echo "disabled"
+    fi
     exit 0
 fi
 
-python3 - "$STATE_FILE" <<'PYEOF'
+python3 - "$STATE_FILE" "$PAIR_MODE" <<'PYEOF'
 import sys
 import json
 from datetime import datetime, timezone, timedelta
 
 state_path = sys.argv[1]
+pair_mode = sys.argv[2] == "true"
 
 try:
     with open(state_path, "r") as f:
         data = json.load(f)
 except (json.JSONDecodeError, OSError):
-    print("disabled")
+    print("none" if pair_mode else "disabled")
     sys.exit(0)
 
 enabled = data.get("enabled", False)
 since_iso = data.get("sinceISO")
+pair = data.get("pair")
 
 if not enabled or since_iso is None:
-    print("disabled")
+    print("none" if pair_mode else "disabled")
     sys.exit(0)
 
 # Parse sinceISO and apply 24h auto-expire (read-time interpretation, no file write)
 try:
-    # Handle both Z suffix and +00:00 format
     since_str = since_iso.replace("Z", "+00:00")
     since_dt = datetime.fromisoformat(since_str)
     now_dt = datetime.now(timezone.utc)
     if (now_dt - since_dt) > timedelta(hours=24):
-        print("disabled")
+        print("none" if pair_mode else "disabled")
         sys.exit(0)
 except (ValueError, TypeError):
     # Unparseable timestamp — treat as expired
-    print("disabled")
+    print("none" if pair_mode else "disabled")
     sys.exit(0)
 
-print("enabled")
+if pair_mode:
+    # Legacy state (no pair field) when enabled defaults to claude+codex
+    if pair is None:
+        print("claude+codex")
+    else:
+        print(pair)
+else:
+    print("enabled")
 PYEOF

package/files/scripts/duo-mode-write.sh

@@ -1,18 +1,21 @@
 #!/usr/bin/env bash
 # duo-mode-write.sh — atomic write to duo-mode.json
-# Usage: duo-mode-write.sh on "<reason>" | off "<reason>"
+# Usage: duo-mode-write.sh on "<reason>" [claude+codex|claude+claude]
+#        duo-mode-write.sh off "<reason>"
 
 set -euo pipefail
 
 if [[ $# -lt 2 ]]; then
-    echo "Usage: duo-mode-write.sh on|off \"<reason>\"" >&2
+    echo "Usage: duo-mode-write.sh on|off \"<reason>\" [claude+codex|claude+claude|codex+codex]" >&2
     exit 1
 fi
 
 ACTION="$1"
 REASON="$2"
+PAIR_ARG="${3:-}"
 STATE_FILE="${HOME}/.claude/merlin-state/duo-mode.json"
 STATE_DIR="$(dirname "$STATE_FILE")"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 # Ensure state directory exists
 mkdir -p "$STATE_DIR"
@@ -20,9 +23,28 @@ mkdir -p "$STATE_DIR"
 case "$ACTION" in
     on)
         ENABLED="true"
+
+        # Validate explicit pair arg if provided
+        if [[ -n "$PAIR_ARG" ]]; then
+            if [[ "$PAIR_ARG" != "claude+codex" && "$PAIR_ARG" != "claude+claude" && "$PAIR_ARG" != "codex+codex" ]]; then
+                echo "Error: pair must be 'claude+codex', 'claude+claude', or 'codex+codex', got: $PAIR_ARG" >&2
+                exit 1
+            fi
+            PAIR="$PAIR_ARG"
+        else
+            # Auto-detect pair: MERLIN_RUNTIME=codex → codex+codex; codex installed → claude+codex; else → claude+claude
+            if [[ "${MERLIN_RUNTIME:-}" == "codex" ]]; then
+                PAIR="codex+codex"
+            elif "${SCRIPT_DIR}/codex-installed.sh" 2>/dev/null; then
+                PAIR="claude+codex"
+            else
+                PAIR="claude+claude"
+            fi
+        fi
         ;;
     off)
         ENABLED="false"
+        PAIR="null"
         ;;
     *)
         echo "Error: first argument must be 'on' or 'off', got: $ACTION" >&2
@@ -31,7 +53,7 @@ case "$ACTION" in
 esac
 
 # Use python3 for JSON serialization and atomic write via mktemp + mv (same FS = atomic)
-python3 - "$STATE_FILE" "$ENABLED" "$REASON" <<'PYEOF'
+python3 - "$STATE_FILE" "$ENABLED" "$REASON" "$PAIR" <<'PYEOF'
 import sys
 import json
 import os
@@ -41,13 +63,16 @@ from datetime import datetime, timezone
 state_path = sys.argv[1]
 enabled = sys.argv[2] == "true"
 reason = sys.argv[3]
+pair_arg = sys.argv[4]
 
 now_iso = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") if enabled else None
+pair_value = None if pair_arg == "null" else pair_arg
 
 data = {
     "enabled": enabled,
     "sinceISO": now_iso,
     "lastToggleReason": reason,
+    "pair": pair_value,
 }
 
 state_dir = os.path.dirname(state_path)

package/files/scripts/duo-pre-route.sh

@@ -30,13 +30,7 @@ if [[ "$DUO_STATE" == "enabled" ]]; then
     exit 0
 fi
 
-# Branch 2: Codex absent — stay solo silently (never mention duo)
-if ! "${SCRIPT_DIR}/duo-installed.sh" 2>/dev/null; then
-    echo "mode=solo"
-    exit 0
-fi
-
-# Branch 3: risk-detect suggestion
+# Branch 2: risk-detect suggestion (duo-installed.sh is always-pass; offer fires regardless of Codex)
 RISK_DETECT="${SCRIPT_DIR}/duo-risk-detect.sh"
 if [[ ! -x "$RISK_DETECT" ]]; then
     echo "mode=solo"
@@ -62,7 +56,7 @@ if [[ "$SUGGEST_DUO" != "true" ]]; then
     exit 0
 fi
 
-# Branch 3a: suppression check — use a temp python script to avoid heredoc-in-subshell issues
+# Branch 2a: suppression check — use a temp python script to avoid heredoc-in-subshell issues
 REASONS_JSON=$(python3 -c "
 import json, sys
 try:

package/files/scripts/install-design-skills.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+set -e
+
+# Merlin Design Skills Installer
+# Installs and prioritizes emilkowalski/skill and pbakaus/impeccable
+
+# Honor skip flag
+if [ "${MERLIN_SKIP_DESIGN_SKILLS:-0}" = "1" ]; then
+  exit 0
+fi
+
+echo "[merlin] Installing priority design skills…"
+
+SKILLS_DIR="${HOME}/.claude/skills"
+mkdir -p "$SKILLS_DIR"
+
+# ═══════════════════════════════════════════════════════════════
+# Install emilkowalski/skill (install-only, no license vendoring)
+# ═══════════════════════════════════════════════════════════════
+
+if [ ! -f "$SKILLS_DIR/emil-design-eng/SKILL.md" ]; then
+  if command -v npx >/dev/null 2>&1; then
+    # Attempt install via skills CLI
+    if npx --yes skills add emilkowalski/skill 2>/dev/null; then
+      : # Success
+    else
+      # Non-fatal — user can install manually
+      echo "[merlin] emil skill install hint: npx --yes skills add emilkowalski/skill"
+    fi
+  else
+    echo "[merlin] npx not found; skipping emil skill (user can install: npx --yes skills add emilkowalski/skill)"
+  fi
+fi
+
+# ═══════════════════════════════════════════════════════════════
+# Install pbakaus/impeccable (fetch + preserve Apache-2.0 attribution)
+# ═══════════════════════════════════════════════════════════════
+
+if [ ! -d "$SKILLS_DIR/impeccable" ]; then
+  if command -v git >/dev/null 2>&1; then
+    tmp=$(mktemp -d)
+    trap "rm -rf '$tmp'" EXIT
+
+    if git clone --depth 1 https://github.com/pbakaus/impeccable.git "$tmp" 2>/dev/null; then
+      # Copy the skill subtree (contains SKILL.md and commands/)
+      if [ -d "$tmp/dist/claude-code/.claude/skills/impeccable" ]; then
+        mkdir -p "$SKILLS_DIR"
+        cp -R "$tmp/dist/claude-code/.claude/skills/impeccable" "$SKILLS_DIR/"
+
+        # Preserve license attribution
+        if [ -f "$tmp/LICENSE" ]; then
+          cp "$tmp/LICENSE" "$SKILLS_DIR/impeccable/LICENSE"
+        fi
+        if [ -f "$tmp/NOTICE.md" ]; then
+          cp "$tmp/NOTICE.md" "$SKILLS_DIR/impeccable/NOTICE.md"
+        fi
+      else
+        echo "[merlin] impeccable skill structure not found in cloned repo"
+      fi
+    else
+      echo "[merlin] git clone failed for impeccable; user can install manually"
+    fi
+  else
+    echo "[merlin] git not found; skipping impeccable skill (user can install manually: git clone pbakaus/impeccable)"
+  fi
+fi
+
+# ═══════════════════════════════════════════════════════════════
+# Verification
+# ═══════════════════════════════════════════════════════════════
+
+has_impeccable=0
+has_emil=0
+
+[ -d "$SKILLS_DIR/impeccable" ] && has_impeccable=1
+[ -f "$SKILLS_DIR/emil-design-eng/SKILL.md" ] && has_emil=1
+
+if [ "$has_impeccable" = "1" ] || [ "$has_emil" = "1" ]; then
+  echo "[merlin] Design skills ready:"
+  [ "$has_impeccable" = "1" ] && echo "  ✓ impeccable"
+  [ "$has_emil" = "1" ] && echo "  ✓ emil-design-eng"
+else
+  echo "[merlin] Design skills install: no changes (already present or install failed)"
+fi
+
+exit 0

package/files/scripts/merlin-codex.sh

@@ -15,6 +15,8 @@
 #
 set -euo pipefail
 
+export MERLIN_RUNTIME=codex
+
 SCRIPTS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 SYSTEM_PROMPT_FILE="${HOME}/.claude/merlin-system-prompt.txt"
 FALLBACK_PROMPT="You are Merlin: orchestrator, not coder. Route implementation to specialists. Badge every action with ⟡🔮 MERLIN ›."
@@ -22,20 +24,23 @@ FALLBACK_PROMPT="You are Merlin: orchestrator, not coder. Route implementation t
 # ── Pass-through subcommands (no Merlin prompt injection) ──────
 PASSTHROUGH_CMDS="login logout mcp mcp-server app app-server completion sandbox debug"
 
-# ── Determine duo mode for banner ──────────────────────────────
+# ── Determine duo mode and pair for banner ─────────────────────
 _mode_label="Solo"
+_pair_label=""
 if [ -x "${SCRIPTS_DIR}/duo-mode-read.sh" ]; then
   _duo=$("${SCRIPTS_DIR}/duo-mode-read.sh" 2>/dev/null) || _duo="disabled"
   if [ "${_duo}" = "enabled" ]; then
-    if [ -x "${SCRIPTS_DIR}/duo-installed.sh" ]; then
-      "${SCRIPTS_DIR}/duo-installed.sh" 2>/dev/null && _mode_label="Duo" || true
+    _mode_label="Duo"
+    _pair=$("${SCRIPTS_DIR}/duo-mode-read.sh" --pair 2>/dev/null) || _pair="none"
+    if [ "${_pair}" != "none" ]; then
+      _pair_label=" (${_pair})"
     fi
   fi
 fi
 
 # ── Print banner to stderr (always) ───────────────────────────
 printf '⟡🔮 MERLIN · entering Codex via merlin-codex\n' >&2
-printf '🎯 Mode: %s\n' "${_mode_label}" >&2
+printf '🎯 Mode: %s%s\n' "${_mode_label}" "${_pair_label}" >&2
 printf '▶ Codex will inherit Merlin'"'"'s orchestrator instructions\n' >&2
 
 # ── If no args, open interactive Codex shell ──────────────────