start-vibing 4.4.3 → 4.4.5

package/dist/cli.js

@@ -121,15 +121,133 @@ async function copyClaudeSetup(targetDir, options = {}) {
   return result;
 }
 
+// src/cleanup.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, statSync as statSync2, unlinkSync } from "fs";
+import { createHash } from "crypto";
+import { homedir } from "os";
+import { join as join2, resolve, sep } from "path";
+var STALE_FILES = [
+  {
+    category: "agents",
+    relPath: "research-web.md",
+    replacedBy: "research skill (scout \u2192 query \u2192 synthesize \u2192 verify)",
+    staleChecksums: [
+      "49d0cb862d199d1dcb59ed932ed04d8abd0064de3b65ef4f346268528dc21772",
+      "72ba14b6cad76a2d8718234775883242e94e82497e4edeec7fb35faf24327d6a",
+      "37c6ace245e2d8441e4f472e0123b5e7693e12bb869ced31f304fa17b7c75398",
+      "4f50d0080c54a972b6ec7053a6b6e3d36e6b27d14207357db26150707426bb2c"
+    ]
+  },
+  {
+    category: "agents",
+    relPath: "domain-updater.md",
+    replacedBy: "documenter agent (removed in start-vibing v4)",
+    staleChecksums: ["7499e0dd753805e6e459e687ce905ac3e949f28231e25bb2ab71036043b00f93"]
+  }
+];
+var VALID_CATEGORIES = new Set(["agents", "skills", "hooks", "commands"]);
+var MAX_FILE_BYTES = 1e6;
+function sha256OfFile(path) {
+  const buf = readFileSync2(path);
+  return createHash("sha256").update(buf).digest("hex");
+}
+function isInside(parent, child) {
+  const p = resolve(parent) + sep;
+  const c = resolve(child);
+  return c === resolve(parent) || c.startsWith(p);
+}
+function safeRelPath(rel) {
+  if (typeof rel !== "string" || rel.length === 0)
+    return null;
+  const normalized = rel.replace(/\\/g, "/");
+  if (normalized.startsWith("/"))
+    return null;
+  if (normalized.split("/").some((seg) => seg === ".." || seg === "" || seg === ".")) {
+    return null;
+  }
+  return normalized;
+}
+function tryDelete(claudeDir, locationLabel, stale, result) {
+  if (!VALID_CATEGORIES.has(stale.category))
+    return;
+  const safeRel = safeRelPath(stale.relPath);
+  if (safeRel === null)
+    return;
+  const categoryDir = join2(claudeDir, stale.category);
+  if (!existsSync2(categoryDir))
+    return;
+  const fullPath = join2(categoryDir, ...safeRel.split("/"));
+  if (!isInside(categoryDir, fullPath))
+    return;
+  if (!existsSync2(fullPath))
+    return;
+  let stat;
+  try {
+    stat = statSync2(fullPath);
+  } catch {
+    return;
+  }
+  if (!stat.isFile())
+    return;
+  if (stat.size > MAX_FILE_BYTES)
+    return;
+  let actual;
+  try {
+    actual = sha256OfFile(fullPath);
+  } catch {
+    return;
+  }
+  if (!stale.staleChecksums.includes(actual)) {
+    result.keptCustomized.push({
+      file: `${stale.category}/${safeRel}`,
+      location: locationLabel
+    });
+    return;
+  }
+  let preDeleteCheck;
+  try {
+    preDeleteCheck = sha256OfFile(fullPath);
+  } catch {
+    return;
+  }
+  if (preDeleteCheck !== actual)
+    return;
+  try {
+    unlinkSync(fullPath);
+    result.deleted.push({
+      file: `${stale.category}/${safeRel}`,
+      location: locationLabel,
+      replacedBy: stale.replacedBy
+    });
+  } catch {
+  }
+}
+function cleanupStaleAgents(targetDir) {
+  const result = { deleted: [], keptCustomized: [] };
+  const globalClaude = join2(homedir(), ".claude");
+  if (existsSync2(globalClaude)) {
+    for (const stale of STALE_FILES) {
+      tryDelete(globalClaude, "~/.claude", stale, result);
+    }
+  }
+  const projectClaude = join2(targetDir, ".claude");
+  if (existsSync2(projectClaude)) {
+    for (const stale of STALE_FILES) {
+      tryDelete(projectClaude, ".claude", stale, result);
+    }
+  }
+  return result;
+}
+
 // src/cli.ts
