create-merlin-brain 5.0.1 → 5.3.1

package/files/commands/merlin/optimize.md

@@ -0,0 +1,89 @@
+---
+name: merlin:optimize
+description: Preview which skills + agent the optimizer would pick for a task — no execution, just the recommendation
+argument-hint: "<task description>"
+allowed-tools:
+  - Read
+  - Bash
+---
+
+<objective>
+Preview the Universal Task Optimizer's recommendation for a given task.
+
+Shows which skills would be loaded and which agent would be routed to, WITHOUT actually executing the routing. Useful for understanding how Merlin pairs tasks with specialists.
+</objective>
+
+<context>
+Task: $ARGUMENTS (required: task description to analyze)
+</context>
+
+<process>
+
+## Step 1: Validate Input
+
+$ARGUMENTS must be provided. If empty, show usage:
+```
+Usage: /merlin:optimize "your task description"
+
+Examples:
+  /merlin:optimize "redesign the dashboard"
+  /merlin:optimize "add OAuth login"
+  /merlin:optimize "write unit tests for the parser"
+```
+
+## Step 2: Run the Universal Task Optimizer
+
+```bash
+bash ~/.claude/scripts/task-optimize.sh --task "$ARGUMENTS"
+```
+
+Store the JSON result.
+
+## Step 3: Parse and Present Result
+
+If score < 25:
+```
+⟡🔮 MERLIN › No specific skill match for this task.
+
+Score: <score>
+Intent: none
+Recommendation: Fall back to default workflow routing (see /merlin:help for options)
+```
+
+If score >= 25:
+```
+⟡🔮 MERLIN › Task Optimization Result
+
+Intent:   <intent>
+Score:    <score>/100
+Skills:   <skills array, comma-separated>
+Agent:    <agent>
+Matched:  <matched_phrases, comma-separated>
+
+Skill file paths:
+  - ~/.claude/merlin/skills/<skill1>.md
+  - ~/.claude/merlin/skills/<skill2>.md
+
+Want me to execute this routing? (y/n)
+```
+
+## Step 4: Handle Follow-up
+
+If user says yes/y/execute:
+- Read the skill files
+- Route to the recommended agent with task and skills prepended
+
+If user says no/n:
+- Exit and let user choose a different approach
+
+</process>
+
+<error_handling>
+
+| Condition | Action |
+|-----------|--------|
+| No task provided | Show usage and examples |
+| Optimizer script missing | Error: run `npx create-merlin-brain` to reinstall |
+| Registry missing | Error: TASK-OPTIMIZER.json not found |
+
+</error_handling>

package/files/commands/merlin/polish.md

