@kodrunhq/opencode-autopilot 0.1.0

package/src/orchestrator/handlers/architect.ts

@@ -0,0 +1,114 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { sanitizeTemplateContent } from "../../review/sanitize";
+import { fileExists } from "../../utils/fs-helpers";
+import { getDebateDepth } from "../arena";
+import { ensurePhaseDir, getArtifactRef, getPhaseDir } from "../artifacts";
+import { filterByPhase } from "../confidence";
+import type { PipelineState } from "../types";
+import { AGENT_NAMES, type DispatchResult } from "./types";
+
+const CONSTRAINT_FRAMINGS: readonly string[] = Object.freeze([
+	"Optimize for simplicity and minimal dependencies",
+	"Optimize for extensibility and future growth",
+	"Optimize for performance and resource efficiency",
+]);
+
+/**
+ * ARCHITECT phase handler with Arena multi-proposal logic.
+ *
+ * Three-step flow using artifact-existence for idempotency:
+ * 1. No proposals/design -> dispatch architect(s) based on debate depth
+ * 2. Proposals exist but no critique -> dispatch critic
+ * 3. Critique or design exists -> complete
+ */
+export async function handleArchitect(
+	state: Readonly<PipelineState>,
+	artifactDir: string,
+	_result?: string,
+): Promise<DispatchResult> {
+	const phaseDir = getPhaseDir(artifactDir, "ARCHITECT");
+	const critiqueExists = await fileExists(join(phaseDir, "critique.md"));
+	const designExists = await fileExists(join(phaseDir, "design.md"));
+
+	// Step 3: critique or design exists -> complete
+	if (critiqueExists || designExists) {
+		return Object.freeze({
+			action: "complete" as const,
+			phase: "ARCHITECT",
+			progress: "ARCHITECT complete",
+		});
+	}
+
+	// Check for existing proposals (Step 2)
+	const proposalsDir = join(phaseDir, "proposals");
+	const hasProposals = await hasProposalFiles(proposalsDir);
+
+	if (hasProposals) {
+		return Object.freeze({
+			action: "dispatch" as const,
+			agent: AGENT_NAMES.CRITIC,
+			prompt: [
+				`Review architecture proposals in phases/ARCHITECT/proposals/`,
+				`Read ${getArtifactRef("RECON", "report.md")} and ${getArtifactRef("CHALLENGE", "brief.md")} for context.`,
+				`Write comparative critique to ${getArtifactRef("ARCHITECT", "critique.md")}`,
+				`Include: strengths, weaknesses, recommendation, confidence (HIGH/MEDIUM/LOW).`,
+			].join("\n"),
+			phase: "ARCHITECT",
+			progress: "Dispatching critic for proposal review",
+		});
+	}
+
+	// Step 1: Dispatch architect(s) based on confidence depth
+	await ensurePhaseDir(artifactDir, "ARCHITECT");
+	const reconEntries = filterByPhase(state.confidence, "RECON");
+	const depth = getDebateDepth(reconEntries);
+	const reconRef = getArtifactRef("RECON", "report.md");
+	const challengeRef = getArtifactRef("CHALLENGE", "brief.md");
+	const safeIdea = sanitizeTemplateContent(state.idea).replace(/[\r\n]+/g, " ");
+
+	if (depth === 1) {
+		return Object.freeze({
+			action: "dispatch" as const,
+			agent: AGENT_NAMES.ARCHITECT,
+			prompt: [
+				`Read ${reconRef} and ${challengeRef} for context.`,
+				`Design architecture for: ${safeIdea}`,
+				`Write design to ${getArtifactRef("ARCHITECT", "design.md")}`,
+				`Include: component diagram, data flow, technology choices, confidence (HIGH/MEDIUM/LOW).`,
+			].join("\n"),
+			phase: "ARCHITECT",
+			progress: "Dispatching architect for design",
+		});
+	}
+
+	const agents = CONSTRAINT_FRAMINGS.slice(0, depth).map((constraint, i) => {
+		const label = String.fromCharCode(65 + i); // A, B, C
+		return Object.freeze({
+			agent: AGENT_NAMES.ARCHITECT,
+			prompt: [
+				`Read ${reconRef} and ${challengeRef} for context.`,
+				`Design architecture for: ${safeIdea}`,
+				`Constraint: ${constraint}`,
+				`Write proposal to phases/ARCHITECT/proposals/proposal-${label}.md`,
+				`Include: component diagram, data flow, technology choices, confidence (HIGH/MEDIUM/LOW).`,
+			].join("\n"),
+		});
+	});
+
+	return Object.freeze({
+		action: "dispatch_multi" as const,
+		agents: Object.freeze(agents),
+		phase: "ARCHITECT",
+		progress: `Dispatching ${depth} architects for Arena proposals`,
+	});
+}
+
+async function hasProposalFiles(proposalsDir: string): Promise<boolean> {
+	try {
+		const entries = await readdir(proposalsDir);
+		return entries.some((e) => e.startsWith("proposal-") && e.endsWith(".md"));
+	} catch {
+		return false;
+	}
+}

