pi-super-dev 0.1.0

package/src/stages/index.ts

@@ -0,0 +1,172 @@
+/**
+ * The super-dev workflow, expressed as a tree of control-flow nodes.
+ *
+ * This is the declarative pipeline definition. To customize:
+ *   - Remove a stage: delete the node from the sequence.
+ *   - Reorder: move nodes (mind data dependencies — a node reads upstream
+ *     artifacts by state key, e.g. `state.spec` is written by the spec stage).
+ *   - Add a stage: write a `Stage` (or compose control nodes), insert it.
+ *   - Replace a stage: swap the node (keep the same output state key).
+ *   - Change control flow: swap a `task` for `branch`/`gate`/`loop`/`parallel`/
+ *     `retry`/`map`/`wait`/`tryCatch` from `nodes.ts`.
+ *
+ * The runner (`workflow.ts`) never changes.
+ *
+ *   setup ─► classify ─► gate(requirements) ─► gate(bdd) ─► gate(research) ─►
+ *   branch[bug]→debug ─► assessment ─► design ─► prototype ─►
+ *   gate(spec) ─► gate(specReview) ─► implementation ─►
+ *   loop{ code-review = parallel[review,adversarial]→merge + fix } ─►
+ *   docs ─► cleanup ─► branch[!blocked]→merge
+ */
+
+import { task, sequence, branch, gate, loop, parallel, noop, gateValidator } from "../nodes.ts";
+import type { ControlObj, PipelineState, StageContext, Workflow } from "../types.ts";
+import { setupStage } from "./setup.ts";
+import { classifyStage, cleanupTask, requirementsWriter, bddWriter, researchWriter, debugWriter, assessmentWriter, specWriter, specReviewWriter, docsWriter, mergeWriter } from "./writers.ts";
+import { designStage } from "./design.ts";
+import { prototypeStage } from "./prototype.ts";
+import { implementationStage } from "./implementation.ts";
+import { buildCodeReviewPrompt, buildAdversarialPrompt, buildFixPrompt } from "../prompts.ts";
+
+// ─── Predicates ─────────────────────────────────────────────────────────────
+
+const isBug = (s: PipelineState) => s.classify?.taskType === "bug";
+
+/** Merge only when cleanup actually ran AND found nothing blocking. Treating a
+ *  missing cleanup result as "safe to merge" is a vacuous pass — cleanup may
+ *  simply have failed to produce output. */
+const notBlocked = (s: PipelineState) => {
+	const c = s.cleanup as { blocked?: boolean } | undefined;
+	return !!c && c.blocked !== true;
+};
+
+/** Only review when there is actually an implementation to review. */
+const hasImplementation = (s: PipelineState) =>
+	((s.implementation as { totalPhases?: number } | undefined)?.totalPhases ?? 0) > 0;
+
+/** Research is complete once it has actually produced a report. Open issues
+ *  are NORMAL research output (the prompt asks for them) — they flow forward
+ *  to the spec/assessment stages, so they must NOT block the pipeline. */
+const researchComplete = async (s: PipelineState, ctx: StageContext) => {
+	const r = s.research as { docPath?: string; openIssues?: unknown[] } | undefined;
+	if (!r || !r.docPath) {
+		ctx.log("Research: no report produced (agent returned nothing or timed out)");
+		return { pass: false, errors: ["no research report produced (agent returned nothing or timed out)"] };
+	}
+	const open = (r.openIssues as unknown[]) ?? [];
+	if (open.length > 0) ctx.log(`Research: ${open.length} open issue(s) noted — forwarded to spec/assessment`);
+	return { pass: true, errors: [] };
+};
+
+/** Code review is approved when the merged verdict is Approved (with or without comments). */
+const reviewApproved = (s: PipelineState) => {
+	const v = s.review?.verdict as string | undefined;
+	return v === "Approved" || v === "Approved with Comments";
+};
+
+// ─── Code review: parallel reviewers → merge, in a loop with fixes ──────────
+
+const setupOf = (s: PipelineState) => s.setup!;
+
+const codeReviewNode = loop(
+	{ until: reviewApproved, times: 3 },
+	sequence([
+		// Parallel split + synchronization: two reviewers converge into one merged verdict.
+		parallel(
+			[
+				task({
+					id: "codeReview",
+					label: "Stage 10a — Code Review",
+					async run(s, ctx) {
+						if (!ctx.budget.check()) return undefined;
+						const r = await ctx.agent({ id: "pipeline.code-review.review", agent: "code-reviewer", prompt: buildCodeReviewPrompt(setupOf(s), s.classify ?? null, ctx.task, s.spec ?? null, s.implementation ?? {}) });
+						return r.control ?? {};
+					},
+				}),
+				task({
+					id: "adversarialReview",
+					label: "Stage 10b — Adversarial Review",
+					async run(s, ctx) {
+						if (!ctx.budget.check()) return undefined;
+						const r = await ctx.agent({ id: "pipeline.code-review.adversarial", agent: "adversarial-reviewer", prompt: buildAdversarialPrompt(setupOf(s), s.classify ?? null, ctx.task, s.spec ?? null, s.implementation ?? {}) });
+						return r.control ?? {};
+					},
+				}),
+			],
+			{
+				into: "review",
+				join: async (_results, s, ctx) =>
+					(await ctx.helper({ name: "merge-review-verdicts", sources: { "code-review": s.codeReview ?? {}, "adversarial-review": s.adversarialReview ?? {} } })).value,
+			},
+		),
+		// If not approved, address findings before the next review round.
+		branch(reviewApproved, {
+			yes: noop(),
+			no: task({
+				id: "reviewFix",
+				label: "Stage 10c — Address Review Findings",
+				async run(s, ctx) {
+					if (!ctx.budget.check()) return undefined;
+					const findings = (s.review?.findings as unknown[]) ?? [];
+					const r = await ctx.agent({ id: "pipeline.code-review.fix", agent: "implementer", prompt: buildFixPrompt(setupOf(s), s.classify ?? null, findings) });
+					return r.control ?? {};
+				},
+			}),
+		}),
+	]),
+);
+
+// ─── The pipeline ───────────────────────────────────────────────────────────
+
+const pipeline = sequence(
+	[
+		task(setupStage),
+		task(classifyStage),
+		// Quality-gate loops: write → validate → re-write until the gate passes.
+		// Retries CONVERGE (the validator's errors are fed into the next attempt's
+		// prompt) and exhaustion is NON-FATAL (the pipeline proceeds with the
+		// best-available artifact rather than discarding every prior stage's work).
+		// Spec review is intentionally NOT gated — its verdict is signal, not a block.
+		gate({ validate: gateValidator("gate-requirements", "write-requirements", "requirements"), feedbackKey: "requirements", attempts: 4 }, task(requirementsWriter)),
+		gate({ validate: gateValidator("gate-bdd", "write-bdd", "bdd"), feedbackKey: "bdd", attempts: 4 }, task(bddWriter)),
+		gate({ validate: researchComplete, feedbackKey: "research", attempts: 4 }, task(researchWriter)),
+		// Conditional branch: debug analysis only for bug fixes.
+		branch(isBug, { yes: task(debugWriter) }),
+		task(assessmentWriter),
+		task(designStage),
+		task(prototypeStage),
+		gate({ validate: gateValidator("gate-spec-trace", "write-spec", "spec"), feedbackKey: "spec", attempts: 4 }, task(specWriter)),
+		// Spec review is SIGNAL, not a gate: a "Changes Requested" verdict is a
+		// judgment call whose findings flow forward to implementation/code-review.
+		// Blocking on it (the old fatal gate) aborted runs on a subjective verdict.
+		task(specReviewWriter),
+		task(implementationStage),
+		// Code review only runs when implementation actually produced phases;
+		// otherwise we'd burn ~9 spawns reviewing nothing.
+		branch(hasImplementation, { yes: codeReviewNode }),
+		task(docsWriter),
+		task(cleanupTask),
+		// Conditional branch: merge only if cleanup found no sensitive data.
+		branch(notBlocked, { yes: task(mergeWriter) }),
+	],
+	{ tolerant: true }, // best-effort: a non-setup stage failure is logged, not fatal
+);
+
+export const SUPER_DEV_WORKFLOW: Workflow = {
+	id: "super-dev",
+	description:
+		"13-stage development pipeline composed from control-flow nodes: classify → requirements → BDD → research → [debug] → assessment → design → [prototype] → spec → spec-review → implementation (TDD) → code review → docs → cleanup → merge.",
+	root: pipeline,
+};
+
+// Re-exports for users composing custom workflows.
+export { task, sequence, branch, gate, loop, parallel, noop, gateValidator } from "../nodes.ts";
+export { setupStage } from "./setup.ts";
+export {
+	classifyStage, cleanupTask, requirementsWriter, bddWriter, researchWriter,
+	debugWriter, assessmentWriter, specWriter, specReviewWriter, docsWriter, mergeWriter,
+} from "./writers.ts";
+export { designStage } from "./design.ts";
+export { prototypeStage } from "./prototype.ts";
+export { implementationStage } from "./implementation.ts";
+export type { ControlObj };

