frappe-builder 1.1.0-dev.8 → 1.2.0-dev.29

package/config/loader.ts

@@ -1,96 +1,16 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { defaults } from "./defaults.js";
 import type { AppConfig } from "./defaults.js";
 
-// ── Credential config types (NFR6, NFR9) ────────────────────────────────────
-
-export interface GlobalConfig {
-  llm_api_key: string;
-  llm_provider?: string;
-  [key: string]: unknown;
-}
-
-export interface ProjectConfig {
-  site_url: string;
-  api_key: string;
-  api_secret: string;
-  [key: string]: unknown;
-}
-
-export interface CredentialConfig {
-  global: GlobalConfig;
-  project: ProjectConfig;
-  sessionLogDir: string;
-}
-
-/** Always ~/.frappe-builder/sessions/ — never the project directory (NFR9). */
+/** Always ~/.frappe-builder/sessions/ — never the project directory. */
 export const SESSION_LOG_DIR = join(homedir(), ".frappe-builder", "sessions");
 
-const GITIGNORE_ERROR =
-  "Site credentials file is not gitignored. Add .frappe-builder-config.json to .gitignore before proceeding.";
-
-/**
- * Validates that {projectRoot}/.gitignore lists .frappe-builder-config.json.
- * Throws with the exact AC error message if missing or absent.
- */
-export function validateGitignore(projectRoot: string): void {
-  const gitignorePath = join(projectRoot, ".gitignore");
-  if (!existsSync(gitignorePath)) {
-    throw new Error(GITIGNORE_ERROR);
-  }
-  const contents = readFileSync(gitignorePath, "utf8");
-  const lines = contents.split("\n").map((l) => l.trim());
-  if (!lines.includes(".frappe-builder-config.json")) {
-    throw new Error(GITIGNORE_ERROR);
-  }
-}
-
-/**
- * Reads LLM API keys from ~/.frappe-builder/config.json (user-global, never project).
- * Creates ~/.frappe-builder/ on first run. Returns empty defaults if file absent.
- */
-export function loadGlobalConfig(): GlobalConfig {
-  const configDir = join(homedir(), ".frappe-builder");
-  mkdirSync(configDir, { recursive: true });
-  const configPath = join(configDir, "config.json");
-  if (!existsSync(configPath)) return { llm_api_key: "" };
-  try {
-    return JSON.parse(readFileSync(configPath, "utf8")) as GlobalConfig;
-  } catch {
-    return { llm_api_key: "" };
-  }
-}
-
-/**
- * Reads Frappe site credentials from {projectRoot}/.frappe-builder-config.json.
- * Returns empty defaults if file absent (caller should surface a warning).
- */
-export function loadProjectConfig(projectRoot: string): ProjectConfig {
-  const configPath = join(projectRoot, ".frappe-builder-config.json");
-  if (!existsSync(configPath)) return { site_url: "", api_key: "", api_secret: "" };
-  try {
-    return JSON.parse(readFileSync(configPath, "utf8")) as ProjectConfig;
-  } catch {
-    return { site_url: "", api_key: "", api_secret: "" };
-  }
-}
-
-/**
- * Full credential loader: validates gitignore, loads global + project configs.
- * Throws if .frappe-builder-config.json is not gitignored.
- * API keys are only ever read from ~/.frappe-builder/ — never from projectRoot.
- */
-export function loadCredentials(projectRoot: string): CredentialConfig {
-  validateGitignore(projectRoot);
-  const global = loadGlobalConfig();
-  const project = loadProjectConfig(projectRoot);
-  return { global, project, sessionLogDir: SESSION_LOG_DIR };
-}
-
 /**
  * Loads ~/.frappe-builder/config.json and merges with defaults.
+ * Stores agent behaviour preferences (permissionMode, requirePermission, etc.).
+ * Site credentials live in the session DB — not in this file.
  * Never throws — returns defaults on any read/parse failure.
  */
 export function loadConfig(): AppConfig {
@@ -103,3 +23,17 @@ export function loadConfig(): AppConfig {
     return { ...defaults };
   }
 }