package/src/orchestrator/handlers/build.ts

@@ -0,0 +1,363 @@
+import { sanitizeTemplateContent } from "../../review/sanitize";
+import { getArtifactRef } from "../artifacts";
+import { groupByWave } from "../plan";
+import type { BuildProgress, Task } from "../types";
+import type { DispatchResult, PhaseHandler } from "./types";
+import { AGENT_NAMES } from "./types";
+
+const MAX_STRIKES = 3;
+
+/**
+ * Find the first wave number that has PENDING tasks.
+ */
+function findCurrentWave(waveMap: ReadonlyMap<number, readonly Task[]>): number | null {
+	const sortedWaves = [...waveMap.keys()].sort((a, b) => a - b);
+	for (const wave of sortedWaves) {
+		const tasks = waveMap.get(wave) ?? [];
+		if (tasks.some((t) => t.status === "PENDING" || t.status === "IN_PROGRESS")) {
+			return wave;
+		}
+	}
+	return null;
+}
+
+/**
+ * Get pending tasks for a specific wave.
+ */
+function findPendingTasks(
+	waveMap: ReadonlyMap<number, readonly Task[]>,
+	wave: number,
+): readonly Task[] {
+	const tasks = waveMap.get(wave) ?? [];
+	return tasks.filter((t) => t.status === "PENDING");
+}
+
+/**
+ * Get in-progress tasks for a specific wave.
+ */
+function findInProgressTasks(
+	waveMap: ReadonlyMap<number, readonly Task[]>,
+	wave: number,
+): readonly Task[] {
+	const tasks = waveMap.get(wave) ?? [];
+	return tasks.filter((t) => t.status === "IN_PROGRESS");
+}
+
+/**
+ * Mark multiple tasks as IN_PROGRESS immutably.
+ */
+function markTasksInProgress(tasks: readonly Task[], taskIds: readonly number[]): readonly Task[] {
+	const idSet = new Set(taskIds);
+	return tasks.map((t) => (idSet.has(t.id) ? { ...t, status: "IN_PROGRESS" as const } : t));
+}
+
+/**
+ * Build a prompt for a single task dispatch.
+ */
+function buildTaskPrompt(task: Task): string {
+	const planRef = getArtifactRef("PLAN", "tasks.md");
+	const designRef = getArtifactRef("ARCHITECT", "design.md");
+	return [
+		`Implement task ${task.id}: ${task.title}.`,
+		`Reference the plan at ${planRef}`,
+		`and architecture at ${designRef}.`,
+		`If a CLAUDE.md file exists in the project root, read it for project-specific conventions.`,
+		`Check ~/.config/opencode/skills/coding-standards/SKILL.md for coding standards.`,
+		`Report completion when done.`,
+	].join(" ");
+}
+
+/**
+ * Mark a task as DONE immutably and return the updated tasks array.
+ */
+function markTaskDone(tasks: readonly Task[], taskId: number): readonly Task[] {
+	return tasks.map((t) => (t.id === taskId ? { ...t, status: "DONE" as const } : t));
+}
+
+/**
+ * Check whether all tasks in a given wave are DONE.
+ */
+function isWaveComplete(waveMap: ReadonlyMap<number, readonly Task[]>, wave: number): boolean {
+	const tasks = waveMap.get(wave) ?? [];
+	return tasks.every((t) => t.status === "DONE");
+}
+
+/**
+ * Parse review result to check for CRITICAL findings.
+ */
+function hasCriticalFindings(resultStr: string): boolean {
+	try {
+		const parsed = JSON.parse(resultStr);
+		if (parsed.severity === "CRITICAL") return true;
+		const hasCritical = (arr: unknown[]): boolean =>
+			arr.some(
+				(f: unknown) =>
+					typeof f === "object" &&
+					f !== null &&
+					"severity" in f &&
+					(f as { severity: string }).severity === "CRITICAL",
+			);
+		if (Array.isArray(parsed.findings)) {
+			return hasCritical(parsed.findings);
+		}
+		if (parsed.report?.findings && Array.isArray(parsed.report.findings)) {
+			return hasCritical(parsed.report.findings);
+		}
+		return false;
+	} catch {
+		return false;
+	}
+}
+
+export const handleBuild: PhaseHandler = async (state, _artifactDir, result?) => {
+	const { tasks, buildProgress } = state;
+
+	// Edge case: no tasks
+	if (tasks.length === 0) {
+		return Object.freeze({
+			action: "error",
+			phase: "BUILD",
+			message: "No tasks found",
+		} satisfies DispatchResult);
+	}
+
+	// Edge case: strike count exceeded
+	if (buildProgress.strikeCount > MAX_STRIKES && buildProgress.reviewPending && result) {
+		return Object.freeze({
+			action: "error",
+			phase: "BUILD",
+			message: "Max retries exceeded — too many CRITICAL review findings",
+		} satisfies DispatchResult);
+	}
+
+	// Case 1: Review pending + result provided -> process review outcome
+	if (buildProgress.reviewPending && result) {
+		if (hasCriticalFindings(result)) {
+			// Re-dispatch implementer with fix instructions
+			const safeResult = sanitizeTemplateContent(result).slice(0, 4000);
+			const prompt = [
+				`CRITICAL review findings detected. Fix the following issues:`,
+				safeResult,
+				`Reference ${getArtifactRef("PLAN", "tasks.md")} for context.`,
+			].join(" ");
+
+			return Object.freeze({
+				action: "dispatch",
+				agent: AGENT_NAMES.BUILD,
+				prompt,
+				phase: "BUILD",
+				progress: "Fix dispatch — CRITICAL findings",
+				_stateUpdates: {
+					buildProgress: {
+						...buildProgress,
+						strikeCount: buildProgress.strikeCount + 1,
+					},
+				},
+			} satisfies DispatchResult);
+		}
+
+		// No critical -> advance to next wave
+		const waveMap = groupByWave(tasks);
+		const nextWave = findCurrentWave(waveMap);
+
+		if (nextWave === null) {
+			return Object.freeze({
+				action: "complete",
+				phase: "BUILD",
+				progress: "All tasks and reviews complete",
+				_stateUpdates: {
+					buildProgress: {
+						...buildProgress,
+						reviewPending: false,
+					},
+				},
+			} satisfies DispatchResult);
+		}
+
+		const pendingTasks = findPendingTasks(waveMap, nextWave);
+		const updatedProgress: BuildProgress = {
+			...buildProgress,
+			reviewPending: false,
+			currentWave: nextWave,
+		};
+
+		if (pendingTasks.length === 1) {
+			const task = pendingTasks[0];
+			return Object.freeze({
+				action: "dispatch",
+				agent: AGENT_NAMES.BUILD,
+				prompt: buildTaskPrompt(task),
+				phase: "BUILD",
+				progress: `Wave ${nextWave} — task ${task.id}`,
+				_stateUpdates: {
+					buildProgress: { ...updatedProgress, currentTask: task.id },
+				},
+			} satisfies DispatchResult);
+		}
+
+		const dispatchedIds = pendingTasks.map((t) => t.id);
+		return Object.freeze({
+			action: "dispatch_multi",
+			agents: pendingTasks.map((task) => ({
+				agent: AGENT_NAMES.BUILD,
+				prompt: buildTaskPrompt(task),
+			})),
+			phase: "BUILD",
+			progress: `Wave ${nextWave} — ${pendingTasks.length} concurrent tasks`,
+			_stateUpdates: {
+				tasks: [...markTasksInProgress(tasks, dispatchedIds)],
+				buildProgress: { ...updatedProgress, currentTask: null },
+			},
+		} satisfies DispatchResult);
+	}
+
+	// Case 2: Result provided + not review pending -> mark task done
+	// For dispatch_multi, currentTask may be null — find the first IN_PROGRESS task instead
+	const taskToComplete =
+		buildProgress.currentTask ?? tasks.find((t) => t.status === "IN_PROGRESS")?.id ?? null;
+	if (result && !buildProgress.reviewPending && taskToComplete !== null) {
+		const updatedTasks = markTaskDone(tasks, taskToComplete);
+		const waveMap = groupByWave(updatedTasks);
+		const currentWave = buildProgress.currentWave ?? 1;
+
+		if (isWaveComplete(waveMap, currentWave)) {
+			// Wave complete -> trigger review (same for final wave or intermediate)
+			return Object.freeze({
+				action: "dispatch",
+				agent: AGENT_NAMES.REVIEW,
+				prompt: "Review completed wave. Scope: branch. Report any CRITICAL findings.",
+				phase: "BUILD",
+				progress: `Wave ${currentWave} complete — review pending`,
+				_stateUpdates: {
+					tasks: [...updatedTasks],
+					buildProgress: {
+						...buildProgress,
+						currentTask: null,
+						reviewPending: true,
+					},
+				},
+			} satisfies DispatchResult);
+		}
+
+		// Wave not complete -> dispatch next pending task or wait for in-progress
+		const pendingInWave = findPendingTasks(waveMap, currentWave);
+		if (pendingInWave.length > 0) {
+			const next = pendingInWave[0];
+			return Object.freeze({
+				action: "dispatch",
+				agent: AGENT_NAMES.BUILD,
+				prompt: buildTaskPrompt(next),
+				phase: "BUILD",
+				progress: `Wave ${currentWave} — task ${next.id}`,
+				_stateUpdates: {
+					tasks: [...updatedTasks],
+					buildProgress: {
+						...buildProgress,
+						currentTask: next.id,
+					},
+				},
+			} satisfies DispatchResult);
+		}
+
+		// No pending tasks but wave not complete — other tasks are still IN_PROGRESS
+		const inProgressInWave = findInProgressTasks(waveMap, currentWave);
+		if (inProgressInWave.length > 0) {
+			return Object.freeze({
+				action: "dispatch",
+				agent: AGENT_NAMES.BUILD,
+				prompt: `Wave ${currentWave} has ${inProgressInWave.length} task(s) still in progress. Continue working on remaining tasks.`,
+				phase: "BUILD",
+				progress: `Wave ${currentWave} — waiting for ${inProgressInWave.length} in-progress task(s)`,
+				_stateUpdates: {
+					tasks: [...updatedTasks],
+					buildProgress: {
+						...buildProgress,
+						currentTask: null,
+					},
+				},
+			} satisfies DispatchResult);
+		}
+	}
+
+	// Case 3: No result (first call or resume) -> find first pending wave
+	const waveMap = groupByWave(tasks);
+	const currentWave = findCurrentWave(waveMap);
+
+	if (currentWave === null) {
+		// All tasks already DONE
+		return Object.freeze({
+			action: "complete",
+			phase: "BUILD",
+			progress: "All tasks complete",
+		} satisfies DispatchResult);
+	}
+
+	const pendingTasks = findPendingTasks(waveMap, currentWave);
+	const inProgressTasks = findInProgressTasks(waveMap, currentWave);
+
+	if (pendingTasks.length === 0 && inProgressTasks.length > 0) {
+		// Wave has only IN_PROGRESS tasks (e.g., resume after dispatch_multi).
+		// Return a dispatch instruction so the orchestrator knows work is underway.
+		return Object.freeze({
+			action: "dispatch",
+			agent: AGENT_NAMES.BUILD,
+			prompt: `Resume: wave ${currentWave} has ${inProgressTasks.length} task(s) still in progress. Wait for agent results and pass them back.`,
+			phase: "BUILD",
+			progress: `Wave ${currentWave} — waiting for ${inProgressTasks.length} in-progress task(s)`,
+			_stateUpdates: {
+				buildProgress: {
+					...buildProgress,
+					currentWave,
+					currentTask: null,
+				},
+			},
+		} satisfies DispatchResult);
+	}
+
+	if (pendingTasks.length === 0) {
+		// All tasks in all waves DONE (findCurrentWave already checked PENDING + IN_PROGRESS)
+		return Object.freeze({
+			action: "complete",
+			phase: "BUILD",
+			progress: "All tasks complete",
+		} satisfies DispatchResult);
+	}
+
+	if (pendingTasks.length === 1) {
+		const task = pendingTasks[0];
+		return Object.freeze({
+			action: "dispatch",
+			agent: AGENT_NAMES.BUILD,
+			prompt: buildTaskPrompt(task),
+			phase: "BUILD",
+			progress: `Wave ${currentWave} — task ${task.id}`,
+			_stateUpdates: {
+				buildProgress: {
+					...buildProgress,
+					currentTask: task.id,
+					currentWave,
+				},
+			},
+		} satisfies DispatchResult);
+	}
+
+	// Multiple pending tasks in wave -> dispatch_multi
+	const dispatchedIds = pendingTasks.map((t) => t.id);
+	return Object.freeze({
+		action: "dispatch_multi",
+		agents: pendingTasks.map((task) => ({
+			agent: AGENT_NAMES.BUILD,
+			prompt: buildTaskPrompt(task),
+		})),
+		phase: "BUILD",
+		progress: `Wave ${currentWave} — ${pendingTasks.length} concurrent tasks`,
+		_stateUpdates: {
+			tasks: [...markTasksInProgress(tasks, dispatchedIds)],
+			buildProgress: {
+				...buildProgress,
+				currentTask: null,
+				currentWave,
+			},
+		},
+	} satisfies DispatchResult);
+};