package/src/stages/prototype.ts

@@ -0,0 +1,43 @@
+/**
+ * Stage 6.5 — Prototype (conditional + loop).
+ * Self-contained task: only runs when the design declares numeric constants
+ * (decided by check-prototype-needed); loops up to 3 rounds until pass.
+ */
+
+import type { ControlObj, Stage } from "../types.ts";
+import { buildPrototypePrompt } from "../prompts.ts";
+
+const MAX_ROUNDS = 3;
+const pad = (n: number) => String(n).padStart(2, "0");
+
+export const prototypeStage: Stage = {
+	id: "prototype",
+	label: "Stage 6.5 — Prototype",
+	async run(state, ctx) {
+		const design = state.design ?? null;
+		if (!design) return null;
+		const check = await ctx.helper({ name: "check-prototype-needed", sources: { design } });
+		if (!check.value.needed) {
+			ctx.log("Prototype not needed — no numeric constants to validate");
+			return null;
+		}
+		const constants = (check.value.constants as string[]) ?? [];
+		const setup = state.setup!;
+		let last: ControlObj | null = null;
+		for (let round = 1; round <= MAX_ROUNDS; round++) {
+			if (!ctx.budget.check()) break;
+			const result = await ctx.agent({
+				id: `pipeline.prototype.r${pad(round)}`,
+				agent: "prototype-runner",
+				prompt: buildPrototypePrompt(setup, state.classify ?? null, ctx.task, design, constants, round),
+			});
+			last = result.control ?? null;
+			if (last?.verdict === "pass") {
+				ctx.log(`Prototype validation PASS on round ${round}`);
+				return last;
+			}
+			ctx.log(`Prototype round ${round}/${MAX_ROUNDS}: verdict=${last?.verdict ?? "unknown"}`);
+		}
+		return last;
+	},
+};

