pi-super-dev 0.1.0

package/src/pi-spawn.ts

@@ -0,0 +1,296 @@
+/**
+ * Spawns `pi` child processes to run specialist agents — the single primitive
+ * that replaces pi-workflow's agent engine. Verified invocation:
+ *
+ *   pi --mode json -p --no-session --no-skills [--no-extensions] \
+ *      --tools read,bash,edit,write,ffgrep,fffind \
+ *      [--model <provider/id>] --system-prompt <temp-file> "Task: <prompt>"
+ *
+ * stdout is newline-delimited JSON; the final assistant text is in the last
+ * `{"type":"message_end","message":{"role":"assistant",...}}` event.
+ */
+
+import { spawn } from "node:child_process";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadAgentPrompt } from "./agents.ts";
+import { extractControl } from "./control.ts";
+import type { AgentProgress, SpawnResult } from "./types.ts";
+
+const BASE_TOOLS = "read,bash,edit,write,ffgrep,fffind";
+
+/** Agents that drive a browser for UI testing. They receive the `browser_execute`
+ *  tool and load extensions (so pi-browser-cdp-extension is available). The
+ *  `--tools` allowlist still keeps every other extension tool (e.g. `subagent`)
+ *  disabled, so this stays isolated. Browser connection uses AUTO-DISCOVERY —
+ *  `await session.connect()` with no args finds any Chrome started with
+ *  `--remote-debugging-port`; see agents/qa-agent.md. */
+const BROWSER_AGENTS = new Set(["qa-agent"]);
+
+export function isBrowserAgent(agent: string): boolean {
+	return BROWSER_AGENTS.has(agent);
+}
+
+export function toolsForAgent(agent: string): string {
+	return BROWSER_AGENTS.has(agent) ? `${BASE_TOOLS},browser_execute` : BASE_TOOLS;
+}
+
+/** Per-spawn wall-clock cap. Generous: capable agents legitimately take 1–2 min. */
+const DEFAULT_SPAWN_TIMEOUT_MS = 480_000;
+
+export interface SpawnAgentOptions {
+	agent: string;
+	prompt: string;
+	cwd: string;
+	model?: string;
+	signal?: AbortSignal;
+	id?: string;
+	timeoutMs?: number;
+	/** Ignored by the subprocess backend (it uses <control> text, not a schema).
+	 *  Accepted so the same `common` options object can feed both backends. */
+	controlKeys?: string[];
+	/** Live progress from the spawned agent (tool calls + streaming text). */
+	onProgress?: AgentProgress;
+}
+
+function resolvePiBinary(): { command: string; args: string[] } {
+	const argv1 = process.argv[1] ?? "";
+	if (argv1 && /\.(?:mjs|cjs|js)$/i.test(argv1)) {
+		return { command: process.execPath, args: [argv1] };
+	}
+	return { command: "pi", args: [] };
+}
+
+export async function spawnAgent(opts: SpawnAgentOptions): Promise<SpawnResult> {
+	const systemPrompt = loadAgentPrompt(opts.agent);
+	const tempDir = mkdtempSync(join(tmpdir(), "super-dev-agent-"));
+	const promptPath = join(tempDir, "agent.md");
+	writeFileSync(promptPath, systemPrompt, { mode: 0o600 });
+
+	const args = buildSpawnArgs(opts, promptPath);
+	const result = await runPi(args, opts.cwd, opts.signal, opts.id ?? opts.agent, opts.timeoutMs ?? DEFAULT_SPAWN_TIMEOUT_MS, opts.onProgress);
+	rmSync(tempDir, { recursive: true, force: true });
+	return result;
+}
+
+/**
+ * Build the full argv vector for a specialist spawn, INCLUDING the executable
+ * as element 0. (Extracted so the command resolution is unit-testable — a
+ * previous version dropped `command` and tried to exec "--mode", causing
+ * `spawn --mode ENOENT` on every single agent spawn.)
+ *
+ * Browser-capable agents (see BROWSER_AGENTS) omit `--no-extensions` so the
+ * pi-browser-cdp-extension loads, and add `browser_execute` to the tool set.
+ * The `--tools` allowlist still restricts active tools to the declared set.
+ */
+export function buildSpawnArgs(opts: SpawnAgentOptions, promptPath: string): string[] {
+	const { command, args: prefix } = resolvePiBinary();
+	const browser = isBrowserAgent(opts.agent);
+	const args = [
+		command, // ← the executable ("pi" on PATH, or `node` re-invoking the host entry)
+		...prefix,
+		"--mode", "json", "-p", "--no-session", "--no-skills",
+	];
+	// Browser agents need pi-browser-cdp-extension loaded, so they do NOT pass
+	// --no-extensions. The --tools allowlist below still restricts active tools
+	// to the declared set (so loading extensions doesn't enable e.g. `subagent`).
+	if (!browser) args.push("--no-extensions");
+	args.push("--tools", toolsForAgent(opts.agent));
+	args.push("--system-prompt", promptPath);
+	if (opts.model) args.push("--model", opts.model);
+	args.push(`Task: ${opts.prompt}`);
+	return args;
+}
+
+function runPi(args: string[], cwd: string, signal: AbortSignal | undefined, label: string, timeoutMs: number, onProgress?: AgentProgress): Promise<SpawnResult> {
+	return new Promise((resolve, reject) => {
+		const child = spawn(args[0], args.slice(1), {
+			cwd,
+			stdio: ["ignore", "pipe", "pipe"],
+			env: { ...process.env },
+			windowsHide: true,
+		});
+		// Bounded capture ONLY: the spawned agent's stdout is a stream of NDJSON
+		// deltas where each message_update re-emits the FULL accumulated partial —
+		// gigabytes for a verbose/long agent (the design stage crashed pi with
+		// RangeError "Invalid string length" at >512MB). Never buffer the whole
+		// stdout; parse line-by-line and keep only the last assistant text.
+		let lineBuf = "";
+		let lastAssistantText = "";
+		let lastModel: string | undefined;
+		let stderrBuf = "";
+		let aborted = false;
+		let timedOut = false;
+		let turns = 0;
+		let currentText = ""; // live streaming text of the current agent text block
+		const STDERR_CAP = 16 * 1024;
+		const LINE_CAP = 16 * 1024 * 1024;
+		const cleanup = () => {
+			signal?.removeEventListener("abort", onAbort);
+			clearTimeout(timer);
+		};
+		const onAbort = () => {
+			aborted = true;
+			try { child.kill("SIGTERM"); } catch { /* ignore */ }
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+		const timer = setTimeout(() => {
+			timedOut = true;
+			try { child.kill("SIGTERM"); } catch { /* ignore */ }
+		}, timeoutMs);
+
+		child.stdout.on("data", (c: Buffer) => {
+			lineBuf += c.toString("utf8");
+			let nl: number;
+			while ((nl = lineBuf.indexOf("\n")) >= 0) {
+				const raw = lineBuf.slice(0, nl);
+				lineBuf = lineBuf.slice(nl + 1);
+				const trimmed = raw.trim();
+				if (!trimmed) continue;
+				let ev: PiJsonEvent;
+				try { ev = JSON.parse(trimmed) as PiJsonEvent; } catch { continue; }
+				// capture the final assistant text (for <control> extraction)
+				const a = assistantFromMessageEnd(ev);
+				if (a) {
+					if (a.text) { lastAssistantText = a.text; if (a.model) lastModel = a.model; }
+					// a finished message finalizes any in-progress live text
+					if (onProgress && currentText.trim()) { onProgress.event(stripControl(currentText).trim()); currentText = ""; }
+					continue;
+				}
+				if (!onProgress) continue;
+				const se = renderEvent(ev, () => ++turns);
+				if (!se) continue;
+				if (se.kind === "text") {
+					// live typing: update the mutable live line
+					currentText = se.text;
+					onProgress.text(stripControl(currentText));
+				} else {
+					// a permanent event finalizes any in-progress text first
+					if (currentText.trim()) { onProgress.event(stripControl(currentText).trim()); currentText = ""; }
+					if (se.kind === "tool") onProgress.event(`→ ${se.summary}`);
+					else if (se.kind === "turn" && se.n > 1) onProgress.event(`turn ${se.n}`);
+				}
+			}
+			if (lineBuf.length > LINE_CAP) lineBuf = ""; // stay bounded on a runaway line
+		});
+		child.stderr.on("data", (c: Buffer) => {
+			stderrBuf += c.toString("utf8");
+			if (stderrBuf.length > STDERR_CAP) stderrBuf = stderrBuf.slice(stderrBuf.length - STDERR_CAP);
+		});
+		child.on("error", (err) => {
+			cleanup();
+			reject(new Error(`super-dev [${label}]: failed to spawn pi: ${err.message}`));
+		});
+		child.on("close", (code) => {
+			cleanup();
+			if (aborted) { resolve({ text: "", control: null, error: "aborted" }); return; }
+			// lastAssistantText already holds the last non-empty assistant text
+			// (resilient to a trailing tool-call turn or a mid-stream kill).
+			if (lastAssistantText) {
+				resolve({ text: lastAssistantText, control: extractControl(lastAssistantText), model: lastModel, error: timedOut ? `timed out after ${timeoutMs}ms (used partial output)` : undefined });
+				return;
+			}
+			const tail = stderrBuf.trim().split("\n").slice(-3).join(" | ");
+			const reason = timedOut ? `timed out after ${Math.round(timeoutMs / 1000)}s` : `produced no output (exit ${code})`;
+			reject(new Error(`super-dev [${label}]: agent ${reason}.${tail ? ` stderr: ${tail}` : ""}`));
+		});
+	});
+}
+
+interface PiJsonEvent {
+	type?: string;
+	toolName?: string;
+	args?: Record<string, unknown>;
+	message?: { role?: string; model?: string; content?: Array<{ type: string; text?: string }> };
+}
+
+/** If an event is an assistant message_end, return its text + model (shared by
+ *  the streaming capture and the batch extractFinalAssistant). */
+function assistantFromMessageEnd(ev: PiJsonEvent): { text: string; model?: string } | null {
+	if (ev.type !== "message_end" || ev.message?.role !== "assistant") return null;
+	const text = (ev.message.content ?? [])
+		.filter((p) => p.type === "text" && typeof p.text === "string")
+		.map((p) => p.text as string)
+		.join("");
+	return { text, model: ev.message.model };
+}
+
+/** Compact one-line summary of a tool call, for live progress.
+ *  Paths/commands are shown IN FULL (no truncation, no abbreviation) — the
+ *  TUI wraps long lines, same as it does for read/write. */
+export function summarizeToolCall(name: string, args: Record<string, unknown> | undefined): string {
+	const a = args ?? {};
+	switch (name) {
+		case "write":
+		case "edit":
+		case "read":
+			return `${name} ${a.path ?? a.file_path ?? ""}`;
+		case "bash":
+			return `$ ${String(a.command ?? "").split("\n")[0]}`;
+		case "ffgrep":
+		case "fffind":
+			return `${name} "${a.pattern ?? ""}"`;
+		default:
+			return name;
+	}
+}
+
+/** Shorten a path/string for display: cwd => ".", $HOME => "~". Keeps live
+ *  progress readable instead of being truncated mid-path by the TUI. */
+export function abbreviatePath(p: string, cwd?: string): string {
+	if (!p) return p;
+	let out = p;
+	if (cwd && cwd.length > 1 && out.includes(cwd)) out = out.split(cwd).join(".");
+	const home = process.env.HOME;
+	if (home && out.startsWith(home)) out = "~" + out.slice(home.length);
+	return out;
+}
+
+/** Parse one streamed NDJSON line: surface live progress AND capture the
+ *  assistant text. Returns {text,model} if the line is an assistant message_end. */
+type StreamEvent =
+	| { kind: "text"; text: string }
+	| { kind: "tool"; summary: string }
+	| { kind: "turn"; n: number };
+
+/** Strip the machine <control> block from displayed text. */
+function stripControl(s: string): string {
+	return s.replace(/<control>[\s\S]*?<\/control>/gi, "");
+}
+
+/** Extract a renderable event from a parsed NDJSON line (pure).
+ *  pi streams assistant text inside `message_update` events whose `message.content`
+ *  holds the full accumulated text so far. */
+export function renderEvent(ev: PiJsonEvent, nextTurn: () => number): StreamEvent | null {
+	switch (ev.type) {
+		case "message_update": {
+			const text = (ev.message?.content ?? []).filter((p) => p.type === "text").map((p) => p.text ?? "").join("");
+			return text ? { kind: "text", text } : null;
+		}
+		case "tool_execution_start":
+			return ev.toolName ? { kind: "tool", summary: summarizeToolCall(ev.toolName, ev.args) } : null;
+		case "turn_start":
+			return { kind: "turn", n: nextTurn() };
+		default:
+			return null;
+	}
+}
+
+export function extractFinalAssistant(stdout: string): { text: string; model?: string } {
+	let text = "";
+	let model: string | undefined;
+	for (const line of stdout.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		let event: PiJsonEvent;
+		try { event = JSON.parse(trimmed) as PiJsonEvent; } catch { continue; }
+		// Keep the LAST NON-EMPTY assistant text — never overwrite with empty,
+		// so a trailing tool-call-only turn doesn't discard the control block
+		// emitted in an earlier turn.
+		const r = assistantFromMessageEnd(event);
+		if (r && r.text) { text = r.text; if (r.model) model = r.model; }
+	}
+	return { text, model };
+}
+

package/src/pipeline.ts

@@ -0,0 +1,15 @@
+/**
+ * Thin public entry: run the super-dev workflow for a task.
+ */
+
+import { runWorkflow } from "./workflow.ts";
+import { SUPER_DEV_WORKFLOW } from "./stages/index.ts";
+import type { RunOptions, RunSummary } from "./types.ts";
+
+export async function runPipelineTask(task: string, options: RunOptions = {}): Promise<RunSummary> {
+	return runWorkflow(SUPER_DEV_WORKFLOW, task, options);
+}
+
+export { SUPER_DEV_WORKFLOW } from "./stages/index.ts";
+export { runWorkflow } from "./workflow.ts";
+export type { RunSummary, RunOptions, Workflow, Node, NodeResult, PipelineState } from "./types.ts";

package/src/prompts.ts

@@ -0,0 +1,120 @@
+/**
+ * Prompt builders for each pipeline stage. Ported from the original controller
+ * so agent `<control>` JSON contracts are unchanged.
+ *
+ * Doc NUMBERING is COMPUTED, never hardcoded: a stage's number = (number of
+ * numbered docs already in the spec dir) + 1. So the sequence is dense and
+ * follows actual execution order — a skipped stage (debug for a feature,
+ * prototype when there are no numeric constants) writes no file and consumes
+ * no number, so code-assessment lands on 04 when debug is skipped and 05 when
+ * debug runs. The current stage's own slug is excluded from the count so gate
+ * retries don't inflate it; spec's three docs take base, base+1, base+2.
+ */
+
+import { readdirSync } from "node:fs";
+import type { SetupControl, Classification, ControlObj } from "./types.ts";
+
+type R = ControlObj | null | undefined;
+
+/** Next doc number = count of existing `NN-*` files in the spec dir (excluding
+ *  any whose name ends in `-<slug>.md` for the given slugs) + 1. */
+function nextDocNumber(specDir: string, excludeSlugs: string[] = []): number {
+	let count = 0;
+	try {
+		for (const entry of readdirSync(specDir)) {
+			if (!/^\d{2}-.+/.test(entry)) continue;
+			if (excludeSlugs.some((sg) => entry.endsWith(`-${sg}.md`))) continue;
+			count++;
+		}
+	} catch { /* dir not readable yet — treat as empty */ }
+	return count + 1;
+}
+
+const pad = (n: number) => String(n).padStart(2, "0");
+
+/** A single stage's doc path: next free number + the slug. */
+function specDoc(s: SetupControl, slug: string): string {
+	return `${s.specDirectory}${pad(nextDocNumber(s.specDirectory, [slug]))}-${slug}.md`;
+}
+
+/** A stage that writes several docs at once (the spec stage): they take
+ *  consecutive numbers base, base+1, … in the given slug order. */
+function specDocRange(s: SetupControl, slugs: string[]): string[] {
+	const base = nextDocNumber(s.specDirectory, slugs);
+	return slugs.map((slug, i) => `${s.specDirectory}${pad(base + i)}-${slug}.md`);
+}
+
+function ctxBlock(setup: SetupControl, c: Classification | null): string {
+	return ["## Context", `- Worktree: ${setup.worktreePath}`, `- Spec Directory: ${setup.specDirectory}`, `- Language: ${c?.language ?? setup.language}`, `- Task Type: ${c?.taskType ?? "unknown"}`, `- UI Scope: ${c?.uiScope ?? "none"}`, `- Default Branch: ${setup.defaultBranch ?? "main"}`].join("\n");
+}
+
+export function buildRequirementsPrompt(s: SetupControl, c: Classification | null, task: string): string {
+	return [ctxBlock(s, c), "", "## Task", task, "", "## Instructions", "Produce an implementation-ready requirements document.", `Write the document to: ${specDoc(s, "requirements")}`, "Include: feature name, acceptance criteria (numbered AC-XX), open questions, and a summary.", "", "Output <control> JSON with: docPath, featureName, acCount, openQuestions, summary."].join("\n");
+}
+export function buildBddPrompt(s: SetupControl, c: Classification | null, task: string, requirements: R): string {
+	return [ctxBlock(s, c), "", "## Upstream Artifacts", `- Requirements: ${(requirements?.docPath as string) ?? "N/A"}`, "", "## Task", task, "", "## Instructions", "Write BDD behavior scenarios in Gherkin-like markdown from the requirements acceptance criteria.", `Write to: ${specDoc(s, "bdd-scenarios")}`, "Cover happy paths, edge cases, and error scenarios.", "", "Output <control> JSON with: docPath, scenarioCount, edgeCasesCovered, coverageScore, summary."].join("\n");
+}
+export function buildResearchPrompt(s: SetupControl, c: Classification | null, task: string, requirements: R, bdd: R, prev: R): string {
+	const parts = [ctxBlock(s, c), "", "## Upstream Artifacts", `- Requirements: ${(requirements?.docPath as string) ?? "N/A"}`, `- BDD Scenarios: ${(bdd?.docPath as string) ?? "N/A"}`];
+	if (prev?.docPath) { parts.push(`- Previous Research: ${prev.docPath as string}`); const oi = prev.openIssues as string[] | undefined; if (Array.isArray(oi) && oi.length) parts.push(`- Open Issues to resolve: ${oi.join(", ")}`); }
+	parts.push("", "## Task", task, "", "## Instructions", "Research best practices, documentation, and patterns relevant to this task.", `Write to: ${specDoc(s, "research-report")}`, "Identify options, tradeoffs, and open issues. Resolve any previously open issues.", "", "Output <control> JSON with: docPath, options (array), openIssues (array), iteration, summary.");
+	return parts.join("\n");
+}
+export function buildDebugPrompt(s: SetupControl, c: Classification | null, task: string, requirements: R, research: R): string {
+	return [ctxBlock(s, c), "", "## Upstream Artifacts", `- Requirements: ${(requirements?.docPath as string) ?? "N/A"}`, `- Research: ${(research?.docPath as string) ?? "N/A"}`, "", "## Task", task, "", "## Instructions", "Perform systematic root-cause debugging with evidence collection.", `Write to: ${specDoc(s, "debug-analysis")}`, "Include: hypotheses, reproduction steps, root cause, and recommended fix.", "", "Output <control> JSON with: docPath, hypotheses (array), rootCause, reproductionSteps, summary."].join("\n");
+}
+export function buildAssessmentPrompt(s: SetupControl, c: Classification | null, task: string, research: R, debug: R): string {
+	const parts = [ctxBlock(s, c), "", "## Upstream Artifacts", `- Research: ${(research?.docPath as string) ?? "N/A"}`];
+	if (debug?.docPath) parts.push(`- Debug Analysis: ${debug.docPath as string}`);
+	parts.push("", "## Task", task, "", "## Instructions", "Assess the existing codebase: architecture patterns, coding standards, dependencies, and framework conventions.", `Write to: ${specDoc(s, "code-assessment")}`, "Identify patterns to follow, anti-patterns to avoid, and relevant files.", "", "Output <control> JSON with: docPath, patterns (array of objects), filesAssessed, recommendations, summary.");
+	return parts.join("\n");
+}
+export function buildDesignPrompt(s: SetupControl, c: Classification | null, task: string, requirements: R, research: R, assessment: R, designerAgent: string): string {
+	return [ctxBlock(s, c), "", "## Upstream Artifacts", `- Requirements: ${(requirements?.docPath as string) ?? "N/A"}`, `- Research: ${(research?.docPath as string) ?? "N/A"}`, `- Code Assessment: ${(assessment?.docPath as string) ?? "N/A"}`, "", "## Task", task, "", "## Instructions", `You are the ${designerAgent}. Design the architecture/UI for this feature.`, `Write to: ${specDoc(s, "design")}`, "Include: module decomposition, interfaces, data flow, and any numeric constants that need validation.", "", "Output <control> JSON with: designer, docs (array of paths), modules (array of objects), hasNumericConstants, summary."].join("\n");
+}
+export function buildPrototypePrompt(s: SetupControl, c: Classification | null, task: string, design: R, constants: string[], round: number): string {
+	return [ctxBlock(s, c), "", "## Design", `- Design doc: ${(design?.docs as string[] | undefined)?.[0] ?? "N/A"}`, `- Constants to validate: ${(constants ?? []).join(", ")}`, "", "## Task", task, "", "## Instructions", `Prototype round ${round}: Empirically validate the numeric design constants.`, "Build a minimal prototype, measure against representative input, and report pass/fail.", `Write the report to: ${specDoc(s, "prototype-report")}`, "", "Output <control> JSON with: docPath, verdict ('pass' or 'fail'), measurements (array), adjustments (array), summary."].join("\n");
+}
+export function buildSpecPrompt(s: SetupControl, c: Classification | null, task: string, requirements: R, bdd: R, research: R, assessment: R, design: R): string {
+	const parts = [ctxBlock(s, c), "", "## Upstream Artifacts", `- Requirements: ${(requirements?.docPath as string) ?? "N/A"}`, `- BDD Scenarios: ${(bdd?.docPath as string) ?? "N/A"}`, `- Research: ${(research?.docPath as string) ?? "N/A"}`, `- Code Assessment: ${(assessment?.docPath as string) ?? "N/A"}`];
+	const docs = design?.docs as string[] | undefined;
+	if (Array.isArray(docs) && docs.length) parts.push(`- Design: ${docs.join(", ")}`);
+	const [specification, plan, tasks] = specDocRange(s, ["specification", "implementation-plan", "task-list"]);
+	parts.push("", "## Task", task, "", "## Instructions", "Write the technical specification, implementation plan, and task list.", `Write specification to: ${specification}`, `Write plan to: ${plan}`, `Write task list to: ${tasks}`, "Break implementation into phases. Each phase must be independently testable.", "", "Output <control> JSON with: specificationPath, planPath, tasksPath, phaseCount, phases (array with name/description per phase), summary.");
+	return parts.join("\n");
+}
+export function buildSpecReviewPrompt(s: SetupControl, c: Classification | null, specControl: R): string {
+	return [ctxBlock(s, c), "", "## Specification to Review", `- Specification: ${(specControl?.specificationPath as string) ?? "N/A"}`, `- Plan: ${(specControl?.planPath as string) ?? "N/A"}`, `- Tasks: ${(specControl?.tasksPath as string) ?? "N/A"}`, `- Phases: ${(specControl?.phaseCount as number) ?? 0}`, "", "## Instructions", "Review the specification across 8 quality dimensions: completeness, correctness, consistency, testability, feasibility, security, performance, and maintainability.", "Score each dimension 1-5. Produce a verdict.", `Write the review to: ${specDoc(s, "spec-review")}`, "", "Output <control> JSON with: docPath, verdict ('Approved'|'Approved with Comments'|'Changes Requested'), findings (array), dimensionsScored (array), summary."].join("\n");
+}
+export function buildTddPrompt(s: SetupControl, c: Classification | null, phase: { name: string; description?: string }, specControl: R): string {
+	return [ctxBlock(s, c), "", "## Implementation Phase", `- Phase: ${phase.name}`, `- Description: ${phase.description ?? ""}`, `- Specification: ${(specControl?.specificationPath as string) ?? "N/A"}`, "", "## Instructions", "Write failing tests FIRST for this implementation phase.", "Tests should cover the acceptance criteria and edge cases.", "Run the tests to confirm they fail (red phase of TDD).", "", "Output <control> JSON with: testsWritten (number), testFiles (array of paths), allFailing (boolean), summary."].join("\n");
+}
+export function buildImplementPrompt(s: SetupControl, c: Classification | null, phase: { name: string; description?: string }, specialist: R, specControl: R): string {
+	const li = (specialist?.languageInstructions as string) ?? "";
+	return [ctxBlock(s, c), "", "## Implementation Phase", `- Phase: ${phase.name}`, `- Description: ${phase.description ?? ""}`, `- Specification: ${(specControl?.specificationPath as string) ?? "N/A"}`, "", li ? `## Language-Specific Instructions\n${li}\n` : "", "## Instructions", "Implement the code to make the failing tests pass (green phase of TDD).", "Follow existing patterns from the code assessment. Keep changes minimal and focused.", "", "Output <control> JSON with: filesModified (array), testsPassCount (number), summary."].join("\n");
+}
+export function buildQaPrompt(s: SetupControl, c: Classification | null, phase: { name: string }): string {
+	return [ctxBlock(s, c), "", "## Implementation Phase", `- Phase: ${phase.name}`, "", "## Instructions", "Run the full test suite and verify build succeeds.", "Check coverage meets threshold. Report any regressions.", "", "Output <control> JSON with: allTestsPass (boolean), buildSuccess (boolean), coveragePercent (number), regressions (array), summary."].join("\n");
+}
+export function buildImplementationSummaryPrompt(s: SetupControl, c: Classification | null, impl: R): string {
+	return [ctxBlock(s, c), "", "## Implementation Result", `- Phases Completed: ${(impl?.phasesCompleted as number) ?? 0}/${(impl?.totalPhases as number) ?? 0}`, `- All Green: ${(impl?.allGreen as boolean) ?? false}`, `- Files Modified: ${((impl?.filesModified as string[]) ?? []).join(", ") || "none"}`, "", "## Instructions", "Write a concise implementation summary: what was built per phase, files changed, test results, and any deviations from the specification.", `Write to: ${specDoc(s, "implementation-summary")}`, "", "Output <control> JSON with: docPath, phasesCompleted, allGreen, summary."].join("\n");
+}
+export function buildCodeReviewPrompt(s: SetupControl, c: Classification | null, task: string, specControl: R, implControl: R): string {
+	return [ctxBlock(s, c), "", "## Upstream Artifacts", `- Specification: ${(specControl?.specificationPath as string) ?? "N/A"}`, `- Phases Completed: ${(implControl?.phasesCompleted as number) ?? 0}/${(implControl?.totalPhases as number) ?? 0}`, "", "## Task", task, "", "## Instructions", "Review the implementation against the specification for correctness, security, performance, and maintainability.", "Produce a verdict and list findings with severity.", `Write the review to: ${specDoc(s, "code-review")}`, "", "Output <control> JSON with: docPath, verdict ('Approved'|'Approved with Comments'|'Changes Requested'), findings (array), dimensionsCovered (array), summary."].join("\n");
+}
+export function buildAdversarialPrompt(s: SetupControl, c: Classification | null, task: string, specControl: R, implControl: R): string {
+	return [ctxBlock(s, c), "", "## Upstream Artifacts", `- Specification: ${(specControl?.specificationPath as string) ?? "N/A"}`, `- Phases Completed: ${(implControl?.phasesCompleted as number) ?? 0}/${(implControl?.totalPhases as number) ?? 0}`, "", "## Task", task, "", "## Instructions", "Challenge the implementation from three critical lenses: Skeptic, Architect, Minimalist.", "Look for issues standard review misses: over-engineering, hidden complexity, missing error paths.", `Write the review to: ${specDoc(s, "adversarial-review")}`, "", "Output <control> JSON with: docPath, verdict ('Approved'|'Approved with Comments'|'Changes Requested'), findings (array), dimensionsCovered (array), summary."].join("\n");
+}
+export function buildFixPrompt(s: SetupControl, c: Classification | null, findings: unknown[]): string {
+	const list = (findings ?? []).map((f) => { const o = f as { severity?: string; title?: string; message?: string }; return `- [${o.severity ?? "medium"}] ${o.title ?? o.message ?? JSON.stringify(f)}`; }).join("\n");
+	return [ctxBlock(s, c), "", "## Code Review Findings to Address", list || "- (no specific findings)", "", "## Instructions", "Fix the issues identified in code review. Make minimal, targeted changes.", "Run tests after each fix to ensure no regressions.", "", "Output <control> JSON with: filesModified (array), fixesApplied (number), summary."].join("\n");
+}
+export function buildDocsPrompt(s: SetupControl, c: Classification | null, task: string, specControl: R): string {
+	return [ctxBlock(s, c), "", "## Task", task, "", "## Upstream Artifacts", `- Specification: ${(specControl?.specificationPath as string) ?? "N/A"}`, `- Spec Directory: ${s.specDirectory}`, "", "## Instructions", "Update documentation to reflect the implementation:", "- Review spec directory files for accuracy against the code", "- Update README, CHANGELOG, API docs as needed", "- Document any deviations from the specification", `Write a summary of documentation changes to: ${specDoc(s, "documentation")}`, "", "Output <control> JSON with: docPath, docsUpdated (boolean), specDirFilesReviewed (array), deviationsDocumented (array), summary."].join("\n");
+}
+export function buildCommitPrompt(s: SetupControl, phaseName: string): string {
+	return ["## Context", `- Worktree: ${s.worktreePath}`, "", "## Instructions", `Commit all changes for implementation phase: ${phaseName}`, "Use a conventional commit message that describes the phase work.", "Stage only files relevant to this phase."].join("\n");
+}
+export function buildMergePrompt(s: SetupControl): string {
+	return ["## Context", `- Worktree: ${s.worktreePath}`, `- Default Branch: ${s.defaultBranch ?? "main"}`, "", "## Instructions", "Merge the feature branch back into the default branch.", "Ensure all changes are committed. Create a merge commit with a summary of all work done.", "If there are conflicts, resolve them preserving the feature branch changes.", "", "Output <control> JSON with: merged (boolean), commitSha, mergeCommand, summary."].join("\n");
+}