package/src/orchestrator/handlers/challenge.ts

@@ -0,0 +1,41 @@
+import { sanitizeTemplateContent } from "../../review/sanitize";
+import { ensurePhaseDir, getArtifactRef } from "../artifacts";
+import type { PipelineState } from "../types";
+import { AGENT_NAMES, type DispatchResult } from "./types";
+
+/**
+ * CHALLENGE phase handler — dispatches oc-challenger with RECON artifact references.
+ * References files by path (not content injection) per D-11.
+ */
+export async function handleChallenge(
+	state: Readonly<PipelineState>,
+	artifactDir: string,
+	result?: string,
+): Promise<DispatchResult> {
+	if (result) {
+		return Object.freeze({
+			action: "complete" as const,
+			phase: "CHALLENGE",
+			progress: "CHALLENGE complete",
+		});
+	}
+
+	await ensurePhaseDir(artifactDir, "CHALLENGE");
+	const reconRef = getArtifactRef("RECON", "report.md");
+	const outputRef = getArtifactRef("CHALLENGE", "brief.md");
+
+	const safeIdea = sanitizeTemplateContent(state.idea).replace(/[\r\n]+/g, " ");
+
+	return Object.freeze({
+		action: "dispatch" as const,
+		agent: AGENT_NAMES.CHALLENGE,
+		prompt: [
+			`Read ${reconRef} for research context.`,
+			`Original idea: ${safeIdea}`,
+			`Propose up to 3 enhancements. Write ambitious brief to ${outputRef}`,
+			`For each: name, user value, complexity (LOW/MEDIUM/HIGH), accept/reject rationale.`,
+		].join("\n"),
+		phase: "CHALLENGE",
+		progress: "Dispatching challenger for product enhancements",
+	});
+}

