create-merlin-brain 3.22.0 → 4.0.0

package/bin/runtime-adapters.cjs

@@ -8,7 +8,6 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
-
 // ---------------------------------------------------------------------------
 // Runtime definitions
 // ---------------------------------------------------------------------------
@@ -65,11 +64,178 @@ function buildMcpCommand(useGlobalBinary) {
   return { command: 'node', args: [path.join(__dirname, 'serve.js')] };
 }
 
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function writeFile(filePath, content) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, content);
+}
+
+function tomlMultiline(text) {
+  return "'''\n" + text.replace(/'''/g, "'''\" + \"'\" + '''") + "\n'''";
+}
+
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function ensureTomlSectionLine(content, sectionName, line) {
+  const key = line.split('=')[0].trim();
+  const sectionRegex = new RegExp(`(^\\[${escapeRegex(sectionName)}\\]\\n)([\\s\\S]*?)(?=^\\[|$)`, 'm');
+  if (sectionRegex.test(content)) {
+    return content.replace(sectionRegex, (match, start, body) => {
+      const keyRegex = new RegExp(`^${escapeRegex(key)}\\s*=.*$`, 'm');
+      let nextBody = body.replace(keyRegex, line);
+      if (!keyRegex.test(body)) {
+        const trimmedBody = body.replace(/\s+$/, '');
+        nextBody = `${trimmedBody ? `${trimmedBody}\n` : ''}${line}\n`;
+      }
+      const trimmedBody = nextBody.replace(/\s+$/, '');
+      return `${start}${trimmedBody ? `${trimmedBody}\n` : ''}`;
+    });
+  }
+
+  const prefix = content.trimEnd();
+  return `${prefix}${prefix ? '\n\n' : ''}[${sectionName}]\n${line}\n`;
+}
+
+function upsertTomlSection(content, sectionName, sectionBody) {
+  const sectionRegex = new RegExp(`^\\[${escapeRegex(sectionName)}\\]\\n[\\s\\S]*?(?=^\\[|$)`, 'm');
+  const next = content.replace(sectionRegex, '').trimEnd();
+  return `${next}${next ? '\n\n' : ''}[${sectionName}]\n${sectionBody.trim()}\n`;
+}
+
+function removeTomlSection(content, sectionName) {
+  const sectionRegex = new RegExp(`^\\[${escapeRegex(sectionName)}\\]\\n[\\s\\S]*?(?=^\\[|$)`, 'm');
+  return content.replace(sectionRegex, '').trimEnd();
+}
+
+function ensureTomlTopLevelLine(content, line) {
+  const key = line.split('=')[0].trim();
+  const lines = content.split('\n');
+  const keyRegex = new RegExp(`^${escapeRegex(key)}\\s*=.*$`);
+  const existingIndex = lines.findIndex((current) => keyRegex.test(current.trim()));
+  if (existingIndex !== -1) {
+    lines[existingIndex] = line;
+    return lines.join('\n');
+  }
+
+  let insertAt = 0;
+  while (insertAt < lines.length && lines[insertAt].trim() === '') insertAt++;
+  if (insertAt < lines.length && !lines[insertAt].startsWith('[')) {
+    while (insertAt < lines.length && lines[insertAt].trim() !== '') insertAt++;
+  }
+
+  const next = [...lines];
+  next.splice(insertAt, 0, line);
+  return next.join('\n');
+}
+
+function mergeHooksJson(existingContent, hooksRoot) {
+  const nextConfig = JSON.parse(buildCodexHooksJson(hooksRoot));
+  let base = { hooks: {} };
+
+  if (existingContent && existingContent.trim()) {
+    try {
+      base = JSON.parse(existingContent);
+    } catch {
+      base = { hooks: {} };
+    }
+  }
+
+  base.hooks = base.hooks || {};
+  for (const [eventName, entries] of Object.entries(nextConfig.hooks)) {
+    base.hooks[eventName] = base.hooks[eventName] || [];
+    for (const entry of entries) {
+      const cmd = entry.hooks?.[0]?.command;
+      const exists = base.hooks[eventName].some((existing) =>
+        existing?.hooks?.some((hook) => hook.command === cmd)
+      );
+      if (!exists) {
+        base.hooks[eventName].push(entry);
+      }
+    }
+  }
+
+  return JSON.stringify(base, null, 2) + '\n';
+}
+
 // ---------------------------------------------------------------------------
-// AGENTS.md content for instruction-file runtimes
+// Instruction file content for non-Claude runtimes
 // ---------------------------------------------------------------------------
 
