stonecut 1.0.0

package/src/runner.ts

@@ -0,0 +1,298 @@
+/**
+ * Runner — commit flow, orchestration loop, and session helpers.
+ *
+ * verifyAndFix: single check → fix cycle.
+ * commitIssue: stage, commit, retry on failure up to maxRetries times.
+ * runAfkLoop: main orchestration loop over issues from any source.
+ * fmtTime / printSummary: session output formatting.
+ *
+ * Modules throw on failure. No process.exit, no console output.
+ */
+
+import {
+	commitChanges as realCommitChanges,
+	revertUncommitted as realRevertUncommitted,
+	snapshotWorkingTree as realSnapshotWorkingTree,
+	stageChanges as realStageChanges,
+} from "./git";
+import type {
+	GitOps,
+	IterationResult,
+	LogWriter,
+	Runner,
+	Session,
+	Source,
+	WorkingTreeSnapshot,
+} from "./types";
+
+/** Default git operations that call the real git module. */
+export const defaultGitOps: GitOps = {
+	snapshotWorkingTree: realSnapshotWorkingTree,
+	stageChanges: realStageChanges,
+	commitChanges: realCommitChanges,
+	revertUncommitted: realRevertUncommitted,
+};
+
+/** Console-only logger for backward compatibility. */
+export const consoleLogger: LogWriter = {
+	log: (message: string) => console.log(message),
+	close: () => {},
+};
+
+/**
+ * Single check → fix cycle.
+ *
+ * Runs `check`. If it passes, returns immediately. If it fails,
+ * spawns the runner with a prompt built from the error output,
+ * then runs the check once more.
+ *
+ * Returns [success, output] from the final check.
+ */
+export async function verifyAndFix(
+	runner: Runner,
+	check: () => [boolean, string],
+	fixPrompt: (error: string) => string,
+): Promise<[boolean, string]> {
+	const [ok, output] = check();
+	if (ok) {
+		return [true, output];
+	}
+	await runner.run(fixPrompt(output));
+	return check();
+}
+
+/**
+ * Stage, commit, and retry on failure up to `maxRetries` times.
+ *
+ * Returns [success, output] where output is the commit or error
+ * output from the last attempt.
+ */
+export async function commitIssue(
+	runner: Runner,
+	message: string,
+	snapshot: WorkingTreeSnapshot,
+	maxRetries: number = 3,
+	git: GitOps = defaultGitOps,
+): Promise<[boolean, string]> {
+	git.stageChanges(snapshot);
+
+	let output = "";
+	for (let attempt = 0; attempt < maxRetries; attempt++) {
+		const [ok, result] = await verifyAndFix(
+			runner,
+			() => git.commitChanges(message),
+			(error) =>
+				"The git commit failed with the following output. " +
+				"Fix the issues and stop. Do not commit.\n\n" +
+				error,
+		);
+		output = result;
+		if (ok) {
+			return [true, output];
+		}
+		// Re-stage after the fix attempt (runner may have changed files)
+		git.stageChanges(snapshot);
+	}
+
+	return [false, output];
+}
+
+/**
+ * Run the autonomous loop over issues from any source.
+ *
+ * Uses the provided Session to execute each issue's prompt.
+ * After each successful run, Stonecut stages and commits the changes.
+ * Works with both LocalSource and GitHubSource.
+ *
+ * A failing issue is retried once (2 total attempts). If it fails
+ * a second time, the session stops — issues are sequential vertical
+ * slices, so skipping is not viable.
+ */
+export async function runAfkLoop<T extends { number: number }>(
+	source: Source<T>,
+	iterations: number | "all",
+	renderPrompt: (issue: T) => string | Promise<string>,
+	displayName: (issue: T) => string,
+	commitMessage: (issue: T) => string,
+	session: Session,
+	onNoChanges?: (issue: T, output: string | undefined) => void,
+): Promise<IterationResult[]> {
+	const { logger, git, runner, runnerName } = session;
+
+	logger.log(`Session started — runner: ${runnerName}, iterations: ${iterations}`);
+	logger.log("");
+	const results: IterationResult[] = [];
+	const sessionStart = performance.now();
+	let iteration = 0;
+	let lastFailedIssueNumber: number | null = null;
+
+	while (true) {
+		// Check iteration limit
+		if (typeof iterations === "number" && iteration >= iterations) {
+			break;
+		}
+
+		const issue = await source.getNextIssue();
+		if (issue === null) {
+			if (iteration === 0) {
+				logger.log("All issues complete!");
+			}
+			break;
+		}
+
+		iteration++;
+		const name = displayName(issue);
+		const [remaining, total] = await source.getRemainingCount();
+
+		// Detect retry
+		if (lastFailedIssueNumber === issue.number) {
+			logger.log(
+				`--- Iteration ${iteration} --- [Issue ${issue.number}: ${name}] (${remaining}/${total} remaining)`,
+			);
+			logger.log(`Retrying issue ${issue.number} (attempt 2 of 2)`);
+		} else {
+			logger.log(
+				`--- Iteration ${iteration} --- [Issue ${issue.number}: ${name}] (${remaining}/${total} remaining)`,
+			);
+		}
+
+		// Snapshot working tree before runner
+		const snapshot = git.snapshotWorkingTree();
+
+		logger.log(`Running ${runnerName}...`);
+		const prompt = await renderPrompt(issue);
+		const runResult = await runner.run(prompt);
+
+		if (!runResult.success) {
+			logger.log(`Reverted working tree to pre-run snapshot.`);
+			git.revertUncommitted(snapshot);
+			const errorDetail = runResult.error || "unknown error";
+			logger.log(
+				`Issue ${issue.number}: runner failed — ${errorDetail} ` +
+					`(${fmtTime(runResult.durationSeconds)})`,
+			);
+			results.push({
+				issueNumber: issue.number,
+				issueFilename: name,
+				success: false,
+				elapsedSeconds: runResult.durationSeconds,
+				error: runResult.error,
+			});
+
+			if (lastFailedIssueNumber === issue.number) {
+				logger.log(`Issue ${issue.number}: failed twice consecutively — stopping session.`);
+				logger.log("");
+				break;
+			}
+			lastFailedIssueNumber = issue.number;
+			logger.log("");
+			continue;
+		}
+
+		// Runner succeeded — check for changes
+		logger.log(`Staging changes...`);
+		const hasChanges = git.stageChanges(snapshot);
+		if (!hasChanges) {
+			const errorMsg = "runner produced no changes";
+			logger.log(`Issue ${issue.number}: ${errorMsg} ` + `(${fmtTime(runResult.durationSeconds)})`);
+			if (onNoChanges) {
+				onNoChanges(issue, runResult.output);
+			}
+			results.push({
+				issueNumber: issue.number,
+				issueFilename: name,
+				success: false,
+				elapsedSeconds: runResult.durationSeconds,
+				error: errorMsg,
+			});
+
+			if (lastFailedIssueNumber === issue.number) {
+				logger.log(`Issue ${issue.number}: failed twice consecutively — stopping session.`);
+				logger.log("");
+				break;
+			}
+			lastFailedIssueNumber = issue.number;
+			logger.log("");
+			continue;
+		}
+
+		// Commit the changes
+		logger.log(`Committing...`);
+		const msg = commitMessage(issue);
+		const [committed] = await commitIssue(runner, msg, snapshot, 3, git);
+
+		if (!committed) {
+			logger.log(
+				`Issue ${issue.number}: commit failed after retries ` +
+					`(${fmtTime(runResult.durationSeconds)})`,
+			);
+			git.revertUncommitted(snapshot);
+			results.push({
+				issueNumber: issue.number,
+				issueFilename: name,
+				success: false,
+				elapsedSeconds: runResult.durationSeconds,
+				error: "commit failed after retries",
+			});
+			// Commit failures always stop the session immediately
+			logger.log("Stopping session: unable to commit.");
+			logger.log("");
+			break;
+		}
+
+		// Commit succeeded — mark issue complete
+		await source.completeIssue(issue);
+		logger.log(
+			`Issue ${issue.number}: committed and completed ` + `(${fmtTime(runResult.durationSeconds)})`,
+		);
+		results.push({
+			issueNumber: issue.number,
+			issueFilename: name,
+			success: true,
+			elapsedSeconds: runResult.durationSeconds,
+		});
+
+		lastFailedIssueNumber = null;
+		logger.log("");
+	}
+
+	// Session summary
+	const totalElapsed = (performance.now() - sessionStart) / 1000;
+	printSummary(results, totalElapsed, logger);
+	return results;
+}
+
+/** Format seconds as a human-readable duration. */
+export function fmtTime(seconds: number): string {
+	if (seconds < 60) {
+		return `${Math.round(seconds)}s`;
+	}
+	const minutes = Math.floor(seconds / 60);
+	const secs = Math.floor(seconds % 60);
+	return `${minutes}m ${secs}s`;
+}
+
+/** Print a summary of the afk session. */
+export function printSummary(
+	results: IterationResult[],
+	totalSeconds: number,
+	logger: LogWriter = consoleLogger,
+): void {
+	if (results.length === 0) {
+		return;
+	}
+
+	logger.log("=== Session Summary ===");
+	const succeeded = results.filter((r) => r.success).length;
+	const failed = results.filter((r) => !r.success).length;
+
+	for (const r of results) {
+		const status = r.success ? "completed" : "failed";
+		const elapsed = fmtTime(r.elapsedSeconds);
+		logger.log(`  Issue ${r.issueNumber} (${r.issueFilename}): ${status} (${elapsed})`);
+	}
+
+	logger.log("");
+	logger.log(`Total: ${results.length} issues — ${succeeded} completed, ${failed} failed`);
+	logger.log(`Total time: ${fmtTime(totalSeconds)}`);
+}