package/src/orchestrator/handlers/explore.ts

@@ -0,0 +1,9 @@
+import type { DispatchResult, PhaseHandler } from "./types";
+
+export const handleExplore: PhaseHandler = async (_state, _artifactDir, _result?) => {
+	return Object.freeze({
+		action: "complete",
+		phase: "EXPLORE",
+		progress: "EXPLORE skipped (not yet implemented)",
+	} satisfies DispatchResult);
+};

package/src/orchestrator/handlers/index.ts

@@ -0,0 +1,21 @@
+import type { Phase } from "../types";
+import { handleArchitect } from "./architect";
+import { handleBuild } from "./build";
+import { handleChallenge } from "./challenge";
+import { handleExplore } from "./explore";
+import { handlePlan } from "./plan";
+import { handleRecon } from "./recon";
+import { handleRetrospective } from "./retrospective";
+import { handleShip } from "./ship";
+import type { PhaseHandler } from "./types";
+
+export const PHASE_HANDLERS: Readonly<Record<Phase, PhaseHandler>> = Object.freeze({
+	RECON: handleRecon,
+	CHALLENGE: handleChallenge,
+	ARCHITECT: handleArchitect,
+	EXPLORE: handleExplore,
+	PLAN: handlePlan,
+	BUILD: handleBuild,
+	SHIP: handleShip,
+	RETROSPECTIVE: handleRetrospective,
+});