-function buildAgentsMd() {
+function buildInstructionMd(runtime = 'generic') {
+  if (runtime === 'codex') {
+    return `# Merlin Brain — Codex Operating Layer
+
+> Installed by Merlin (https://merlin.build). Keep this file so Codex loads Merlin context automatically.
+
+## Session Boot
+
+Before doing real work in a repository:
+
+1. Call \`merlin_get_selected_repo\`.
+2. Call \`merlin_get_project_status\`.
+3. Call \`merlin_get_rules\` and \`merlin_get_brief\`.
+4. Summarize the current state, then proceed.
+
+Do not skip boot. Do not start editing code without Merlin context.
+
+## Discoverability
+
+- If the user asks what Merlin can do, call \`merlin_help\`.
+- If the best Merlin path is unclear, call \`merlin_help(task)\`.
+- For new features or integrations, call \`merlin_recommend_for_task(task)\` before building from scratch.
+- For agent selection, call \`merlin_smart_route(task)\`.
+- For reusable prompt packs, call \`merlin_find_skill(query)\`.
+
+## Codex + Merlin Workflow
+
+- For codebase questions, start with \`merlin_search("query")\` or \`merlin_get_context("task")\`.
+- Before every code edit, call \`merlin_get_context("your task")\`.
+- Let Merlin choose the route first when helpful: tool vs skill vs custom agent vs direct execution.
+- When local file search is still needed, prefer fast repo-native tools such as \`rg\`.
+- Use Codex's normal execution style: inspect first, edit surgically, verify after changes.
+- Keep progress updates concise and factual while work is in flight.
+- Prefer Merlin skills and custom agents installed in this repo when the task matches them.
+
+## Editing Discipline
+
+- Prefer \`apply_patch\` for manual edits.
+- Avoid broad rewrites when a narrow patch is sufficient.
+- Preserve user changes you did not make.
+- Verify behavior after implementation work before claiming completion.
+
+## Delegation
+
+- Use Merlin tools first for routing and context.
+- Use Codex sub-agents only for clearly bounded side tasks that can run in parallel.
+- Keep the critical path local when the next step depends on immediate code understanding.
+
+## MCP Tools Available
+
+- \`merlin_get_selected_repo\` — identify the active repository
+- \`merlin_get_project_status\` — load project state and active tasks
+- \`merlin_help(task?)\` — explain Merlin capabilities and recommend the best route
+- \`merlin_get_context(task)\` — fetch targeted implementation context
+- \`merlin_find_files(query)\` — locate files by purpose
+- \`merlin_search(query)\` — semantic code search
+- \`merlin_find_skill(query)\` — find reusable Merlin skills
+- \`merlin_smart_route(task)\` — choose the best specialist agent
+- \`merlin_recommend_for_task(task)\` — find agents and reference codebases before building
+
+## Defaults
+
+- Search before writing.
+- Reuse existing patterns before introducing new ones.
+- If Merlin Sights is unavailable, continue with disciplined local exploration instead of blocking.
+`;
+  }
+
   return `# Merlin Brain — AI Development System
 
 > Installed by Merlin (https://merlin.build). Keep this file to preserve Merlin context.
@@ -115,6 +281,443 @@ The Merlin MCP server exposes these tools:
 `;
 }
 
+function buildCodexHooksJson(hooksRoot) {
+  return JSON.stringify({
+    hooks: {
+      SessionStart: [
+        {
+          matcher: 'startup|resume',
+          hooks: [
+            {
+              type: 'command',
+              command: `bash "${path.join(hooksRoot, 'session-start.sh')}"`,
+              statusMessage: 'Merlin booting',
+            },
+          ],
+        },
+      ],
+      UserPromptSubmit: [
+        {
+          hooks: [
+            {
+              type: 'command',
+              command: `bash "${path.join(hooksRoot, 'user-prompt-router.sh')}"`,
+              statusMessage: 'Merlin routing',
+            },
+          ],
+        },
+      ],
+      PreToolUse: [
+        {
+          matcher: 'Bash',
+          hooks: [
+            {
+              type: 'command',
+              command: `bash "${path.join(hooksRoot, 'bash-pre-tool.sh')}"`,
+              statusMessage: 'Merlin command guard',
+            },
+          ],
+        },
+      ],
+      PostToolUse: [
+        {
+          matcher: 'Bash',
+          hooks: [
+            {
+              type: 'command',
+              command: `bash "${path.join(hooksRoot, 'bash-post-tool.sh')}"`,
+              statusMessage: 'Merlin command review',
+            },
+          ],
+        },
+      ],
+      Stop: [
+        {
+          hooks: [
+            {
+              type: 'command',
+              command: `bash "${path.join(hooksRoot, 'stop.sh')}"`,
+              statusMessage: 'Merlin wrap-up',
+            },
+          ],
+        },
+      ],
+    },
+  }, null, 2) + '\n';
+}
+
+function buildCodexSessionStartHook() {
+  return `#!/usr/bin/env bash
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+MERLIN_HOME="\${HOME}/.codex/merlin"
+mkdir -p "\${MERLIN_HOME}/analytics" "\${MERLIN_HOME}/sessions" 2>/dev/null || true
+
+_context="MERLIN MODE ACTIVE. Before handling the user request, call merlin_get_selected_repo, then merlin_get_project_status, then merlin_get_rules and merlin_get_brief."
+_context="\${_context} Use Merlin context before edits: call merlin_get_context(task)."
+_context="\${_context} If the best Merlin path is unclear, call merlin_help(task) before acting."
+_context="\${_context} For task routing, prefer merlin_smart_route(task), merlin_find_skill(query), and merlin_recommend_for_task(task) over improvising."
+_context="\${_context} Prefer Merlin skills and custom agents installed in this repository when they match the task."
+_context="\${_context} Keep the Codex experience pragmatic: inspect first, patch surgically, verify before claiming completion."
+_context="\${_context} Prefix visible progress updates with the Merlin badge when practical: ⟡🔮 MERLIN ›"
+
+printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\\n' "\${_context//\"/\\\\\"}"
+`;
+}
+
+function buildCodexUserPromptRouterHook() {
+  return `#!/usr/bin/env bash
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+input=""
+if [ ! -t 0 ]; then
+  input=$(cat 2>/dev/null || true)
+fi
+
+[ -z "$input" ] && echo "{}" && exit 0
+
+prompt=""
+if command -v jq >/dev/null 2>&1; then
+  prompt=$(echo "$input" | jq -r '.prompt // .userPrompt // empty' 2>/dev/null || true)
+else
+  prompt=$(echo "$input" | sed 's/.*"prompt"[[:space:]]*:[[:space:]]*"\\(.*\\)".*/\\1/' 2>/dev/null || true)
+fi
+
+[ -z "$prompt" ] && echo "{}" && exit 0
+
+clean=$(printf '%s' "$prompt" | sed -E -e 's/<[^>]+>//g' -e 's|https?://[^ ]*||g' -e 's|/[a-zA-Z0-9._/-]+||g' -e 's/\`[^\`]*\`//g')
+
+suggestion=""
+if echo "$clean" | grep -qiE "what can merlin do|how do i use merlin|what is available|available skills|available agents|available tools|help me use merlin"; then
+  suggestion='Merlin routing: call merlin_help first, then pick the recommended tool, skill, or agent path.'
+elif echo "$clean" | grep -qiE "resume|pick up|continue|where were we"; then
+  suggestion='Merlin routing: call merlin_get_project_status, then use the merlin-resume skill.'
+elif echo "$clean" | grep -qiE "progress|status|where are we|how far"; then
+  suggestion='Merlin routing: call merlin_get_project_status, then use the merlin-progress skill.'
+elif echo "$clean" | grep -qiE "map codebase|understand this repo|learn this codebase|explore the architecture"; then
+  suggestion='Merlin routing: call merlin_search and merlin_get_context, then use the merlin-map-codebase skill before implementation.'
+elif echo "$clean" | grep -qiE "bug|crash|error|not working|fix|failing|exception"; then
+  suggestion='Merlin routing: call merlin_get_context for the bug, then merlin_smart_route(task), then use merlin-verify after the fix.'
+elif echo "$clean" | grep -qiE "refactor|cleanup|clean up|dry|restructure"; then
+  suggestion='Merlin routing: call merlin_get_context first, keep scope narrow, and use merlin-workflow plus merlin-verify.'
+elif echo "$clean" | grep -qiE "oauth|auth|stripe|prisma|sdk|integration|api|graphql|railway|deploy"; then
+  suggestion='Merlin routing: call merlin_recommend_for_task(task), merlin_find_skill(query), and merlin_smart_route(task) before building.'
+elif echo "$clean" | grep -qiE "build|add|create|implement|new feature|develop"; then
+  suggestion='Merlin routing: call merlin_help(task) or merlin_smart_route(task), gather Merlin context, then execute with implementation-focused agents.'
+fi
+
+[ -z "$suggestion" ] && echo "{}" && exit 0
+
+printf '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"%s"}}\\n' "\${suggestion//\"/\\\\\"}"
+`;
+}
+
+function buildCodexBashPreToolHook() {
+  return `#!/usr/bin/env bash
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+input=""
+if [ ! -t 0 ]; then
+  input=$(cat 2>/dev/null || true)
+fi
+
+[ -z "$input" ] && echo "{}" && exit 0
+
+command_str=""
+if command -v jq >/dev/null 2>&1; then
+  command_str=$(echo "$input" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
+else
+  command_str=$(echo "$input" | grep -o '"command":"[^"]*"' | head -1 | cut -d'"' -f4 || true)
+fi
+
+[ -z "$command_str" ] && echo "{}" && exit 0
+
+block() {
+  printf '{"decision":"block","reason":"%s"}\\n' "$1"
+  exit 2
+}
+
+if echo "$command_str" | grep -qE '(curl|wget)\\s[^|]*\\|\\s*(bash|sh|zsh|python|ruby|perl)\\b' 2>/dev/null; then
+  block "Merlin blocked pipe-to-shell execution."
+fi
+if echo "$command_str" | grep -qE '(^|\\s|;|&&|\\|\\|)(sudo|su)\\s' 2>/dev/null; then
+  block "Merlin blocked privilege escalation."
+fi
+if echo "$command_str" | grep -qE 'git\\s+reset\\s+.*--hard|git\\s+clean\\s+.*-[a-z]*f|git\\s+push\\s+.*--force' 2>/dev/null; then
+  block "Merlin blocked a destructive git command."
+fi
+if echo "$command_str" | grep -qE '\\brm\\s+(-[a-z]*r[a-z]*f|-rf|-fr|--recursive)' 2>/dev/null; then
+  block "Merlin blocked a destructive rm command."
+fi
+if echo "$command_str" | grep -qE 'AKIA[0-9A-Z]{16}|sk-[A-Za-z0-9_-]{40,}|-----BEGIN (RSA|EC|DSA|OPENSSH|PRIVATE) KEY-----' 2>/dev/null; then
+  block "Merlin blocked a command containing a secret or private key."
+fi
+
+echo '{}'
+`;
+}
+
+function buildCodexBashPostToolHook() {
+  return `#!/usr/bin/env bash
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+input=""
+if [ ! -t 0 ]; then
+  input=$(cat 2>/dev/null || true)
+fi
+
+[ -z "$input" ] && echo "{}" && exit 0
+
+if command -v jq >/dev/null 2>&1; then
+  cmd=$(echo "$input" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
+else
+  cmd=""
+fi
+
+if echo "$cmd" | grep -qiE 'npm test|pnpm test|yarn test|vitest|pytest|cargo test|go test'; then
+  printf '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"Merlin note: summarize whether verification passed before moving on."}}\\n'
+  exit 0
+fi
+
+echo '{}'
+`;
+}
+
+function buildCodexStopHook() {
+  return `#!/usr/bin/env bash
+set -euo pipefail
+trap 'echo "{}"; exit 0' ERR
+
+MERLIN_HOME="\${HOME}/.codex/merlin"
+mkdir -p "\${MERLIN_HOME}/sessions" 2>/dev/null || true
+
+if command -v jq >/dev/null 2>&1; then
+  ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  jq -n --arg ts "$ts" '{ timestamp: $ts }' > "\${MERLIN_HOME}/sessions/session-$(date +%s).json" 2>/dev/null || true
+fi
+
+echo '{}'
+`;
+}
+
+function installCodexHookScripts(codexDir) {
+  const hooksRoot = path.join(codexDir, 'merlin', 'hooks');
+  const scripts = {
+    'session-start.sh': buildCodexSessionStartHook(),
+    'user-prompt-router.sh': buildCodexUserPromptRouterHook(),
+    'bash-pre-tool.sh': buildCodexBashPreToolHook(),
+    'bash-post-tool.sh': buildCodexBashPostToolHook(),
+    'stop.sh': buildCodexStopHook(),
+  };
+
+  ensureDir(hooksRoot);
+  for (const [name, content] of Object.entries(scripts)) {
+    const target = path.join(hooksRoot, name);
+    writeFile(target, content);
+    fs.chmodSync(target, '755');
+  }
+
+  return hooksRoot;
+}
+
+function buildCodexAgentSpecs() {
+  return [
+    {
+      filename: 'implementation-dev.toml',
+      name: 'implementation_dev',
+      description: 'Implementation specialist for bounded code changes with verification.',
+      model: 'gpt-5.4',
+      effort: 'medium',
+      sandbox: 'workspace-write',
+      nicknames: ['Forge', 'Patch', 'Build'],
+      instructions: 'Implement the requested change with minimal surface area. Inspect existing patterns first, preserve unrelated user edits, and verify behavior before handing back results.',
+    },
+    {
+      filename: 'tests-qa.toml',
+      name: 'tests_qa',
+      description: 'Testing specialist focused on regressions, missing cases, and verification.',
+      model: 'gpt-5.4-mini',
+      effort: 'medium',
+      sandbox: 'workspace-write',
+      nicknames: ['Spec', 'Check', 'Proof'],
+      instructions: 'Focus on tests, reproducibility, and verification evidence. Add or improve tests when justified, and report concrete coverage gaps when testing is blocked.',
+    },
+    {
+      filename: 'system-architect.toml',
+      name: 'system_architect',
+      description: 'Architecture specialist for design tradeoffs and decomposition.',
+      model: 'gpt-5.4',
+      effort: 'high',
+      sandbox: 'read-only',
+      nicknames: ['Northstar', 'Grid', 'Frame'],
+      instructions: 'Stay at the design layer unless explicitly asked to patch code. Map dependencies, tradeoffs, and sequencing clearly. Prefer the simplest architecture that satisfies the real constraints.',
+    },
+    {
+      filename: 'docs-keeper.toml',
+      name: 'docs_keeper',
+      description: 'Documentation specialist for READMEs, usage guides, and project docs.',
+      model: 'gpt-5.4-mini',
+      effort: 'medium',
+      sandbox: 'workspace-write',
+      nicknames: ['Ledger', 'Script', 'Index'],
+      instructions: 'Update documentation to match the actual implementation. Prefer concise, accurate edits tied to real behavior and verified paths.',
+    },
+    {
+      filename: 'hardening-guard.toml',
+      name: 'hardening_guard',
+      description: 'Security and resilience reviewer for edge cases and failure handling.',
+      model: 'gpt-5.4',
+      effort: 'high',
+      sandbox: 'read-only',
+      nicknames: ['Shield', 'Gate', 'Sentinel'],
+      instructions: 'Review for security issues, data loss, unsafe command usage, auth gaps, and weak failure handling. Lead with concrete risks and mitigations.',
+    },
+    {
+      filename: 'merlin-codebase-mapper.toml',
+      name: 'merlin_codebase_mapper',
+      description: 'Read-only codebase mapper for architecture, flows, and key files.',
+      model: 'gpt-5.4-mini',
+      effort: 'medium',
+      sandbox: 'read-only',
+      nicknames: ['Scout', 'Atlas', 'Survey'],
+      instructions: 'Map the relevant code paths, file ownership, and architectural seams before implementation. Prefer precise citations over broad summaries.',
+    },
+    {
+      filename: 'merlin-researcher.toml',
+      name: 'merlin_researcher',
+      description: 'Research specialist for external docs and fast-moving technical questions.',
+      model: 'gpt-5.4-mini',
+      effort: 'medium',
+      sandbox: 'read-only',
+      nicknames: ['Query', 'Lens', 'Signal'],
+      instructions: 'Use primary sources when research is needed. Distinguish verified facts from inference and return concise findings with citations.',
+    },
+    {
+      filename: 'merlin-verifier.toml',
+      name: 'merlin_verifier',
+      description: 'Verification specialist for validation, behavior checks, and release confidence.',
+      model: 'gpt-5.4-mini',
+      effort: 'medium',
+      sandbox: 'workspace-write',
+      nicknames: ['Audit', 'Pulse', 'Trace'],
+      instructions: 'Verify the requested outcome rather than merely restating changes. Prefer direct evidence from tests, builds, or code paths, and call out residual risks clearly.',
+    },
+  ];
+}
+
+function installCodexAgents(projectDir) {
+  const agentsDir = path.join(projectDir, '.codex', 'agents');
+  ensureDir(agentsDir);
+  const created = [];
+
+  for (const spec of buildCodexAgentSpecs()) {
+    const content = [
+      `name = "${spec.name}"`,
+      `description = "${spec.description}"`,
+      `model = "${spec.model}"`,
+      `model_reasoning_effort = "${spec.effort}"`,
+      `sandbox_mode = "${spec.sandbox}"`,
+      `nickname_candidates = [${spec.nicknames.map((n) => `"${n}"`).join(', ')}]`,
+      `developer_instructions = ${tomlMultiline(spec.instructions)}`,
+      '',
+    ].join('\n');
+    writeFile(path.join(agentsDir, spec.filename), content);
+    created.push(path.join(agentsDir, spec.filename));
+  }
+
+  return created;
+}
+
+function buildCodexSkillSpecs() {
+  return [
+    {
+      dir: 'merlin-discover',
+      content: `---
+name: merlin-discover
+description: Use when the user asks what Merlin can do, which Merlin features are available, or which Merlin path should be used for a task in Codex.
+---
+
+Start with \`merlin_help\`.
+If the user also has a concrete task, call \`merlin_help(task)\`.
+Then choose the recommended route: direct Merlin tools, a Merlin skill, a custom Codex agent, or local execution.
+Do not assume the user already knows internal Merlin names.`,
+    },
+    {
+      dir: 'merlin-map-codebase',
+      content: `---
+name: merlin-map-codebase
+description: Use when the user wants to understand a repository, onboard to a codebase, or map architecture before implementing changes.
+---
+
+Before making architectural claims, call \`merlin_get_selected_repo\` and \`merlin_get_project_status\`.
+Then use \`merlin_search\` and \`merlin_get_context\` to identify the core files, flows, and conventions relevant to the request.
+When the task is large, prefer the \`merlin_codebase_mapper\` custom agent for bounded exploration.`,
+    },
+    {
+      dir: 'merlin-progress',
+      content: `---
+name: merlin-progress
+description: Use when the user asks for current status, progress, next steps, or where work left off in the repository.
+---
+
+Call \`merlin_get_project_status\` first.
+Summarize the current state, active tasks, and recommended next step.
+If local planning files exist, reconcile them with Merlin status instead of trusting either source blindly.`,
+    },
+    {
+      dir: 'merlin-resume',
+      content: `---
+name: merlin-resume
+description: Use when the user is returning to a project and wants to continue, resume, or recover context quickly.
+---
+
+Boot with Merlin tools first, then reconstruct the current state from project status, local planning files, and recent git changes.
+Prefer concise orientation: what was in progress, what is blocked, and the most reasonable next action.`,
+    },
+    {
+      dir: 'merlin-workflow',
+      content: `---
+name: merlin-workflow
+description: Use when the task should be decomposed into architecture, implementation, testing, docs, or verification specialists instead of one monolithic pass.
+---
+
+Use Merlin context before decomposition.
+For bounded parallel work, use the custom Codex agents installed in \`.codex/agents\`.
+Keep the critical path local when a side task would block the very next action.`,
+    },
+    {
+      dir: 'merlin-verify',
+      content: `---
+name: merlin-verify
+description: Use when implementation work is complete and you need focused validation, test review, or release confidence.
+---
+
+Prefer direct evidence over narration.
+Run or inspect the relevant verification commands, summarize what passed, what failed, and any residual risk.
+Use the \`merlin_verifier\` or \`tests_qa\` agent for bounded validation passes when parallel work helps.`,
+    },
+  ];
+}
+
+function installCodexSkills(projectDir) {
+  const skillsRoot = path.join(projectDir, '.agents', 'skills');
+  ensureDir(skillsRoot);
+  const created = [];
+
+  for (const spec of buildCodexSkillSpecs()) {
+    const skillDir = path.join(skillsRoot, spec.dir);
+    ensureDir(skillDir);
+    writeFile(path.join(skillDir, 'SKILL.md'), spec.content.trim() + '\n');
+    created.push(path.join(skillDir, 'SKILL.md'));
+  }
+
+  return created;
+}
+
 // ---------------------------------------------------------------------------
 // Codex CLI adapter
 // Writes: ~/.codex/AGENTS.md + ~/.codex/config.toml (MCP section)
@@ -130,7 +733,7 @@ function configureCodex(rt, useGlobalBinary, apiKey) {
 
   // Write AGENTS.md
   const agentsMdPath = path.join(rt.configDir, 'AGENTS.md');
-  const agentsMd = buildAgentsMd();
+  const agentsMd = buildInstructionMd('codex');
   const existingAgentsMd = fs.existsSync(agentsMdPath)
     ? fs.readFileSync(agentsMdPath, 'utf8')
     : '';
@@ -145,29 +748,62 @@ function configureCodex(rt, useGlobalBinary, apiKey) {
     results.push('Wrote ~/.codex/AGENTS.md');
   }
 
-  // Write / update config.toml with MCP section
-  const configTomlPath = path.join(rt.configDir, 'config.toml');
-  const { command, args } = buildMcpCommand(useGlobalBinary);
-  const argsToml = args
-    ? `args = [${args.map((a) => `"${a}"`).join(', ')}]`
+  // Install Codex hook scripts + hooks.json
+  const hooksRoot = installCodexHookScripts(rt.configDir);
+  const hooksJsonPath = path.join(rt.configDir, 'hooks.json');
+  const existingHooks = fs.existsSync(hooksJsonPath)
+    ? fs.readFileSync(hooksJsonPath, 'utf8')
     : '';
-  const envToml = apiKey ? `\n  MERLIN_API_KEY = "${apiKey}"` : '';
-  const mcpToml = `
-[mcp.merlin]
-command = "${command}"
-${argsToml ? argsToml + '\n' : ''}${apiKey ? `[mcp.merlin.env]${envToml}\n` : ''}`;
+  writeFile(hooksJsonPath, mergeHooksJson(existingHooks, hooksRoot));
+  results.push('Installed ~/.codex/hooks.json');
 
+  // Write / update config.toml with MCP section and Codex features
+  const configTomlPath = path.join(rt.configDir, 'config.toml');
+  const { command, args } = buildMcpCommand(useGlobalBinary);
   let tomlContent = fs.existsSync(configTomlPath)
     ? fs.readFileSync(configTomlPath, 'utf8')
     : '';
 
-  if (tomlContent.includes('[mcp.merlin]')) {
-    results.push('config.toml already has Merlin MCP (skipped)');
-  } else {
-    fs.appendFileSync(configTomlPath, mcpToml);
-    results.push('Added Merlin MCP to ~/.codex/config.toml');
+  tomlContent = removeTomlSection(removeTomlSection(tomlContent, 'mcp.merlin'), 'mcp_servers.merlin');
+  tomlContent = removeTomlSection(tomlContent, 'features');
+  tomlContent = removeTomlSection(tomlContent, 'tui');
+  tomlContent = removeTomlSection(tomlContent, 'agents');
+  tomlContent = removeTomlSection(tomlContent, 'shell_environment_policy');
+  tomlContent = tomlContent
+    .replace(/^project_doc_fallback_filenames = .*$/gm, '')
+    .replace(/^codex_hooks = .*$/gm, '')
+    .replace(/^notifications = .*$/gm, '')
+    .replace(/^max_threads = .*$/gm, '')
+    .replace(/^max_depth = .*$/gm, '')
+    .replace(/^inherit = .*$/gm, '')
+    .replace(/^startup_timeout_sec = .*$/gm, '')
+    .replace(/^tool_timeout_sec = .*$/gm, '')
+    .replace(/^command = "merlin-brain"\n?/m, '')
+    .replace(/^args = \[.*create-merlin-brain.*\]\n?/m, '')
+    .replace(/^args = \[.*packages\/create-merlin-brain\/bin\/serve\.js.*\]\n?/m, '')
+    .trimEnd();
+  tomlContent = ensureTomlSectionLine(tomlContent, 'features', 'codex_hooks = true');
+  tomlContent = ensureTomlSectionLine(tomlContent, 'tui', 'notifications = true');
+  tomlContent = ensureTomlSectionLine(tomlContent, 'agents', 'max_threads = 8');
+  tomlContent = ensureTomlSectionLine(tomlContent, 'agents', 'max_depth = 2');
+  tomlContent = ensureTomlSectionLine(tomlContent, 'shell_environment_policy', 'inherit = "all"');
+  tomlContent = ensureTomlTopLevelLine(tomlContent, 'project_doc_fallback_filenames = ["CLAUDE.md", "GEMINI.md"]');
+
+  const mcpLines = [
+    `command = "${command}"`,
+    args ? `args = [${args.map((a) => `"${a}"`).join(', ')}]` : null,
+    'startup_timeout_sec = 20',
+    'tool_timeout_sec = 120',
+  ].filter(Boolean).join('\n');
+
+  tomlContent = upsertTomlSection(tomlContent, 'mcp_servers.merlin', mcpLines);
+  if (apiKey) {
+    tomlContent = upsertTomlSection(tomlContent, 'mcp_servers.merlin.env', `MERLIN_API_KEY = "${apiKey}"`);
   }
 
+  writeFile(configTomlPath, tomlContent.trimEnd() + '\n');
+  results.push('Configured Merlin MCP and Codex features in ~/.codex/config.toml');
+
   return results;
 }
 
@@ -216,8 +852,8 @@ function configureOpenCode(rt, useGlobalBinary, apiKey) {
     results.push('AGENTS.md already has Merlin (skipped)');
   } else {
     const combined = existingAgentsMd
-      ? existingAgentsMd.trimEnd() + '\n\n---\n\n' + buildAgentsMd()
-      : buildAgentsMd();
+      ? existingAgentsMd.trimEnd() + '\n\n---\n\n' + buildInstructionMd('opencode')
+      : buildInstructionMd('opencode');
     fs.writeFileSync(agentsMdPath, combined);
     results.push('Wrote ~/.opencode/AGENTS.md');
   }
@@ -246,8 +882,8 @@ function configureGemini(rt, useGlobalBinary, apiKey) {
     results.push('GEMINI.md already has Merlin (skipped)');
   } else {
     const combined = existingGeminiMd
-      ? existingGeminiMd.trimEnd() + '\n\n---\n\n' + buildAgentsMd()
-      : buildAgentsMd();
+      ? existingGeminiMd.trimEnd() + '\n\n---\n\n' + buildInstructionMd('gemini')
+      : buildInstructionMd('gemini');
     fs.writeFileSync(geminiMdPath, combined);
     results.push('Wrote ~/.gemini/GEMINI.md');
   }
@@ -297,22 +933,67 @@ function generateProjectRuntimeFiles(projectDir, runtimeIds = ['all']) {
     ? ['codex', 'opencode', 'gemini']
     : runtimeIds;
 
-  const agentsMd = buildAgentsMd();
-
   // AGENTS.md — used by Codex and OpenCode
   if (targets.includes('codex') || targets.includes('opencode')) {
     const agentsMdPath = path.join(projectDir, 'AGENTS.md');
     if (!fs.existsSync(agentsMdPath)) {
-      fs.writeFileSync(agentsMdPath, agentsMd);
+      const instructionMd = targets.includes('codex')
+        ? buildInstructionMd('codex')
+        : buildInstructionMd('opencode');
+      fs.writeFileSync(agentsMdPath, instructionMd);
       results.push(`Created ${agentsMdPath}`);
     }
   }
 
+  if (targets.includes('codex')) {
+    const projectConfigPath = path.join(projectDir, '.codex', 'config.toml');
+    let projectConfig = fs.existsSync(projectConfigPath)
+      ? fs.readFileSync(projectConfigPath, 'utf8')
+      : '';
+    projectConfig = ensureTomlTopLevelLine(projectConfig, 'project_doc_fallback_filenames = ["CLAUDE.md", "GEMINI.md"]');
+    projectConfig = ensureTomlSectionLine(projectConfig, 'features', 'codex_hooks = true');
+    projectConfig = ensureTomlSectionLine(projectConfig, 'agents', 'max_threads = 8');
+    projectConfig = ensureTomlSectionLine(projectConfig, 'agents', 'max_depth = 2');
+    writeFile(projectConfigPath, projectConfig.trimEnd() + '\n');
+    results.push(`Created ${projectConfigPath}`);
+
+    const projectHooksRoot = path.join(projectDir, '.codex', 'merlin', 'hooks');
+    ensureDir(projectHooksRoot);
+    const hookSpecs = {
+      'session-start.sh': buildCodexSessionStartHook(),
+      'user-prompt-router.sh': buildCodexUserPromptRouterHook(),
+      'bash-pre-tool.sh': buildCodexBashPreToolHook(),
+      'bash-post-tool.sh': buildCodexBashPostToolHook(),
+      'stop.sh': buildCodexStopHook(),
+    };
+    for (const [name, content] of Object.entries(hookSpecs)) {
+      const hookPath = path.join(projectHooksRoot, name);
+      writeFile(hookPath, content);
+      fs.chmodSync(hookPath, '755');
+    }
+    const projectHooksPath = path.join(projectDir, '.codex', 'hooks.json');
+    const existingProjectHooks = fs.existsSync(projectHooksPath)
+      ? fs.readFileSync(projectHooksPath, 'utf8')
+      : '';
+    writeFile(projectHooksPath, mergeHooksJson(existingProjectHooks, projectHooksRoot));
+    results.push(`Created ${path.join(projectDir, '.codex', 'hooks.json')}`);
+
+    const createdAgents = installCodexAgents(projectDir);
+    if (createdAgents.length) {
+      results.push(`Installed ${createdAgents.length} Codex agents`);
+    }
+
+    const createdSkills = installCodexSkills(projectDir);
+    if (createdSkills.length) {
+      results.push(`Installed ${createdSkills.length} Codex skills`);
+    }
+  }
+
   // GEMINI.md — used by Gemini CLI
   if (targets.includes('gemini')) {
     const geminiMdPath = path.join(projectDir, 'GEMINI.md');
     if (!fs.existsSync(geminiMdPath)) {
-      fs.writeFileSync(geminiMdPath, agentsMd);
+      fs.writeFileSync(geminiMdPath, buildInstructionMd('gemini'));
       results.push(`Created ${geminiMdPath}`);
     }
   }
@@ -392,5 +1073,5 @@ module.exports = {
   detectRuntimes,
   configureRuntimes,
   generateProjectRuntimeFiles,
-  buildAgentsMd,
+  buildInstructionMd,
 };