create-harness-vibe-coding 0.8.7 → 0.8.9

package/package.json

@@ -1,44 +1,47 @@
-{
-  "name": "create-harness-vibe-coding",
-  "version": "0.8.7",
-  "description": "Scaffold a 0-1 product harness for AI-assisted research, PRD, planning, architecture, build, test, and feedback loops",
-  "type": "module",
-  "bin": {
-    "create-harness-vibe-coding": "bin/create-harness-vibe-coding.js"
-  },
-  "files": [
-    "bin/",
-    "src/",
-    "templates/",
-    "README-CN.md"
-  ],
-  "scripts": {
-    "start": "node src/index.js",
-    "build:version": "node scripts/build-version.mjs",
-    "prepush": "node scripts/pre-push-check.mjs",
-    "test": "node --test tests/*.test.js",
-    "test:smoke": "node --test tests/cli-smoke.test.js",
-    "pack:smoke": "node --test tests/pack-smoke.test.js"
-  },
-  "dependencies": {
-    "@clack/prompts": "^0.7.0",
-    "picocolors": "^1.1.0"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/zingspark/create-harness-vibe-coding.git"
-  },
-  "keywords": [
-    "claude-code",
-    "harness",
-    "scaffold",
-    "vibe-coding",
-    "agentic",
-    "ecc",
-    "superpowers"
-  ],
-  "license": "MIT"
-}
+{
+  "name": "create-harness-vibe-coding",
+  "version": "0.8.9",
+  "description": "Scaffold a 0-1 product harness for AI-assisted research, PRD, planning, architecture, build, test, and feedback loops",
+  "type": "module",
+  "bin": {
+    "create-harness-vibe-coding": "bin/create-harness-vibe-coding.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "docs/images/harness-icon.png",
+    "docs/images/harness-architecture-light.png",
+    "docs/images/harness-architecture.drawio",
+    "README-CN.md"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "build:version": "node scripts/build-version.mjs",
+    "prepush": "node scripts/pre-push-check.mjs",
+    "test": "node --test tests/*.test.js",
+    "test:smoke": "node --test tests/cli-smoke.test.js",
+    "pack:smoke": "node --test tests/pack-smoke.test.js"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "picocolors": "^1.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zingspark/create-harness-vibe-coding.git"
+  },
+  "keywords": [
+    "claude-code",
+    "harness",
+    "scaffold",
+    "vibe-coding",
+    "agentic",
+    "ecc",
+    "superpowers"
+  ],
+  "license": "MIT"
+}

package/src/generator.js

@@ -254,6 +254,28 @@ function duplicateDests(fileSpecs) {
   return [...duplicates].sort();
 }
 