@@ -0,0 +1,99 @@
+---
+name: merlin:polish
+description: Apply animation craft + UI polish using emil-design-eng skill via animation-expert
+argument-hint: "[path] - file/component to polish (required)"
+allowed-tools:
+  - Read
+  - Glob
+  - Edit
+  - Bash
+  - mcp__merlin__merlin_get_context
+  - mcp__merlin__merlin_route
+---
+
+<objective>
+Apply polish and animation craft to a component or file using the emil-design-eng skill.
+
+Focuses on: easing functions, smooth transitions, micro-interactions, gesture handling, prefers-reduced-motion accessibility, GPU-optimized performance.
+
+Routes to `animation-expert` agent with emil-design-eng skill loaded.
+</objective>
+
+<context>
+Target: $ARGUMENTS (required: file or component path)
+</context>
+
+<process>
+
+## Step 1: Validate Path
+
+$ARGUMENTS must be provided. If empty, show usage:
+```
+Usage: /merlin:polish "path/to/component.tsx"
+```
+
+## Step 2: Ensure Skills Installed
+
+```bash
+bash ~/.claude/scripts/install-design-skills.sh
+```
+
+## Step 3: Detect Task Intent
+
+```bash
+bash ~/.claude/scripts/task-optimize.sh --task "polish animation"
+```
+
+Store result.
+
+## Step 4: Read Emil Design Engineering Skill
+
+```bash
+Read: ~/.claude/skills/emil-design-eng/SKILL.md
+```
+
+Store skill body.
+
+## Step 5: Read Target File
+
+```bash
+Read: $ARGUMENTS
+```
+
+If read fails, error and exit.
+
+## Step 6: Route to animation-expert
+
+Call `merlin_route` with:
+- Agent: `animation-expert`
+- Task: "Polish this component with animation craft: improve easing, add prefers-reduced-motion, smooth transitions, polish micro-interactions, optimize for 60fps"
+- Context: prepend emil-design-eng skill body
+- Include requirements:
+  - Easing: cubic-bezier or spring easing (ease-in-out for semantic, custom for premium feel)
+  - Transitions: review timing (150-300ms for interactions, 1-2s for page transitions)
+  - Micro-interactions: add subtle feedback on user actions (hover, focus, click)
+  - Gestures: swipe, drag, pinch interactions where appropriate
+  - Performance: CSS animations preferred, requestAnimationFrame for JS, will-change hints
+  - Accessibility: respect prefers-reduced-motion, provide keyboard navigation
+
+## Step 7: Review Changes
+
+After agent completes:
+```bash
+git diff HEAD path/to/file
+```
+
+Show user the diff and confirm changes look good.
+
+</process>
+
+<error_handling>
+
+| Condition | Action |
+|-----------|--------|
+| No path provided | Show usage and exit |
+| Path invalid | Error and exit |
+| Skills missing | Attempt install, continue with warning |
+| animation-expert unavailable | Use ui-builder fallback |
+
+</error_handling>

package/files/commands/merlin/quick.md

@@ -12,6 +12,14 @@ allowed-tools:
   - mcp__merlin__merlin_get_context
   - mcp__merlin__merlin_search
   - mcp__merlin__merlin_find_files
+provenance:
+  upstream: gsd-build/get-shit-done
+  upstream_path: commands/gsd/quick.md
+  upstream_commit: 9045c81
+  license: MIT
+  license_verification: confirmed
+  adapted: "2026-03-14"
+  changes: adapted from GSD command pattern
 ---
 
 <objective>

package/files/commands/merlin/readiness-gate.md

@@ -9,6 +9,14 @@ allowed-tools:
   - Glob
   - mcp__merlin__merlin_get_context
   - mcp__merlin__merlin_get_project_status
+provenance:
+  upstream: bmad-code-org/BMAD-METHOD
+  upstream_path: "pattern: BMAD readiness gate"
+  upstream_commit: 285bad4
+  license: MIT
+  license_verification: pending
+  adapted: "2026-03-14"
+  changes: BMAD-inspired command pattern
 ---
 
 <objective>

package/files/commands/merlin/redesign.md

