create-merlin-brain 5.0.2 → 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/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

package/files/merlin/skills/TASK-OPTIMIZER.json

@@ -0,0 +1,310 @@
+{
+  "version": "1.0",
+  "default_agent": "implementation-dev",
+  "default_threshold": 25,
+  "skills": [
+    {
+      "id": "design/impeccable",
+      "path": "~/.claude/skills/impeccable/SKILL.md",
+      "triggers": [
+        "redesign", "make it pretty", "looks ugly", "make it beautiful", "the ui is bad",
+        "typography", "fonts", "font pairing", "font", "spacing", "alignment", "grid", "rhythm",
+        "color system", "oklch", "palette", "contrast", "design audit", "design review",
+        "design critique", "responsive design", "mobile broken", "container queries",
+        "fluid design", "dark mode", "light mode", "theme switching", "match stripe",
+        "match linear", "match vercel", "design quality", "design system", "loading state",
+        "empty state", "error state", "form polish", "ux writing", "labels", "error messages",
+        "copy", "looks bad", "ugly", "beautiful", "pretty", "visual", "visuals", "ui design",
+        "ui polish", "ui/ux", "ux design"
+      ],
+      "agent": "ui-builder",
+      "intent": "design",
+      "weight": 1.0,
+      "bundles_with": ["design/emil-design-eng"]
+    },
+    {
+      "id": "design/emil-design-eng",
+      "path": "~/.claude/skills/emil-design-eng/SKILL.md",
+      "triggers": [
+        "animate", "animation", "feels stiff", "add motion", "smoother", "polish",
+        "micro-interactions", "feels cheap", "easing", "transitions", "transitions are bad",
+        "gestures", "60fps", "premium feel", "make it feel premium", "stiff", "motion",
+        "micro-interaction", "microinteraction", "feel premium", "feel cheap"
+      ],
+      "agent": "animation-expert",
+      "intent": "animation-polish",
+      "weight": 1.0,
+      "bundles_with": ["design/impeccable"]
+    },
+    {
+      "id": "design/animation",
+      "path": "design/animation",
+      "triggers": [
+        "framer-motion", "framer motion", "gsap", "scroll trigger", "spring animation",
+        "enter exit animation", "lottie", "rive", "animejs", "anime.js"
+      ],
+      "agent": "animation-expert",
+      "intent": "animation",
+      "weight": 0.8
+    },
+    {
+      "id": "coding/react-patterns",
+      "path": "coding/react-patterns",
+      "triggers": [
+        "react", "react component", "jsx", "tsx", "usestate", "useeffect", "usecallback",
+        "usememo", "hook", "custom hook", "server component", "client component", "next.js",
+        "nextjs", "remix", "vite", "react hook", "react hooks", "use client", "use server"
+      ],
+      "agent": "merlin-frontend",
+      "intent": "react",
+      "weight": 1.0
+    },
+    {
+      "id": "coding/security-hardening",
+      "path": "coding/security-hardening",
+      "triggers": [
+        "auth", "authentication", "authorization", "oauth", "jwt", "owasp", "csrf", "xss",
+        "sql injection", "sqli", "input validation", "sanitize", "session", "rate limit",
+        "secret", "credentials", "harden", "security audit", "vulnerability", "exploit",
+        "security", "secure", "hardening", "security check", "security review", "pen test",
+        "penetration test"
+      ],
+      "agent": "hardening-guard",
+      "intent": "security",
+      "weight": 1.2,
+      "bundles_with": ["testing/tdd-workflow"]
+    },
+    {
+      "id": "coding/api-design",
+      "path": "coding/api-design",
+      "triggers": [
+        "api design", "rest api", "restful", "endpoint design", "openapi", "swagger",
+        "graphql schema", "graphql", "pagination", "api versioning", "express route",
+        "hono", "fastapi", "api endpoint", "trpc", "grpc"
+      ],
+      "agent": "merlin-api-designer",
+      "intent": "api",
+      "weight": 1.0
+    },
+    {
+      "id": "coding/performance",
+      "path": "coding/performance",
+      "triggers": [
+        "performance", "slow", "core web vitals", "lcp", "fid", "cls", "bundle size",
+        "lazy load", "code split", "lighthouse", "memory leak", "cpu", "optimize",
+        "optimization", "fast", "faster", "speed", "perf", "web vitals", "ttfb", "inp"
+      ],
+      "agent": "merlin-performance",
+      "intent": "performance",
+      "weight": 1.0
+    },
+    {
+      "id": "coding/accessibility",
+      "path": "coding/accessibility",
+      "triggers": [
+        "a11y", "accessibility", "wcag", "wcag compliance", "aria", "screen reader",
+        "keyboard navigation", "keyboard nav", "focus management", "alt text",
+        "contrast ratio", "accessible", "accessibility fixes", "accessibility audit",
+        "voiceover", "nvda", "jaws", "accessibility check"
+      ],
+      "agent": "hardening-guard",
+      "intent": "a11y",
+      "weight": 1.1,
+      "bundles_with": ["design/impeccable"]
+    },
+    {
+      "id": "coding/debug-mode",
+      "path": "coding/debug-mode",
+      "triggers": [
+        "bug", "crash", "error", "stack trace", "broken deploy", "broken build",
+        "not working", "fails", "exception", "investigate", "debug", "troubleshoot",
+        "reproduce", "debugging", "null pointer", "undefined", "type error", "runtime error"
+      ],
+      "agent": "merlin-debugger",
+      "intent": "debug",
+      "weight": 1.1
+    },
+    {
+      "id": "coding/verify",
+      "path": "coding/verify",
+      "triggers": [
+        "verify", "validate", "check if it works", "confirm", "smoke test", "qa",
+        "verification", "validation", "sanity check"
+      ],
+      "agent": "merlin-work-verifier",
+      "intent": "verify",
+      "weight": 0.9
+    },
+    {
+      "id": "testing/tdd-workflow",
+      "path": "testing/tdd-workflow",
+      "triggers": [
+        "test", "tests", "unit test", "tdd", "tdd workflow", "red green refactor",
+        "jest", "vitest", "pytest", "rspec", "test coverage", "write tests", "testing",
+        "test suite", "integration test", "e2e test", "end to end", "playwright",
+        "cypress", "mocha"
+      ],
+      "agent": "tests-qa",
+      "intent": "testing",
+      "weight": 1.1
+    },
+    {
+      "id": "devops/docker-containers",
+      "path": "devops/docker-containers",
+      "triggers": [
+        "docker", "dockerfile", "container", "docker-compose", "multi-stage build",
+        "multi-stage", "containerize", "kubernetes", "k8s", "helm", "docker image",
+        "container build", "docker build"
+      ],
+      "agent": "ops-railway",
+      "intent": "docker",
+      "weight": 1.1
+    },
+    {
+      "id": "automation/payments",
+      "path": "automation/payments",
+      "triggers": [
+        "stripe", "payment", "checkout", "subscription", "invoice", "billing",
+        "payment provider", "paddle", "lemonsqueezy", "lemon squeezy", "payments",
+        "payment integration", "subscription billing"
+      ],
+      "agent": "implementation-dev",
+      "intent": "payments",
+      "weight": 1.0
+    },
+    {
+      "id": "automation/webhooks",
+      "path": "automation/webhooks",
+      "triggers": [
+        "webhook", "webhooks", "http callback", "event delivery", "signature verification",
+        "payload", "webhook handler", "webhook endpoint"
+      ],
+      "agent": "implementation-dev",
+      "intent": "webhooks",
+      "weight": 0.9
+    },
+    {
+      "id": "communication/email-gmail",
+      "path": "communication/email-gmail",
+      "triggers": [
+        "gmail", "email send", "email read", "email draft", "gmail api", "mailbox",
+        "send email", "email automation", "email"
+      ],
+      "agent": "implementation-dev",
+      "intent": "email",
+      "weight": 0.9
+    },
+    {
+      "id": "communication/whatsapp",
+      "path": "communication/whatsapp",
+      "triggers": [
+        "whatsapp", "whatsapp business", "wa api", "whatsapp bot", "whatsapp api",
+        "whatsapp integration"
+      ],
+      "agent": "implementation-dev",
+      "intent": "whatsapp",
+      "weight": 0.9
+    },
+    {
+      "id": "communication/telegram",
+      "path": "communication/telegram",
+      "triggers": [
+        "telegram", "telegram bot", "bot api", "tg bot", "telegram api",
+        "telegram integration"
+      ],
+      "agent": "implementation-dev",
+      "intent": "telegram",
+      "weight": 0.9
+    },
+    {
+      "id": "data/google-sheets",
+      "path": "data/google-sheets",
+      "triggers": [
+        "google sheets", "spreadsheet", "sheets api", "sheets formula", "sheet automation",
+        "google sheet", "gsheets"
+      ],
+      "agent": "implementation-dev",
+      "intent": "sheets",
+      "weight": 0.9
+    },
+    {
+      "id": "research/brainstorm",
+      "path": "research/brainstorm",
+      "triggers": [
+        "brainstorm", "ideate", "explore ideas", "what if", "options", "approaches",
+        "brainstorming", "ideas", "explore options"
+      ],
+      "agent": "merlin-researcher",
+      "intent": "brainstorm",
+      "weight": 0.8
+    },
+    {
+      "id": "coding/focus-mode",
+      "path": "coding/focus-mode",
+      "triggers": [
+        "focus mode", "deep work", "no distractions", "focused", "concentrate"
+      ],
+      "agent": "implementation-dev",
+      "intent": "focus",
+      "weight": 0.7
+    },
+    {
+      "id": "coding/loop",
+      "path": "coding/loop",
+      "triggers": [
+        "loop", "autonomous", "auto mode", "keep going", "run continuously"
+      ],
+      "agent": "implementation-dev",
+      "intent": "loop",
+      "weight": 0.7
+    },
+    {
+      "id": "communication/dispatcher",
+      "path": "communication/dispatcher",
+      "triggers": [
+        "dispatch", "notify", "send notification", "alert", "message"
+      ],
+      "agent": "implementation-dev",
+      "intent": "dispatch",
+      "weight": 0.7
+    },
+    {
+      "id": "docs-keeper",
+      "path": "docs-keeper",
+      "triggers": [
+        "documentation", "docs", "readme", "jsdoc", "typedoc", "document", "api docs"
+      ],
+      "agent": "docs-keeper",
+      "intent": "docs",
+      "weight": 0.8
+    },
+    {
+      "id": "hardening-guard",
+      "path": "hardening-guard",
+      "triggers": [
+        "harden", "secure", "lock down", "production ready", "security hardening"
+      ],
+      "agent": "hardening-guard",
+      "intent": "hardening",
+      "weight": 0.9
+    },
+    {
+      "id": "code-organization-supervisor",
+      "path": "code-organization-supervisor",
+      "triggers": [
+        "organize code", "code organization", "file structure", "folder structure",
+        "project structure", "refactor structure"
+      ],
+      "agent": "code-organization-supervisor",
+      "intent": "organization",
+      "weight": 0.8
+    }
+  ],
+  "intent_overrides": {
+    "auth_security_combo": {
+      "match_all": ["auth", "production"],
+      "skills": ["coding/security-hardening", "testing/tdd-workflow"],
+      "agent": "hardening-guard"
+    }
+  }
+}