create-merlin-brain 3.2.0 → 3.3.1

package/bin/install.cjs

@@ -135,23 +135,21 @@ function logWarn(msg) {
 }
 
 function banner() {
+  const version = require('../package.json').version;
   console.log(`
-${colors.magenta}${colors.bright}
-  ███╗   ███╗███████╗██████╗ ██╗     ██╗███╗   ██╗
-  ████╗ ████║██╔════╝██╔══██╗██║     ██║████╗  ██║
-  ██╔████╔██║█████╗  ██████╔╝██║     ██║██╔██╗ ██║
-  ██║╚██╔╝██║██╔══╝  ██╔══██╗██║     ██║██║╚██╗██║
-  ██║ ╚═╝ ██║███████╗██║  ██║███████╗██║██║ ╚████║
-  ╚═╝     ╚═╝╚══════╝╚═╝  ╚═╝╚══════╝╚═╝╚═╝  ╚═══╝
-${colors.reset}
+${colors.magenta}${colors.bright}  __  __ _____ ____  _     ___ _   _
+ |  \\/  | ____|  _ \\| |   |_ _| \\ | |
+ | |\\/| |  _| | |_) | |    | ||  \\| |
+ | |  | | |___|  _ <| |___ | || |\\  |
+ |_|  |_|_____|_| \\_\\_____|___|_| \\_|${colors.reset}
+
   ${colors.cyan}The Ultimate AI Brain for Claude Code${colors.reset}
-  ${colors.bright}v3 — One Install, Everything Included${colors.reset}
+  ${colors.bright}v${version}${colors.reset}
 
-  Four integrated layers:
-  • ${colors.bright}Merlin Loop${colors.reset} - Autonomous orchestration (hours of unattended work)
-  • ${colors.bright}Merlin Sights${colors.reset} - Knowledge layer (instant codebase context)
-  • ${colors.bright}Merlin Workflows${colors.reset} - Planning & execution (/merlin:* commands)
-  • ${colors.bright}Merlin Agents${colors.reset} - Specialist agents for every task
+  ${colors.bright}Loop${colors.reset}      Autonomous orchestration
+  ${colors.bright}Sights${colors.reset}    Instant codebase context
+  ${colors.bright}Workflows${colors.reset} Planning & execution
+  ${colors.bright}Agents${colors.reset}    28 specialist agents
 `);
 }
 
@@ -742,7 +740,7 @@ async function install() {
   }
 
   // Step 0: Clean up legacy GSD/ccwiki artifacts
