pi-super-dev 0.1.0

package/skills/super-dev/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: super-dev
+description: Self-contained 13-stage development pipeline built on a composable control-flow node algebra (branch/parallel/loop/retry/gate). Orchestrates requirements, research, design, specification, TDD implementation, code review, documentation, and merge through 21 specialist agents spawned directly as `pi` subprocesses. No external workflow engine required.
+---
+
+# Super Dev
+
+Use this skill when the user asks to implement a feature, fix a bug, refactor code, or do systematic multi-stage development work.
+
+## When to use
+
+Triggers: "implement", "build", "fix bug", "refactor", "add feature", "develop this", "help me build", "optimize performance", "resolve deprecation".
+
+Do NOT trigger on: simple questions, file searches, one-off commands, code explanations, quick edits.
+
+## Action
+
+Use the `super_dev` tool to start the pipeline. It spawns 21 specialist `pi` subagents directly — there is no `workflow_run` tool and no dependency on pi-workflow.
+
+```text
+super_dev({ task: "<user's full request>" })
+```
+
+Optional flags:
+- `skipWorktree: true` — operate in the current directory instead of a git worktree.
+- `model: "provider/id"` — override the model used by spawned specialists.
+- `maxAgents: 200` — cap total specialist spawns.
+
+Preserve the user's language, file references, and constraints verbatim in the `task`.
+
+The user can also invoke the pipeline via the `/super-dev` command:
+
+```text
+/super-dev <task description>
+```

package/src/agents.ts

@@ -0,0 +1,38 @@
+/**
+ * Loads specialist agent system prompts from `agents/<name>.md`.
+ * The YAML frontmatter is metadata; the body is passed to spawned `pi` via
+ * `--system-prompt`.
+ */
+
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const AGENTS_DIR = join(MODULE_DIR, "..", "agents");
+const cache = new Map<string, string>();
+
+function stripFrontmatter(md: string): string {
+	if (!md.startsWith("---")) return md;
+	const end = md.indexOf("\n---", 3);
+	if (end === -1) return md;
+	return md.slice(end + 4).replace(/^\s*\n/, "");
+}
+
+export function loadAgentPrompt(name: string): string {
+	const cached = cache.get(name);
+	if (cached !== undefined) return cached;
+	const path = join(AGENTS_DIR, `${name}.md`);
+	let body: string;
+	try {
+		body = stripFrontmatter(readFileSync(path, "utf8"));
+	} catch {
+		throw new Error(`super-dev: unknown agent "${name}" (no file at ${path})`);
+	}
+	cache.set(name, body);
+	return body;
+}
+
+export function agentsDirectory(): string {
+	return AGENTS_DIR;
+}

package/src/control.ts

@@ -0,0 +1,85 @@
+/**
+ * Tolerant extraction of the `<control>` JSON object specialist agents emit.
+ * Tries, in order: `<control>...</control>` tag, ```json fenced block, then the
+ * last balanced `{...}` object in the text. Returns null if none parse.
+ */
+
+import type { ControlObj } from "./types.ts";
+
+const CONTROL_TAG_RE = /<control>\s*([\s\S]*?)\s<\/control>/i;
+
+export function extractControl(text: string): ControlObj | null {
+	if (!text) return null;
+	const tag = text.match(CONTROL_TAG_RE);
+	if (tag?.[1]) {
+		const parsed = tryParseJsonObject(tag[1]);
+		if (parsed) return parsed;
+	}
+	for (const match of text.matchAll(/```(?:json)?\s*([\s\S]*?)\s```/gi)) {
+		const parsed = tryParseJsonObject(match[1]);
+		if (parsed) return parsed;
+	}
+	const obj = findLastJsonObject(text);
+	if (obj) {
+		const parsed = tryParseJsonObject(obj);
+		if (parsed) return parsed;
+	}
+	return null;
+}
+
+function tryParseJsonObject(raw: string): ControlObj | null {
+	const trimmed = raw.replace(/,(\s*[}\]])/g, "$1").trim();
+	if (!trimmed.startsWith("{")) return null;
+	try {
+		const value = JSON.parse(trimmed);
+		if (value && typeof value === "object" && !Array.isArray(value)) {
+			return value as ControlObj;
+		}
+	} catch {
+		// fall through
+	}
+	return null;
+}
+
+/** The list of control keys a stage expects, parsed from its prompt.
+ *  Every `build*Prompt` ends with a line like:
+ *      Output <control> JSON with: docPath, featureName, acCount, openQuestions, summary.
+ *  We parse that comma-list (stripping inline `(type)` annotations) so the
+ *  session backend can declare those keys in its `structured_output` tool
+ *  schema — which is what actually makes the model fill them (see
+ *  docs/findings/session-backend-requirements-gate.md). Returns [] if the
+ *  prompt has no such line (e.g. commit tasks), which safely degrades to the
+ *  permissive schema. */
+export function extractControlKeys(prompt: string): string[] {
+	const m = prompt.match(/<control>\s*JSON\s*with:\s*([^\n.]+)/i);
+	if (!m) return [];
+	return m[1]
+		.split(",")
+		.map((s) => s.replace(/\([^)]*\)/g, "").trim())
+		.filter((s) => /^[A-Za-z_][\w]*$/.test(s));
+}
+
+/** Find the last balanced `{...}` substring via a brace scan. */
+export function findLastJsonObject(text: string): string | null {
+	const lastOpen = text.lastIndexOf("{");
+	if (lastOpen === -1) return null;
+	let depth = 0;
+	let inString = false;
+	let escape = false;
+	for (let i = lastOpen; i < text.length; i++) {
+		const ch = text[i];
+		if (inString) {
+			if (escape) escape = false;
+			else if (ch === "\\") escape = true;
+			else if (ch === '"') inString = false;
+			continue;
+		}
+		if (ch === '"') inString = true;
+		else if (ch === "{") depth++;
+		else if (ch === "}") {
+			depth--;
+			if (depth === 0) return text.slice(lastOpen, i + 1);
+		}
+	}
+	return null;
+}

