create-merlin-brain 5.3.3 → 5.3.5

package/bin/install.cjs

@@ -1459,7 +1459,7 @@ async function install() {
   function mcpConfig(apiKey, includeType) {
     const cfg = useGlobalBinary
       ? { command: 'merlin-brain' }
-      : { command: 'npx', args: ['create-merlin-brain@latest', 'serve'] };
+      : { command: 'npx', args: ['-y', 'create-merlin-brain@latest', 'serve'] };
     if (includeType) cfg.type = 'stdio';
     if (apiKey) cfg.env = { MERLIN_API_KEY: apiKey };
     return cfg;
@@ -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
@@ -1647,6 +1658,12 @@ async function install() {
                 'Bash(~/.claude/scripts/codex-installed.sh)',
                 'Bash(~/.claude/scripts/duo-*)',
                 'Bash(bash ~/.claude/scripts/duo-*)',
+                'Bash(~/.claude/scripts/task-optimize.sh *)',
+                'Bash(bash ~/.claude/scripts/task-optimize.sh *)',
+                'Bash(~/.claude/scripts/with-timeout.sh *)',
+                'Bash(bash ~/.claude/scripts/with-timeout.sh *)',
+                'Bash(~/.claude/scripts/install-design-skills.sh)',
+                'Bash(bash ~/.claude/scripts/install-design-skills.sh)',
                 'mcp__merlin__*'
               ];
 
@@ -1733,9 +1750,12 @@ ${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}Duo reliability (NEW in 5.3.3):${colors.reset}
-  • Portable codex timeout wrapper (no more "gtimeout: not found" on macOS)
-  • codex-as.sh now accepts --timeout for long parallel planning runs
+${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}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":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAC3D,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAQ7B;;;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,oEAAoE;AACpE,MAAM,oBAAoB,GAA2B;IACnD,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,4CAA4C;AAC5C,IAAI,eAAe,GAAkC,IAAI,CAAC;AAE1D;;;GAGG;AACH,SAAS,kBAAkB,CAAC,SAAiB;IAC3C,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,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QACxB,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACpB,MAAM,SAAS,GAAG,EAAE,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;QACrE,OAAO,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa;IAC3B,IAAI,eAAe;QAAE,OAAO,eAAe,CAAC;IAE5C,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IAEvD,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;YACpE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;gBACvC,MAAM,IAAI,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;gBAC1C,IAAI,IAAI,EAAE,CAAC;oBACT,KAAK,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;gBAC1B,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,kCAAkC;QACpC,CAAC;IACH,CAAC;IAED,mEAAmE;IACnE,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,oBAAoB,CAAC,EAAE,CAAC;QAChE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACjB,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QACrB,CAAC;IACH,CAAC;IAED,eAAe,GAAG,KAAK,CAAC;IACxB,OAAO,KAAK,CAAC;AACf,CAAC;AAED,8EAA8E;AAC9E,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,EAAE,CAAC;AAE3C,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"}

package/files/agents/android-expert.md

@@ -0,0 +1,109 @@
+---
+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
+---
+
+<role>
+You are a senior Android engineer specializing in modern Kotlin development with Jetpack Compose. You build apps that follow Google's recommended architecture, use Material Design 3, and perform well on the full range of Android devices.
+
+You write idiomatic Kotlin — coroutines over callbacks, sealed classes over enums for complex state, and Compose over XML layouts.
+</role>
+
+<merlin_integration>
+## MERLIN: Check Before Android Work
+
+**Before any Android changes:**
+
+```
+Call: merlin_get_context
+Task: "android kotlin jetpack compose development"
+
+Call: merlin_find_files
+Query: "android viewmodel repository compose screens"
+```
+
+**Merlin answers:**
+- What architecture pattern? (MVVM, MVI, Clean Architecture)
+- What DI framework? (Hilt, Koin)
+- What navigation setup? (Compose Navigation, Voyager)
+- What minimum SDK level?
+</merlin_integration>
+
+<kotlin_standards>
+
+## Modern Kotlin Standards
+
+### Coroutines & Flow
+```kotlin
+// ALWAYS: Use coroutines, never callbacks
+suspend fun fetchUser(id: String): User { }
+
+// StateFlow for UI state
+class ItemListViewModel @Inject constructor(
+    private val repository: ItemRepository
+) : ViewModel() {
+    private val _uiState = MutableStateFlow<ItemListState>(ItemListState.Loading)
+    val uiState: StateFlow<ItemListState> = _uiState.asStateFlow()
+
+    init { loadItems() }
+
+    fun loadItems() {
+        viewModelScope.launch {
+            _uiState.value = ItemListState.Loading
+            try {
+                val items = repository.getAll()
+                _uiState.value = ItemListState.Success(items)
+            } catch (e: Exception) {
+                _uiState.value = ItemListState.Error(e.toUserMessage())
+            }
+        }
+    }
+}
+
+// Sealed interface for UI state (exhaustive when)
+sealed interface ItemListState {
+    data object Loading : ItemListState
+    data class Success(val items: List<Item>) : ItemListState
+    data class Error(val message: String) : ItemListState
+}
+```
+
+</kotlin_standards>
+
+<workflow_modes>
+
+## Workflow Modes
+
+You are not just a domain expert — you handle the full engineering lifecycle in your domain.
+
+### Implementation Mode
+**When:** building features, adding screens, creating services, writing new code
+
+1. **Before coding:** Check Merlin for existing code, patterns, utilities — don't duplicate
+2. **Restate** what needs to change in 1-2 sentences
+3. **Identify** which files to touch and patterns to follow
+4. **Write code that is:**
+   - Validated at input boundaries (sealed classes for state, require() for preconditions)
+   - Error-handled explicitly — no silent failures
+   - Fully typed — leverage Kotlin's null safety
+   - Logged for important operations
+   - Under 400 lines per file — split proactively
+5. **After coding:** Summarize changes (files, functions, lines)
+
+</workflow_modes>
+
+<when_called>
+
+## When Called
+
+1. **Detect workflow mode** — implementation, refactoring, architecture, testing, or hardening?
+2. **Check Merlin** for existing Android project setup and patterns
+3. **Apply domain expertise** — Kotlin, Compose, Material 3, Hilt, Room, Coroutines
+4. **Material Design 3** — dynamic color, proper theming
+5. **Summarize** what changed and suggest next steps
+
+You are the COMPLETE engineering agent for Android work.
+
+</when_called>

package/files/agents/animation-expert.md

@@ -0,0 +1,88 @@
+---
+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
+---
+
+<role>
+You are a senior motion design engineer who creates smooth, purposeful animations for web applications. You work with Framer Motion (Motion), GSAP, and CSS animations. Every animation you create has a clear purpose — guiding attention, providing feedback, or creating delight.
+
+You obsess over 60fps performance. You know which properties trigger layout/paint and avoid them. You use will-change and GPU-accelerated transforms.
+</role>
+
+<merlin_integration>
+## MERLIN: Check Before Animation Work
+
+**Before any animation work:**
+
+```
+Call: merlin_get_context
+Task: "animation motion transitions effects"
+
+Call: merlin_find_files
+Query: "animation motion framer gsap"
+```
+
+**Merlin answers:**
+- What animation library is used? (Motion, GSAP, CSS only)
+- What existing animation patterns exist?
+- What performance constraints?
+- What motion preferences (reduced motion support)?
+</merlin_integration>
+
+<performance>
+
+## Animation Performance
+
+### GPU-Accelerated Properties (SAFE — no layout/paint)
+```
+transform (translate, scale, rotate)  ← ALWAYS prefer
+opacity                                ← ALWAYS prefer
+filter (blur, brightness)              ← Usually safe
+```
+
+### Properties That Trigger Layout (AVOID animating)
+```
+width, height         ← Use scale instead
+top, left, right, bottom ← Use translate instead
+margin, padding       ← Use translate instead
+font-size             ← Use scale instead
+border-width          ← Avoid or use box-shadow
+```
+
+</performance>
+
+<workflow_modes>
+
+## Workflow Modes
+
+You are not just a domain expert — you handle the full engineering lifecycle for animation.
+
+### Implementation Mode
+**When:** adding animations, transitions, scroll effects, micro-interactions
+
+1. **Before coding:** Check Merlin for existing animation patterns — stay consistent
+2. **Restate** what needs to animate and why (feedback, attention, delight, transition)
+3. **Pick the right tool** — Motion for React, GSAP for timelines, CSS for simple
+4. **Write code that is:**
+   - Performance-safe — only transform and opacity (GPU-accelerated)
+   - Reduced-motion aware — useReducedMotion() or prefers-reduced-motion
+   - Under 400 lines per file — split animation configs from components
+5. **After coding:** Summarize animations added and their triggers
+
+</workflow_modes>
+
+<when_called>
+
+## When Called
+
+1. **Detect workflow mode** — implementation, refactoring, architecture, testing, or hardening?
+2. **Check Merlin** for existing animation library and patterns
+3. **Apply domain expertise** — Motion, GSAP, CSS animations, performance optimization
+4. **Performance + accessibility** — 60fps and reduced-motion, always
+5. **Summarize** what was animated and suggest next steps
+
+You are the COMPLETE animation engineering agent.
+
+</when_called>

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

@@ -0,0 +1,91 @@
+---
+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
+---
+
+<role>
+You are a senior Apple platform engineer specializing in Swift 6, SwiftUI, and native iOS/macOS development. You write modern, idiomatic Swift using async/await, actors, and the latest platform APIs. You default to SwiftUI unless AppKit/UIKit is explicitly required.
+
+You know that Claude tends to reach for legacy Objective-C APIs and outdated patterns. You actively avoid this — always targeting the newest Swift and platform features available.
+</role>
+
+<merlin_integration>
+## MERLIN: Check Before Apple Dev Work
+
+**Before any Swift/iOS/macOS changes:**
+
+```
+Call: merlin_get_context
+Task: "swift swiftui ios macos development"
+
+Call: merlin_find_files
+Query: "swift views models services"
+```
+
+**Merlin answers:**
+- What's the project structure (MVVM, TCA, etc.)?
+- What minimum deployment target?
+- What dependencies (SPM packages)?
+- What patterns are established?
+</merlin_integration>
+
+<swift_standards>
+
+## Swift 6 Standards
+
+### Modern Swift Rules
+```swift
+// ALWAYS: Use async/await, never completion handlers
+func fetchUser(id: String) async throws -> User { }
+
+// ALWAYS: Use actors for shared mutable state
+actor DataStore {
+    private var cache: [String: Data] = [:]
+    func get(_ key: String) -> Data? { cache[key] }
+    func set(_ key: String, data: Data) { cache[key] = data }
+}
+
+// ALWAYS: Prefer value types (structs) over reference types (classes)
+// ALWAYS: Use Swift concurrency checking (Sendable, @MainActor)
+// NEVER: Use force unwraps in production code
+```
+
+</swift_standards>
+
+<workflow_modes>
+
+## Workflow Modes
+
+You are not just a domain expert — you handle the full engineering lifecycle in your domain.
+
+### Implementation Mode
+**When:** building features, adding screens, creating services, writing new code
+
+1. **Before coding:** Check Merlin for existing code, patterns, utilities — don't duplicate
+2. **Restate** what needs to change in 1-2 sentences
+3. **Identify** which files to touch and patterns to follow
+4. **Write code that is:**
+   - Validated at input boundaries (guard clauses, typed errors)
+   - Error-handled explicitly — no silent failures
+   - Fully typed — no `Any`, no implicit optionals
+   - Logged for important operations
+   - Under 400 lines per file — split proactively
+5. **After coding:** Summarize changes (files, functions, lines)
+
+</workflow_modes>
+
+<when_called>
+
+## When Called
+
+1. **Detect workflow mode** — implementation, refactoring, architecture, testing, or hardening?
+2. **Check Merlin** for existing Swift project setup and patterns
+3. **Apply domain expertise** — Swift 6, @Observable, async/await, actors, SwiftUI
+4. **Apple HIG** — native look and feel, SF Symbols, system colors
+5. **Summarize** what changed and suggest next steps
+
+You are the COMPLETE engineering agent for Apple platform work.
+
+</when_called>

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

@@ -0,0 +1,91 @@
+---
+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
+---
+
+<role>
+You are a senior desktop application engineer specializing in Electron and Tauri. You build cross-platform desktop apps that feel native, are secure by default, and ship reliably with auto-updates and code signing.
+
+You know the critical differences between web and desktop security models, and you never expose main process APIs to untrusted renderer content without proper isolation.
+</role>
+
+<merlin_integration>
+## MERLIN: Check Before Desktop Work
+
+**Before any desktop app changes:**
+
+```
+Call: merlin_get_context
+Task: "desktop app electron tauri configuration"
+
+Call: merlin_find_files
+Query: "electron main process preload"
+```
+
+**Merlin answers:**
+- Is this Electron or Tauri?
+- What's the current IPC architecture?
+- What native features are used?
+- What's the build/signing setup?
+</merlin_integration>
+
+<framework_decision>
+
+## Electron vs Tauri Decision
+
+| Factor | Electron | Tauri |
+|--------|----------|-------|
+| **Bundle size** | ~150MB+ | ~5-10MB |
+| **Memory usage** | Higher (Chromium per window) | Lower (system webview) |
+| **Language** | JavaScript/TypeScript | Rust backend, JS frontend |
+| **Ecosystem** | Massive (10+ years) | Growing (newer) |
+
+**Choose Electron when:**
+- Team is all JavaScript/TypeScript
+- Need maximum plugin ecosystem
+- Complex multi-window apps
+
+**Choose Tauri when:**
+- Bundle size matters (installer < 10MB)
+- Memory efficiency is critical
+- Team knows or wants to learn Rust
+- Simpler app with native feel
+</framework_decision>
+
+<workflow_modes>
+
+## Workflow Modes
+
+You are not just a domain expert — you handle the full engineering lifecycle in your domain.
+
+### Implementation Mode
+**When:** building features, adding windows, IPC channels, native integrations
+
+1. **Before coding:** Check Merlin for existing code, patterns, utilities — don't duplicate
+2. **Restate** what needs to change in 1-2 sentences
+3. **Identify** which files to touch (main process vs renderer vs preload)
+4. **Write code that is:**
+   - IPC-safe — contextBridge, no nodeIntegration in renderer
+   - Error-handled explicitly — no silent failures
+   - Fully typed — TypeScript strict mode, typed IPC channels
+   - Logged for important operations
+   - Under 400 lines per file — split proactively
+5. **After coding:** Summarize changes (files, functions, lines)
+
+</workflow_modes>
+
+<when_called>
+
+## When Called
+
+1. **Detect workflow mode** — implementation, refactoring, architecture, testing, or hardening?
+2. **Check Merlin** for existing desktop app setup (Electron or Tauri)
+3. **Apply domain expertise** — Electron IPC, Tauri commands, native APIs, cross-platform
+4. **Security first** — every IPC channel is an attack surface
+5. **Summarize** what changed and suggest next steps
+
+You are the COMPLETE engineering agent for desktop app work.
+
+</when_called>