package/src/stages/setup.ts

@@ -0,0 +1,32 @@
+/**
+ * Stage 1 — Setup (deterministic, fatal).
+ * Detects language/framework, creates a git worktree, creates the spec dir.
+ * Fatal: failure aborts the whole workflow.
+ */
+
+import type { Stage } from "../types.ts";
+import { runSetup } from "../setup.ts";
+import { abbreviatePath } from "../pi-spawn.ts";
+import { summarizeSlug } from "../session-agent.ts";
+
+export const setupStage: Stage = {
+	id: "setup",
+	label: "Stage 1 — Setup",
+	fatal: true,
+	async run(_state, ctx) {
+		const cwd = ctx.options.cwd ?? process.cwd();
+		// Try an LLM-summarized spec slug (concise, meaningful); fall back to the
+		// deterministic slugifyTask inside runSetup on any failure/timeout.
+		let slug = "";
+		try {
+			slug = await summarizeSlug(ctx.task, cwd, { signal: ctx.signal });
+		} catch { /* fallback below */ }
+		const setup = runSetup(ctx.task, { cwd: ctx.options.cwd, skipWorktree: ctx.options.skipWorktree, slug });
+		const relWorktree = abbreviatePath(setup.worktreePath, cwd);
+		const relSpec = abbreviatePath(setup.specDirectory, setup.worktreePath) || ".";
+		ctx.log(`Setup: spec ${setup.specIdentifier} | ${setup.language}${setup.isWebUi ? " (Web UI)" : ""} | branch ${setup.defaultBranch}`);
+		ctx.log(`Worktree: ${relWorktree}${setup.worktreeCreated ? " (created)" : " (in-place)"}${setup.initializedRepo ? "; git init'd" : ""}`);
+		ctx.log(`Spec dir: ${relSpec}`);
+		return setup;
+	},
+};

