create-merlin-brain 5.3.5 → 5.3.8

package/bin/install.cjs

@@ -1320,10 +1320,17 @@ async function install() {
       hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/user-prompt-router.sh' }]
     });
 
-    // PostToolUse: file size enforcement (implementation agents only)
-    addHookIfMissing(settings.hooks.PostToolUse, {
-      matcher: 'Edit|Write',
-      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/check-file-size.sh' }]
+    // PreToolUse: file size enforcement (400-LOC rule, blocks oversized writes)
+    // NOTE: Moved from PostToolUse to PreToolUse in v5.3.8 to BLOCK before write, not warn after.
+    addHookIfMissing(settings.hooks.PreToolUse, {
+      matcher: 'Edit|Write|MultiEdit',
+      hooks: [{ type: 'command', command: 'bash ~/.claude/hooks/check-file-size.sh', timeout: 10 }]
+    });
+
+    // Remove legacy PostToolUse check-file-size.sh (pre-5.3.8)
+    settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(entry => {
+      const cmd = entry.hooks?.[0]?.command || '';
+      return !cmd.includes('check-file-size.sh');
     });
 
     // PreToolUse: security scanner (prompt injection, secrets, data exfiltration)
@@ -1750,12 +1757,21 @@ ${colors.cyan}Universal Task Optimization (NEW in 5.3.0):${colors.reset}
   • ${colors.bright}/merlin:polish${colors.reset}           - Animation polish via animation-expert
   • ${colors.bright}/merlin:redesign${colors.reset}         - Full redesign via ui-builder
 
-${colors.cyan}Tier-2 cleanup (NEW in 5.3.5):${colors.reset}
-  • 4 new agents wired (android-expert, apple-swift-expert, desktop-app-expert, marketing-automation)
-  • Counter-reset bug diagnosed in duo-codex-call.sh (fix pending v5.3.6)
-  • MCP routing reads live agent list from disk (no drift)
-  • Concurrent codex calls protected by flock
-  • Malformed config files now backed up before overwrite
+${colors.cyan}Attribution hardening (NEW in 5.3.6):${colors.reset}
+  • All shipped agents now carry provenance frontmatter (source + license + import date)
+  • check-provenance.js now requires every agent to declare provenance
+  • Unknown-origin agents documented in NOTICE.md (attribution pending — see issue tracker)
+
+${colors.cyan}Discovery-first (NEW in 5.3.7):${colors.reset}
+  • Brain now proactively searches 1000+ community agents before routing
+  • ${colors.bright}/merlin:install <slug>${colors.reset} - One-keystroke install of any catalog agent
+  • smart_route + discover_agents wired into the orchestrator protocol
+
+${colors.cyan}File-size enforcement (NEW in 5.3.8):${colors.reset}
+  • 400-LOC rule now enforced by PreToolUse hook (blocks oversized writes)
+  • ${colors.bright}/merlin:check-size${colors.reset} - Scan repo for violations
+  • Justify exceptions with: ${colors.yellow}// merlin:allow-large-file: <reason>${colors.reset}
+  • Override: MERLIN_SKIP_FILE_SIZE_CHECK=1 or MERLIN_FILE_SIZE_LIMIT=N
 
 ${colors.cyan}Merlin works with or without Sights:${colors.reset}
   • ${colors.green}With Sights${colors.reset}: Instant context, cross-session memory

package/files/CLAUDE.md

@@ -53,11 +53,23 @@ Do NOT spawn Explore agents or run Glob/Grep for codebase questions. Use Sights
 
 Never just dump an agent result and go silent. Always follow through.
 
+## Discovery-First Routing (1000+ community agents)
+
+Before routing any non-trivial task to a built-in specialist, proactively check the community catalog:
+
+1. Call `merlin_smart_route(task="<full user text>")` to score both built-in and catalog agents.
+2. If a catalog match (Grade A+ or A) scores higher than built-in options, surface it to the user.
+3. Example: "⟡🔮 MERLIN › Found a community agent: **Payment Integration** (Grade A). Install with `/merlin:install payment-integration`, or use built-in implementation-dev?"
+4. Wait for user choice — never auto-install without confirmation.
+5. Use `/merlin:install <slug>` to install, or the user can describe what they want and Merlin will auto-route.
+
+Skip discovery for: trivial edits (single file, comment, rename), debug runs, doc updates, or when user explicitly names an agent.
+
 ## Execution
 
 Run independent agents in PARALLEL. Never sequential when parallel is possible.
 NEVER run `claude --agent` via Bash. Always use `Skill("merlin:route")` or `merlin_route()`.
-For ANY routing, call `merlin_smart_route(task="...")` FIRST to check 500+ community agents.
+For ANY routing, call `merlin_smart_route(task="...")` FIRST to check community agents + built-ins.
 
 ## Learning
 
@@ -71,6 +83,7 @@ When user corrects you → `merlin_save_behavior`. When user says "always/never/
 - Never kill user processes (Xcode, VS Code, browsers) without explicit confirmation.
 - Never claim "done" without actually building/compiling/testing.
 - Badge on EVERY action — call `~/.claude/scripts/duo-badge.sh` to get the right badge. If the user can't see the badge, you're not doing your job.
+- No file may exceed 400 LOC. Enforced by ~/.claude/hooks/check-file-size.sh (PreToolUse hook). Override per-file with `// merlin:allow-large-file: <reason>` comment. Override per-session with MERLIN_SKIP_FILE_SIZE_CHECK=1.
 
 ## Codex Execution Mode
 

package/files/agents/android-expert.md

@@ -3,6 +3,15 @@ name: android-expert
 description: Full-lifecycle Android agent — implements, refactors, architects, tests, and hardens Kotlin, Jetpack Compose, Material Design 3, and Android apps.
 model: sonnet
 color: green
+provenance:
+  upstream: unknown-origin/vendored-agents-feb2026
+  source: unknown
+  imported_date: "2026-02-04"
+  style_signature: "Full-lifecycle X agent — builds, refactors, architects, tests, and hardens"
+  license: unknown
+  license_verification: unconfirmed
+  adapted: "Vendored as-is from local cache on 2026-02-04. No modifications beyond Merlin integration."
+  note: "Imported in batch on 2026-02-04 from an unidentified source. Style is consistent with a single author/tool but no public catalog match was found (checked wshobson/agents, VoltAgent/awesome-claude-code-subagents). Curated, integrated, and shipped via create-merlin-brain. If you recognize this as your work, please open an issue at https://github.com/sandman66666/merlin and we'll update attribution."
 ---
 
 <role>

package/files/agents/animation-expert.md

@@ -3,6 +3,15 @@ name: animation-expert
 description: Full-lifecycle animation agent — builds, refactors, architects, tests, and hardens animations with Motion, GSAP, CSS, and 60fps performance.
 model: sonnet
 color: violet
+provenance:
+  upstream: unknown-origin/vendored-agents-feb2026
+  source: unknown
+  imported_date: "2026-02-04"
+  style_signature: "Full-lifecycle X agent — builds, refactors, architects, tests, and hardens"
+  license: unknown
+  license_verification: unconfirmed
+  adapted: "Vendored as-is from local cache on 2026-02-04. No modifications beyond Merlin integration."
+  note: "Imported in batch on 2026-02-04 from an unidentified source. Style is consistent with a single author/tool but no public catalog match was found (checked wshobson/agents, VoltAgent/awesome-claude-code-subagents). Curated, integrated, and shipped via create-merlin-brain. If you recognize this as your work, please open an issue at https://github.com/sandman66666/merlin and we'll update attribution."
 ---
 
 <role>

package/files/agents/apple-swift-expert.md

@@ -3,6 +3,15 @@ name: apple-swift-expert
 description: Full-lifecycle Apple platform agent — implements, refactors, architects, tests, and hardens Swift 6, SwiftUI, AppKit, iOS and macOS code.
 model: sonnet
 color: blue
+provenance:
+  upstream: unknown-origin/vendored-agents-feb2026
+  source: unknown
+  imported_date: "2026-02-04"
+  style_signature: "Full-lifecycle X agent — builds, refactors, architects, tests, and hardens"
+  license: unknown
+  license_verification: unconfirmed
+  adapted: "Vendored as-is from local cache on 2026-02-04. No modifications beyond Merlin integration."
+  note: "Imported in batch on 2026-02-04 from an unidentified source. Style is consistent with a single author/tool but no public catalog match was found (checked wshobson/agents, VoltAgent/awesome-claude-code-subagents). Curated, integrated, and shipped via create-merlin-brain. If you recognize this as your work, please open an issue at https://github.com/sandman66666/merlin and we'll update attribution."
 ---
 
 <role>

package/files/agents/desktop-app-expert.md

@@ -3,6 +3,15 @@ name: desktop-app-expert
 description: Full-lifecycle desktop app agent — implements, refactors, architects, tests, and hardens Electron and Tauri apps with IPC security and cross-platform distribution.
 model: sonnet
 color: cyan
+provenance:
+  upstream: unknown-origin/vendored-agents-feb2026
+  source: unknown
+  imported_date: "2026-02-04"
+  style_signature: "Full-lifecycle X agent — builds, refactors, architects, tests, and hardens"
+  license: unknown
+  license_verification: unconfirmed
+  adapted: "Vendored as-is from local cache on 2026-02-04. No modifications beyond Merlin integration."
+  note: "Imported in batch on 2026-02-04 from an unidentified source. Style is consistent with a single author/tool but no public catalog match was found (checked wshobson/agents, VoltAgent/awesome-claude-code-subagents). Curated, integrated, and shipped via create-merlin-brain. If you recognize this as your work, please open an issue at https://github.com/sandman66666/merlin and we'll update attribution."
 ---
 
 <role>

package/files/agents/marketing-automation.md

@@ -3,6 +3,15 @@ name: marketing-automation
 description: Full-lifecycle marketing engineering agent — builds, refactors, architects, tests, and hardens email campaigns, drip sequences, A/B tests, and analytics.
 model: sonnet
 color: red
+provenance:
+  upstream: unknown-origin/vendored-agents-feb2026
+  source: unknown
+  imported_date: "2026-02-04"
+  style_signature: "Full-lifecycle X agent — builds, refactors, architects, tests, and hardens"
+  license: unknown
+  license_verification: unconfirmed
+  adapted: "Vendored as-is from local cache on 2026-02-04. No modifications beyond Merlin integration."
+  note: "Imported in batch on 2026-02-04 from an unidentified source. Style is consistent with a single author/tool but no public catalog match was found (checked wshobson/agents, VoltAgent/awesome-claude-code-subagents). Curated, integrated, and shipped via create-merlin-brain. If you recognize this as your work, please open an issue at https://github.com/sandman66666/merlin and we'll update attribution."
 ---
 
 <role>

package/files/agents/orchestrator.md

@@ -3,6 +3,14 @@ name: orchestrator
 description: Master router for a vibe coder building serious, production-leaning systems. Always choose and coordinate the right specialist agent instead of doing work yourself.
 model: opus
 color: red
+provenance:
+  upstream: unknown-origin/vendored-agents-feb2026
+  source: unknown
+  imported_date: "2026-01-22"
+  license: unknown
+  license_verification: unconfirmed
+  adapted: "Vendored as-is from local cache on 2026-01-22. No modifications beyond Merlin integration."
+  note: "Imported on 2026-01-22 from an unidentified source (different style than the Feb 4 batch). Curated, integrated, and shipped via create-merlin-brain. If you recognize this as your work, please open an issue at https://github.com/sandman66666/merlin and we'll update attribution."
 ---
 
 You are the orchestrator for a very strong product thinker and vibe coder who uses Claude Code as their main dev environment.

package/files/agents/ui-builder.md

@@ -3,6 +3,15 @@ name: ui-builder
 description: Full-lifecycle UI engineering agent — builds, refactors, architects, tests, and hardens React components with Tailwind, shadcn/ui, and Radix.
 model: sonnet
 color: orange
+provenance:
+  upstream: unknown-origin/vendored-agents-feb2026
+  source: unknown
+  imported_date: "2026-02-04"
+  style_signature: "Full-lifecycle X agent — builds, refactors, architects, tests, and hardens"
+  license: unknown
+  license_verification: unconfirmed
+  adapted: "Vendored as-is from local cache on 2026-02-04. No modifications beyond Merlin integration."
+  note: "Imported in batch on 2026-02-04 from an unidentified source. Style is consistent with a single author/tool but no public catalog match was found (checked wshobson/agents, VoltAgent/awesome-claude-code-subagents). Curated, integrated, and shipped via create-merlin-brain. If you recognize this as your work, please open an issue at https://github.com/sandman66666/merlin and we'll update attribution."
 ---
 
 <role>

package/files/agents/ui-designer.md

@@ -3,6 +3,15 @@ name: ui-designer
 description: Full-lifecycle design agent — creates, refactors, architects, audits, and hardens design systems, accessibility, tokens, and component specs.
 model: sonnet
 color: pink
+provenance:
+  upstream: unknown-origin/vendored-agents-feb2026
+  source: unknown
+  imported_date: "2026-02-04"
+  style_signature: "Full-lifecycle X agent — builds, refactors, architects, tests, and hardens"
+  license: unknown
+  license_verification: unconfirmed
+  adapted: "Vendored as-is from local cache on 2026-02-04. No modifications beyond Merlin integration."
+  note: "Imported in batch on 2026-02-04 from an unidentified source. Style is consistent with a single author/tool but no public catalog match was found (checked wshobson/agents, VoltAgent/awesome-claude-code-subagents). Curated, integrated, and shipped via create-merlin-brain. If you recognize this as your work, please open an issue at https://github.com/sandman66666/merlin and we'll update attribution."
 ---
 
 <role>

package/files/commands/merlin/check-size.md

@@ -0,0 +1,152 @@
+---
+name: merlin:check-size
+description: Scan the repo for files exceeding the 400-LOC convention and surface violations
+argument-hint: "[path]"
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - AskUserQuestion
+  - mcp__merlin__merlin_route
+---
+
+<objective>
+Scan the current repository for files that exceed the 400-LOC project convention.
+Surface violations grouped by severity, identify opt-out markers, and offer to route to
+`code-organization-supervisor` for refactor proposals on the worst offenders.
+</objective>
+
+<context>
+Optional path argument: $ARGUMENTS
+If provided, scan only that directory. Otherwise scan from repo root (cwd).
+</context>
+
+<process>
+
+## Step 1: Discover Code Files
+
+Run a find command to locate all code files, excluding common generated/vendor directories:
+
+```bash
+find "${1:-.}" -type f \( \
+  -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \
+  -o -name "*.py" -o -name "*.rs" -o -name "*.go" -o -name "*.sh" \
+  -o -name "*.cjs" -o -name "*.mjs" -o -name "*.swift" -o -name "*.kt" \
+  -o -name "*.java" -o -name "*.rb" -o -name "*.php" -o -name "*.c" \
+  -o -name "*.cpp" -o -name "*.h" -o -name "*.hpp" \
+\) \
+  -not -path "*/node_modules/*" \
+  -not -path "*/dist/*" \
+  -not -path "*/build/*" \
+  -not -path "*/.next/*" \
+  -not -path "*/.git/*" \
+  -not -path "*/coverage/*" \
+  -not -path "*/.vite/*" \
+  -not -path "*/vendor/*" \
+  -not -path "*/__pycache__/*" \
+  2>/dev/null | xargs wc -l 2>/dev/null | awk '$1 > 400 && !/total$/' | sort -rn
+```
+
+Capture the output as VIOLATIONS.
+
+## Step 2: Group by Severity
+
+Parse VIOLATIONS and categorize:
+
+| Tier | LOC Range | Label |
+|------|-----------|-------|
+| Critical | 1000+ | files that urgently need splitting |
+| High | 600-999 | should be refactored soon |
+| Warn | 401-599 | approaching limit, watch closely |
+
+## Step 3: Check for Opt-Out Markers
+
+For each violation, check if the file contains the opt-out marker:
+
+```bash
+grep -l "merlin:allow-large-file:" <file>
+```
+
+Tag files that have the marker with "(justified)" in the output.
+
+## Step 4: Present Report
+
+Output a structured report:
+
+```
+============================================
+ FILE SIZE AUDIT — 400-LOC Convention
+============================================
+
+CRITICAL (1000+ LOC):
+  * path/to/file.ts — 1523 lines
+  * path/to/other.js — 1201 lines
+
+HIGH (600-999 LOC):
+  * path/to/module.py — 812 lines (justified: "generated parser tables")
+
+WARN (401-599 LOC):
+  * path/to/component.tsx — 456 lines
+
+--------------------------------------------
+Total violations: X files
+  - X critical, X high, X warn
+  - X have justification markers
+--------------------------------------------
+```
+
+If no violations found:
+```
+All files are within the 400-LOC convention.
+```
+
+## Step 5: Offer Refactor Help
+
+If there are critical-tier violations (1000+ LOC) without markers, ask:
+
+```
+The following files are critically oversized and lack justification:
+  * path/to/file.ts (1523 lines)
+  * path/to/other.js (1201 lines)
+
+Would you like me to route these to `code-organization-supervisor` for
+a proposed split? (y/n)
+```
+
+If user says yes, route to the agent:
+
+```
+Call: merlin_route
+Agent: code-organization-supervisor
+Task: "Propose a refactor plan to split these oversized files into smaller, focused modules:
+  - <file1>: <LOC> lines
+  - <file2>: <LOC> lines
+
+Each resulting module should be under 400 lines. Provide:
+1. Proposed module boundaries
+2. Which functions/classes go where
+3. Import graph after the split
+4. Step-by-step migration plan"
+```
+
+</process>
+
+<error_handling>
+
+| Condition | Action |
+|-----------|--------|
+| No code files found | Report "No code files found in <path>." |
+| Permission errors | Skip inaccessible files, note count skipped |
+| wc/find unavailable | Fall back to Glob + Read with manual line counting |
+| Path doesn't exist | Report error and suggest checking the path |
+
+</error_handling>
+
+<tips>
+- This command is advisory — it doesn't block anything
+- The PreToolUse hook (`~/.claude/hooks/check-file-size.sh`) does the actual blocking
+- Add `// merlin:allow-large-file: <reason>` to justify genuinely large files
+- Override the limit per-session with `MERLIN_FILE_SIZE_LIMIT=600`
+- Skip all checks with `MERLIN_SKIP_FILE_SIZE_CHECK=1`
+</tips>

package/files/commands/merlin/install.md

@@ -0,0 +1,49 @@
+---
+name: merlin:install
+description: Install a community agent/skill from the Merlin catalog by slug. Wraps `npx skills add` and similar install commands per the agent's metadata.
+argument-hint: "<slug> — agent slug from merlin_discover_agents (e.g., 'payment-integration')"
+allowed-tools:
+  - Bash
+  - Read
+  - mcp__merlin__merlin_get_agent_detail
+---
+
+<objective>
+Install a community agent or skill from the Merlin catalog into the user's local Claude environment.
+</objective>
+
+## Steps
+
+1. Read the agent detail via `merlin_get_agent_detail(slug="$ARGUMENTS")` to get the install command and source.
+
+2. Show the user what's about to be installed:
+   - Name, grade, description
+   - Install command from agent metadata
+   - Source repo URL
+   Then ask explicit confirmation: "Install <name>? (Y/N)"
+
+3. On YES, run the install command:
+   - If it starts with `npx skills add`: `bash -c "<install_command>"`
+   - If it starts with `npm install`: `bash -c "<install_command>"` (in cwd or globally based on agent type)
+   - If unknown: surface the command and tell user to run it manually
+
+4. After install, verify the agent is now reachable:
+   - For Claude agents: check `~/.claude/agents/<slug>.md` exists
+   - For skills: check `~/.claude/skills/<slug>/SKILL.md` exists
+   - Otherwise: trust the install command's exit code
+
+5. Surface a usage hint: "Installed <name>. Use via `merlin_route(agent=\"<name>\", task=\"...\")` or just describe what you want — Merlin will route to it."
+
+## Safety
+
+- NEVER run install commands without explicit user Y confirmation.
+- NEVER pipe install commands through eval or shell injection unsafe channels.
+- If the install command from the catalog looks suspicious (contains `curl | sh`, sudo, etc.), refuse and surface the command for manual review.
+- Honor the user's deny list (`~/.claude/settings.json` permissions.deny).
+
+## Errors
+
+- Slug not found → "Slug `<x>` not found. Try `merlin_discover_agents(query=\"...\")` to search."
+- No install command in metadata → "This agent doesn't have an automated install. Visit <source_url> for instructions."
+- Install command failed → show stderr, suggest manual run.
+

package/files/hooks/check-file-size.sh

@@ -1,73 +1,181 @@
 #!/usr/bin/env bash
+# check-file-size.sh — Claude Code PreToolUse hook
 #
-# Merlin Hook: PostToolUse (Write/Edit)
-# Checks if the modified file exceeds the 400-line convention.
-# Exits with code 2 to inject feedback when file is too large.
+# Enforces the 400-LOC project rule. Blocks Edit/Write/MultiEdit when the
+# resulting file would exceed the limit, unless the file contains an opt-out
+# marker (`merlin:allow-large-file: <reason>`).
 #
-# Agent-type awareness: only enforce for implementation agents.
-# Non-code agents (docs, review, verify, etc.) are fully exempt.
+# Contract per hooks-rules.md + Claude Code hooks docs:
+#   - stdin: JSON {tool_name, tool_input, ...}
+#   - block: exit 0 + stdout JSON {"decision":"block","reason":"..."}
+#   - allow: exit 0 + stdout {} (or empty)
+#   - any other exit code is treated as pass; never exit 1 to block
 #
-set -euo pipefail
-trap 'echo "{}"; exit 0' ERR
+# Env opt-outs (allow legitimate overrides):
+#   MERLIN_SKIP_FILE_SIZE_CHECK=1  — skip entirely
+#   MERLIN_FILE_SIZE_LIMIT=N        — override 400 default
 
-# Read CLAUDE_AGENT_TYPE from env — support both var names
-AGENT_TYPE="${CLAUDE_AGENT_TYPE:-${CLAUDE_CODE_AGENT_TYPE:-main}}"
+set -uo pipefail
+# NO `set -e` and NO ERR trap — explicit exit codes only, so a stray non-zero
+# step (e.g. a grep that finds nothing) doesn't accidentally short-circuit the
+# decision.
 
-# Only enforce for implementation agents
-# Skip for all doc/review/verification/analysis agents
-case "$AGENT_TYPE" in
-  implementation-dev|merlin-executor)
-    # Enforcement is active for these agents — continue
-    ;;
-  docs-keeper|merlin-reviewer|merlin-verifier|merlin-milestone-auditor|\
-  merlin-integration-checker|merlin-work-verifier|code-organization-supervisor|\
-  context-guardian|dry-refactor|tests-qa|merlin-codebase-mapper)
-    echo '{}'
-    exit 0
-    ;;
-  *)
-    # For all other agents (including 'main'), skip enforcement
-    echo '{}'
-    exit 0
-    ;;
-esac
+allow() { echo '{}'; exit 0; }
+block() {
+  local reason="$1"
+  # Escape backslashes and double quotes for JSON.
+  local escaped="${reason//\\/\\\\}"
+  escaped="${escaped//\"/\\\"}"
+  escaped="${escaped//$'\n'/\\n}"
+  printf '{"decision":"block","reason":"%s"}\n' "$escaped"
+  exit 0
+}
+
+# Opt-out via env
+[ "${MERLIN_SKIP_FILE_SIZE_CHECK:-0}" = "1" ] && allow
+
+LIMIT="${MERLIN_FILE_SIZE_LIMIT:-400}"
 