-import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
-import { join as join5, dirname as dirname2 } from "path";
+import { existsSync as existsSync6, readFileSync as readFileSync5, appendFileSync, writeFileSync as writeFileSync5 } from "fs";
+import { join as join6, dirname as dirname2 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { execSync as execSync3 } from "child_process";
 
 // src/update.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
-import { join as join2 } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
+import { join as join3 } from "path";
 
 // src/platform.ts
 import { platform } from "os";
@@ -200,8 +318,8 @@ function getHomeDir() {
 
 // src/update.ts
 var NPM_REGISTRY_URL = "https://registry.npmjs.org/start-vibing/latest";
-var CACHE_DIR = join2(getHomeDir(), ".start-vibing-cache");
-var CACHE_FILE = join2(CACHE_DIR, "version-check.json");
+var CACHE_DIR = join3(getHomeDir(), ".start-vibing-cache");
+var CACHE_FILE = join3(CACHE_DIR, "version-check.json");
 var CACHE_TTL_MS = 60 * 60 * 1000;
 function compareVersions(a, b) {
   const partsA = a.replace(/^v/, "").split(".").map(Number);
@@ -218,10 +336,10 @@ function compareVersions(a, b) {
 }
 function readCache() {
   try {
-    if (!existsSync2(CACHE_FILE)) {
+    if (!existsSync3(CACHE_FILE)) {
       return null;
     }
-    const content = readFileSync2(CACHE_FILE, "utf-8");
+    const content = readFileSync3(CACHE_FILE, "utf-8");
     const entry = JSON.parse(content);
     if (typeof entry.timestamp !== "number" || typeof entry.latestVersion !== "string") {
       return null;
@@ -233,7 +351,7 @@ function readCache() {
 }
 function writeCache(latestVersion) {
   try {
-    if (!existsSync2(CACHE_DIR)) {
+    if (!existsSync3(CACHE_DIR)) {
       mkdirSync2(CACHE_DIR, { recursive: true });
     }
     const entry = {
@@ -311,9 +429,9 @@ function getUpdateCommand() {
 
 // src/claude.ts
 import { spawn, execSync as execSync2, spawnSync } from "child_process";
-import { existsSync as existsSync3, readFileSync as readFileSync3, readdirSync as readdirSync2, writeFileSync as writeFileSync3 } from "fs";
-import { join as join3 } from "path";
-import { homedir } from "os";
+import { existsSync as existsSync4, readFileSync as readFileSync4, readdirSync as readdirSync2, writeFileSync as writeFileSync3 } from "fs";
+import { join as join4 } from "path";
+import { homedir as homedir2 } from "os";
 function isClaudeInstalled() {
   return commandExists("claude");
 }
@@ -423,11 +541,11 @@ function encodeProjectPath(absolutePath) {
 }
 function hasExistingSession(projectDir) {
   const encodedPath = encodeProjectPath(projectDir);
-  const sessionDir = join3(homedir(), ".claude", "projects", encodedPath);
-  const indexFile = join3(sessionDir, "sessions-index.json");
-  if (existsSync3(indexFile)) {
+  const sessionDir = join4(homedir2(), ".claude", "projects", encodedPath);
+  const indexFile = join4(sessionDir, "sessions-index.json");
+  if (existsSync4(indexFile)) {
     try {
-      const raw = readFileSync3(indexFile, "utf-8");
+      const raw = readFileSync4(indexFile, "utf-8");
       const index = JSON.parse(raw);
       if (Array.isArray(index.entries)) {
         const mainSessions = index.entries.filter((e) => !e.isSidechain);
@@ -437,7 +555,7 @@ function hasExistingSession(projectDir) {
     } catch {
     }
   }
-  if (existsSync3(sessionDir)) {
+  if (existsSync4(sessionDir)) {
     try {
       const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.jsonl$/;
       return readdirSync2(sessionDir).some((f) => uuidPattern.test(f));
@@ -479,12 +597,12 @@ function launchClaude(cwd, options = {}) {
 }
 function ensureHooksEnabled() {
   try {
-    const home = homedir();
-    const globalSettingsPath = join3(home, ".claude", "settings.json");
-    if (!existsSync3(globalSettingsPath)) {
+    const home = homedir2();
+    const globalSettingsPath = join4(home, ".claude", "settings.json");
+    if (!existsSync4(globalSettingsPath)) {
       return { modified: false };
     }
-    const content = readFileSync3(globalSettingsPath, "utf-8");
+    const content = readFileSync4(globalSettingsPath, "utf-8");
     let settings;
     try {
       settings = JSON.parse(content);
@@ -577,7 +695,7 @@ async function installMcp(server) {
   if (isMcpInstalled(server.name)) {
     return { server: server.name, success: true, message: "Already installed", skipped: true };
   }
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const args = ["mcp", "add", "-s", "user", server.name, "--", server.command, ...server.args];
     const proc = spawn2("claude", args, {
       shell: true,
@@ -592,14 +710,14 @@ async function installMcp(server) {
       stderr += data.toString();
     });
     proc.on("close", (code) => {
-      resolve(code === 0 ? { server: server.name, success: true, message: "Installed" } : { server: server.name, success: false, message: stderr || stdout || `Exit code: ${code}` });
+      resolve2(code === 0 ? { server: server.name, success: true, message: "Installed" } : { server: server.name, success: false, message: stderr || stdout || `Exit code: ${code}` });
     });
     proc.on("error", (err) => {
-      resolve({ server: server.name, success: false, message: err.message });
+      resolve2({ server: server.name, success: false, message: err.message });
     });
     setTimeout(() => {
       proc.kill();
-      resolve({ server: server.name, success: false, message: "Installation timed out" });
+      resolve2({ server: server.name, success: false, message: "Installation timed out" });
     }, 60000);
   });
 }
@@ -674,7 +792,7 @@ async function installPlugin(plugin) {
   if (isPluginInstalled(plugin.name, plugin.marketplace)) {
     return { plugin: pluginId, success: true, message: "Already installed", skipped: true };
   }
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const args = ["plugin", "install", pluginId, "--scope", "user"];
     const proc = spawn3("claude", args, {
       shell: true,
@@ -695,14 +813,14 @@ async function installPlugin(plugin) {
       stderr += data.toString();
     });
     proc.on("close", (code) => {
-      resolve(code === 0 ? { plugin: pluginId, success: true, message: "Installed" } : { plugin: pluginId, success: false, message: stderr || stdout || `Exit code: ${code}` });
+      resolve2(code === 0 ? { plugin: pluginId, success: true, message: "Installed" } : { plugin: pluginId, success: false, message: stderr || stdout || `Exit code: ${code}` });
     });
     proc.on("error", (err) => {
-      resolve({ plugin: pluginId, success: false, message: err.message });
+      resolve2({ plugin: pluginId, success: false, message: err.message });
     });
     setTimeout(() => {
       proc.kill();
-      resolve({ plugin: pluginId, success: false, message: "Installation timed out" });
+      resolve2({ plugin: pluginId, success: false, message: "Installation timed out" });
     }, 30000);
   });
 }
@@ -729,8 +847,8 @@ function getRecommendedPlugins() {
 }
 
 // src/skills.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "fs";
-import { join as join4 } from "path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "fs";
+import { join as join5 } from "path";
 import https from "https";
 var GITHUB_RAW = "https://raw.githubusercontent.com";
 var RECOMMENDED_SKILLS = [
@@ -753,12 +871,12 @@ var RECOMMENDED_SKILLS = [
   { name: "typeui-paper", url: `${GITHUB_RAW}/bergside/awesome-design-skills/main/skills/paper/SKILL.md`, description: "paper design system" }
 ];
 function fetchUrl(url) {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     const request = https.get(url, { headers: { "User-Agent": '"start-vibing"' } }, (res) => {
       if (res.statusCode === 301 || res.statusCode === 302) {
         const location = res.headers["location"];
         if (location) {
-          fetchUrl(location).then(resolve, reject);
+          fetchUrl(location).then(resolve2, reject);
           return;
         }
       }
@@ -770,7 +888,7 @@ function fetchUrl(url) {
       res.on("data", (chunk) => {
         data += chunk;
       });
-      res.on("end", () => resolve(data));
+      res.on("end", () => resolve2(data));
       res.on("error", reject);
     });
     request.on("error", reject);
@@ -782,9 +900,9 @@ function fetchUrl(url) {
 }
 async function installSkill(skill) {
   try {
-    const skillDir = join4(process.cwd(), ".claude", "skills", skill.name);
-    const skillFile = join4(skillDir, "SKILL.md");
-    if (existsSync4(skillFile)) {
+    const skillDir = join5(process.cwd(), ".claude", "skills", skill.name);
+    const skillFile = join5(skillDir, "SKILL.md");
+    if (existsSync5(skillFile)) {
       return { skill: skill.name, success: true, message: "Already installed", skipped: true };
     }
     const content = await fetchUrl(skill.url);
@@ -912,12 +1030,12 @@ var TOTAL_PHASES = 6;
 function getVersion() {
   try {
     const paths = [
-      join5(__dirname3, "..", "package.json"),
-      join5(__dirname3, "..", "..", "package.json")
+      join6(__dirname3, "..", "package.json"),
+      join6(__dirname3, "..", "..", "package.json")
     ];
     for (const pkgPath of paths) {
-      if (existsSync5(pkgPath)) {
-        const pkg = JSON.parse(readFileSync4(pkgPath, "utf-8"));
+      if (existsSync6(pkgPath)) {
+        const pkg = JSON.parse(readFileSync5(pkgPath, "utf-8"));
         return pkg.version || "4.0.0";
       }
     }
@@ -927,28 +1045,67 @@ function getVersion() {
   }
 }
 var VERSION = getVersion();
-function autoCommitClaudeFiles(targetDir) {
+var MANAGED_PATHS = [
+  ".claude/agents/",
+  ".claude/skills/",
+  ".claude/commands/",
+  ".claude/hooks/",
+  ".claude/scripts/",
+  ".claude/config/",
+  ".claude/settings.json",
+  ".claude/settings.local.json",
+  ".claude/CLAUDE.md",
+  "CLAUDE.md"
+];
+function isPathTracked(targetDir, path) {
   try {
-    try {
-      execSync3("git rev-parse --git-dir", { cwd: targetDir, stdio: "pipe" });
-    } catch {
-      return { success: false, message: "Not a git repository" };
-    }
-    const status = execSync3("git status --porcelain .claude CLAUDE.md .claude/", {
+    const out = execSync3(`git ls-files -- "${path}"`, {
       cwd: targetDir,
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"]
     }).trim();
-    if (!status) {
-      return { success: true, message: "No changes to commit" };
-    }
-    execSync3("git add .claude/ CLAUDE.md", { cwd: targetDir, stdio: "pipe" });
-    execSync3(`git commit --no-verify -m "chore: update Claude Code setup (start-vibing v${VERSION})"`, { cwd: targetDir, stdio: "pipe" });
-    return { success: true, message: "Changes committed" };
+    return out.length > 0;
   } catch {
-    return { success: false, message: "Commit failed (non-critical)" };
+    return false;
   }
 }
+function syncGitignore(targetDir) {
+  try {
+    execSync3("git rev-parse --git-dir", { cwd: targetDir, stdio: "pipe" });
+  } catch {
+    return { success: false, added: [], tracked: [], message: "Not a git repository" };
+  }
+  const toIgnore = [];
+  const tracked = [];
+  for (const p of MANAGED_PATHS) {
+    if (isPathTracked(targetDir, p))
+      tracked.push(p);
+    else
+      toIgnore.push(p);
+  }
+  const gitignorePath = join6(targetDir, ".gitignore");
+  const header = "# start-vibing (local Claude setup - not tracked in this repo)";
+  let current = "";
+  if (existsSync6(gitignorePath))
+    current = readFileSync5(gitignorePath, "utf-8");
+  const existing = new Set(current.split(/\r?\n/).map((l) => l.trim()).filter(Boolean));
+  const missing = toIgnore.filter((e) => !existing.has(e));
+  if (missing.length === 0) {
+    return { success: true, added: [], tracked, message: "Already in .gitignore" };
+  }
+  if (current.length === 0) {
+    writeFileSync5(gitignorePath, `${header}\n${missing.join("\n")}\n`, "utf-8");
+  } else {
+    const prefix = current.endsWith("\n") ? "" : "\n";
+    appendFileSync(gitignorePath, `${prefix}\n${header}\n${missing.join("\n")}\n`, "utf-8");
+  }
+  return {
+    success: true,
+    added: missing,
+    tracked,
+    message: `Added ${missing.length} entr${missing.length === 1 ? "y" : "ies"} to .gitignore`
+  };
+}
 var HELP = `${createBanner(VERSION)}
   Setup Claude Code agents, skills, plugins, and MCP servers.
 
@@ -1022,13 +1179,30 @@ async function main() {
   const spinner1 = createSpinner(phaseHeader(1, TOTAL_PHASES, "Copying template files..."));
   try {
     const result = await copyClaudeSetup(targetDir, { force });
-    autoCommitClaudeFiles(targetDir);
+    const cleanup = cleanupStaleAgents(targetDir);
+    const ignoreResult = syncGitignore(targetDir);
     ensureHooksEnabled();
     const counts = `${result.agents} agents, ${result.skills} skills`;
     spinner1.succeed(phaseHeader(1, TOTAL_PHASES, `Template files ${c.dim}${"\xB7".repeat(14)}${c.reset} ${counts}  ${c.dim}${formatElapsed(phase1Start)}${c.reset}`));
+    if (ignoreResult.success && ignoreResult.added.length > 0) {
+      console.log(`        ${c.dim}gitignored ${ignoreResult.added.length} path(s) not tracked upstream (remove from .gitignore to commit)${c.reset}`);
+    }
+    if (ignoreResult.success && ignoreResult.tracked.length > 0) {
+      console.log(`        ${c.dim}left ${ignoreResult.tracked.length} tracked path(s) alone (e.g. shared settings)${c.reset}`);
+    }
     if (result.preserved > 0) {
       console.log(`        ${c.dim}(preserved ${result.preserved} custom file(s))${c.reset}`);
     }
+    if (cleanup.deleted.length > 0) {
+      for (const d of cleanup.deleted) {
+        console.log(`        ${c.yellow}removed${c.reset} ${d.location}/${d.file} ${c.dim}-> ${d.replacedBy}${c.reset}`);
+      }
+    }
+    if (cleanup.keptCustomized.length > 0) {
+      for (const k of cleanup.keptCustomized) {
+        console.log(`        ${c.dim}kept customized ${k.location}/${k.file} (checksum diverges from any known stale version)${c.reset}`);
+      }
+    }
   } catch (error) {
     spinner1.fail(phaseHeader(1, TOTAL_PHASES, `Template files failed`));
     console.error(`        ${c.red}${error}${c.reset}`);

package/package.json

@@ -1,42 +1,42 @@
-{
-	"name": "start-vibing",
-	"version": "4.4.3",
-	"description": "Setup Claude Code with 9 plugins, 6 community skills, and 8 MCP servers. Parallel install, auto-accept, superpowers + ralph-loop. e2e-audit 0.2.0 refactor (skill-only, no agents): SessionStart hook + slash command make the skill keyword-invokable (\"e2e audit\", \"roda o e2e\", \"integration test\", \"test coverage gaps\"). Source-first discovery via detect-stack, discover-routes (Next app/pages/Remix/SvelteKit/Nuxt/Astro), discover-api-surface (HTTP handlers, tRPC procedures, GraphQL, server actions, middleware auth), inventory-existing-tests (preserve prior corpus + sha256 drift hash), and detect-uncovered (branch-diff vs origin/main finds changes not covered by existing specs). Report-then-ask between mapping and Playwright run; post-run-feedback report before writing findings. SHOT+TRACE+ASSERT+SOURCE evidence quad per non-meta finding; meta rules (coverage-gap-*, uncovered-*, test-drift, stack-detect, post-run-feedback) exempt. verify-audit.sh enforces schema + quad. Generic (no project leakage). super-design 0.7.0 carries over.",
-	"type": "module",
-	"bin": {
-		"start-vibing": "./dist/cli.js"
-	},
-	"files": [
-		"dist",
-		"template"
-	],
-	"scripts": {
-		"build": "bun build ./src/cli.ts --outdir ./dist --target node",
-		"dev": "bun run ./src/cli.ts",
-		"prepublishOnly": "bun run build"
-	},
-	"keywords": [
-		"claude",
-		"claude-code",
-		"ai",
-		"agents",
-		"skills",
-		"hooks",
-		"automation",
-		"workflow",
-		"cli"
-	],
-	"author": "joaov",
-	"license": "MIT",
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/LimaTechnologies/ai-development"
-	},
-	"engines": {
-		"node": ">=18.0.0"
-	},
-	"devDependencies": {
-		"@types/node": "^20.0.0",
-		"typescript": "^5.0.0"
-	}
-}
+{
+	"name": "start-vibing",
+	"version": "4.4.5",
+	"description": "Setup Claude Code with 9 plugins, 6 community skills, and 8 MCP servers. Parallel install, auto-accept, superpowers + ralph-loop. e2e-audit 0.2.0 refactor (skill-only, no agents): SessionStart hook + slash command make the skill keyword-invokable (\"e2e audit\", \"roda o e2e\", \"integration test\", \"test coverage gaps\"). Source-first discovery via detect-stack, discover-routes (Next app/pages/Remix/SvelteKit/Nuxt/Astro), discover-api-surface (HTTP handlers, tRPC procedures, GraphQL, server actions, middleware auth), inventory-existing-tests (preserve prior corpus + sha256 drift hash), and detect-uncovered (branch-diff vs origin/main finds changes not covered by existing specs). Report-then-ask between mapping and Playwright run; post-run-feedback report before writing findings. SHOT+TRACE+ASSERT+SOURCE evidence quad per non-meta finding; meta rules (coverage-gap-*, uncovered-*, test-drift, stack-detect, post-run-feedback) exempt. verify-audit.sh enforces schema + quad. Generic (no project leakage). super-design 0.7.0 carries over.",
+	"type": "module",
+	"bin": {
+		"start-vibing": "./dist/cli.js"
+	},
+	"files": [
+		"dist",
+		"template"
+	],
+	"scripts": {
+		"build": "bun build ./src/cli.ts --outdir ./dist --target node",
+		"dev": "bun run ./src/cli.ts",
+		"prepublishOnly": "bun run build"
+	},
+	"keywords": [
+		"claude",
+		"claude-code",
+		"ai",
+		"agents",
+		"skills",
+		"hooks",
+		"automation",
+		"workflow",
+		"cli"
+	],
+	"author": "joaov",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/LimaTechnologies/ai-development"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"devDependencies": {
+		"@types/node": "^20.0.0",
+		"typescript": "^5.0.0"
+	}
+}

package/template/.claude/agents/research-query.md

@@ -0,0 +1,128 @@
+---
+name: research-query
+description: Executes the research plan from scout-plan.json. Runs parallel WebSearch + WebFetch + context7 lookups, extracts atomic claims with URL+QUOTE+ACCESSED-AT evidence, and writes claims.jsonl + sources.jsonl to the session directory. Honors per-domain authority hierarchies from references/source-directory.md and per-bucket freshness windows from research-methodology.md §7.
+tools: Read, Write, Glob, Grep, Bash, WebSearch, WebFetch
+model: sonnet
+color: blue
+---
+
+# Role
+
+You are the query executor. You take a scout-plan and turn it into raw
+evidence: a stream of atomic claims with verifiable citations. You do
+**not** triangulate or synthesize — that is the next agent's job. You
+optimize for evidence density and citation integrity.
+
+# When invoked
+
+You receive: `$SESSION_DIR/scout-plan.json` + the path to
+`/docs/research/.cache/sessions/<id>/`.
+
+# Steps
+
+## 1. Load context
+
+Read:
+
+- `$SESSION_DIR/scout-plan.json`
+- `.claude/skills/research/references/source-directory.md` (the domain table for `scout.domain`)
+- `.claude/skills/research/references/research-methodology.md` §5 (query engineering) and §7 (freshness)
+- The relevant playbook from `.claude/skills/research/references/domain-playbooks.md`
+
+## 2. Build the query plan
+
+For each sub-question in `scout.decomposition`, generate 2–4 search
+queries using the templates in §5 of research-methodology.md:
+
+- Boolean: `("RSC" OR "React Server Components") AND "data fetching"`
+- Time-boxed: `after:2025-01-01`
+- Site-narrowed: `site:nextjs.org` for canonical, `site:react.dev`, `site:github.com`
+- Negative-space: `"X disadvantages"`, `"X alternatives"`
+- Authority-first: query official docs and IETF/W3C/ECMA before blog aggregators
+
+Cap total queries at `scout.estimated_queries × 1.25`. Stop early if
+diminishing returns (3 consecutive queries return only republications).
+
+## 3. Execute searches in PARALLEL
+
+Use multiple `WebSearch` calls in a single message when sub-questions
+are independent. Collect all result URLs into a candidate pool.
+
+## 4. Filter by authority
+
+Per `source-directory.md`, rank candidates 1–5 by authority. Drop level-1
+SEO-farm domains unless they are the only source for a niche claim
+(then add `quality_warning: "low-authority-only-source"` in the claim).
+
+## 5. Fetch + snapshot
+
+For each high-authority candidate, run `WebFetch` with a focused prompt
+("extract the section that addresses <sub-question>, return verbatim
+quotes with their headings"). Save the raw markdown response to
+`$SESSION_DIR/snapshots/<n>.md` (used later by verify-citations.sh for
+quote-grep verification).
+
+For library/framework docs, prefer `mcp__context7__query-docs` over
+WebFetch — it's already structured.
+
+## 6. Extract atomic claims
+
+For each fetched source, extract 1–8 atomic claims. Each claim:
+
+```jsonc
+{
+	"id": "C-0042",
+	"sub_question": "How does Promise.all interact with cache()?",
+	"assertion": "Calling fetch inside cache() within Promise.all parallelizes requests but cache key is the deduped URL.",
+	"source_id": "S-0007",
+	"quote": "verbatim string from the source — must be greppable in snapshots/<n>.md",
+	"quote_location": "section heading or paragraph anchor",
+	"verify_method": "web-fetch",
+	"confidence_signal": "official-docs",
+	"tags": ["nextjs", "rsc", "data-fetching"],
+}
+```
+
+Append one JSON per line to `$SESSION_DIR/claims.jsonl`.
+
+## 7. Record sources
+
+For each unique source, write to `$SESSION_DIR/sources.jsonl`:
+
+```jsonc
+{
+	"id": "S-0007",
+	"url": "https://nextjs.org/docs/app/building-your-application/caching",
+	"title": "Caching | Next.js",
+	"publisher": "Vercel",
+	"publisher_independence": "vendor", // wire | primary-journalism | vendor | academic | community | seo-content
+	"author": null,
+	"doi": null,
+	"published_at": "2024-11-03",
+	"accessed_at": "2026-04-25T13:45:11Z",
+	"authority_level": 5,
+	"snapshot_path": ".cache/sessions/<id>/snapshots/7.md",
+}
+```
+
+## 8. Independence check
+
+Before exiting, group sources by `publisher` and ownership tree (per
+source-directory.md "AI content red flags" section). If a claim's
+sources all belong to the same ownership/wire chain, mark the claim
+`triangulation_warning: "single-ownership-cluster"`.
+
+## 9. Return summary
+
+≤5 lines: claim count, source count, distinct ownership clusters,
+warnings. Hand off to research-synthesize.
+
+# Hard rules
+
+1. **Every claim has a verbatim QUOTE that is greppable in its snapshot.** No paraphrase-only claims.
+2. **Every URL must HTTP 200 at fetch time.** If WebFetch fails, drop the claim and log to `$SESSION_DIR/fetch-errors.log`.
+3. **Never invent sources.** If you cannot fetch, you cannot cite.
+4. **Honor freshness window** from `scout.freshness_window_days`. Sources older than the window get `freshness_warning: true` and require explicit reasoning to keep.
+5. **Parallelize** — independent WebSearch calls go in one message.
+6. **Stop at claims.jsonl.** Do not write to `/docs/research/<slug>.md`.
+7. **Snapshots are mandatory** — they are the evidence the verify agent will grep.