package/src/runners/claude.ts

@@ -0,0 +1,89 @@
+/**
+ * ClaudeRunner — adapter for Claude Code CLI.
+ *
+ * Spawns a headless Claude Code session, parses the JSON output to
+ * determine success/failure, and translates error subtypes into
+ * human-readable messages.
+ */
+
+import type { Runner, RunResult } from "../types.js";
+
+const ERROR_MESSAGES: Record<string, string> = {
+	error_max_turns: "max turns exceeded",
+	error_max_budget_usd: "max budget exceeded",
+};
+
+export class ClaudeRunner implements Runner {
+	async run(prompt: string): Promise<RunResult> {
+		const start = performance.now();
+
+		let proc: Awaited<ReturnType<typeof Bun.spawn>>;
+		try {
+			proc = Bun.spawn(
+				[
+					"claude",
+					"-p",
+					"--output-format",
+					"json",
+					"--allowedTools",
+					"Bash,Edit,Read,Write,Glob,Grep",
+				],
+				{ stdin: new Response(prompt), stdout: "pipe", stderr: "pipe" },
+			);
+		} catch {
+			return {
+				success: false,
+				exitCode: 1,
+				durationSeconds: (performance.now() - start) / 1000,
+				error: "claude binary not found in PATH",
+			};
+		}
+
+		const exitCode = await proc.exited;
+		const durationSeconds = (performance.now() - start) / 1000;
+
+		const stdout = await new Response(proc.stdout as ReadableStream).text();
+		const output = stdout || undefined;
+
+		if (output === undefined) {
+			return {
+				success: false,
+				exitCode,
+				durationSeconds,
+				error: `no output (exit code ${exitCode})`,
+			};
+		}
+
+		let data: unknown;
+		try {
+			data = JSON.parse(output);
+		} catch {
+			return {
+				success: false,
+				exitCode,
+				durationSeconds,
+				output,
+				error: "malformed JSON output",
+			};
+		}
+
+		if (typeof data !== "object" || data === null || Array.isArray(data)) {
+			return {
+				success: false,
+				exitCode,
+				durationSeconds,
+				output,
+				error: "unexpected JSON output (not an object)",
+			};
+		}
+
+		const subtype = (data as Record<string, unknown>).subtype ?? "";
+		if (subtype === "success") {
+			return { success: true, exitCode, durationSeconds, output };
+		}
+
+		const error =
+			ERROR_MESSAGES[subtype as string] ?? `failed (${(subtype as string) || "unknown"})`;
+		return { success: false, exitCode, durationSeconds, output, error };
+	}
+}

