create-merlin-brain 5.0.2 → 5.3.1

package/files/merlin/skills/coding/focus-mode.md

@@ -9,6 +9,14 @@ source: builtin
 successRate: 0
 usageCount: 0
 evolution: []
+provenance:
+  upstream: gsd-build/get-shit-done
+  upstream_path: skills/focus-mode.md
+  upstream_commit: 9045c81
+  license: MIT
+  license_verification: confirmed
+  adapted: "2026-03-14"
+  changes: adapted from GSD skill pattern
 ---
 # Focus Mode (GSD)
 Work in Get Stuff Done mode. Make reasonable decisions without asking. Build quickly and show results. Only ask questions when truly blocked. Prefer action over deliberation. If two approaches seem equally valid, pick the simpler one and move on.

package/files/merlin/skills/design/emil-design-eng.md

@@ -0,0 +1,31 @@
+---
+id: emil-design-eng
+name: Emil Design Engineering
+domain: coding
+category: design
+tags: [design, ui, animation, polish, micro-interactions, easing, transforms, gestures, performance, accessibility]
+triggers: [animate, animation, "feels stiff", "add motion", smoother, polish, "micro-interactions", "feels cheap", easing, transitions, gestures, "60fps", "premium feel"]
+version: 1
+source: external
+upstream: emilkowalski/skill
+license: unlicensed
+install_path: ~/.claude/skills/emil-design-eng/SKILL.md
+successRate: 0
+usageCount: 0
+evolution: []
+---
+# Emil Design Engineering
+
+Animation craft and UI polish from Emil Kowalski. Covers easing functions, transforms, gestures, micro-interactions, performance optimization, and accessibility (`prefers-reduced-motion`).
+
+**Usage:** Read the full skill at `~/.claude/skills/emil-design-eng/SKILL.md` (installed via `npx --yes skills add emilkowalski/skill`).
+
+If the file is missing, run: `npx --yes skills add emilkowalski/skill` or `bash ~/.claude/scripts/install-design-skills.sh`
+
+This skill covers:
+- Easing functions and animation timing
+- CSS and JS transforms
+- Gesture interactions and touch handling
+- Micro-interactions and polish
+- Performance (GPU compositing, will-change)
+- Motion preferences and accessibility

package/files/merlin/skills/design/impeccable.md

@@ -0,0 +1,36 @@
+---
+id: impeccable
+name: Impeccable Design Language
+domain: coding
+category: design
+tags: [design, ui, typography, color, spacing, motion, interaction, responsive, ux-writing, accessibility, dark-mode, oklch]
+triggers: [redesign, "make it pretty", "looks ugly", typography, "color system", spacing, "design audit", accessibility, responsive, "dark mode", OKLCH, "fluid design", "design review", "UX writing", "design system", polish, "premium feel", professional]
+version: 1
+source: external
+upstream: pbakaus/impeccable
+license: Apache-2.0
+install_path: ~/.claude/skills/impeccable/SKILL.md
+successRate: 0
+usageCount: 0
+evolution: []
+---
+# Impeccable Design Language
+
+Comprehensive design language by Philipp Bakaus covering 7 design domains + 23 specialized commands for design critique, auditing, and refinement.
+
+**Usage:** Read the full skill at `~/.claude/skills/impeccable/SKILL.md` (installed at setup via `install-design-skills.sh`).
+
+If the file is missing, run: `bash ~/.claude/scripts/install-design-skills.sh`
+
+This skill covers:
+- Typography (scales, families, weights, line-height)
+- Color theory (OKLCH, accessibility, dark-mode)
+- Spatial design (spacing, grids, proportions)
+- Motion design (timing, easing, interactions)
+- Interaction design (states, feedback, patterns)
+- Responsive design (breakpoints, fluid scaling)
+- UX writing (copy, tone, clarity)
+
+Commands include `/audit`, `/polish`, `/critique`, `/animate`, `/harden`, `/distill` and 17+ more.
+
+Apache-2.0 license attribution preserved at `~/.claude/skills/impeccable/NOTICE.md`.

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"