@@ -0,0 +1,108 @@
+---
+name: merlin:redesign
+description: Comprehensive redesign using impeccable + emil-design-eng with ui-builder
+argument-hint: "[path] - file/component to redesign (required)"
+allowed-tools:
+  - Read
+  - Glob
+  - Edit
+  - Bash
+  - mcp__merlin__merlin_get_context
+  - mcp__merlin__merlin_route
+---
+
+<objective>
+Full redesign using both impeccable and emil-design-eng skills. Covers all 7 impeccable design domains + animation polish from emil.
+
+Scope: typography, color, spacing, motion, interaction, responsive, UX writing, plus easing, micro-interactions, gestures, and performance optimization.
+
+Routes to `ui-builder` agent with both priority design skills loaded.
+</objective>
+
+<context>
+Target: $ARGUMENTS (required: file or component path)
+</context>
+
+<process>
+
+## Step 1: Validate Path
+
+$ARGUMENTS must be provided. If empty, show usage:
+```
+Usage: /merlin:redesign "path/to/component.tsx"
+```
+
+## Step 2: Ensure Skills Installed
+
+```bash
+bash ~/.claude/scripts/install-design-skills.sh
+```
+
+## Step 3: Detect Task Intent
+
+```bash
+bash ~/.claude/scripts/task-optimize.sh --task "redesign"
+```
+
+Store result.
+
+## Step 4: Read Both Priority Skills
+
+```bash
+Read: ~/.claude/skills/impeccable/SKILL.md
+Read: ~/.claude/skills/emil-design-eng/SKILL.md
+```
+
+Store both skill bodies.
+
+## Step 5: Read Target File
+
+```bash
+Read: $ARGUMENTS
+```
+
+If read fails, error and exit.
+
+## Step 6: Route to ui-builder
+
+Call `merlin_route` with:
+- Agent: `ui-builder`
+- Task: "Comprehensive redesign using impeccable + emil-design-eng: improve typography, color, spacing, motion, interaction, responsive design, UX writing, easing, micro-interactions, and 60fps performance. Include before/after rationale."
+- Context: prepend both skill bodies
+- Include redesign checklist:
+  - **Typography (impeccable):** font families, scales, weights, line-height, readability, hierarchy
+  - **Color (impeccable):** OKLCH-based system, accessible contrast ratios, dark-mode, semantic naming
+  - **Spacing (impeccable):** proportional grid, breathing room, visual hierarchy consistency
+  - **Motion (impeccable):** timing curves, keyframes, transitions between states
+  - **Interaction (impeccable):** hover/focus/active/disabled states, feedback patterns, accessibility
+  - **Responsive (impeccable):** breakpoints, fluid scaling, container queries, mobile-first
+  - **UX writing (impeccable):** copy clarity, tone consistency, error messages, microcopy
+  - **Easing (emil):** cubic-bezier curves, spring physics, motion feel
+  - **Micro-interactions (emil):** subtle feedback, gestures, polish details
+  - **Performance (emil):** 60fps animations, GPU compositing, will-change hints, reduced-motion
+
+## Step 7: Review Changes
+
+After agent completes:
+```bash
+git diff HEAD path/to/file
+```
+
+Show user the full diff. Highlight:
+- Before/after visual differences
+- Key design system changes
+- Performance improvements
+- Accessibility enhancements
+
+</process>
+
+<error_handling>
+
+| Condition | Action |
+|-----------|--------|
+| No path provided | Show usage and exit |
+| Path invalid | Error and exit |
+| Skills missing | Attempt install, continue with warning |
+| ui-builder unavailable | Use merlin-frontend fallback |
+
+</error_handling>

package/files/hooks/session-start.sh

@@ -199,8 +199,94 @@ _merlin_check_voice_mode
 _voice_note=""
 [ "${MERLIN_VOICE_MODE:-}" = "1" ] && _voice_note=" Voice mode active: keep all responses short and direct."
 