package/src/orchestrator/handlers/plan.ts

@@ -0,0 +1,35 @@
+import { getArtifactRef } from "../artifacts";
+import type { DispatchResult, PhaseHandler } from "./types";
+import { AGENT_NAMES } from "./types";
+
+export const handlePlan: PhaseHandler = async (_state, _artifactDir, result?) => {
+	if (result) {
+		return Object.freeze({
+			action: "complete",
+			phase: "PLAN",
+			progress: "Planning complete — tasks written",
+		} satisfies DispatchResult);
+	}
+
+	const architectRef = getArtifactRef("ARCHITECT", "design.md");
+	const challengeRef = getArtifactRef("CHALLENGE", "brief.md");
+
+	const prompt = [
+		"Read the architecture design at",
+		architectRef,
+		"and the challenge brief at",
+		challengeRef,
+		"then produce a task plan.",
+		"Write tasks to phases/PLAN/tasks.md.",
+		"Each task should have a 300-line diff max.",
+		"Assign wave numbers for parallel execution.",
+	].join(" ");
+
+	return Object.freeze({
+		action: "dispatch",
+		agent: AGENT_NAMES.PLAN,
+		prompt,
+		phase: "PLAN",
+		progress: "Dispatching planner",
+	} satisfies DispatchResult);
+};

