create-merlin-brain 5.0.2 → 5.3.2

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 ──────────────────