+
+/**
+ * Writes a partial config merged over the current config to ~/.frappe-builder/config.json.
+ * Creates the directory if needed. Non-fatal — never throws.
+ */
+export function saveConfig(partial: Partial<AppConfig>): void {
+  try {
+    const configDir = join(homedir(), ".frappe-builder");
+    mkdirSync(configDir, { recursive: true });
+    const configPath = join(configDir, "config.json");
+    const merged = { ...loadConfig(), ...partial };
+    writeFileSync(configPath, JSON.stringify(merged, null, 2) + "\n", "utf-8");
+  } catch { /* non-fatal */ }
+}

package/dist/cli.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+//#region src/cli.ts
+/**
+* src/cli.ts — frappe-builder CLI entry point
+*
+* Commands:
+*   frappe-builder init    — bootstrap agent toolchain (run once per machine)
+*   frappe-builder         — start a pi session with frappe-builder extensions loaded
+*/
+const cmd = process.argv[2];
+if (cmd === "init") {
+	const { runInit } = await import("./init-DvtJrAiJ.mjs");
+	await runInit();
+	process.exit(0);
+}
+if (cmd === "--help" || cmd === "-h") {
+	console.log(`
+Usage: frappe-builder [command]
+
+Commands:
+  init    Bootstrap agent toolchain: context-mode, mcp2cli, context7 (run once per machine)
+  (none)  Start a frappe-builder session
+
+Options:
+  --help, -h   Show this help message
+`);
+	process.exit(0);
+}
+if (!existsSync(join(homedir(), ".frappe-builder", ".initialized"))) {
+	console.error("frappe-builder toolchain not set up.");
+	console.error("Run: frappe-builder init");
+	process.exit(1);
+}
+const pkgRoot = resolve(fileURLToPath(import.meta.url), "..", "..");
+const extensions = [
+	"frappe-session",
+	"frappe-state",
+	"frappe-workflow",
+	"frappe-tools",
+	"frappe-gates",
+	"frappe-ui"
+].map((name) => resolve(pkgRoot, "extensions", `${name}.ts`));
+const agentsFile = resolve(pkgRoot, "AGENTS.md");
+const require = createRequire(import.meta.url);
+let piCli;
+try {
+	piCli = require.resolve("@mariozechner/pi-coding-agent/dist/cli.js");
+} catch {}
+if (!piCli) {
+	const direct = resolve(pkgRoot, "node_modules/@mariozechner/pi-coding-agent/dist/cli.js");
+	if (existsSync(direct)) piCli = direct;
+}
+if (!piCli) {
+	const sibling = resolve(pkgRoot, "..", "@mariozechner", "pi-coding-agent", "dist", "cli.js");
+	if (existsSync(sibling)) piCli = sibling;
+}
+if (!piCli) {
+	console.error("Could not locate pi CLI.");
+	console.error("Try reinstalling: npm install -g frappe-builder@dev");
+	process.exit(1);
+}
+const extArgs = extensions.flatMap((e) => ["-e", e]);
+const result = spawnSync(process.execPath, [
+	piCli,
+	...extArgs,
+	"--append-system-prompt",
+	agentsFile
+], { stdio: "inherit" });
+process.exit(result.status ?? 0);
+//#endregion
+export {};