package/src/orchestrator/handlers/recon.ts

@@ -0,0 +1,40 @@
+import { sanitizeTemplateContent } from "../../review/sanitize";
+import { ensurePhaseDir, getArtifactRef } from "../artifacts";
+import type { PipelineState } from "../types";
+import { AGENT_NAMES, type DispatchResult } from "./types";
+
+/**
+ * RECON phase handler — dispatches oc-researcher with idea and artifact path.
+ * Uses file references (not content injection) per D-11.
+ */
+export async function handleRecon(
+	state: Readonly<PipelineState>,
+	artifactDir: string,
+	result?: string,
+): Promise<DispatchResult> {
+	if (result) {
+		return Object.freeze({
+			action: "complete" as const,
+			phase: "RECON",
+			progress: "RECON complete",
+		});
+	}
+
+	const phaseDir = await ensurePhaseDir(artifactDir, "RECON");
+	const outputRef = getArtifactRef("RECON", "report.md");
+
+	const safeIdea = sanitizeTemplateContent(state.idea).replace(/[\r\n]+/g, " ");
+
+	return Object.freeze({
+		action: "dispatch" as const,
+		agent: AGENT_NAMES.RECON,
+		prompt: [
+			`Research the following idea and write findings to ${outputRef}`,
+			`Idea: ${safeIdea}`,
+			`Output: ${phaseDir}/report.md`,
+			`Include: Market Analysis, Technology Options, UX Considerations, Feasibility Assessment, Confidence (HIGH/MEDIUM/LOW)`,
+		].join("\n"),
+		phase: "RECON",
+		progress: "Dispatching researcher for domain analysis",
+	});
+}