+/**
+ * Walk the directory chain from rootDir down to the parent of absPath.
+ * Returns the first ancestor that is a symbolic link, or null if none.
+ * Prevents writes from escaping the workspace via symlinked parent dirs
+ * (e.g. .claude/, Harness/, .opencode/ pointing outside the project).
+ */
+function symlinkInChain(rootDir, absPath) {
+  const root = path.resolve(rootDir);
+  const target = path.resolve(absPath);
+  const rel = path.relative(root, target);
+  if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) return null;
+  const parts = rel.split(path.sep).filter(Boolean);
+  let cur = root;
+  for (let i = 0; i < parts.length - 1; i += 1) {
+    cur = path.join(cur, parts[i]);
+    try {
+      if (fs.lstatSync(cur).isSymbolicLink()) return cur;
+    } catch (_) { /* directory not created yet */ }
+  }
+  return null;
+}
+
 function createPlan(resolvedDir, fileSpecs) {
   const plan = {
     create: [],
@@ -381,11 +403,11 @@ function registerOptionalContent(file, content, selectedSkills) {
     return `${next.trimEnd()}\n\n## Installed Optional Workflows\n\n${lines.join('\n')}\n`;
   }
 
-  if (file === '.claude/commands/wf-help.md' && hasBrowserE2e) {
-    return content.replace(
-      '| `/wf-readme <task>` |',
-      '| `/wf-browser <task>` | optional workflow skill | `/wf-browser verify checkout flow` | Browser automation/E2E workflow with real UI interaction, screenshots, traces, and CDP/network evidence. |\n| `/wf-readme <task>` |',
-    );
+  if ((file === '.claude/commands/wf-help.md' || file === '.opencode/commands/wf-help.md') && hasBrowserE2e) {
+    return content.replace(
+      '| `/wf-readme <task>` |',
+      '| `/wf-browser <task>` | optional workflow skill | `/wf-browser verify checkout flow` | Browser automation/E2E workflow with real UI interaction, screenshots, traces, and CDP/network evidence. |\n| `/wf-readme <task>` |',
+    );
   }
 
   return content;
@@ -528,12 +550,20 @@ export function generate({
       const dirPath = dir === './'
         ? resolvedDir
         : path.join(resolvedDir, ...dir.slice(0, -1).split('/'));
+      const __slMkdir = symlinkInChain(resolvedDir, dirPath);
+      if (__slMkdir) throw new Error(`Cannot create directory ${dir}: symlinked directory in path (${__slMkdir})`);
       fs.mkdirSync(dirPath, { recursive: true });
       created.push(dir === './' ? './ (directory)' : `${dir} (directory)`);
     }
 
     for (const file of plan.backup) {
       const destPath = path.join(resolvedDir, ...file.split('/'));
+      const __slBackup = symlinkInChain(resolvedDir, destPath);
+      if (__slBackup) throw new Error(`Cannot backup ${file}: symlinked directory in path (${__slBackup})`);
+      // Symlink safety: never rename or follow symlinks to avoid path traversal
+      if (fs.existsSync(destPath)) {
+        try { if (fs.lstatSync(destPath).isSymbolicLink()) throw new Error('Symlink rejected'); } catch (e) { throw new Error(`Cannot backup ${file}: ${e.message}`); }
+      }
       fs.renameSync(destPath, nextBackupPath(destPath));
     }
 
@@ -554,6 +584,12 @@ export function generate({
       }
       const spec = specsByDest.get(file);
       const destPath = path.join(resolvedDir, ...file.split('/'));
+      const __slWrite = symlinkInChain(resolvedDir, destPath);
+      if (__slWrite) throw new Error(`Cannot create/overwrite ${file}: symlinked directory in path (${__slWrite})`);
+      // Symlink safety: reject symlinks before writing to prevent path traversal outside workspace
+      if (fs.existsSync(destPath)) {
+        try { if (fs.lstatSync(destPath).isSymbolicLink()) throw new Error('Symlink rejected'); } catch (e) { throw new Error(`Cannot create/overwrite ${file}: ${e.message}`); }
+      }
       let content = spec.type === 'empty'
         ? ''
         : renderTemplate(spec.src, vars);

package/src/index.js

@@ -89,6 +89,12 @@ if (generationOptions.json) {
   const projectName = argName || DEFAULT_NAME;
   const targetDir = argDir || `./${projectName}`;
   const scan = scanTarget(targetDir);
+  if (needsScaffoldRecovery(scan)) {
+    const recovery = createScaffoldRecoveryResult({ projectName, targetDir, options: generationOptions, scan });
+    printJsonResult(recovery);
+    process.exit(recovery.success ? 0 : 1);
+  }
+
   if (scan.hasHarness) {
     printJsonResult(createUpdateSwitchResult(scan, { json: true }));
     process.exit(0);
@@ -121,6 +127,10 @@ if (argName || skipPrompts) {
   targetDir = argDir || `./${projectName}`;
   const scan = scanTarget(targetDir);
 
+  if (needsScaffoldRecovery(scan)) {
+    process.exit(runScaffoldRecovery({ projectName, targetDir, options: generationOptions, scan }));
+  }
+
   if (scan.hasHarness) {
     process.exit(runUpdateSwitch(scan, { json: false }));
   }
@@ -128,9 +138,9 @@ if (argName || skipPrompts) {
   console.log(pc.dim('────────────────────────────────────────────'));
   console.log(`  Project     ${pc.green(projectName)}`);
   console.log(`  Directory   ${pc.green(targetDir)}`);
-  console.log(`  Creates     ${pc.cyan('CLAUDE.md, README.md, Harness/PROGRESS.md, Harness/, .claude/, .agents/, tests/')}`);
+  console.log(`  Creates     ${pc.cyan('CLAUDE.md, README.md, Harness/PROGRESS.md, Harness/, .claude/, .agents/, .opencode/, opencode.json, tests/')}`);
   if (generationOptions.dryRun) {
-    console.log(`  Mode        ${pc.yellow('dry-run')}`);
+    console.log(`  Mode        ${pc.yellow('dry-run')}`);
   }
   console.log(`  Conflicts   ${pc.cyan(generationOptions.onConflict)}`);
   if (generationOptions.withOptions.length > 0) {
@@ -172,6 +182,10 @@ if (argName || skipPrompts) {
   const scan = scanTarget(targetDir);
   printScan(scan);
 
+  if (needsScaffoldRecovery(scan)) {
+    process.exit(runScaffoldRecovery({ projectName, targetDir, options: generationOptions, scan }));
+  }
+
   if (scan.hasHarness) {
     process.exit(runUpdateSwitch(scan, { json: false }));
   }
@@ -206,7 +220,7 @@ if (argName || skipPrompts) {
   console.log(pc.dim('────────────────────────────────────────────'));
   console.log(`  Project     ${pc.green(projectName)}`);
   console.log(`  Directory   ${pc.green(targetDir)}`);
-  console.log(`  Creates     ${pc.cyan('CLAUDE.md, README.md, Harness/PROGRESS.md, Harness/, .claude/, .agents/, tests/')}`);
+  console.log(`  Creates     ${pc.cyan('CLAUDE.md, README.md, Harness/PROGRESS.md, Harness/, .claude/, .agents/, .opencode/, opencode.json, tests/')}`);
   console.log(`  Conflicts   ${pc.cyan(generationOptions.onConflict)}`);
   if (generationOptions.withOptions.length > 0) {
     console.log(`  Optional    ${pc.cyan(generationOptions.withOptions.join(','))}`);
@@ -276,8 +290,9 @@ function printResult(result, targetDir) {
 
     console.log(pc.bold('Next steps:'));
     console.log(`  ${pc.cyan(`cd ${targetDir}`)}`);
-    console.log(`  ${pc.cyan('claude')}                          # Start Claude Code`);
-    console.log(`  ${pc.cyan('codex')}                           # Or start Codex`);
+    console.log(`  ${pc.cyan('claude')}                          # Start Claude Code`);
+    console.log(`  ${pc.cyan('codex')}                           # Or start Codex`);
+    console.log(`  ${pc.cyan('opencode')}                        # Or start OpenCode`);
     console.log(`  Tell your agent: "${pc.yellow('Read Harness/SETUP.md. Bootstrap this project from idea to first vertical slice.')}"`);
     console.log('');
     console.log(pc.dim('  Harness/SETUP.md is temporary. Delete it after initialization.'));
@@ -438,12 +453,55 @@ function printWarnings(result) {
 }
 
 function printJsonResult(result) {
-  // Remove `created` array from output — it is already in the plan, avoid duplication
-  const { created, ...rest } = result;
+  // Remove `created` array from output — it is already in the plan, avoid duplication
+  const { created, ...rest } = result;
   console.log(JSON.stringify(rest, null, 2));
   if (!result.success) {
     process.exit(1);
-  }
+  }
+}
+
+function updateScriptPath(scan) {
+  return path.join(scan.resolvedDir, 'Harness', 'scripts', 'wf-update-check.mjs');
+}
+
+function missingRecoveryReasons(scan) {
+  const reasons = [];
+  if (!fs.existsSync(updateScriptPath(scan))) reasons.push('Harness/scripts/wf-update-check.mjs');
+  return reasons;
+}
+
+function needsScaffoldRecovery(scan) {
+  return scan.hasHarness && missingRecoveryReasons(scan).length > 0;
+}
+
+function recoveryOptions(options) {
+  return {
+    ...options,
+    onConflict: 'skip',
+  };
+}
+
+function createScaffoldRecoveryResult({ projectName, targetDir, options, scan }) {
+  const reasons = missingRecoveryReasons(scan);
+  const recovery = generate({
+    projectName,
+    targetDir,
+    ...recoveryOptions(options),
+  });
+  recovery.mode = 'recovery';
+  recovery.recoveryNote = `Missing ${reasons.join(' and ')}. Re-ran generate with --on-conflict ${recoveryOptions(options).onConflict} to restore missing Harness infrastructure without overwriting existing files.`;
+  return recovery;
+}
+
+function runScaffoldRecovery({ projectName, targetDir, options, scan }) {
+  const reasons = missingRecoveryReasons(scan);
+  console.log('');
+  console.log(pc.yellow(`Old Harness detected: missing ${reasons.join(' and ')}. Running safe recovery (--on-conflict ${recoveryOptions(options).onConflict}).`));
+  const recovery = createScaffoldRecoveryResult({ projectName, targetDir, options, scan });
+  printResult(recovery, targetDir);
+  if (recovery.success) console.log(pc.green('Recovery complete. Now run: node Harness/scripts/wf-update-check.mjs'));
+  return recovery.success ? 0 : 1;
 }
 
 function runUpdateSwitch(scan, { json }) {
@@ -512,8 +570,19 @@ function createUpdateSwitchResult(scan, { json }) {
   if (!fs.existsSync(scriptPath)) {
     return {
       ...base,
-      error: 'Existing Harness detected, but Harness/scripts/wf-update-check.mjs was not found. Install writes were skipped; inspect the existing Harness before updating manually.',
+      success: false,
+      error: 'Existing Harness detected, but Harness/scripts/wf-update-check.mjs was not found. The Harness install is incomplete or was created by an older version that did not include the update checker script. Install writes were skipped — no files were overwritten.',
       errors: ['Harness/scripts/wf-update-check.mjs not found'],
+      agent: {
+        ...base.agent,
+        next: [{
+          action: 'recovery',
+          reason: 'This Harness install predates the update-checker script.',
+          recoveryPath: 'Run npx create-harness-vibe-coding@latest <project-name> . -y --on-conflict skip --json from the project root. Current CLI versions detect missing updater infrastructure before update switch and regenerate missing files without overwriting existing user data. After recovery, run node Harness/scripts/wf-update-check.mjs --json to check for updates.',
+          command: 'npx create-harness-vibe-coding@latest <project-name> . -y --on-conflict skip',
+          note: 'The --on-conflict skip policy preserves all existing files and only creates missing ones. You may still need to merge CLAUDE.md changes manually after recovery.',
+        }],
+      },
     };
   }
 
@@ -564,7 +633,8 @@ function scanTarget(targetDir) {
   const hasClaude = isDirectory && fs.existsSync(path.join(resolvedDir, 'CLAUDE.md'));
   const hasAgents = isDirectory && fs.existsSync(path.join(resolvedDir, 'AGENTS.md'));
   const hasAgentSkills = isDirectory && fs.existsSync(path.join(resolvedDir, '.agents'));
-  const hasCodex = isDirectory && fs.existsSync(path.join(resolvedDir, '.codex'));
+  const hasCodex = isDirectory && fs.existsSync(path.join(resolvedDir, '.codex'));
+  const hasOpencode = isDirectory && (fs.existsSync(path.join(resolvedDir, '.opencode')) || fs.existsSync(path.join(resolvedDir, 'opencode.json')));
   const hasDocs = isDirectory && fs.existsSync(path.join(resolvedDir, 'docs'));
   const hasReadme = isDirectory && fs.existsSync(path.join(resolvedDir, 'README.md'));
   const hasPackageJson = isDirectory && fs.existsSync(path.join(resolvedDir, 'package.json'));
@@ -582,7 +652,8 @@ function scanTarget(targetDir) {
     hasClaude,
     hasAgents,
     hasAgentSkills,
-    hasCodex,
+    hasCodex,
+    hasOpencode,
     hasDocs,
     hasReadme,
     hasPackageJson,
@@ -610,7 +681,8 @@ function createJsonScan(scan) {
       hasClaude: scan.hasClaude,
       hasAgents: scan.hasAgents,
       hasAgentSkills: scan.hasAgentSkills,
-      hasCodex: scan.hasCodex,
+      hasCodex: scan.hasCodex,
+      hasOpencode: scan.hasOpencode,
       hasDocs: scan.hasDocs,
       hasReadme: scan.hasReadme,
       hasPackageJson: scan.hasPackageJson,
@@ -784,6 +856,7 @@ function printScan(scan) {
   if (scan.hasClaude) console.log(`  CLAUDE.md   ${pc.yellow('exists')}`);
   if (scan.hasAgents) console.log(`  AGENTS.md   ${pc.yellow('exists')}`);
   if (scan.hasAgentSkills) console.log(`  .agents/    ${pc.yellow('exists')}`);
-  if (scan.hasCodex) console.log(`  .codex/     ${pc.yellow('exists')}`);
+  if (scan.hasCodex) console.log(`  .codex/     ${pc.yellow('exists')}`);
+  if (scan.hasOpencode) console.log(`  opencode     ${pc.yellow('exists')}  ${pc.dim('(.opencode/ or opencode.json)')}`);
   if (scan.hasDocs) console.log(`  docs/       ${pc.dim('project-owned; Harness stays in Harness/')}`);
 }

package/src/prompts.js

@@ -1,41 +1,41 @@
-import * as p from '@clack/prompts';
-import pc from 'picocolors';
-
-export async function askProjectName() {
-  const name = await p.text({
-    message: 'Project name?',
-    placeholder: 'my-vibe-project',
-    defaultValue: 'my-vibe-project',
-    validate(value) {
-      if (!value.trim()) return 'Project name is required';
-      if (!/^[a-zA-Z0-9_-]+$/.test(value)) return 'Only letters, numbers, hyphens, and underscores allowed';
-      return;
-    },
-  });
-
-  if (p.isCancel(name)) {
-    p.cancel('Cancelled');
-    process.exit(0);
-  }
-
-  return name.trim();
-}
-
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+
+export async function askProjectName() {
+  const name = await p.text({
+    message: 'Project name?',
+    placeholder: 'my-vibe-project',
+    defaultValue: 'my-vibe-project',
+    validate(value) {
+      if (!value.trim()) return 'Project name is required';
+      if (!/^[a-zA-Z0-9_-]+$/.test(value)) return 'Only letters, numbers, hyphens, and underscores allowed';
+      return;
+    },
+  });
+
+  if (p.isCancel(name)) {
+    p.cancel('Cancelled');
+    process.exit(0);
+  }
+
+  return name.trim();
+}
+
 export async function askTargetDir(projectName) {
-  const dir = await p.text({
-    message: 'Target directory?',
-    placeholder: `./${projectName}`,
-    defaultValue: `./${projectName}`,
-    validate(value) {
-      if (!value.trim()) return 'Directory is required';
-      return;
-    },
-  });
-
-  if (p.isCancel(dir)) {
-    p.cancel('Cancelled');
-    process.exit(0);
-  }
+  const dir = await p.text({
+    message: 'Target directory?',
+    placeholder: `./${projectName}`,
+    defaultValue: `./${projectName}`,
+    validate(value) {
+      if (!value.trim()) return 'Directory is required';
+      return;
+    },
+  });
+
+  if (p.isCancel(dir)) {
+    p.cancel('Cancelled');
+    process.exit(0);
+  }
 
   return dir.trim();
 }

package/templates/common/.claude/agents/architect-manager.md

@@ -1,45 +1,45 @@
----
-name: architect-manager
-description: WF-MAX Manager for W1 architecture wave. Spawns 3 boundary/interface/data-flow architects, synthesizes interface contracts, reports to CEO. Read-only + Agent spawn; no Edit/Write.
-tools: Read, Grep, Glob, Agent, Bash(git *), Bash(ls *), Bash(dir *)
-model: sonnet
----
-
-# Architect Manager — W1 Architecture Wave
-
-You are an Architect Manager in the WF-MAX hierarchy. You report to the CEO.
-
-## Role
-
-Cross-file interface design → parallel dispatch of 3 architects → synthesize boundary decisions + interface contract → report to CEO for approval.
-
-## What You Do
-
-1. Receive architecture scope from the CEO (which modules/layers need boundaries defined)
-2. Spawn 3 parallel architects:
-   - **boundary-researcher**: study existing interfaces, dependencies, import graphs
-   - **interface-designer**: propose new interface contracts, ports, adapters
-   - **data-flow-mapper**: trace data through the system, identify state ownership
-3. ALL 3 spawned in ONE message
-4. Synthesize: reconcile interface proposals, flag conflicts, produce one interface contract
-5. Report to CEO with recommended decisions and trade-offs
-
-## What You NEVER Do
-
-- Write or edit source code
-- Implement interfaces (that's W2)
-- Make final architecture decisions (present options with trade-offs)
-- Write to task files
-
-## Synthesis Format
-
-```
-Boundary decisions (proposed):
-Interface contract:
-  - Port A: <signature, owner, consumers>
-  - Port B: <signature, owner, consumers>
-Data flow:
-State ownership:
-Conflicts/risks:
-Open questions for CEO:
-```
+---
+name: architect-manager
+description: WF-MAX Manager for W1 architecture wave. Spawns 3 boundary/interface/data-flow architects, synthesizes interface contracts, reports to CEO. Read-only + Agent spawn; no Edit/Write.
+tools: Read, Grep, Glob, Agent, Bash(git *), Bash(ls *), Bash(dir *)
+model: sonnet
+---
+
+# Architect Manager — W1 Architecture Wave
+
+You are an Architect Manager in the WF-MAX hierarchy. You report to the CEO.
+
+## Role
+
+Cross-file interface design → parallel dispatch of 3 architects → synthesize boundary decisions + interface contract → report to CEO for approval.
+
+## What You Do
+
+1. Receive architecture scope from the CEO (which modules/layers need boundaries defined)
+2. Spawn 3 parallel architects:
+   - **boundary-researcher**: study existing interfaces, dependencies, import graphs
+   - **interface-designer**: propose new interface contracts, ports, adapters
+   - **data-flow-mapper**: trace data through the system, identify state ownership
+3. ALL 3 spawned in ONE message
+4. Synthesize: reconcile interface proposals, flag conflicts, produce one interface contract
+5. Report to CEO with recommended decisions and trade-offs
+
+## What You NEVER Do
+
+- Write or edit source code
+- Implement interfaces (that's W2)
+- Make final architecture decisions (present options with trade-offs)
+- Write to task files
+
+## Synthesis Format
+
+```
+Boundary decisions (proposed):
+Interface contract:
+  - Port A: <signature, owner, consumers>
+  - Port B: <signature, owner, consumers>
+Data flow:
+State ownership:
+Conflicts/risks:
+Open questions for CEO:
+```

package/templates/common/.claude/agents/architect.md

@@ -1,31 +1,31 @@
----
-name: architect
-description: Use to review layer boundaries, ports, data flow, state machines, dependency direction, and architecture impact before implementation.
-tools: Read, Grep, Glob
-model: sonnet
----
-
-# Architect
-
-You are an architecture review agent for this project harness.
-
-Load first:
-
-- `Harness/architecture.md`
-- current PRD or feature doc
-
-Rules:
-
-- Do not write files.
-- Domain must not depend on harness, infrastructure, or interfaces.
-- Harness coordinates workflows but must not make business judgments.
-- New cross-layer capability needs a domain port.
-- Boundary changes must name affected docs.
-
-Return:
-
-- boundary decision
-- impacted docs
-- risks and missing contracts
-- port/data-flow/state updates needed
-- implementation constraints
+---
+name: architect
+description: Use to review layer boundaries, ports, data flow, state machines, dependency direction, and architecture impact before implementation.
+tools: Read, Grep, Glob
+model: sonnet
+---
+
+# Architect
+
+You are an architecture review agent for this project harness.
+
+Load first:
+
+- `Harness/architecture.md`
+- current PRD or feature doc
+
+Rules:
+
+- Do not write files.
+- Domain must not depend on harness, infrastructure, or interfaces.
+- Harness coordinates workflows but must not make business judgments.
+- New cross-layer capability needs a domain port.
+- Boundary changes must name affected docs.
+
+Return:
+
+- boundary decision
+- impacted docs
+- risks and missing contracts
+- port/data-flow/state updates needed
+- implementation constraints

package/templates/common/.claude/agents/codebase-explorer.md

@@ -0,0 +1,45 @@
+---
+name: codebase-explorer
+description: Use for scoped read-only source exploration, file discovery, symbol tracing, and simple codebase summaries before planning or implementation.
+tools: Read, Grep, Glob, Bash(rg *), Bash(git grep *), Bash(git ls-files *)
+model: haiku
+---
+
+# Codebase Explorer
+
+You are a scoped read-only source exploration agent. You find files, trace symbols, and summarize codebase structure. You do not write code, make decisions, or read the entire repository.
+
+## Input Contract
+
+Every dispatch MUST include:
+- **question**: what to find or answer
+- **readSet**: explicit file paths or search roots (directories)
+- **forbidden**: paths or patterns to skip
+- **maxFiles**: maximum files to read (controller sets this) — return BLOCKED if the scope exceeds this
+- **returnSchema**: fields expected in return (facts, files, risks, suggestedNextReads)
+
+If any of these are missing, return BLOCKED with what is needed.
+
+## Rules
+
+- Read only within the declared readSet and search roots.
+- Do not read the entire repository unless readSet explicitly includes it.
+- Do not write files. Read-only.
+- Prefer Grep/Glob for discovery; Read only the most relevant matches.
+- Stop when the question is answered or maxFiles is reached.
+- If the answer requires broader reading, note it in suggestedNextReads.
+
+## Return Format
+
+Return <= 250 tokens:
+```
+Question: [re-state the question]
+Facts: [<=5 concrete findings with file:line references]
+Files: [<=8 paths read or searched]
+Risks: [<=3 — what the exploration missed or could be wrong]
+Suggested next readSet: [<=5 files or search patterns]
+```
+
+## Model Tier
+
+You are dispatched as small-fast (haiku) for cost efficiency. If the question needs deeper reasoning (architecture judgment, security risk analysis, multi-layer trace), the controller should dispatch architect, reviewer, or researcher instead.