-# Read tool input from stdin (Claude Code pipes JSON)
-input=""
+# Read stdin (defensive: never block on TTY)
+INPUT=""
 if [ ! -t 0 ]; then
-  input=$(cat 2>/dev/null || true)
+  INPUT=$(cat 2>/dev/null || true)
 fi
+[ -z "$INPUT" ] && allow
 
-# Extract file path from tool input
-file_path=""
-if [ -n "$input" ] && command -v jq >/dev/null 2>&1; then
-  file_path=$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null || true)
-fi
+# Need python3 for reliable JSON parsing + line counting. If missing, allow.
+command -v python3 >/dev/null 2>&1 || allow
 
-# If no file path found, exit cleanly
-if [ -z "$file_path" ] || [ ! -f "$file_path" ]; then
-  echo '{}'
-  exit 0
-fi
+RESULT=$(MERLIN_LIMIT="$LIMIT" python3 - "$INPUT" <<'PYEOF' 2>/dev/null || echo "ERROR"
+import sys, json, os, fnmatch, re
 
-# Skip non-code files (images, binaries, configs, etc.)
-case "$file_path" in
-  *.png|*.jpg|*.jpeg|*.gif|*.svg|*.ico|*.woff|*.woff2|*.ttf|*.eot) echo '{}'; exit 0 ;;
-  *.lock|*.json|*.yaml|*.yml|*.toml|*.env*) echo '{}'; exit 0 ;;
-  *node_modules*|*.git/*) echo '{}'; exit 0 ;;
-esac
+try:
+    payload = json.loads(sys.argv[1])
+except Exception:
+    print("ALLOW||json-error"); sys.exit(0)
 
-# Count lines in the file
-line_count=$(wc -l < "$file_path" 2>/dev/null || echo "0")
-line_count=$(echo "$line_count" | tr -d ' ')
+limit = int(os.environ.get("MERLIN_LIMIT", "400"))
+tool = payload.get("tool_name", "")
+ti = payload.get("tool_input") or {}
+fp = ti.get("file_path") or ""
 
-# If file exceeds 400 lines, send feedback via exit code 2
-if [ "$line_count" -gt 400 ]; then
-  echo "WARNING: ${file_path} is ${line_count} lines (convention is <400). Consider splitting into smaller, focused modules." >&2
-  echo '{}'
-  exit 2
-fi
+IGNORE_GLOBS = [
+    "*.lock", "*-lock.json", "pnpm-lock.yaml", "yarn.lock", "bun.lockb",
+    "Cargo.lock", "Pipfile.lock", "composer.lock", "Gemfile.lock",
+    "*.min.*", "*.bundle.*",
+    "*.svg", "*.png", "*.jpg", "*.jpeg", "*.gif", "*.ico", "*.webp", "*.pdf",
+    "*.woff", "*.woff2", "*.ttf", "*.eot",
+    "*.snap", "*.csv", "*.tsv",
+    "*.md",
+]
+IGNORE_PATH_SUBSTRINGS = [
+    "/node_modules/", "/dist/", "/build/", "/.next/", "/.git/", "/out/",
+    "/coverage/", "/.vite/", "/migrations/", "/__fixtures__/", "/fixtures/",
+    "/__snapshots__/",
+]
+
+def is_ignored(path):
+    if not path: return True
+    base = os.path.basename(path).lower()
+    for g in IGNORE_GLOBS:
+        if fnmatch.fnmatchcase(base, g.lower()): return True
+    norm = path.replace("\\", "/")
+    for s in IGNORE_PATH_SUBSTRINGS:
+        if s in norm: return True
+    return False
+
+if is_ignored(fp):
+    print("ALLOW||ignored"); sys.exit(0)
+
+def read_existing():
+    try:
+        with open(fp, "r", encoding="utf-8") as f:
+            return f.read()
+    except Exception:
+        return ""
 
-# File is within limits
-echo '{}'
-exit 0
+if tool == "Write":
+    new_content = ti.get("content") or ""
+elif tool == "Edit":
+    existing = read_existing()
+    old = ti.get("old_string", "")
+    new = ti.get("new_string", "")
+    if not existing:
+        new_content = new
+    elif ti.get("replace_all"):
+        new_content = existing.replace(old, new)
+    else:
+        new_content = existing.replace(old, new, 1)
+elif tool == "MultiEdit":
+    cur = read_existing()
+    for e in ti.get("edits") or []:
+        old = e.get("old_string", "")
+        new = e.get("new_string", "")
+        if e.get("replace_all"):
+            cur = cur.replace(old, new)
+        else:
+            cur = cur.replace(old, new, 1)
+    new_content = cur
+else:
+    print("ALLOW||unknown-tool"); sys.exit(0)
+
+# Opt-out marker scan (first 50 + last 50 lines — let big middles still trigger)
+lines = new_content.split("\n")
+loc = len(lines)
+if loc > 100:
+    sample = "\n".join(lines[:50] + lines[-50:])
+else:
+    sample = new_content
+marker = re.search(r"merlin:allow-large-file:\s*([^\n\r]*)", sample)
+if marker:
+    reason = marker.group(1).strip()[:200].replace("|", "/")
+    print(f"ALLOW||marker:{reason}"); sys.exit(0)
+
+if loc > limit:
+    print(f"BLOCK||{loc}||{fp}"); sys.exit(0)
+
+print(f"ALLOW||{loc}"); sys.exit(0)
+PYEOF
+)
+
+# Defensive: any python error → allow
+[ "$RESULT" = "ERROR" ] && allow
+[ -z "$RESULT" ] && allow
+
+ACTION="${RESULT%%||*}"
+
+case "$ACTION" in
+  BLOCK)
+    REST="${RESULT#BLOCK||}"
+    LOC_COUNT="${REST%%||*}"
+    FILE_PATH="${REST#*||}"
+    REASON="File ${FILE_PATH} would be ${LOC_COUNT} LOC, exceeding the ${LIMIT}-LOC project rule.
+
+To proceed, either:
+
+1. REFACTOR — split this file into smaller modules by feature.
+   • Invoke the code-organization-supervisor agent for proposed splits
+   • Run /merlin:check-size to scan the whole repo for offenders
+
+2. JUSTIFY — add this comment in the first 50 lines of the file:
+     // merlin:allow-large-file: <one-line reason this file must stay long>
+   (Python/shell: # merlin:allow-large-file: <reason>)
+   (CSS: /* merlin:allow-large-file: <reason> */)
+   (HTML/JSX: <!-- merlin:allow-large-file: <reason> -->)
+   The reason is your audit trail — make it specific (e.g. 'generated by codegen', 'single-source-of-truth lookup table', 'vendored library').
+
+Override per-session: MERLIN_SKIP_FILE_SIZE_CHECK=1
+Override limit:        MERLIN_FILE_SIZE_LIMIT=600"
+    block "$REASON"
+    ;;
+  ALLOW)
+    REST="${RESULT#ALLOW||}"
+    if [[ "$REST" == marker:* ]]; then
+      echo "[merlin] Allowed large file with marker: ${REST#marker:}" >&2
+    fi
+    allow
+    ;;
+  *)
+    allow
+    ;;
+esac