package/dist/init-DvtJrAiJ.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+//#region src/init.ts
+/**
+* src/init.ts — toolchain setup for frappe-builder
+*
+* Bootstraps the agent environment: context-mode, mcp2cli, context7.
+* No credential prompts — site credentials are collected at runtime via set_active_project.
+*
+* No imports from state/, extensions/, or gates/.
+* Uses Node.js built-ins only.
+*/
+function writeAtomic(filePath, content) {
+	const tmp = filePath + ".tmp";
+	writeFileSync(tmp, content, "utf-8");
+	renameSync(tmp, filePath);
+}
+/** Patches .gitignore to include the exact entry if not already present. */
+function patchGitignore(projectRoot, entry) {
+	const gitignorePath = join(projectRoot, ".gitignore");
+	if (!existsSync(gitignorePath)) {
+		writeFileSync(gitignorePath, entry + "\n", "utf-8");
+		return "created";
+	}
+	const content = readFileSync(gitignorePath, "utf-8");
+	if (content.split("\n").includes(entry)) return "already-present";
+	writeFileSync(gitignorePath, content.endsWith("\n") ? content + entry + "\n" : content + "\n" + entry + "\n", "utf-8");
+	return "patched";
+}
+async function runInit(opts = {}) {
+	const projectRoot = opts.projectRoot ?? process.cwd();
+	const homeDir = homedir();
+	const markerPath = join(homeDir, ".frappe-builder", ".initialized");
+	console.log("\n=== frappe-builder Setup ===\n");
+	mkdirSync(join(homeDir, ".frappe-builder"), { recursive: true });
+	writeFileSync(markerPath, (/* @__PURE__ */ new Date()).toISOString() + "\n", "utf-8");
+	const gitignoreResult = patchGitignore(projectRoot, ".fb/");
+	const written = [];
+	if (gitignoreResult === "patched") written.push(".gitignore (patched with .fb/)");
+	else if (gitignoreResult === "created") written.push(".gitignore (created with .fb/)");
+	setupMcp2cli(homeDir, await setupContextMode(homeDir));
+	setupContext7();
+	if (written.length > 0) {
+		console.log("\nFiles written:");
+		for (const f of written) console.log(`  ✓ ${f}`);
+	}
+	console.log("\nReady. Run: frappe-builder\n");
+}
+/**
+* Resolves the actual path to context-mode's start.mjs after build.
+* Checks candidates in order: repo root, dist/, dist/index, node_modules self-ref.
+* Returns the first path that exists, or the first candidate as a fallback for mcp.json.
+*/
+function resolveContextModeStartScript(extDir) {
+	const candidates = [
+		join(extDir, "start.mjs"),
+		join(extDir, "dist", "start.mjs"),
+		join(extDir, "dist", "index.mjs"),
+		join(extDir, "node_modules", "context-mode", "start.mjs")
+	];
+	return candidates.find((p) => existsSync(p)) ?? candidates[0];
+}
+/**
+* Installs and configures the context-mode pi MCP extension.
+* Clones https://github.com/mksglu/context-mode into ~/.pi/extensions/context-mode,
+* builds it, and patches ~/.pi/settings/mcp.json with the server entry.
+*
+* Returns the resolved start.mjs path (for use by setupMcp2cli).
+* Non-fatal — failures are logged as warnings, never abort init.
+*/
+async function setupContextMode(homeDir) {
+	const extDir = join(homeDir, ".pi", "extensions", "context-mode");
+	const mcpSettingsDir = join(homeDir, ".pi", "settings");
+	const mcpSettingsPath = join(mcpSettingsDir, "mcp.json");
+	const startScript = resolveContextModeStartScript(extDir);
+	console.log("\n[context-mode MCP extension]");
+	if (existsSync(extDir)) console.log("  ✓ context-mode already installed at ~/.pi/extensions/context-mode");
+	else {
+		console.log("  context-mode not found — installing (requires git + Node.js)...");
+		mkdirSync(join(homeDir, ".pi", "extensions"), { recursive: true });
+		const clone = spawnSync("git", [
+			"clone",
+			"https://github.com/mksglu/context-mode.git",
+			extDir
+		], { stdio: "pipe" });
+		if (clone.status !== 0) {
+			console.warn(`  ⚠ git clone failed: ${clone.stderr?.toString().trim()}`);
+			console.warn("  Skipping context-mode setup. Install manually: https://github.com/mksglu/context-mode");
+			return startScript;
+		}
+		const install = spawnSync("npm", ["install"], {
+			cwd: extDir,
+			stdio: "pipe"
+		});
+		if (install.status !== 0) {
+			console.warn(`  ⚠ npm install failed: ${install.stderr?.toString().trim()}`);
+			return startScript;
+		}
+		const build = spawnSync("npm", ["run", "build"], {
+			cwd: extDir,
+			stdio: "pipe"
+		});
+		if (build.status !== 0) {
+			console.warn(`  ⚠ npm run build failed: ${build.stderr?.toString().trim()}`);
+			return startScript;
+		}
+		console.log("  ✓ context-mode installed and built");
+	}
+	mkdirSync(mcpSettingsDir, { recursive: true });
+	let mcpConfig = {};
+	if (existsSync(mcpSettingsPath)) try {
+		mcpConfig = JSON.parse(readFileSync(mcpSettingsPath, "utf-8"));
+	} catch {}
+	const servers = mcpConfig.mcpServers ?? {};
+	if (servers["context-mode"]) {
+		console.log("  ✓ context-mode already in ~/.pi/settings/mcp.json");
+		return startScript;
+	}
+	servers["context-mode"] = {
+		command: "node",
+		args: [startScript]
+	};
+	mcpConfig.mcpServers = servers;
+	writeAtomic(mcpSettingsPath, JSON.stringify(mcpConfig, null, 2) + "\n");
+	console.log("  ✓ Added context-mode to ~/.pi/settings/mcp.json");
+	console.log("  Restart pi (or frappe-builder) for context-mode to activate.");
+	return startScript;
+}
+/**
+* Installs the mcp2cli Claude Code skill and bakes the context-mode connection
+* so the agent can call `mcp2cli @context-mode <tool>` without repeating flags.
+*
+* startScript is passed in from setupContextMode so both functions use the same resolved path.
+* Non-fatal — failures are logged as warnings, never abort init.
+*/
+function setupMcp2cli(homeDir, startScript) {
+	if (!startScript) startScript = resolveContextModeStartScript(join(homeDir, ".pi", "extensions", "context-mode"));
+	console.log("\n[mcp2cli skill + context-mode bake]");
+	if (spawnSync("mcp2cli", ["--version"], { stdio: "pipe" }).status === 0) console.log("  ✓ mcp2cli already installed");
+	else {
+		console.log("  Installing mcp2cli...");
+		if (spawnSync("uv", [
+			"tool",
+			"install",
+			"mcp2cli"
+		], { stdio: "pipe" }).status === 0) console.log("  ✓ mcp2cli installed via uv");
+		else if (spawnSync("pip", ["install", "mcp2cli"], { stdio: "pipe" }).status === 0) console.log("  ✓ mcp2cli installed via pip");
+		else {
+			console.warn("  ⚠ mcp2cli install failed (tried uv and pip)");
+			console.warn("  Install manually: uv tool install mcp2cli");
+		}
+	}
+	const skillAdd = spawnSync("npx", [
+		"skills",
+		"add",
+		"knowsuchagency/mcp2cli",
+		"--skill",
+		"mcp2cli"
+	], { stdio: "pipe" });
+	if (skillAdd.status !== 0) {
+		console.warn(`  ⚠ mcp2cli skill install failed: ${skillAdd.stderr?.toString().trim()}`);
+		console.warn("  Install manually: npx skills add knowsuchagency/mcp2cli --skill mcp2cli");
+	} else console.log("  ✓ mcp2cli skill installed");
+	if (spawnSync("mcp2cli", [
+		"bake",
+		"show",
+		"context-mode"
+	], { stdio: "pipe" }).status === 0) {
+		console.log("  ✓ mcp2cli @context-mode already baked");
+		return;
+	}
+	if (!existsSync(startScript)) {
+		console.warn("  ⚠ context-mode start.mjs not found — skipping bake (run init again after context-mode installs)");
+		return;
+	}
+	const bakeCreate = spawnSync("mcp2cli", [
+		"bake",
+		"create",
+		"context-mode",
+		"--mcp-stdio",
+		`node ${startScript}`
+	], { stdio: "pipe" });
+	if (bakeCreate.status !== 0) console.warn(`  ⚠ mcp2cli bake failed: ${bakeCreate.stderr?.toString().trim()}`);
+	else console.log("  ✓ mcp2cli @context-mode baked — agent can now call: mcp2cli @context-mode <tool>");
+}
+/**
+* Bakes the context7 cloud MCP server as @context7 and installs the
+* netresearch context7 Claude Code skill for general-purpose library research.
+*
+* Non-fatal — failures are logged as warnings, never abort init.
+*/
+function setupContext7() {
+	console.log("\n[context7 MCP bake + skill]");
+	if (spawnSync("mcp2cli", [
+		"bake",
+		"show",
+		"context7"
+	], { stdio: "pipe" }).status === 0) console.log("  ✓ mcp2cli @context7 already baked");
+	else {
+		const bakeCreate = spawnSync("mcp2cli", [
+			"bake",
+			"create",
+			"context7",
+			"--mcp",
+			"https://mcp.context7.com/mcp"
+		], { stdio: "pipe" });
+		if (bakeCreate.status !== 0) {
+			console.warn(`  ⚠ context7 bake failed: ${bakeCreate.stderr?.toString().trim()}`);
+			console.warn("  Install mcp2cli first: uv tool install mcp2cli");
+		} else console.log("  ✓ mcp2cli @context7 baked — agent can now call: mcp2cli @context7 resolve-library-id");
+	}
+	spawnSync("npx", [
+		"skills",
+		"add",
+		"knowsuchagency/mcp2cli",
+		"--skill",
+		"mcp2cli"
+	], { stdio: "pipe" });
+	if (spawnSync("claude", [
+		"plugin",
+		"marketplace",
+		"add",
+		"netresearch/claude-code-marketplace"
+	], { stdio: "pipe" }).status !== 0) {
+		console.warn("  ⚠ context7 skill install failed (netresearch marketplace unavailable)");
+		console.warn("  Install manually: claude plugin marketplace add netresearch/claude-code-marketplace");
+	} else console.log("  ✓ context7 Claude Code skill installed — use /context7 for library research");
+}
+//#endregion
+export { runInit };