package/src/stages/writers.ts

@@ -0,0 +1,105 @@
+/**
+ * Leaf stages built from the convenience builders in `nodes.ts`:
+ *   - single-shot agent "writer" tasks (wrapped in `gate`/`loop` upstream)
+ *   - deterministic helper tasks (classify, cleanup)
+ */
+
+import { writerTask, helperTask } from "../nodes.ts";
+import type { Stage, SetupControl } from "../types.ts";
+import * as P from "../prompts.ts";
+
+const S = (s: { setup?: SetupControl }) => s.setup!;
+
+export const requirementsWriter: Stage = writerTask({
+	id: "requirements",
+	label: "Stage 2B — Requirements",
+	agent: "requirements-clarifier",
+	buildPrompt: (state, ctx) => P.buildRequirementsPrompt(S(state), state.classify ?? null, ctx.task),
+});
+
+export const bddWriter: Stage = writerTask({
+	id: "bdd",
+	label: "Stage 2C — BDD Scenarios",
+	agent: "bdd-scenario-writer",
+	requires: ["*-requirements.md"],
+	buildPrompt: (state, ctx) => P.buildBddPrompt(S(state), state.classify ?? null, ctx.task, state.requirements ?? null),
+});
+
+export const researchWriter: Stage = writerTask({
+	id: "research",
+	label: "Stage 3 — Research",
+	agent: "research-agent",
+	requires: ["*-requirements.md"],
+	buildPrompt: (state, ctx) =>
+		P.buildResearchPrompt(S(state), state.classify ?? null, ctx.task, state.requirements ?? null, state.bdd ?? null, state.research ?? null),
+});
+
+export const debugWriter: Stage = writerTask({
+	id: "debug",
+	label: "Stage 4 — Debug Analysis",
+	agent: "debug-analyzer",
+	requires: ["*-requirements.md"],
+	buildPrompt: (state, ctx) => P.buildDebugPrompt(S(state), state.classify ?? null, ctx.task, state.requirements ?? null, state.research ?? null),
+});
+
+export const assessmentWriter: Stage = writerTask({
+	id: "assessment",
+	label: "Stage 5 — Code Assessment",
+	agent: "code-assessor",
+	buildPrompt: (state, ctx) => P.buildAssessmentPrompt(S(state), state.classify ?? null, ctx.task, state.research ?? null, state.debug ?? null),
+});
+
+export const specWriter: Stage = writerTask({
+	id: "spec",
+	label: "Stage 7 — Specification",
+	agent: "spec-writer",
+	requires: ["*-requirements.md", "*-bdd-scenarios.md"],
+	buildPrompt: (state, ctx) =>
+		P.buildSpecPrompt(S(state), state.classify ?? null, ctx.task, state.requirements ?? null, state.bdd ?? null, state.research ?? null, state.assessment ?? null, state.design ?? null),
+});
+
+export const specReviewWriter: Stage = writerTask({
+	id: "specReview",
+	label: "Stage 8 — Spec Review",
+	agent: "spec-reviewer",
+	requires: ["*-specification.md", "*-implementation-plan.md", "*-task-list.md"],
+	buildPrompt: (state) => P.buildSpecReviewPrompt(S(state), state.classify ?? null, state.spec ?? null),
+});
+
+export const docsWriter: Stage = writerTask({
+	id: "docs",
+	label: "Stage 11 — Documentation",
+	agent: "docs-executor",
+	requires: ["*-specification.md"],
+	buildPrompt: (state, ctx) => P.buildDocsPrompt(S(state), state.classify ?? null, ctx.task, state.spec ?? null),
+});
+
+export const mergeWriter: Stage = writerTask({
+	id: "merge",
+	label: "Stage 13 — Merge",
+	agent: "orchestrator",
+	buildPrompt: (state) => P.buildMergePrompt(S(state)),
+});
+
+/** Classify the task via a helper. Needs the runtime task text from ctx. */
+export const classifyStage: Stage = {
+	id: "classify",
+	label: "Stage 2A — Classify Task",
+	async run(state, ctx) {
+		const result = await ctx.helper({
+			name: "classify-task",
+			sources: { setup: state.setup },
+			options: { runtimeTask: ctx.task },
+		});
+		return result.value;
+	},
+};
+
+/** Scan the worktree for build artifacts + sensitive data; decide merge blocking. */
+export const cleanupTask: Stage = helperTask({
+	id: "cleanup",
+	label: "Stage 12 — Cleanup",
+	helper: "cleanup",
+	sources: (state) => ({ docs: state.docs ?? {} }),
+	context: (state) => ({ cwd: state.setup?.worktreePath ?? "" }),
+});