package/files/merlin-system-prompt.txt

@@ -32,4 +32,8 @@ wait
 
 **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.
+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.
+
+DISCOVERY-FIRST: Before routing any non-trivial task to a built-in specialist, call `merlin_smart_route(task="...")` and `merlin_discover_agents(query="...")` to check the community catalog (1000+ indexed agents/skills). If a catalog match scores a higher grade (A+/A++) than the best built-in for the task, surface it: "⟡🔮 MERLIN › I found a community agent that fits better: <name> (Grade: <X>). Install with /merlin:install <slug> or stick with built-in <built-in>?" — then wait for user choice. NEVER install without confirmation. Skip discovery only for: trivial single-file edits, debug runs, doc updates, or when the user explicitly names an agent.
+
+FILE-SIZE ENFORCEMENT: Every Write/Edit/MultiEdit is blocked by ~/.claude/hooks/check-file-size.sh if the resulting file exceeds 400 LOC (configurable via MERLIN_FILE_SIZE_LIMIT). When blocked, EITHER refactor into smaller modules (preferred) OR add `// merlin:allow-large-file: <one-line reason>` in the first 50 lines if the size is genuinely justified (e.g., generated code, big lookup table, single-file library). Use /merlin:check-size to scan the whole repo at any time.

package/files/rules/merlin-routing.md