-# Build the additionalContext with embedded routing rules.
-_context="STOP. Your FIRST action must be: call merlin_get_selected_repo, then call merlin_get_project_status, then call merlin_get_rules and merlin_get_brief in parallel. Do not respond to the user until you complete the boot sequence."
+# ── 4a. Session banner (best-effort, all reads use || true) ────
+_SCRIPTS_DIR="${HOME}/.claude/scripts"
+
+# Project name: git basename or pwd basename (handle spaces in path)
+_git_top=$(git -C "${PWD}" rev-parse --show-toplevel 2>/dev/null || true)
+if [ -n "${_git_top:-}" ]; then
+  _project_name=$(basename "${_git_top}" 2>/dev/null || true)
+else
+  _project_name=$(basename "${PWD}" 2>/dev/null || true)
+fi
+if [ -z "${_project_name:-}" ]; then
+  _project_name="project"
+fi
+
+# Mode: Solo or Duo
+_duo_status="disabled"
+if [ -x "${_SCRIPTS_DIR}/duo-mode-read.sh" ]; then
+  _duo_status=$("${_SCRIPTS_DIR}/duo-mode-read.sh" 2>/dev/null || echo "disabled")
+fi
+_duo_installed=false
+if [ -x "${_SCRIPTS_DIR}/duo-installed.sh" ]; then
+  if "${_SCRIPTS_DIR}/duo-installed.sh" 2>/dev/null; then
+    _duo_installed=true
+  fi
+fi
+if [ "${_duo_status}" = "enabled" ] && [ "${_duo_installed}" = "true" ]; then
+  _mode_label="Duo"
+else
+  _mode_label="Solo"
+fi
+
+# Codex: installed or missing
+_codex_label="missing"
+if [ -x "${_SCRIPTS_DIR}/codex-installed.sh" ]; then
+  if "${_SCRIPTS_DIR}/codex-installed.sh" 2>/dev/null; then
+    _codex_label="installed"
+  fi
+fi
+
+# Badge: use duo-badge.sh if available
+_badge="⟡🔮 MERLIN ›"
+if [ -x "${_SCRIPTS_DIR}/duo-badge.sh" ]; then
+  _badge=$("${_SCRIPTS_DIR}/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›")
+fi
+
+# Recommended next action (priority order, all reads use || true)
+_next_action="Ready: ask anything or /merlin:help"
+if [ -f "${HOME}/.merlin/state/active-plan.md" ] || \
+   [ -f "${HOME}/.claude/merlin/active-plan.md" ] || \
+   [ -f "${PWD}/PLAN.md" ]; then
+  _next_action="Continue execution: /merlin:execute-phase"
+elif [ -f "${HOME}/.merlin/state/verification.json" ]; then
+  _vfailed=""
+  if command -v jq >/dev/null 2>&1; then
+    _vfailed=$(jq -r '.status // ""' "${HOME}/.merlin/state/verification.json" 2>/dev/null || echo "")
+  fi
+  if [ "${_vfailed:-}" = "failed" ]; then
+    _next_action="Verification failed last time — investigate or rerun"
+  fi
+fi
+if [ "${_next_action}" = "Ready: ask anything or /merlin:help" ]; then
+  if git -C "${PWD}" rev-parse --git-dir >/dev/null 2>&1 && [ ! -f "${PWD}/PROJECT.md" ]; then
+    _next_action="New project: /merlin:new-project"
+  fi
+fi
+if [ "${_next_action}" = "Ready: ask anything or /merlin:help" ] && \
+   [ -f "${HOME}/.merlin/state/tasks.json" ]; then
+  _pending=0
+  if command -v jq >/dev/null 2>&1; then
+    _tdone=$(jq '.done // 0' "${HOME}/.merlin/state/tasks.json" 2>/dev/null || echo "0")
+    _ttotal=$(jq '.total // 0' "${HOME}/.merlin/state/tasks.json" 2>/dev/null || echo "0")
+    if [ "${_ttotal:-0}" -gt 0 ] 2>/dev/null && [ "${_tdone:-0}" -lt "${_ttotal:-0}" ] 2>/dev/null; then
+      _pending=$(( _ttotal - _tdone ))
+    fi
+  fi
+  if [ "${_pending:-0}" -gt 0 ] 2>/dev/null; then
+    _next_action="${_pending} tasks pending: /merlin:next"
+  fi
+fi
+
+# Banner line 1: "⟡🔮 MERLIN · connected · {project}" (spec format)
+# Use the badge prefix (everything before "MERLIN") plus fixed text so
+# "MERLIN · connected" always appears regardless of duo/solo badge variant.
+_badge_prefix=$(echo "${_badge}" | sed 's/MERLIN.*//' 2>/dev/null || true)
+_banner="${_badge_prefix}MERLIN · connected · ${_project_name} | Mode: ${_mode_label} · Codex: ${_codex_label} | Next: ${_next_action}"
+
+# ── 4b. Build the additionalContext with banner + routing rules ─
+_context="${_banner} || STOP. Your FIRST action must be: call merlin_get_selected_repo, then call merlin_get_project_status, then call merlin_get_rules and merlin_get_brief in parallel. Do not respond to the user until you complete the boot sequence."
 _context="${_context} AFTER BOOT — MANDATORY ROUTING (you MUST follow this, do NOT skip):"
 _context="${_context} Bug/crash/error logs/deploy failure: use Skill(merlin:workflow, args=run bug-fix <summary>)."
 _context="${_context} Build feature/add feature: use Skill(merlin:workflow, args=run feature-dev <summary>)."

package/files/hooks/statusline.sh