package/extensions/agent-chain.ts

@@ -0,0 +1,254 @@
+import { spawn } from "node:child_process";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { appendFileSync } from "node:fs";
+import { db } from "../state/db.js";
+import {
+  FB_DIR,
+  CHAIN_EVENTS_FILE,
+  PLANNING_ARTIFACTS_DIR,
+  IMPL_ARTIFACTS_DIR,
+  CHAIN_STEP_TIMEOUT_MS,
+  ARTIFACT_MIN_BYTES,
+} from "../config/constants.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENTS_DIR = resolve(__dirname, "../agents");
+const CHAIN_EVENTS_PATH = join(FB_DIR, CHAIN_EVENTS_FILE);
+const PREV_ARTIFACT_MAX_CHARS = 4096;
+
+interface ChainStep {
+  phase: string;
+  specialist: string;
+  artifactFile: string; // relative to artifactDir
+  tools: string[];
+}
+
+export const CHAIN_STEPS: ChainStep[] = [
+  {
+    phase: "requirements",
+    specialist: "frappe-ba",
+    artifactFile: "planning-artifacts/requirements.md",
+    tools: ["Read", "Write", "get_frappe_docs"],
+  },
+  {
+    phase: "architecture",
+    specialist: "frappe-architect",
+    artifactFile: "planning-artifacts/architecture.md",
+    tools: ["Read", "Write", "get_frappe_docs"],
+  },
+  {
+    phase: "planning",
+    specialist: "frappe-planner",
+    artifactFile: "planning-artifacts/plan.md",
+    tools: ["Read", "Write", "create_component"],
+  },
+  {
+    phase: "implementation",
+    specialist: "frappe-dev",
+    artifactFile: "implementation-artifacts/sprint-status.yaml",
+    tools: ["Read", "Write", "Edit", "Bash", "create_component", "complete_component", "bench_execute"],
+  },
+  {
+    phase: "testing",
+    specialist: "frappe-qa",
+    artifactFile: "implementation-artifacts/test-report.md",
+    tools: ["Read", "Write", "Bash", "bench_execute"],
+  },
+  {
+    phase: "documentation",
+    specialist: "frappe-docs",
+    artifactFile: "implementation-artifacts/docs.md",
+    tools: ["Read", "Write"],
+  },
+];
+
+const PHASE_TASKS: Record<string, string> = {
+  requirements:
+    "Analyse the feature description and produce requirements.md covering DocTypes, roles, process flows, and acceptance criteria.",
+  architecture:
+    "Design the Frappe-native technical solution based on the requirements above. Produce architecture.md covering DocType schemas, relationships, server logic, and permissions.",
+  planning:
+    "Break the architecture into ordered implementation components. Produce plan.md, then call create_component for every component listed.",
+  implementation:
+    "Implement every component from the plan in order. Call complete_component after each one passes tests.",
+  testing:
+    "Run the full test suite, verify all acceptance criteria, check the permission matrix, and produce test-report.md with Result: PASS.",
+  documentation:
+    "Document the implemented feature — DocType fields, hooks, docstrings, and changelog entry — and produce docs.md.",
+};
+
+function appendChainEvent(entry: Record<string, unknown>): void {
+  try {
+    mkdirSync(FB_DIR, { recursive: true });
+    appendFileSync(CHAIN_EVENTS_PATH, JSON.stringify({ ts: new Date().toISOString(), ...entry }) + "\n", "utf-8");
+  } catch { /* non-fatal */ }
+}
+
+function readArtifact(artifactDir: string, artifactFile: string): string | null {
+  try {
+    const content = readFileSync(join(artifactDir, artifactFile), "utf-8");
+    return content.slice(0, PREV_ARTIFACT_MAX_CHARS);
+  } catch {
+    return null;
+  }
+}
+
+function verifyArtifact(artifactDir: string, artifactFile: string): boolean {
+  try {
+    const content = readFileSync(join(artifactDir, artifactFile), "utf-8");
+    return content.length >= ARTIFACT_MIN_BYTES;
+  } catch {
+    return false;
+  }
+}
+
+function buildTaskPrompt(
+  step: ChainStep,
+  featureId: string,
+  featureName: string,
+  artifactDir: string,
+  prevArtifact: string | null,
+): string {
+  const prevSection = prevArtifact
+    ? `## Previous Phase Output\n\`\`\`\n${prevArtifact}\n\`\`\`\n\n`
+    : "";
+
+  return [
+    `Feature: "${featureName}" (ID: ${featureId})`,
+    `Artifact directory: ${artifactDir}`,
+    "",
+    prevSection,
+    `## Your Task`,
+    PHASE_TASKS[step.phase],
+    "",
+    `Write your output to: ${join(artifactDir, step.artifactFile)}`,
+    `Do not stop until the artifact file exists with substantive content.`,
+  ].join("\n");
+}
+
+function runSubprocess(
+  step: ChainStep,
+  taskPrompt: string,
+): Promise<{ exitCode: number; stderr: string }> {
+  return new Promise((resolvePromise) => {
+    const agentFile = join(AGENTS_DIR, `${step.specialist}.md`);
+    let systemPrompt = "";
+    try {
+      systemPrompt = readFileSync(agentFile, "utf-8");
+    } catch {
+      systemPrompt = `You are ${step.specialist}, a Frappe specialist. ${PHASE_TASKS[step.phase]}`;
+    }
+
+    const args = [
+      "--mode", "json",
+      "-p",
+      "--no-extensions",
+      "--tools", step.tools.join(","),
+      "--append-system-prompt", systemPrompt,
+      taskPrompt,
+    ];
+
+    const proc = spawn("pi", args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env },
+    });
+
+    const stderrChunks: string[] = [];
+    proc.stderr?.setEncoding("utf-8");
+    proc.stderr?.on("data", (chunk: string) => stderrChunks.push(chunk));
+
+    // Hard timeout per step
+    const timer = setTimeout(() => proc.kill("SIGTERM"), CHAIN_STEP_TIMEOUT_MS);
+
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      resolvePromise({
+        exitCode: code ?? 1,
+        stderr: stderrChunks.slice(-20).join("").slice(-2000),
+      });
+    });
+  });
+}
+
+function updateDb(featureId: string, phase: string, chainStep: string | null): void {
+  try {
+    db.transaction(() => {
+      db.prepare("UPDATE sessions SET chain_step = ? WHERE is_active = 1").run(chainStep);
+      db.prepare("UPDATE features SET current_phase = ? WHERE feature_id = ?").run(phase, featureId);
+    })();
+  } catch { /* non-fatal — chain continues */ }
+}
+
+/**
+ * Runs the full agent chain for a feature. Fire-and-forget: called via setImmediate from startFeature.
+ * Each phase spawns an isolated pi subprocess with a specialist system prompt.
+ * Artifacts are passed between phases via files in artifactDir.
+ */
+export async function spawnChain(
+  featureId: string,
+  featureName: string,
+  artifactDir: string,
+): Promise<void> {
+  appendChainEvent({ featureId, featureName, status: "chain_started" });
+
+  let prevArtifact: string | null = null;
+
+  for (const step of CHAIN_STEPS) {
+    // Update state: chain is now on this phase
+    updateDb(featureId, step.phase, step.phase);
+    appendChainEvent({ featureId, phase: step.phase, status: "started" });
+
+    // Ensure artifact subdirs exist
+    const planningDir = join(artifactDir, PLANNING_ARTIFACTS_DIR);
+    const implDir = join(artifactDir, IMPL_ARTIFACTS_DIR);
+    mkdirSync(planningDir, { recursive: true });
+    mkdirSync(implDir, { recursive: true });
+
+    const taskPrompt = buildTaskPrompt(step, featureId, featureName, artifactDir, prevArtifact);
+
+    // Run subprocess — retry once if artifact missing despite exit 0
+    let result = await runSubprocess(step, taskPrompt);
+    const artifactOk = verifyArtifact(artifactDir, step.artifactFile);
+
+    if (result.exitCode === 0 && !artifactOk) {
+      // Retry with explicit nudge
+      const retryPrompt = taskPrompt +
+        `\n\nWARNING: Your artifact was not detected at ${join(artifactDir, step.artifactFile)}. ` +
+        `You MUST write this file before exiting.`;
+      result = await runSubprocess(step, retryPrompt);
+    }
+
+    if (result.exitCode !== 0 || !verifyArtifact(artifactDir, step.artifactFile)) {
+      // Chain failed — write error file and update state
+      const errorContent = [
+        `# Chain Error`,
+        `Phase: ${step.phase}`,
+        `Exit code: ${result.exitCode}`,
+        `Artifact expected: ${join(artifactDir, step.artifactFile)}`,
+        `Artifact found: ${verifyArtifact(artifactDir, step.artifactFile)}`,
+        ``,
+        `## Stderr (last 2000 chars)`,
+        result.stderr,
+      ].join("\n");
+
+      try {
+        writeFileSync(join(artifactDir, "chain_error.md"), errorContent, "utf-8");
+      } catch { /* non-fatal */ }
+
+      updateDb(featureId, "chain_failed", null);
+      appendChainEvent({ featureId, phase: step.phase, status: "failed", exitCode: result.exitCode });
+      return;
+    }
+
+    appendChainEvent({ featureId, phase: step.phase, status: "complete" });
+
+    // Pass this phase's artifact to the next phase
+    prevArtifact = readArtifact(artifactDir, step.artifactFile);
+  }
+
+  // All steps complete
+  updateDb(featureId, "done", null);
+  appendChainEvent({ featureId, status: "chain_complete" });
+}