@@ -55,6 +55,41 @@ Slash commands: `/merlin:optimize`, `/merlin:design-audit`, `/merlin:polish`, `/
 
 The optimizer is the AUTHORITY. Don't override its recommendations unless the user explicitly asks for a different agent.
 
+## Discovery-First Routing (1000+ community agents)
+
+The Merlin Sights server indexes 1000+ community agents/skills from GitHub, npm, skills.sh, and other sources. Before routing any non-trivial task to a built-in, ALWAYS check if a better community agent exists.
+
+### Protocol
+
+For tasks that are NOT trivial (i.e., > 5 minutes of work, or touching a new domain):
+
+1. Call `merlin_smart_route(task="<full user text>")` — returns the best match from BOTH installed local agents AND the community catalog.
+2. If the response includes a catalog match (source: catalog, grade A+/A++):
+   - Surface it to the user: `⟡🔮 MERLIN › Catalog match: <name> (Grade <X>). Install with /merlin:install <slug>, or use built-in <fallback>?`
+   - Wait for user choice. Never install without confirmation.
+3. If only built-in matches, proceed with normal routing.
+
+For tasks that ARE trivial (single-file edit, rename, comment fix, debug print):
+- Skip discovery. Use the optimizer + built-in directly.
+
+### When to use discover_agents vs smart_route
+
+- `merlin_smart_route(task)` — best for "what agent should I use" decisions (returns ranked recommendation)
+- `merlin_discover_agents(query)` — best for "what's available for X technology" exploration (returns 5-10 matches with install commands)
+
+### Examples
+
+Bad:
+> User: "build me a Stripe payments integration"
+> Merlin: routes to implementation-dev without checking catalog
+
+Good:
+> User: "build me a Stripe payments integration"
+> Merlin: `merlin_smart_route("build Stripe payments...")` → finds "Payment Integration" (Grade A) catalog agent
+> Merlin: "⟡🔮 MERLIN › Found a community agent: **Payment Integration** (Grade A) by ChatAndBuild. Install with `/merlin:install payment-integration`, or use built-in implementation-dev?"
+
+This is what makes the "1000+ skills on the server" actually useful.
+
 ## Agent Routing
 
 Call `merlin_smart_route(task="...")` FIRST (searches 500+ community agents). Then:

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

@@ -33,8 +33,13 @@ pair=$(grep -o '"pair"[[:space:]]*:[[:space:]]*"[^"]*"' "$STATE_FILE" 2>/dev/nul
 [[ "$enabled" != "true" ]] && { if [[ "$PAIR_MODE" == "true" ]]; then echo "none"; else echo "disabled"; fi; exit 0; }
 [[ -z "$since" || "$since" == "null" ]] && { if [[ "$PAIR_MODE" == "true" ]]; then echo "none"; else echo "disabled"; fi; exit 0; }
 
-# Check 24h expiry using portable date commands (macOS has date -j, Linux has date -d)
-since_epoch=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$since" "+%s" 2>/dev/null || date -d "$since" "+%s" 2>/dev/null || echo "")
+# Check 24h expiry using portable date commands (macOS has date -j, Linux has date -d).
+# Normalize +00:00 / +0000 offsets to Z so the strict macOS parser accepts them.
+since_normalized=$(echo "$since" | sed 's/\+00:00$/Z/; s/\+0000$/Z/; s/\.[0-9][0-9][0-9]Z$/Z/; s/\.[0-9][0-9][0-9]\+00:00$/Z/')
+since_epoch=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$since_normalized" "+%s" 2>/dev/null \
+    || date -d "$since" "+%s" 2>/dev/null \
+    || date -d "$since_normalized" "+%s" 2>/dev/null \
+    || echo "")
 if [[ -z "$since_epoch" ]]; then
     # Unparseable timestamp — treat as expired
     if [[ "$PAIR_MODE" == "true" ]]; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-merlin-brain",
-  "version": "5.3.5",
+  "version": "5.3.8",
   "description": "Merlin - The Ultimate AI Brain for Claude Code, Codex, and other AI CLIs. One install: workflows, agents, loop, and Sights MCP server.",
   "type": "module",
   "main": "./dist/server/index.js",