@@ -9,6 +9,7 @@
 #   {"hookSpecificOutput":{"hookEventName":"Notification","statusLine":"..."}}
 #
 # Metrics included:
+#   - Merlin badge    (from ~/.claude/scripts/duo-badge.sh — duo-aware)
 #   - Merlin version  (from ~/.claude/merlin/VERSION)
 #   - Active agents   (from ~/.merlin/state/agents.json)
 #   - Task progress   (from ~/.merlin/state/tasks.json)
@@ -132,8 +133,15 @@ else
   RATE_DISPLAY="OK"
 fi
 
+# ── Badge (duo-aware) ──────────────────────────────────────────────────────
+SCRIPTS_DIR="${HOME}/.claude/scripts"
+BADGE="⟡🔮 MERLIN ›"
+if [ -x "${SCRIPTS_DIR}/duo-badge.sh" ]; then
+  BADGE=$("${SCRIPTS_DIR}/duo-badge.sh" 2>/dev/null || echo "⟡🔮 MERLIN ›")
+fi
+
 # ── Compose statusline ─────────────────────────────────────────────────────
-STATUSLINE="v${MERLIN_VERSION} | ${AGENT_COUNT} agents | ${TASKS_DISPLAY} | ${COST_DISPLAY} | ${GIT_BRANCH} | ctx:${CTX_DISPLAY} | rate:${RATE_DISPLAY}"
+STATUSLINE="${BADGE} v${MERLIN_VERSION} | ${AGENT_COUNT} agents | ${TASKS_DISPLAY} | ${COST_DISPLAY} | ${GIT_BRANCH} | ctx:${CTX_DISPLAY} | rate:${RATE_DISPLAY}"
 
 # ── Output ─────────────────────────────────────────────────────────────────
 if command -v jq >/dev/null 2>&1; then

package/files/loop/README.md

@@ -1,3 +1,14 @@
+---
+provenance:
+  upstream: community/ralph-wiggum
+  upstream_path: "pattern: ralph wiggum autonomous loop"
+  upstream_commit: 1e73be0
+  license: varies (mostly MIT)
+  license_verification: pattern_only
+  adapted: "2026-02-11"
+  changes: adapted ralph autonomous-loop pattern
+---
+
 # Merlin Loop
 
 **Autonomous AI Development Orchestrator**

package/files/merlin/skills/SKILLS-INDEX.md

@@ -1,3 +1,14 @@
+---
+provenance:
+  upstream: gsd-build/get-shit-done
+  upstream_path: skills/SKILLS-INDEX.md
+  upstream_commit: 9045c81
+  license: MIT
+  license_verification: confirmed
+  adapted: "2026-03-14"
+  changes: adapted from GSD skill pattern
+---
+
 # Merlin Skills Index
 
 When planning or executing a task, search this index to find relevant skills to load.
@@ -31,7 +42,11 @@ Skills are prompt injections that enhance your capabilities for specific domains
 - `devops/docker-containers` — Dockerfiles, multi-stage builds, docker-compose, minimal images — [docker, containers, devops]
 - `devops/ci-cd` — GitHub Actions, CI pipelines, automated testing and deployment — [ci, cd, github-actions, deployment]
 
-## Design
+## Design (Priority — load FIRST for any design/UI work)
+- `design/impeccable` — Comprehensive design language: typography, color (OKLCH), spatial, motion, interaction, responsive, UX writing — [design, ui, typography, color, spacing, motion, accessibility, oklch] **[priority]**
+  · Triggers: redesign, "make it pretty", typography, spacing, color system, accessibility, responsive, dark mode, design review, UX writing
+- `design/emil-design-eng` — Animation craft & UI polish from Emil Kowalski: easing, gestures, transforms, performance — [animation, polish, micro-interactions, easing, gestures] **[priority]**
+  · Triggers: animate, feels stiff, add motion, polish, micro-interactions, easing, transitions, 60fps
 - `design/animation` — Smooth animations with Framer Motion, GSAP, CSS transitions — [animation, framer-motion, gsap, motion]
 
 ## Research