package/src/runners/codex.ts

@@ -0,0 +1,77 @@
+/**
+ * CodexRunner — adapter for OpenAI Codex CLI.
+ *
+ * Spawns a headless Codex session in full-auto mode, uses exit code as
+ * the primary success signal, and extracts error details from JSONL
+ * output on failure.
+ */
+
+import type { Runner, RunResult } from "../types.js";
+
+function extractError(stdout: string): string {
+	for (const raw of stdout.split("\n")) {
+		const line = raw.trim();
+		if (!line) continue;
+
+		let event: unknown;
+		try {
+			event = JSON.parse(line);
+		} catch {
+			continue;
+		}
+
+		if (typeof event !== "object" || event === null || Array.isArray(event)) {
+			continue;
+		}
+
+		const rec = event as Record<string, unknown>;
+		const eventType = rec.type;
+
+		if (eventType === "turn.failed") {
+			const nested = rec.error;
+			if (typeof nested === "object" && nested !== null && !Array.isArray(nested)) {
+				const msg = (nested as Record<string, unknown>).message;
+				if (typeof msg === "string" && msg) return msg;
+			}
+		} else if (eventType === "error") {
+			const msg = rec.message;
+			if (typeof msg === "string" && msg) return msg;
+		}
+	}
+
+	return "codex exited with non-zero status";
+}
+
+export class CodexRunner implements Runner {
+	async run(prompt: string): Promise<RunResult> {
+		const start = performance.now();
+
+		let proc: Awaited<ReturnType<typeof Bun.spawn>>;
+		try {
+			proc = Bun.spawn(["codex", "exec", "--full-auto", "--json", "--ephemeral", "-"], {
+				stdin: new Response(prompt),
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+		} catch {
+			return {
+				success: false,
+				exitCode: 1,
+				durationSeconds: (performance.now() - start) / 1000,
+				error: "codex binary not found in PATH",
+			};
+		}
+
+		const exitCode = await proc.exited;
+		const durationSeconds = (performance.now() - start) / 1000;
+
+		if (exitCode === 0) {
+			return { success: true, exitCode: 0, durationSeconds };
+		}
+
+		const stdout = await new Response(proc.stdout as ReadableStream).text();
+		const error = extractError(stdout);
+
+		return { success: false, exitCode, durationSeconds, error };
+	}
+}

package/src/runners/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Runner registry — maps runner names to their implementations.
+ */
+
+import type { Runner } from "../types.js";
+import { ClaudeRunner } from "./claude.js";
+import { CodexRunner } from "./codex.js";
+
+const RUNNERS: Record<string, new () => Runner> = {
+	claude: ClaudeRunner,
+	codex: CodexRunner,
+};
+
+export function getRunner(name: string): Runner {
+	const Cls = RUNNERS[name];
+	if (!Cls) {
+		const available = Object.keys(RUNNERS).sort().join(", ");
+		throw new Error(`Unknown runner '${name}'. Available runners: ${available}`);
+	}
+	return new Cls();
+}

package/src/skills/stonecut-interview/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: stonecut-interview
+description: Stress-test a plan or design through relentless interviewing. Walk down each branch of the decision tree, resolving dependencies one-by-one until reaching shared understanding. Use when the user wants to validate an idea before writing a PRD.
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+## Guidelines
+
+- Be relentless. Push back on vague answers. The goal is stress-testing, not politeness.
+- Prioritize questions that could change the shape of the solution.
+- When you discover a contradiction or gap, state it clearly and demand resolution.
+- For each question, provide your recommended answer.
+- Once a branch is resolved, move on. Don't revisit settled decisions.
+
+## Next Step
+
+When the interview is complete and you've reached shared understanding, ask the user: "Ready to write the PRD? I can run `/stonecut-prd` next."

package/src/skills/stonecut-issues/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: stonecut-issues
+description: Break a PRD into independently-grabbable GitHub issues or local markdown files using tracer-bullet vertical slices. Use when the user wants to convert a PRD into implementation tickets or work items.
+---
+
+You are breaking a PRD into issues as part of the Stonecut workflow. Each issue should be a thin vertical slice that cuts through all integration layers end-to-end.
+
+## Process
+
+### 1. Locate the PRD
+
+Determine where the PRD lives. Check these in order:
+
+1. **Conversation context** — If a PRD was created earlier in this conversation (via `/stonecut-prd` or otherwise), you already know where it is. State where you found it and confirm with the user.
+2. **Ask the user** — If no PRD is in context, ask: "Where is the PRD? Give me a local file path (e.g., `.stonecut/ASC-1/prd.md`) or a GitHub issue number."
+
+If given a GitHub issue number, fetch it with `gh issue view <number>`.
+If given a local path, read the file.
+
+### 2. Explore the codebase (optional)
+
+If you have not already explored the codebase, do so to understand the current state of the code.
+
+### 3. Draft vertical slices
+
+Break the PRD into **tracer bullet** issues. Each issue is a thin vertical slice that cuts through ALL integration layers end-to-end, NOT a horizontal slice of one layer.
+
+Slices may be 'HITL' or 'AFK'. HITL slices require human interaction, such as an architectural decision or a design review. AFK slices can be implemented and merged without human interaction. Prefer AFK over HITL where possible.
+
+<vertical-slice-rules>
+- Each slice delivers a narrow but COMPLETE path through every layer (schema, API, UI, tests)
+- A completed slice is demoable or verifiable on its own
+- Prefer many thin slices over few thick ones
+</vertical-slice-rules>
+
+#### Documentation Impact check
+
+Inspect the PRD's **Documentation Impact** section to determine whether documentation work is needed:
+
+- **Non-trivial changes** (new README sections, updated usage examples, new docs/ pages): generate a **dedicated documentation issue** — typically the last or near-last slice, since it depends on the feature being built.
+- **Trivial changes** (adding one line to a table, fixing a version number): fold the doc update into the relevant feature slice's acceptance criteria instead of creating a separate issue.
+- **No changes needed**: no action required — the PRD author already stated why.
+
+### 4. Quiz the user
+
+Present the proposed breakdown as a numbered list. For each slice, show:
+
+- **Title**: short descriptive name
+- **Type**: HITL / AFK
+- **Blocked by**: which other slices (if any) must complete first
+- **User stories covered**: which user stories from the PRD this addresses
+
+Ask the user:
+
+- Does the granularity feel right? (too coarse / too fine)
+- Are the dependency relationships correct?
+- Should any slices be merged or split further?
+- Are the correct slices marked as HITL and AFK?
+
+Iterate until the user approves the breakdown.
+
+### 5. Determine where to create the issues
+
+Default to **matching the PRD location**:
+
+- If the PRD is a **local file** (e.g., `.stonecut/ASC-1/prd.md`), default to creating issues in the same directory under `issues/` (e.g., `.stonecut/ASC-1/issues/01-short-title.md`).
+- If the PRD is a **GitHub issue**, default to creating issues as GitHub issues using `gh issue create`.
+
+Confirm with the user before creating. If they want a different destination, respect that.
+
+### 6. Create the issues
+
+#### Local files
+
+Create each issue as a markdown file in the issues directory. Use zero-padded numbering with a kebab-case descriptive suffix:
+
+```
+.stonecut/<name>/issues/
+  01-short-descriptive-title.md
+  02-another-slice-title.md
+  ...
+```
+
+Create issues in dependency order (blockers first). Use the local issue template below.
+
+<local-issue-template>
+# Issue <N>: <Title>
+
+## Parent PRD
+
+See `.stonecut/<name>/prd.md`
+
+## What to build
+
+A concise description of this vertical slice. Describe the end-to-end behavior, not layer-by-layer implementation. Reference specific sections of the parent PRD rather than duplicating content.
+
+## Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Blocked by
+
+- Blocked by Issue <N> (if any)
+
+Or "None — can start immediately" if no blockers.
+
+## User stories addressed
+
+Reference by number from the parent PRD:
+
+- User story 3
+- User story 7
+
+</local-issue-template>
+
+#### GitHub issues
+
+Create each issue using `gh issue create`. Create in dependency order so you can reference real issue numbers in the "Blocked by" field.
+
+After creating each GitHub issue, link it as a sub-issue of the PRD:
+
+```bash
+# Get node IDs
+PRD_NODE_ID=$(gh api repos/{owner}/{repo}/issues/{prd_number} --jq '.node_id')
+ISSUE_NODE_ID=$(gh api repos/{owner}/{repo}/issues/{new_issue_number} --jq '.node_id')
+
+# Link as sub-issue
+gh api graphql -f query="mutation { addSubIssue(input: { issueId: \"$PRD_NODE_ID\" subIssueId: \"$ISSUE_NODE_ID\" }) { subIssue { number } } }"
+```
+
+<github-issue-template>
+## What to build
+
+A concise description of this vertical slice. Describe the end-to-end behavior, not layer-by-layer implementation. Reference specific sections of the parent PRD rather than duplicating content.
+
+## Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Blocked by
+
+- Blocked by #<issue-number> (if any)
+
+Or "None - can start immediately" if no blockers.
+
+## User stories addressed
+
+Reference by number from the parent PRD:
+
+- User story 3
+- User story 7
+
+</github-issue-template>
+
+Do NOT close or modify the parent PRD issue (if it's a GitHub issue).
+
+## Workflow Complete
+
+Once all issues are created, present the user with their options:
+
+1. **Implement now** — Start on the first issue in this session
+2. **Start fresh** — Pick up implementation in a new session
+3. **Use the stonecut CLI** — Run implementation via the CLI