-  logStep('0/9', 'Cleaning up legacy installations...');
+  logStep('0/10', 'Cleaning up legacy installations...');
   const cleaned = cleanupLegacy();
   if (cleaned.length > 0) {
     for (const item of cleaned) {
@@ -753,7 +751,7 @@ async function install() {
   }
 
   // Step 1: Install globally for instant startup across all terminals
-  logStep('1/9', 'Installing globally (fast startup for all terminals)...');
+  logStep('1/10', 'Installing globally (fast startup for all terminals)...');
   try {
     const { execSync } = require('child_process');
     // Check if already installed globally and up-to-date
@@ -794,7 +792,7 @@ async function install() {
   }
 
   // Step 2: Create directories
-  logStep('2/9', 'Creating directories...');
+  logStep('2/10', 'Creating directories...');
   ensureDir(CLAUDE_DIR);
   ensureDir(MERLIN_DIR);
   ensureDir(AGENTS_DIR);
@@ -802,7 +800,7 @@ async function install() {
   logSuccess('Directories created');
 
   // Step 3: Install Merlin core (workflows, references, templates)
-  logStep('3/9', 'Installing Merlin workflows...');
+  logStep('3/10', 'Installing Merlin workflows...');
   const merlinSrc = path.join(filesDir, 'merlin');
   if (fs.existsSync(merlinSrc)) {
     const count = copyDirRecursive(merlinSrc, MERLIN_DIR);
@@ -812,7 +810,7 @@ async function install() {
   }
 
   // Step 4: Install agents
-  logStep('4/9', 'Installing Merlin agents...');
+  logStep('4/10', 'Installing Merlin agents...');
   const agentsSrc = path.join(filesDir, 'agents');
   if (fs.existsSync(agentsSrc)) {
     const count = copyDirRecursive(agentsSrc, AGENTS_DIR);
@@ -822,7 +820,7 @@ async function install() {
   }
 
   // Step 5: Install commands
-  logStep('5/9', 'Installing /merlin:* commands...');
+  logStep('5/10', 'Installing /merlin:* commands...');
   const commandsSrc = path.join(filesDir, 'commands', 'merlin');
   if (fs.existsSync(commandsSrc)) {
     const count = copyDirRecursive(commandsSrc, COMMANDS_DIR);
@@ -832,7 +830,7 @@ async function install() {
   }
 
   // Step 6: Install CLAUDE.md
-  logStep('6/9', 'Configuring Claude Code...');
+  logStep('6/10', 'Configuring Claude Code...');
   const claudeMdSrc = path.join(filesDir, 'CLAUDE.md');
   const claudeMdDest = path.join(CLAUDE_DIR, 'CLAUDE.md');
 
@@ -844,7 +842,7 @@ async function install() {
   }
 
   // Step 7: Install Merlin Loop (autonomous orchestration)
-  logStep('7/9', 'Installing Merlin Loop...');
+  logStep('7/10', 'Installing Merlin Loop...');
   const loopSrc = path.join(filesDir, 'loop');
   if (fs.existsSync(loopSrc)) {
     ensureDir(LOOP_DIR);
@@ -869,6 +867,119 @@ async function install() {
     logWarn('Merlin Loop not found in package');
   }
 
+  // Step 8: Install Claude Code hooks
+  logStep('8/10', 'Installing Claude Code hooks...');
+  const HOOKS_DIR = path.join(CLAUDE_DIR, 'hooks');
+  const hooksSrc = path.join(filesDir, 'hooks');
+  if (fs.existsSync(hooksSrc)) {
+    ensureDir(HOOKS_DIR);
+    const hookCount = copyDirRecursive(hooksSrc, HOOKS_DIR);
+    // Make all .sh files executable (top-level and lib/)
+    const makeShExecutable = (dir) => {
+      if (!fs.existsSync(dir)) return;
+      fs.readdirSync(dir, { withFileTypes: true }).forEach(entry => {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          makeShExecutable(fullPath);
+        } else if (entry.name.endsWith('.sh')) {
+          fs.chmodSync(fullPath, '755');
+        }
+      });
+    };
+    makeShExecutable(HOOKS_DIR);
+    logSuccess(`Installed ${hookCount} hook files`);
+
+    // Configure hooks in settings.local.json
+    const settingsPath = path.join(CLAUDE_DIR, 'settings.local.json');
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+      try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch (e) { settings = {}; }
+    }
+    settings.hooks = settings.hooks || {};
+
+    const addHookIfMissing = (hookArray, hookConfig) => {
+      const exists = hookArray.some(h => h.command === hookConfig.command);
+      if (!exists) hookArray.push(hookConfig);
+      return hookArray;
+    };
+
+    // SessionStart hook
+    settings.hooks.SessionStart = settings.hooks.SessionStart || [];
+    addHookIfMissing(settings.hooks.SessionStart, {
+      type: 'command',
+      command: 'bash ~/.claude/hooks/session-start.sh'
+    });
+
+    // SessionStart hook: Agent sync (background, runs at most once/hour)
+    addHookIfMissing(settings.hooks.SessionStart, {
+      type: 'command',
+      command: 'bash ~/.claude/hooks/agent-sync.sh'
+    });
+
+    // PreToolUse hook (Edit/Write only)
+    settings.hooks.PreToolUse = settings.hooks.PreToolUse || [];
+    addHookIfMissing(settings.hooks.PreToolUse, {
+      type: 'command',
+      command: 'bash ~/.claude/hooks/pre-edit-sights-check.sh',
+      matcher: 'Edit|Write'
+    });
+
+    // PostToolUse hook (Edit/Write only)
+    settings.hooks.PostToolUse = settings.hooks.PostToolUse || [];
+    addHookIfMissing(settings.hooks.PostToolUse, {
+      type: 'command',
+      command: 'bash ~/.claude/hooks/post-edit-logger.sh',
+      matcher: 'Edit|Write'
+    });
+
+    // Stop hook (session end)
+    settings.hooks.Stop = settings.hooks.Stop || [];
+    addHookIfMissing(settings.hooks.Stop, {
+      type: 'command',
+      command: 'bash ~/.claude/hooks/session-end.sh'
+    });
+
+    // TeammateIdle hook (Agent Teams quality gate — only fires when Teams active)
+    settings.hooks.TeammateIdle = settings.hooks.TeammateIdle || [];
+    addHookIfMissing(settings.hooks.TeammateIdle, {
+      type: 'command',
+      command: 'bash ~/.claude/hooks/teammate-idle-verify.sh'
+    });
+
+    // SubagentStart hook (Agent Teams context injection — only fires when Teams active)
+    settings.hooks.SubagentStart = settings.hooks.SubagentStart || [];
+    addHookIfMissing(settings.hooks.SubagentStart, {
+      type: 'command',
+      command: 'bash ~/.claude/hooks/subagent-context.sh'
+    });
+
+    // --- Prompt-based hooks (LLM evaluates .md content) ---
+    const addPromptHookIfMissing = (hookArray, hookConfig) => {
+      const exists = hookArray.some(h => h.type === 'prompt' && h.prompt === hookConfig.prompt);
+      if (!exists) hookArray.push(hookConfig);
+      return hookArray;
+    };
+
+    // Prompt-based Stop hook: quality gate before session ends
+    addPromptHookIfMissing(settings.hooks.Stop, {
+      type: 'prompt',
+      prompt: fs.readFileSync(path.join(HOOKS_DIR, 'stop-check.md'), 'utf8')
+    });
+
+    // Prompt-based Notification hook: verify task completion quality
+    settings.hooks.Notification = settings.hooks.Notification || [];
+    addPromptHookIfMissing(settings.hooks.Notification, {
+      type: 'prompt',
+      prompt: fs.readFileSync(path.join(HOOKS_DIR, 'task-completed-verify.md'), 'utf8'),
+      matcher: 'task_completed'
+    });
+
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+    logSuccess('Configured hooks in settings.local.json');
+  } else {
+    logWarn('Hooks not found in package');
+  }
+
   // Helper: create MCP config object based on available binary
   function mcpConfig(apiKey, includeType) {
     const cfg = useGlobalBinary
@@ -879,8 +990,8 @@ async function install() {
     return cfg;
   }
 
-  // Step 8: Optional Merlin Sights configuration
-  logStep('8/9', 'Optional: Merlin Sights configuration...');
+  // Step 9: Optional Merlin Sights configuration
+  logStep('9/10', 'Optional: Merlin Sights configuration...');
   console.log(`Merlin Sights provides instant codebase context.`);
   console.log(`Get your API key at: ${colors.cyan}https://merlin.build${colors.reset}`);
 
@@ -978,8 +1089,8 @@ async function install() {
     logWarn('Skipped Merlin Sights (you can configure it later)');
   }
 
-  // Step 9: Set up shell integration
-  logStep('9/9', 'Setting up shell integration...');
+  // Step 10: Set up shell integration
+  logStep('10/10', 'Setting up shell integration...');
   const shellConfigured = setupShellIntegration();
   if (shellConfigured) {
     log(`\n  ${colors.yellow}IMPORTANT:${colors.reset} Run ${colors.cyan}source ~/.zshrc${colors.reset} or ${colors.bright}restart your terminal${colors.reset}`);

package/bin/merlin-cli.cjs

@@ -363,6 +363,8 @@ Usage:
   merlin brief              Get project overview
   merlin rules              Get coding rules
   merlin files <purpose>    Find files by purpose
+  merlin analytics [cmd]   View session analytics (summary|compare|upload|clean)
+  merlin agents [cmd]      Manage agents (sync|list|info <name>)
 
 Environment:
   MERLIN_API_KEY            Your merlin.build API key
@@ -405,6 +407,30 @@ async function main() {
     case 'status':
       await status();
       break;
+    case 'analytics': {
+      const analyticsScript = path.join(process.env.HOME || '', '.claude', 'merlin', 'analytics.sh');
+      if (!fs.existsSync(analyticsScript)) {
+        console.error('Analytics not installed. Run: npx create-merlin-brain');
+        process.exit(1);
+      }
+      const analyticsArgs = args.slice(1).map(a => `"${a}"`).join(' ');
+      try {
+        execSync(`bash "${analyticsScript}" ${analyticsArgs}`, { stdio: 'inherit' });
+      } catch { process.exit(1); }
+      break;
+    }
+    case 'agents': {
+      const agentsSyncScript = path.join(process.env.HOME || '', '.claude', 'merlin', 'agents-sync.sh');
+      if (!fs.existsSync(agentsSyncScript)) {
+        console.error('Agents sync not installed. Run: npx create-merlin-brain');
+        process.exit(1);
+      }
+      const agentsArgs = args.slice(1).map(a => `"${a}"`).join(' ');
+      try {
+        execSync(`bash "${agentsSyncScript}" ${agentsArgs}`, { stdio: 'inherit' });
+      } catch { process.exit(1); }
+      break;
+    }
     case 'help':
     case '--help':
     case '-h':

package/files/agents/code-organization-supervisor.md

@@ -3,6 +3,7 @@ name: code-organization-supervisor
 description: Use this agent when you need to ensure code quality standards are maintained, specifically monitoring file sizes and project organization. This agent should be used proactively after code is written or modified to check for files exceeding 400 lines, after creating new files to ensure proper folder structure, when the codebase needs reorganization, or when you suspect files have grown too large. Examples:\n\n<example>\nContext: The user has just finished implementing a large feature that added significant code to a file.\nuser: "Add user authentication with login, registration, password reset, and session management"\nassistant: "I've implemented the authentication system. Here's what was added:"\n<implementation details>\nassistant: "Now let me use the code-organization-supervisor agent to check if any files have exceeded the 400-line limit and ensure the code is properly organized."\n<commentary>\nSince significant code was just added, use the code-organization-supervisor agent to verify file sizes and organization standards are maintained.\n</commentary>\n</example>\n\n<example>\nContext: The user is working on a growing project and wants to ensure code organization standards.\nuser: "Can you check if our codebase is well organized?"\nassistant: "I'll use the code-organization-supervisor agent to analyze the codebase structure and file sizes."\n<commentary>\nThe user is explicitly asking about code organization, so use the code-organization-supervisor agent to perform a comprehensive review.\n</commentary>\n</example>\n\n<example>\nContext: After multiple development sessions, the codebase may have accumulated large files.\nuser: "I've been coding for a while, let's make sure everything is clean"\nassistant: "I'll launch the code-organization-supervisor agent to review the codebase for any files exceeding 400 lines and verify the folder structure is logical and maintainable."\n<commentary>\nProactive maintenance request - use the code-organization-supervisor agent to audit and refactor as needed.\n</commentary>\n</example>
 model: haiku
 color: blue
+version: "1.0.0"
 ---
 
 You are an elite Code Organization Supervisor with deep expertise in software architecture, clean code principles, and maintainable project structures. Your primary mission is to ensure codebases remain organized, readable, and maintainable by enforcing strict file size limits and logical folder hierarchies.

package/files/agents/context-guardian.md

@@ -4,6 +4,7 @@ description: Use this agent when starting new development work, before implement
 tools: Glob, Grep, Read, WebFetch, TodoWrite, WebSearch
 model: haiku
 color: green
+version: "1.0.0"
 ---
 
 You are the Context Guardian, an expert project analyst and architectural advisor whose mission is to ensure developers have complete contextual awareness before writing any code. Your role is critical in preventing code duplication, maintaining architectural consistency, and maximizing reuse of existing functionality.

package/files/agents/docs-keeper.md

@@ -2,7 +2,8 @@
 name: docs-keeper
 description: Keeps claude.md documentation files up to date for each service or folder so AI agents always know what lives where and what does what.
 model: sonnet
-Color: green
+color: green
+version: "1.0.0"
 ---
 
 You are the Documentation Keeper for a vibe coded system.

package/files/agents/dry-refactor.md

@@ -2,7 +2,8 @@
 name: dry-refactor
 description: Keeps the codebase DRY, small, and maintainable by finding duplication, enforcing file size limits, and improving project structure.
 model: sonnet
-Color: purple
+color: purple
+version: "1.0.0"
 ---
 
 You are an elite Code Organization and DRY Supervisor with deep expertise in software architecture, clean code principles, and maintainable project structures.

package/files/agents/elite-code-refactorer.md

@@ -3,6 +3,7 @@ name: elite-code-refactorer
 description: "Use this agent when you need to transform existing code into production-grade, enterprise-quality software. This includes when you want to: refactor a module or service to eliminate technical debt, ensure code is free from memory leaks and race conditions, restructure files exceeding 400 lines into well-organized smaller units, optimize a specific service's architecture before deployment, prepare code for production release with professional-grade standards, or when you need a thorough line-by-line code review with actionable improvements. This agent works best when focused on a single service or module at a time.\\n\\n<example>\\nContext: The user has completed implementing a new authentication service and wants it production-ready.\\nuser: \"I just finished the auth service, can you make sure it's production ready?\"\\nassistant: \"I'll use the elite-code-refactorer agent to perform a comprehensive refactoring pass on your authentication service, ensuring it meets production-grade standards.\"\\n<commentary>\\nSince the user wants production-ready code for a specific service, spawn the elite-code-refactorer agent via fresh process to perform deep analysis and refactoring of the auth service.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user notices a file has grown too large during development.\\nuser: \"The UserService.ts file is getting pretty big, probably needs some cleanup\"\\nassistant: \"I'll launch the elite-code-refactorer agent to analyze UserService.ts and restructure it into a well-organized, maintainable architecture.\"\\n<commentary>\\nSince the user mentioned a file that likely exceeds size limits and needs cleanup, spawn the elite-code-refactorer agent via fresh process to break it down and optimize the structure.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user is concerned about potential issues in their data processing module.\\nuser: \"Can you check the data-processor module for any potential issues? It handles concurrent requests.\"\\nassistant: \"I'll use the elite-code-refactorer agent to perform a deep analysis of your data-processor module, specifically looking for race conditions, memory leaks, and concurrency issues.\"\\n<commentary>\\nSince the user mentioned concurrent request handling which could have race conditions, spawn the elite-code-refactorer agent via fresh process to thoroughly audit and refactor the module.\\n</commentary>\\n</example>"
 model: opus
 color: green
+version: "1.0.0"
 ---
 
 You are the Elite Code Refactorer—the most senior, meticulous, and uncompromising software architect on any engineering team. You possess deep expertise across the entire stack: backend systems, frontend applications, databases, APIs, and infrastructure. Your singular mission is to transform functional code into flawless, production-grade software that exemplifies engineering excellence.

package/files/agents/hardening-guard.md

@@ -2,7 +2,8 @@
 name: hardening-guard
 description: Reviews features for security, error handling, validation, and reliability to make them safer for real users and production use.
 model: sonnet
-Color: green
+color: green
+version: "1.0.0"
 ---
 
 You are the Hardening Guard.

package/files/agents/implementation-dev.md

@@ -2,7 +2,8 @@
 name: implementation-dev
 description: Implements features and changes across the codebase, following the architecture and reusing existing code whenever possible.
 model: sonnet
-Color: blue
+color: blue
+version: "1.0.0"
 ---
 
 You are the primary implementation developer working with a strong product minded vibe coder.

package/files/agents/merlin-api-designer.md

@@ -3,6 +3,7 @@ name: merlin-api-designer
 description: Designs clean, consistent REST and GraphQL APIs with proper documentation, versioning, and error handling.
 tools: Read, Write, Grep, Glob
 color: blue
+version: "1.0.0"
 ---
 
 <role>

package/files/agents/merlin-codebase-mapper.md

@@ -3,6 +3,7 @@ name: merlin-codebase-mapper
 description: Explores codebase and writes structured analysis documents. Spawned by map-codebase with a focus area (tech, arch, quality, concerns). Writes documents directly to reduce orchestrator context load.
 tools: Read, Bash, Grep, Glob, Write
 color: cyan
+version: "1.0.0"
 ---
 
 <role>

package/files/agents/merlin-debugger.md

@@ -3,6 +3,7 @@ name: merlin-debugger
 description: Investigates bugs using scientific method, manages debug sessions, handles checkpoints. Spawned by /merlin:debug orchestrator.
 tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch
 color: orange
+version: "1.0.0"
 ---
 
 <role>

package/files/agents/merlin-executor.md

@@ -3,6 +3,7 @@ name: merlin-executor
 description: Executes Merlin plans with atomic commits, deviation handling, checkpoint protocols, and state management. Spawned by execute-phase orchestrator or execute-plan command.
 tools: Read, Write, Edit, Bash, Grep, Glob
 color: yellow
+version: "1.0.0"
 ---
 
 <role>

package/files/agents/merlin-frontend.md

@@ -3,6 +3,7 @@ name: merlin-frontend
 description: Frontend specialist for React, Vue, and modern web development with focus on patterns, state management, and accessibility.
 tools: Read, Write, Grep, Glob, Bash
 color: cyan
+version: "1.0.0"
 ---
 
 <role>

package/files/agents/merlin-integration-checker.md

@@ -3,6 +3,7 @@ name: merlin-integration-checker
 description: Verifies cross-phase integration and E2E flows. Checks that phases connect properly and user workflows complete end-to-end.
 tools: Read, Bash, Grep, Glob
 color: blue
+version: "1.0.0"
 ---
 
 <role>

package/files/agents/merlin-migrator.md

@@ -3,6 +3,7 @@ name: merlin-migrator
 description: Plans and executes safe database schema migrations with rollback strategies and zero-downtime approaches.
 tools: Read, Write, Bash, Grep, Glob
 color: yellow
+version: "1.0.0"
 ---
 
 <role>

package/files/agents/merlin-milestone-auditor.md

@@ -3,6 +3,7 @@ name: merlin-milestone-auditor
 description: Orchestrates milestone-level verification. Spawns phase verifiers in parallel, runs integration checks, aggregates into MILESTONE-AUDIT.md.
 tools: Read, Bash, Grep, Glob, Task
 color: blue
+version: "1.0.0"
 ---
 
 <role>

package/files/agents/merlin-performance.md

@@ -3,6 +3,7 @@ name: merlin-performance
 description: Analyzes code for performance issues and provides optimization recommendations with benchmarking guidance.
 tools: Read, Grep, Glob, Bash
 color: red
+version: "1.0.0"
 ---
 
 <role>

package/files/agents/merlin-planner.md

@@ -3,6 +3,8 @@ name: merlin-planner
 description: Creates executable phase plans (PLAN.md files) with discovery, dependency graphs, and wave-based parallelization. Spawned by /merlin:plan-phase command.
 tools: Read, Write, Bash, Grep, Glob, AskUserQuestion, WebFetch, mcp__context7__*, mcp__merlin__merlin_get_context, mcp__merlin__merlin_search, mcp__merlin__merlin_find_files
 color: blue
+version: "1.0.0"
+disallowedTools: [Edit, Write, NotebookEdit, Bash]
 ---
 
 <role>

package/files/agents/merlin-researcher.md

@@ -3,6 +3,7 @@ name: merlin-researcher
 description: Conducts comprehensive research using systematic methodology, source verification, and structured output. Spawned by /merlin:research-phase and /merlin:research-project orchestrators.
 tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
 color: cyan
+version: "1.0.0"
 ---
 
 <role>

package/files/agents/merlin-reviewer.md

@@ -3,6 +3,8 @@ name: merlin-reviewer
 description: Conducts thorough code reviews with actionable feedback on quality, patterns, security, and maintainability.
 tools: Read, Grep, Glob, Bash
 color: orange
+version: "1.0.0"
+disallowedTools: [Edit, Write, NotebookEdit]
 ---
 
 <role>

package/files/agents/merlin-security.md

@@ -3,6 +3,8 @@ name: merlin-security
 description: Conducts deep security audits with OWASP awareness, threat modeling, and penetration testing mindset.
 tools: Read, Grep, Glob, Bash
 color: red
+version: "1.0.0"
+disallowedTools: [Edit, Write, NotebookEdit]
 ---
 
 <role>

package/files/agents/merlin-verifier.md

@@ -3,6 +3,8 @@ name: merlin-verifier
 description: Verifies phase goal achievement through goal-backward analysis. Checks codebase delivers what phase promised, not just that tasks completed. Creates VERIFICATION.md report.
 tools: Read, Bash, Grep, Glob
 color: green
+version: "1.0.0"
+disallowedTools: [Edit, Write, NotebookEdit]
 ---
 
 <role>

package/files/agents/merlin-work-verifier.md

@@ -3,6 +3,7 @@ name: merlin-work-verifier
 description: Validates built features through conversational UAT with persistent state. Spawned by /merlin:verify-work command.
 tools: Read, Bash, Grep, Glob, Edit, Write, AskUserQuestion
 color: green
+version: "1.0.0"
 ---
 
 <role>

package/files/agents/merlin.md

@@ -3,6 +3,7 @@ name: merlin
 description: The Merlin Brain - Master AI orchestrator. Routes to specialist agents, manages the full development pipeline, and uses Merlin Sights for cross-session memory.
 model: opus
 color: magenta
+version: "1.0.0"
 ---
 
 # Merlin — Master Orchestrator

package/files/agents/ops-railway.md

@@ -2,7 +2,8 @@
 name: ops-railway
 description: Manages deployment, environments, and configuration on Railway and Google Cloud in a pragmatic way.
 model: sonnet
-Color: red
+color: red
+version: "1.0.0"
 ---
 
 You are the ops and infrastructure guide focusing on Railway and Google Cloud for a small, fast moving team.

package/files/agents/orchestrator-retrofit.md

@@ -3,6 +3,7 @@ name: orchestrator-retrofit
 description: Orchestrator used to audit and improve existing projects by applying architecture, DRY, hardening, testing, and documentation standards. Supports an autonomous “GO mode” for fully automatic retrofitting.
 model: opus
 color: purple
+version: "1.0.0"
 ---
 
 You are the retrofit orchestrator for existing projects that were already built, usually through vibe coding.

package/files/agents/product-spec.md

@@ -2,7 +2,9 @@
 name: product-spec
 description: Converts raw ideas into a lean, explicit product spec and user flows tailored for vibe coding and incremental delivery.
 model: opus
-Color: white
+color: white
+version: "1.0.0"
+disallowedTools: [Edit, Write, NotebookEdit, Bash]
 ---
 
 You are a product specifier for a very strong product thinker and vibe coder.

package/files/agents/system-architect.md

@@ -2,7 +2,9 @@
 name: system-architect
 description: Designs simple, pragmatic architecture and service boundaries, avoiding over splitting while preventing tangled code.
 model: opus
-Color: Black
+color: black
+version: "1.0.0"
+disallowedTools: [Edit, Write, NotebookEdit, Bash]
 ---
 
 You are a system architect for a vibe coder who tends to create many microservices.

package/files/agents/tests-qa.md

@@ -2,7 +2,8 @@
 name: tests-qa
 description: Designs and implements lightweight but meaningful tests and manual QA flows for features and bug fixes.
 model: sonnet
-Color: yellow
+color: yellow
+version: "1.0.0"
 ---
 
 You are a tests and QA designer for a busy founder and vibe coder.

package/files/hooks/agent-sync.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Merlin Hook: Agent Sync (SessionStart, background)
+# Checks installed agents freshness and updates from cloud. Max once/hour.
+set -euo pipefail
+trap 'exit 0' ERR
+
+AGENTS_DIR="${HOME}/.claude/agents"
+MERLIN_DIR="${HOME}/.claude/merlin"
+LAST_SYNC="${MERLIN_DIR}/.last-agent-sync"
+API_URL="${MERLIN_API_URL:-https://api.merlin.build}"
+
+[ -d "${AGENTS_DIR}" ] || exit 0
+
+# Skip if synced within the last hour
+if [ -f "${LAST_SYNC}" ]; then
+  last=$(cat "${LAST_SYNC}" 2>/dev/null || echo "0")
+  [ $(($(date +%s) - last)) -lt 3600 ] && exit 0
+fi
+
+sync_agents() {
+  local installed=""
+  for f in "${AGENTS_DIR}"/*.md; do
+    [ -f "${f}" ] || continue
+    local name hash
+    name=$(basename "${f}" .md)
+    hash=$(md5sum "${f}" 2>/dev/null | cut -c1-8 || md5 -q "${f}" 2>/dev/null | cut -c1-8 || echo "unknown")
+    installed="${installed}${name}:${hash},"
+  done
+  local response
+  response=$(curl -s --max-time 5 "${API_URL}/api/agents-sync/check?installed=${installed}" 2>/dev/null) || return 0
+  local stale_names
+  stale_names=$(echo "${response}" | grep -o '"name":"[^"]*"' | sed 's/"name":"//;s/"//' 2>/dev/null) || return 0
+  [ -z "${stale_names}" ] && { date +%s > "${LAST_SYNC}"; return 0; }
+  for agent_name in ${stale_names}; do
+    local content md_content
+    content=$(curl -s --max-time 5 "${API_URL}/api/agents-sync/${agent_name}" 2>/dev/null) || continue
+    md_content=$(echo "${content}" | python3 -c "import sys,json;print(json.load(sys.stdin).get('content',''))" 2>/dev/null) || continue
+    [ -n "${md_content}" ] && echo "${md_content}" > "${AGENTS_DIR}/${agent_name}.md"
+  done
+  date +%s > "${LAST_SYNC}"
+}
+
+sync_agents &
+exit 0