package/src/doc-validators.ts

@@ -0,0 +1,164 @@
+/**
+ * Doc-content validators for the spec-stage gates.
+ *
+ * The gates in helpers.ts used to trust the agent's self-reported control JSON
+ * (scenarioCount, coverageScore, …). That was fragile: models return numbers
+ * as strings ("13"), omit keys, or self-report scores that don't match the doc.
+ * A real /super-dev run wrote an excellent 26-scenario BDD doc but the gate
+ * failed on the control object's shape — a false negative.
+ *
+ * These validators read the ACTUAL .md file the agent wrote and check its
+ * content (regex / min-size), ported from the original super-dev-plugin's
+ * scripts/gates/definitions.mjs. Gates prefer this; the old metadata checks
+ * survive only as a fallback when no doc can be found on disk.
+ */
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import type { ControlObj } from "./types.ts";
+
+export interface DocRef {
+	path: string;
+	content: string;
+}
+
+/** Convert a simple filename glob ("*-bdd-scenarios.md") into a RegExp. */
+function globToRegExp(glob: string): RegExp {
+	const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+	return new RegExp(`^${escaped}$`, "i");
+}
+
+/** Count regex matches in content (ensures the `g` flag so match() counts all). */
+function countMatches(content: string, re: RegExp): number {
+	const global = re.flags.includes("g") ? re : new RegExp(re.source, re.flags + "g");
+	return (content.match(global) ?? []).length;
+}
+
+/**
+ * Locate & read a stage's doc. Prefer an explicitly-declared path in the control
+ * object (docPath / specificationPath / …); fall back to a glob of the spec
+ * directory so the gate still works when the agent omits or misreports the path.
+ * Returns null if no doc can be found.
+ */
+export function readSpecDoc(specDir: string, control: ControlObj | undefined, glob: string, pathKeys: string[] = ["docPath"]): DocRef | null {
+	for (const k of pathKeys) {
+		const p = control?.[k];
+		if (typeof p === "string" && p && existsSync(p)) {
+			return { path: p, content: readFileSync(p, "utf8") };
+		}
+	}
+	if (specDir) {
+		try {
+			const re = globToRegExp(glob);
+			for (const entry of readdirSync(specDir)) {
+				if (re.test(entry)) {
+					const p = join(specDir, entry);
+					if (existsSync(p)) return { path: p, content: readFileSync(p, "utf8") };
+				}
+			}
+		} catch { /* spec dir unreadable — fall through */ }
+	}
+	return null;
+}
+
+/** True if a sibling doc exists in the spec dir (for file-existence checks). */
+export function specDocExists(specDir: string, glob: string): boolean {
+	if (!specDir) return false;
+	try {
+		const re = globToRegExp(glob);
+		return readdirSync(specDir).some((e) => re.test(e));
+	} catch {
+		return false;
+	}
+}
+
+// ─── coercion: models return "13" / "true" where a gate wants 13 / true ───────
+
+export function toNumber(v: unknown): number | null {
+	if (typeof v === "number") return Number.isFinite(v) ? v : null;
+	if (typeof v === "string") {
+		const n = Number(v.trim());
+		return Number.isFinite(n) ? n : null;
+	}
+	return null;
+}
+
+export function toBool(v: unknown): boolean {
+	if (typeof v === "boolean") return v;
+	if (typeof v === "string") return /^(true|yes|y|1|pass)$/i.test(v.trim());
+	return false;
+}
+
+/** Normalize a spec's `phases` field into a usable {name, description?} array.
+ *  Agents occasionally return phases as a string (newline/comma list) or an
+ *  object instead of an array; the implementation stage iterates it, so a
+ *  non-array must never reach `for...of phases.entries()` (which threw:
+ *  "phases.entries is not a function"). Array → keep valid entries; string →
+ *  best-effort split into names; anything else → []. */
+export function normalizePhases(raw: unknown): Array<{ name: string; description?: string }> {
+	if (Array.isArray(raw)) {
+		return raw.filter((p): p is { name: string; description?: string } =>
+			!!p && typeof p === "object" && typeof (p as { name?: unknown }).name === "string" && (p as { name: string }).name.trim() !== "",
+		);
+	}
+	if (typeof raw === "string" && raw.trim()) {
+		return raw
+			.split(/\r?\n|,|;|•/)
+			.map((x) => x.trim().replace(/^[-*\d.)\s]+/, "").trim())
+			.filter((x) => x.length > 0)
+			.map((name) => ({ name }));
+	}
+	return [];
+}
+
+/** Tolerant approved-verdict test. Accepts Approved / Approved with Comments /
+ *  Approved with minor changes / PASS / Accepted (any case); rejects Changes
+ *  Requested / Rejected / CONTEST / Blocked / FAIL. */
+export function isApprovedVerdict(verdict: unknown): boolean {
+	const v = String(verdict ?? "").trim().toLowerCase();
+	if (/(changes?\s+requested|reject|contest|blocked|fail|revision|declined)/i.test(v)) return false;
+	return /\b(approved|pass|accept)/i.test(v);
+}
+
+// ─── per-stage content checks (ported from definitions.mjs) ──────────────────
+// Each returns a list of human-readable errors; empty = doc content is valid.
+
+/** requirements.md: acceptance criteria, AC items, NFRs, summary, substance. */
+export function requirementsContentErrors(c: string): string[] {
+	const e: string[] = [];
+	if (countMatches(c, /acceptance\s+criteria/i) < 1) e.push("missing an 'Acceptance Criteria' section");
+	if (countMatches(c, /AC-\d+/g) < 2) e.push("needs ≥2 acceptance-criteria items (AC-NN)");
+	if (countMatches(c, /non-functional|performance|security|accessibility/i) < 1) e.push("missing non-functional requirements");
+	if (countMatches(c, /executive\s+summary|##\s+summary|\bsummary\b/i) < 1) e.push("missing a summary section");
+	if (c.length < 500) e.push("doc is too short (<500 bytes) — likely a stub");
+	return e;
+}
+
+/** bdd-scenarios.md: SCENARIO-NN ids, Given/When/Then, AC traceability, substance. */
+export function bddContentErrors(c: string): string[] {
+	const e: string[] = [];
+	if (countMatches(c, /SCENARIO-\d+/g) < 1) e.push("missing SCENARIO-NN identifiers");
+	// Given/When/Then keyword lines (tolerant of bullets/bold), ≥3 distinct blocks
+	if (countMatches(c, /^\s*(?:[-*]\s+)?\*{0,2}(?:given|when|then|and)\b/im) < 3) e.push("missing Given/When/Then structure (≥3 blocks)");
+	if (countMatches(c, /AC-\d+/g) < 1) e.push("missing AC references for traceability");
+	if (c.length < 300) e.push("doc is too short (<300 bytes) — likely a stub");
+	return e;
+}
+
+/** specification.md: BDD scenario refs, testing strategy, substance. */
+export function specContentErrors(c: string): string[] {
+	const e: string[] = [];
+	if (countMatches(c, /SCENARIO-\d+/g) < 1) e.push("specification must reference BDD scenarios (SCENARIO-NN)");
+	if (countMatches(c, /testing\s+strategy|test\s+plan|test\s+approach|test\s+coverage|unit\s+test|integration\s+test|e2e\s+test/i) < 1) e.push("missing a testing strategy");
+	if (c.length < 500) e.push("specification is too short (<500 bytes) — likely a stub");
+	return e;
+}
+
+/** spec-review.md: all 8 review dimensions present. */
+export function specReviewContentErrors(c: string): string[] {
+	const e: string[] = [];
+	const dims = ["Completeness", "Consistency", "Feasibility", "Testability", "Traceability", "Grounding", "Complexity", "Ambiguity"];
+	const found = dims.filter((d) => new RegExp(d, "i").test(c));
+	if (found.length < 8) e.push(`missing review dimensions (${found.length}/8: ${found.join(", ") || "none"})`);
+	return e;
+}

package/src/extension.ts

@@ -0,0 +1,164 @@
+/**
+ * Pi extension entry point.
+ *
+ * Registers:
+ *   - `super_dev` tool — the LLM-callable entry that runs the 13-stage
+ *     pipeline by spawning `pi` child processes. Fully self-contained: no
+ *     dependency on @agwab/pi-workflow or any other workflow engine. The
+ *     pipeline is a tree of control-flow nodes (src/nodes.ts) composed in
+ *     src/stages/index.ts.
+ *   - `/super-dev <task>` command — dispatches the task to the agent, which
+ *     invokes the `super_dev` tool.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { runPipelineTask } from "./pipeline.ts";
+import { abbreviatePath } from "./pi-spawn.ts";
+import type { ProgressSink, RunStatus, RunSummary } from "./types.ts";
+
+export { runPipelineTask } from "./pipeline.ts";
+export { SUPER_DEV_WORKFLOW } from "./stages/index.ts";
+export * as nodes from "./nodes.ts";
+export { runWorkflow } from "./workflow.ts";
+
+const SUPER_DEV_TOOL = "super_dev";
+const SUPER_DEV_COMMAND = "super-dev";
+
+/** Format a run summary honestly: success ✅ / partial ⚠️ / failed ❌. */
+function formatSummary(s: RunSummary, cwd?: string): string[] {
+	const icon: Record<RunStatus, string> = { success: "✅", partial: "⚠️", failed: "❌" };
+	const title: Record<RunStatus, string> = {
+		success: "super-dev pipeline complete",
+		partial: "super-dev pipeline completed with issues",
+		failed: "super-dev pipeline did NOT complete",
+	};
+	const impl = s.state.implementation as { summary?: string; totalPhases?: number; allGreen?: boolean } | undefined;
+	const review = s.state.review as { verdict?: string } | undefined;
+	const setup = s.state.setup as { language?: string; isWebUi?: boolean; defaultBranch?: string; worktreeCreated?: boolean; initializedRepo?: boolean } | undefined;
+	const classify = s.state.classify as { taskType?: string; uiScope?: string } | undefined;
+	const lines = [
+		`${icon[s.status]} ${title[s.status]}`,
+		`  Spec:     ${s.specIdentifier || "(none)"}`,
+		`  Worktree: ${abbreviatePath(s.worktreePath, cwd)}${setup?.worktreeCreated ? " (created)" : setup ? " (in-place)" : ""}`,
+		`  Stack:    ${setup ? `${setup.language}${setup.isWebUi ? " | Web UI" : ""}${setup.defaultBranch ? ` | branch ${setup.defaultBranch}` : ""}` : "n/a"}`,
+		`  Classify: ${classify ? `${classify.taskType}${classify.uiScope ? ` | ${classify.uiScope}` : ""}` : "n/a"}`,
+		`  Agents:   ${s.agentsSpawned} spawned`,
+		`  Impl:     ${impl?.summary ?? (impl ? `${impl.totalPhases ?? 0} phase(s), allGreen=${impl.allGreen ?? false}` : "none produced")}`,
+		`  Review:   ${review?.verdict ?? (s.state.review ? "no verdict" : "skipped")}`,
+		`  Merged:   ${s.state.merge ? String((s.state.merge as { merged?: boolean }).merged ?? false) : "skipped"}`,
+	];
+	if (s.failedStages.length > 0) {
+		const fmt = (f: { label: string; error?: string }) => {
+			const e = f.error ? ` — ${f.error}` : "";
+			return `${f.label}${e}`;
+		};
+		lines.push(`  Failed:   ${s.failedStages.map(fmt).join("\n            ")}`);
+	}
+	if (s.error) lines.push(`  Error:    ${s.error}`);
+	return lines;
+}
+
+export default function activate(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: SUPER_DEV_TOOL,
+		label: "Super Dev",
+		description:
+			"Run the self-contained 13-stage super-dev pipeline (requirements → research → design → spec → TDD implementation → code review → docs → merge). Spawns specialist `pi` subagents directly — no external workflow engine required.",
+		promptSnippet: "Run the full 13-stage super-dev development pipeline for a feature/bug/refactor task",
+		promptGuidelines: [
+			"Use super_dev when the user asks to implement a feature, fix a bug, or refactor code as a structured multi-stage workflow.",
+			"Pass the user's full task verbatim to super_dev; do not paraphrase constraints, file references, or acceptance criteria.",
+		],
+		parameters: Type.Object({
+			task: Type.String({ description: "The full development task, e.g. 'implement OAuth2 login' or 'fix the crash on large file upload'." }),
+			skipWorktree: Type.Optional(Type.Boolean({ description: "Skip git worktree creation and operate in the current directory. Default: false." })),
+			skipStages: Type.Optional(Type.Array(Type.String(), { description: "Stage output keys to skip (advanced). Default: none." })),
+			model: Type.Optional(Type.String({ description: "Model override for spawned specialist agents in provider/id form." })),
+			maxAgents: Type.Optional(Type.Number({ description: "Maximum specialist agent spawns. Default: 200." })),
+		}),
+		async execute(_toolCallId, params, signal, onUpdate) {
+			const task = String(params.task ?? "").trim();
+			if (!task) {
+				return { content: [{ type: "text", text: "super_dev requires a non-empty `task`." }], isError: true, details: {} };
+			}
+			const transcript: string[] = [];
+			let live = "";
+			let lastFlush = 0;
+			const FLUSH_MS = 80;
+			// The live display is a ROLLING TAIL. A full run (100+ agents) produces
+			// thousands of transcript lines; sending the whole thing on every flush
+			// let pi truncate it, and since later stages append at the END, they were
+			// the first to fall off the visible window ("very little logs afterwards").
+			// The tail keeps the CURRENT activity visible; the full log is written to
+			// disk at run end so nothing is lost.
+			const TAIL_LINES = 400;
+			const finalizeLive = () => {
+				if (live) {
+					transcript.push(live);
+					live = "";
+				}
+			};
+			const flush = () => {
+				const all = live ? [...transcript, live] : transcript;
+				const body = all.length > TAIL_LINES
+					? `… ${all.length - TAIL_LINES} earlier lines trimmed (full log saved to .super-dev-logs/ at run end) …\n` + all.slice(-TAIL_LINES).join("\n")
+					: all.join("\n");
+				onUpdate?.({ content: [{ type: "text", text: body }], details: {} });
+			};
+			const sink: ProgressSink = {
+				phase: (label) => { finalizeLive(); transcript.push(`▶ ${label}`); flush(); },
+				log: (message) => { finalizeLive(); transcript.push(`  ${message}`); flush(); },
+				text: (partial) => {
+					live = partial;
+					const now = Date.now();
+					if (now - lastFlush >= FLUSH_MS) { flush(); lastFlush = now; }
+				},
+			};
+			try {
+				const summary = await runPipelineTask(task, {
+					cwd: process.cwd(),
+					skipWorktree: params.skipWorktree === true,
+					skipStages: params.skipStages as string[] | undefined,
+					model: params.model as string | undefined,
+					maxAgents: typeof params.maxAgents === "number" ? params.maxAgents : undefined,
+				progress: sink,
+					signal,
+				});
+				const lines = formatSummary(summary, process.cwd());
+				// Preserve the FULL run log to disk (the live display is a rolling tail).
+				let logPath = "";
+				try {
+					const logDir = join(process.cwd(), ".super-dev-logs");
+					mkdirSync(logDir, { recursive: true });
+					logPath = join(logDir, `${new Date().toISOString().replace(/[:.]/g, "-")}-${summary.specIdentifier || "run"}.log`);
+					writeFileSync(logPath, transcript.join("\n") + "\n");
+				} catch { /* best-effort; the live tail is the primary surface */ }
+				if (logPath) lines.push(`Full run log: ${logPath}`);
+				const isError = summary.status === "failed";
+				return { content: [{ type: "text", text: lines.join("\n") }], isError, details: { summary } };
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				return { content: [{ type: "text", text: `❌ super-dev pipeline failed: ${message}` }], isError: true, details: {} };
+			}
+		},
+	});
+
+	pi.registerCommand(SUPER_DEV_COMMAND, {
+		description: "Run the 13-stage super-dev pipeline. Usage: /super-dev <task description>",
+		handler: async (args, ctx) => {
+			const task = String(args ?? "").trim();
+			if (!task) {
+				ctx.ui.notify(
+					"Usage: /super-dev <task description>\n\nExamples:\n  /super-dev implement user authentication with OAuth2\n  /super-dev fix the crash when uploading large files",
+					"info",
+				);
+				return;
+			}
+			// Dispatch to the agent so it runs interruptibly and the tool streams progress.
+			pi.sendUserMessage(`Use the ${SUPER_DEV_TOOL} tool to run the full super-dev pipeline for this task: ${task}`);
+		},
+	});
+}