package/src/types.ts

@@ -0,0 +1,235 @@
+/**
+ * Core type system for the self-contained super-dev control-flow engine.
+ *
+ * Architecture: a pipeline is a tree of `Node`s evaluated over a shared
+ * `PipelineState`. Leaf nodes (`task`) wrap a `Stage` (a unit of work that
+ * spawns agents / runs helpers). Control nodes (`sequence`, `branch`,
+ * `parallel`, `loop`, `retry`, `gate`, `map`, `wait`, `tryCatch`, ...) compose
+ * nodes and are self-evaluating: each implements `run(state, ctx)`. The engine
+ * itself is just `await root.run(state, ctx)` — adding a new control construct
+ * means writing one builder function in `nodes.ts`, never touching the runner.
+ *
+ * Zero dependency on @agwab/pi-workflow: agents are spawned directly as `pi`
+ * child processes (see `pi-spawn.ts`).
+ */
+
+import type { EventEmitter } from "node:events";
+
+// ─── Primitive result types ─────────────────────────────────────────────────
+
+export type ControlObj = Record<string, unknown>;
+
+/** Result of parsing an agent's final assistant message. */
+export interface SpawnResult {
+	text: string;
+	control: ControlObj | null;
+	model?: string;
+	error?: string;
+}
+
+export interface AgentCall {
+	id: string;
+	agent: string;
+	prompt: string;
+	/** Control keys the caller expects back (for the session backend's
+	 *  structured_output schema). Optional; omitted for non-writer calls. */
+	controlKeys?: string[];
+}
+
+export interface AgentResult extends SpawnResult {}
+
+export interface HelperCall {
+	name: string;
+	sources: Record<string, unknown>;
+	options?: Record<string, unknown>;
+	context?: Record<string, unknown>;
+}
+
+export interface HelperResult {
+	value: ControlObj;
+	digest: string;
+}
+
+export interface Budget {
+	check(): boolean;
+	spent(): void;
+	count: number;
+}
+
+export interface ProgressSink {
+	phase(label: string): void;
+	log(message: string): void;
+	/** Live streaming text from the active agent (typing effect). `partial` is the
+	 *  full accumulated text of the current text block so far. */
+	text(partial: string): void;
+}
+
+/** Streaming callbacks from a spawned agent to the progress sink. */
+export interface AgentProgress {
+	/** A permanent log line (tool call, turn marker, finalized agent text). */
+	event(message: string): void;
+	/** Live partial text as the agent generates it (control block stripped). */
+	text(partial: string): void;
+}
+
+// ─── Domain shapes ──────────────────────────────────────────────────────────
+
+export interface SetupControl {
+	worktreePath: string;
+	specDirectory: string;
+	defaultBranch: string;
+	language: string;
+	isWebUi: boolean;
+	specIdentifier: string;
+	/** True when an isolated git worktree was created (vs. operating in cwd). */
+	worktreeCreated: boolean;
+	/** True when setup had to `git init` the directory first. */
+	initializedRepo: boolean;
+}
+
+export interface Classification {
+	taskType: "bug" | "feature" | "refactor";
+	uiScope: string;
+	language: string;
+	isWebUi: boolean;
+}
+
+// ─── Pipeline state (shared blackboard) ─────────────────────────────────────
+
+/**
+ * Mutable state threaded through every node. A `task` node stores its return
+ * value under `state[stage.id]`. Control nodes read upstream artifacts by key.
+ * The index signature allows custom stages without extending the interface.
+ */
+export interface PipelineState {
+	setup?: SetupControl;
+	classify?: Classification;
+	requirements?: ControlObj;
+	bdd?: ControlObj;
+	research?: ControlObj;
+	debug?: ControlObj;
+	assessment?: ControlObj;
+	design?: ControlObj;
+	prototype?: ControlObj;
+	spec?: ControlObj;
+	specReview?: ControlObj;
+	implementation?: ControlObj;
+	review?: ControlObj;
+	codeReview?: ControlObj;
+	adversarialReview?: ControlObj;
+	docs?: ControlObj;
+	cleanup?: ControlObj;
+	merge?: ControlObj;
+	[index: string]: unknown;
+}
+
+// ─── Stage (leaf unit of work) ──────────────────────────────────────────────
+
+/** Outcome of one leaf-stage execution, recorded for honest run reporting. */
+export interface StageResult {
+	id: string;
+	label: string;
+	status: NodeStatus;
+	error?: string;
+}
+
+/**
+ * Execution primitives handed to every stage. The runner builds one context
+ * and passes the same reference around; `agent()` resolves its cwd from
+ * `state.setup` (falling back to the run cwd).
+ */
+export interface StageContext {
+	task: string;
+	options: RunOptions;
+	state: PipelineState;
+	agent(call: AgentCall): Promise<AgentResult>;
+	helper(call: HelperCall): Promise<HelperResult>;
+	parallel(calls: Array<() => Promise<AgentResult>>): Promise<AgentResult[]>;
+	budget: Budget;
+	log(message: string): void;
+	events: EventEmitter;
+	signal?: AbortSignal;
+	/** Every leaf-stage outcome, appended by `task()`. Used for honest summaries. */
+	results: StageResult[];
+}
+
+/** A leaf unit of work. Its return value is stored under `state[id]`. */
+export interface Stage {
+	id: string;
+	label: string;
+	description?: string;
+	enabled?: (state: PipelineState) => boolean;
+	run: (state: PipelineState, ctx: StageContext) => Promise<unknown>;
+	fatal?: boolean;
+	/** Upstream artifact docs this stage needs (filename globs in the spec dir,
+	 *  e.g. "*-requirements.md"). task() checks they exist before running and
+	 *  logs ✓/✗, making inter-stage dependencies visible. Missing artifacts are
+	 *  logged (not fatal) — the tolerant pipeline proceeds and the prompt shows
+	 *  "N/A" for absent upstream. */
+	requires?: string[];
+}
+
+// ─── Control-flow node algebra ──────────────────────────────────────────────
+
+export type NodeStatus = "ok" | "skipped" | "failed" | "cancelled";
+
+export interface NodeResult {
+	status: NodeStatus;
+	/** Stored artifact (for tasks) or aggregate (for some control nodes). */
+	value?: unknown;
+	error?: string;
+	/** Round/attempt count reached (for loop/retry/gate). */
+	attempts?: number;
+}
+
+/**
+ * A self-evaluating pipeline node. Leaf `task` nodes do work; control nodes
+ * recursively evaluate children. The runner is `await root.run(state, ctx)`.
+ */
+export interface Node {
+	kind: string;
+	label?: string;
+	run(state: PipelineState, ctx: StageContext): Promise<NodeResult>;
+}
+
+/** A workflow: a root node plus metadata. */
+export interface Workflow {
+	id: string;
+	description?: string;
+	root: Node;
+}
+
+// ─── Run options + summary ──────────────────────────────────────────────────
+
+export interface RunOptions {
+	cwd?: string;
+	skipWorktree?: boolean;
+	skipStages?: string[];
+	model?: string;
+	maxAgents?: number;
+	maxConcurrency?: number;
+	progress?: ProgressSink;
+	signal?: AbortSignal;
+	/** Specialist execution backend. "subprocess" (default) = raw `pi` spawn;
+	 *  "session" = in-process `createAgentSession`. Also set via
+	 *  SUPER_DEV_BACKEND env. */
+	backend?: "subprocess" | "session";
+}
+
+/** Honest, derived overall outcome of a run. */
+export type RunStatus = "success" | "partial" | "failed";
+
+export interface RunSummary {
+	workflowId: string;
+	specIdentifier: string;
+	worktreePath: string;
+	specDirectory: string;
+	agentsSpawned: number;
+	state: PipelineState;
+	/** Derived overall outcome — never faked. */
+	status: RunStatus;
+	/** Stages that ended in `failed`, with their error message (deduped). */
+	failedStages: { label: string; error?: string }[];
+	/** Error message when the run aborted (e.g. a fatal gate threw). */
+	error?: string;
+}