create-merlin-brain 5.3.4 → 5.3.7

package/bin/install.cjs

@@ -1557,6 +1557,10 @@ async function install() {
       try {
         claudeDirConfig = JSON.parse(fs.readFileSync(claudeDirDesktopConfig, 'utf8'));
       } catch (e) {
+        // Backup the malformed file before overwriting
+        const bakPath = claudeDirDesktopConfig + '.bak.' + Date.now();
+        fs.copyFileSync(claudeDirDesktopConfig, bakPath);
+        logWarn(`Config file malformed, backed up to ${bakPath} before overwriting`);
         claudeDirConfig = {};
       }
     }
@@ -1575,7 +1579,14 @@ async function install() {
         fs.writeFileSync(claudeJsonPath, JSON.stringify(claudeJson, null, 2));
         logSuccess('Merlin Sights configured for ~/.claude.json (Claude MCP registry)');
       } catch (e) {
-        logWarn('Could not update ~/.claude.json - you may need to run: claude mcp remove merlin && claude mcp add merlin ...');
+        // Backup the malformed file before overwriting
+        const bakPath = claudeJsonPath + '.bak.' + Date.now();
+        fs.copyFileSync(claudeJsonPath, bakPath);
+        logWarn(`Config file malformed, backed up to ${bakPath} before overwriting`);
+        // Create with minimal config
+        const claudeJson = { mcpServers: { merlin: mcpConfig(apiKey, true) } };
+        fs.writeFileSync(claudeJsonPath, JSON.stringify(claudeJson, null, 2));
+        logWarn('Could not update ~/.claude.json - created minimal config with backup');
       }
     } else {
       // Create ~/.claude.json with MCP config if it doesn't exist
@@ -1739,13 +1750,15 @@ ${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}Brain audit fixes (NEW in 5.3.4):${colors.reset}
-  • 8 missing agents vendored (ui-builder, animation-expert, android-expert, etc.)
-  • codex-as.sh now actually prepends optimizer-matched skill bodies
-  • merlin-codex.sh preserves codex exec flags
-  • with-timeout.sh GNU path returns 124 consistently
-  • duo permissions allowlist expanded to cover all runtime scripts
-  • Removed hostile postinstall hook
+${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}Merlin works with or without Sights:${colors.reset}
   • ${colors.green}With Sights${colors.reset}: Instant context, cross-session memory

package/dist/server/tools/route-helpers.d.ts

@@ -38,7 +38,12 @@ export declare function buildEffortPrefix(effort: EffortLevel): {
     prefix: string;
     suffix: string;
 };
-/** Known specialist agents and their roles */
+/**
+ * Read live agent roles from ~/.claude/agents/*.md files.
+ * Caches the result after first access.
+ */
+export declare function getAgentRoles(): Record<string, string>;
+/** Known specialist agents and their roles (live from disk, with fallback) */
 export declare const AGENT_ROLES: Record<string, string>;
 /** Merlin internal workflow agents */
 export declare const WORKFLOW_AGENTS: string[];

package/dist/server/tools/route-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-helpers.d.ts","sourceRoot":"","sources":["../../../src/server/tools/route-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,gDAAgD;AAChD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEpD,kDAAkD;AAClD,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,IAAI,CAAC;AAE9C;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQjE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,CAM9D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAKnE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAI9D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAWzF;AAED,8CAA8C;AAC9C,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAS9C,CAAC;AAEF,sCAAsC;AACtC,eAAO,MAAM,eAAe,UAM3B,CAAC"}
+{"version":3,"file":"route-helpers.d.ts","sourceRoot":"","sources":["../../../src/server/tools/route-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,gDAAgD;AAChD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEpD,kDAAkD;AAClD,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,IAAI,CAAC;AAE9C;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQjE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,CAM9D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAKnE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAI9D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAWzF;AAkCD;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA+BtD;AAED,8EAA8E;AAC9E,eAAO,MAAM,WAAW,wBAAkB,CAAC;AAE3C,sCAAsC;AACtC,eAAO,MAAM,eAAe,UAM3B,CAAC"}

package/dist/server/tools/route-helpers.js

@@ -4,7 +4,9 @@
  * Extracted from route.ts to keep the main routing file focused on
  * tool registration and orchestration logic.
  */
-import { readFileSync } from 'fs';
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
 /**
  * Parse the YAML frontmatter block from an agent .md file.
  * Returns the raw frontmatter string or null if not present.
@@ -71,8 +73,8 @@ export function buildEffortPrefix(effort) {
     }
     return { prefix: '', suffix: '' };
 }
-/** Known specialist agents and their roles */
-export const AGENT_ROLES = {
+/** Fallback specialist agents (used if agent files not readable) */
+const FALLBACK_AGENT_ROLES = {
     'product-spec': 'Feature specification and product definition',
     'system-architect': 'Architecture decisions and system design',
     'implementation-dev': 'Code implementation and feature building',
@@ -82,6 +84,62 @@ export const AGENT_ROLES = {
     'ops-railway': 'Deployment, ops, Railway, Google Cloud',
     'docs-keeper': 'Documentation updates',
 };
+/**  Cache for agent roles read from disk */
+let agentRolesCache = null;
+/**
+ * Extract agent description from .md file frontmatter.
+ * Looks for 'description:' field in YAML frontmatter.
+ */
+function extractDescription(agentPath) {
+    try {
+        const content = readFileSync(agentPath, 'utf-8');
+        const match = content.match(/^---\n([\s\S]*?)\n---/);
+        if (!match)
+            return null;
+        const fm = match[1];
+        const descMatch = fm.match(/^description:\s*["']([^"']*?)["']\s*$/m);
+        return descMatch ? descMatch[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read live agent roles from ~/.claude/agents/*.md files.
+ * Caches the result after first access.
+ */
+export function getAgentRoles() {
+    if (agentRolesCache)
+        return agentRolesCache;
+    const roles = {};
+    const agentsDir = join(homedir(), '.claude', 'agents');
+    if (existsSync(agentsDir)) {
+        try {
+            const files = readdirSync(agentsDir).filter(f => f.endsWith('.md'));
+            for (const file of files) {
+                const agentName = file.replace('.md', '');
+                const filePath = join(agentsDir, file);
+                const desc = extractDescription(filePath);
+                if (desc) {
+                    roles[agentName] = desc;
+                }
+            }
+        }
+        catch {
+            // Fall back to hardcoded defaults
+        }
+    }
+    // Merge with fallback defaults (fallback wins for missing entries)
+    for (const [name, role] of Object.entries(FALLBACK_AGENT_ROLES)) {
+        if (!roles[name]) {
+            roles[name] = role;
+        }
+    }
+    agentRolesCache = roles;
+    return roles;
+}
+/** Known specialist agents and their roles (live from disk, with fallback) */
+export const AGENT_ROLES = getAgentRoles();
 /** Merlin internal workflow agents */
 export const WORKFLOW_AGENTS = [
     'merlin-planner', 'merlin-executor', 'merlin-codebase-mapper',

package/dist/server/tools/route-helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"route-helpers.js","sourceRoot":"","sources":["../../../src/server/tools/route-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAQlC;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAiB;IAChD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACjD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC;QACrD,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,MAAM,WAAW,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAChD,IAAI,CAAC,WAAW;QAAE,OAAO,QAAQ,CAAC;IAClC,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACrE,IAAI,CAAC,KAAK;QAAE,OAAO,QAAQ,CAAC;IAC5B,OAAO,KAAK,CAAC,CAAC,CAAgB,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAiB;IAClD,MAAM,WAAW,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAChD,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAC9B,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACjE,OAAO,KAAK,CAAC,CAAC,CAAE,KAAK,CAAC,CAAC,CAAmB,CAAC,CAAC,CAAC,IAAI,CAAC;AACpD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAiB;IACnD,MAAM,WAAW,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAChD,IAAI,CAAC,WAAW;QAAE,OAAO,KAAK,CAAC;IAC/B,OAAO,0BAA0B,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;AACtD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAmB;IACnD,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAClD,CAAC;IACD,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;QACrB,OAAO;YACL,MAAM,EAAE,EAAE;YACV,MAAM,EAAE,6EAA6E;SACtF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AACpC,CAAC;AAED,8CAA8C;AAC9C,MAAM,CAAC,MAAM,WAAW,GAA2B;IACjD,cAAc,EAAE,8CAA8C;IAC9D,kBAAkB,EAAE,0CAA0C;IAC9D,oBAAoB,EAAE,0CAA0C;IAChE,cAAc,EAAE,kDAAkD;IAClE,iBAAiB,EAAE,sDAAsD;IACzE,UAAU,EAAE,+BAA+B;IAC3C,aAAa,EAAE,wCAAwC;IACvD,aAAa,EAAE,uBAAuB;CACvC,CAAC;AAEF,sCAAsC;AACtC,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,gBAAgB,EAAE,iBAAiB,EAAE,wBAAwB;IAC7D,iBAAiB,EAAE,mBAAmB,EAAE,iBAAiB;IACzD,sBAAsB,EAAE,0BAA0B;IAClD,iBAAiB,EAAE,qBAAqB,EAAE,iBAAiB;IAC3D,oBAAoB,EAAE,iBAAiB,EAAE,4BAA4B;CACtE,CAAC"}
+{"version":3,"file":"route-helpers.js","sourceRoot":"","sources":["../../../src/server/tools/route-helpers.ts"],"names":[],"mappings":"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"}

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
 

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/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/merlin/skills/TASK-OPTIMIZER.json

@@ -298,6 +298,51 @@
       "agent": "code-organization-supervisor",
       "intent": "organization",
       "weight": 0.8
+    },
+    {
+      "id": "platform/android",
+      "path": "platform/android",
+      "triggers": [
+        "android", "kotlin", "jetpack compose", "android studio", "google play", "material you",
+        "android ui", "android intent", "android activity", "android fragment", "viewmodel"
+      ],
+      "agent": "android-expert",
+      "intent": "android",
+      "weight": 1.0
+    },
+    {
+      "id": "platform/apple",
+      "path": "platform/apple",
+      "triggers": [
+        "ios", "macos", "swift", "swiftui", "objective-c", "xcode", "uikit", "appkit",
+        "iphone", "ipad", "app store", "watchos", "tvos"
+      ],
+      "agent": "apple-swift-expert",
+      "intent": "apple",
+      "weight": 1.0
+    },
+    {
+      "id": "platform/desktop",
+      "path": "platform/desktop",
+      "triggers": [
+        "electron", "tauri", "desktop app", "system tray", "menu bar app", "native window",
+        "ipc", "windows app", "macos app", "linux app"
+      ],
+      "agent": "desktop-app-expert",
+      "intent": "desktop",
+      "weight": 1.0
+    },
+    {
+      "id": "marketing/automation",
+      "path": "marketing/automation",
+      "triggers": [
+        "email campaign", "drip sequence", "marketing automation", "marketing campaign",
+        "email marketing", "mailchimp", "sendgrid", "transactional email", "newsletter",
+        "growth marketing", "lifecycle email", "ab test email"
+      ],
+      "agent": "marketing-automation",
+      "intent": "marketing",
+      "weight": 1.0
     }
   ],
   "intent_overrides": {

package/files/merlin-system-prompt.txt

@@ -32,4 +32,6 @@ 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.

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-codex-call.sh

@@ -15,15 +15,9 @@ FAILURES_FILE="${HOME}/.claude/merlin-state/.duo-codex-failures"
 DECISIONS_LOG="${HOME}/.claude/merlin-state/duo-decisions.log"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
-# --- Counter helpers ---
+# --- Counter helpers with flock protection ---
 _read_counter() {
-    # Reset counter if file is > 6h old (session boundary)
     if [[ -f "$FAILURES_FILE" ]]; then
-        AGE=$(python3 -c "import os,time; print(int(time.time() - os.path.getmtime('$FAILURES_FILE')))" 2>/dev/null || echo "99999")
-        if [[ "$AGE" -gt 21600 ]]; then
-            rm -f "$FAILURES_FILE"
-            echo 0; return
-        fi
         cat "$FAILURES_FILE" 2>/dev/null || echo 0
     else
         echo 0
@@ -31,9 +25,34 @@ _read_counter() {
 }
 
 _write_counter() {
+    mkdir -p "$(dirname "$FAILURES_FILE")" 2>/dev/null || true
     echo "$1" > "$FAILURES_FILE"
 }
 
+_read_counter_locked() {
+    local result
+    if command -v flock >/dev/null 2>&1; then
+        (
+            flock -s 9 2>/dev/null || true
+            result=$(_read_counter)
+            echo "$result"
+        ) 9>"${FAILURES_FILE}.lock" 2>/dev/null || _read_counter
+    else
+        _read_counter
+    fi
+}
+
+_write_counter_locked() {
+    if command -v flock >/dev/null 2>&1; then
+        (
+            flock -x 9 2>/dev/null || true
+            _write_counter "$1"
+        ) 9>"${FAILURES_FILE}.lock" 2>/dev/null || _write_counter "$1"
+    else
+        _write_counter "$1"
+    fi
+}
+
 _log_failure() {
     local exit_code="$1"
     local ts
@@ -64,15 +83,15 @@ fi
 
 if [[ $EXIT_CODE -eq 0 ]]; then
     # Success — reset failure counter
-    _write_counter 0
+    _write_counter_locked 0
     exit 0
 fi
 
 # Failure path
 _log_failure "$EXIT_CODE" "$@"
 
-COUNT=$(( $(_read_counter) + 1 ))
-_write_counter "$COUNT"
+COUNT=$(( $(_read_counter_locked) + 1 ))
+_write_counter_locked "$COUNT"
 
 if [[ $COUNT -ge 3 ]]; then
     _auto_disable_duo

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/files/scripts/task-optimize.sh

@@ -93,6 +93,14 @@ TEST_CASES = [
     ("React component refactor", "react", "merlin-frontend", 25),
     ("useState hook pattern", "react", "merlin-frontend", 25),
     ("Next.js server component", "react", "merlin-frontend", 25),
+    ("build Android app with Kotlin", "android", "android-expert", 25),
+    ("Jetpack Compose UI for Material You", "android", "android-expert", 25),
+    ("iOS SwiftUI development", "apple", "apple-swift-expert", 25),
+    ("macOS AppKit interface", "apple", "apple-swift-expert", 25),
+    ("Electron app development", "desktop", "desktop-app-expert", 25),
+    ("Tauri system tray application", "desktop", "desktop-app-expert", 25),
+    ("email marketing campaign setup", "marketing", "marketing-automation", 25),
+    ("drip sequence for onboarding", "marketing", "marketing-automation", 25),
     ("fix the database query", "none", "", 0),
     ("rename a variable", "none", "", 0),
     ("update README", "none", "", 0),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-merlin-brain",
-  "version": "5.3.4",
+  "version": "5.3.7",
   "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",