stonecut 1.2.1 → 1.3.0

package/README.md

@@ -14,7 +14,7 @@ Ideas can come from anywhere — Jira tickets, Slack threads, MCP servers, or ju
 1. **`/stonecut-interview`** — Stress-test the idea. Get grilled on the plan until it's solid.
 2. **`/stonecut-prd`** — Turn the validated idea into a PRD (local file or GitHub issue).
 3. **`/stonecut-issues`** — Break the PRD into independently-grabbable issues (local markdown files or GitHub sub-issues).
-4. **`stonecut import`** _(optional)_ — If the PRD lives in GitHub, import it and its issues into `.stonecut/`.
+4. **`stonecut import`** _(optional)_ — If the PRD lives in GitHub, import it and its issues into `.stonecut/specs/`.
 5. **`stonecut`** — Execute the issues sequentially with an agentic coding CLI.
 
 **From a technical exploration:** `RFC issue → PRD → issues → execute`
@@ -83,7 +83,7 @@ Running bare `stonecut` starts the interactive run wizard — the primary workfl
 
 ### `stonecut` — Interactive wizard
 
-Stonecut uses a local-first execution model: `stonecut run` always reads from `.stonecut/<name>/`. External sources like GitHub are handled via `stonecut import`, which pulls PRDs and issues into the local structure before execution.
+Stonecut uses a local-first execution model: `stonecut run` always reads from `.stonecut/specs/<name>/`. External sources like GitHub are handled via `stonecut import`, which pulls PRDs and issues into the local structure before execution.
 
 When flags are omitted, Stonecut prompts for each missing parameter:
 
@@ -100,7 +100,7 @@ stonecut -i all
 
 You can also use `stonecut run` explicitly — it's identical to bare `stonecut`.
 
-The wizard scans `.stonecut/*/` for local PRDs and presents them with completion counts (e.g. "my-feature (3/7 done)"). An "Import from GitHub" option is always available at the bottom of the list for importing PRDs inline.
+The wizard scans `.stonecut/specs/*/` for local PRDs and presents them with completion counts (e.g. "my-feature (3/7 done)"). An "Import from GitHub" option is always available at the bottom of the list for importing PRDs inline.
 
 Flags provided via CLI skip the corresponding prompts. When all flags are given, the command runs without any prompts.
 
@@ -143,7 +143,7 @@ When config is present, the wizard uses these as default values — you can hit
 
 ### `stonecut import` — Import from external sources
 
-Pulls a PRD and its sub-issues from an external source into `.stonecut/<name>/` so they can be executed locally with `stonecut run`.
+Pulls a PRD and its sub-issues from an external source into `.stonecut/specs/<name>/` so they can be executed locally with `stonecut run`.
 
 ```sh
 # Import GitHub PRD #42 — spec name derived from PRD title
@@ -161,7 +161,7 @@ The import command:
 1. Fetches the PRD content and title from the source.
 2. Fetches all sub-issues, ordered by number.
 3. Derives a local spec name from the PRD title (e.g. "Add user authentication" becomes `add-user-authentication`). Override with `--name`.
-4. Writes `prd.md` and numbered issue files into `.stonecut/<name>/issues/`.
+4. Writes `prd.md` and numbered issue files into `.stonecut/specs/<name>/issues/`.
 5. Creates initial `status.json` and `progress.txt`.
 
 Import errors if the spec directory already exists (to avoid overwriting in-progress work). Use `--force` to overwrite intentionally.
@@ -220,7 +220,7 @@ When issues imported from GitHub are completed, Stonecut automatically closes th
 
 | Flag           | Short | Required | Description                                                              |
 | -------------- | ----- | -------- | ------------------------------------------------------------------------ |
-| `--local`      | —     | No       | Local PRD name (`.stonecut/<name>/`). Prompted if omitted.               |
+| `--local`      | —     | No       | Local PRD name (`.stonecut/specs/<name>/`). Prompted if omitted.         |
 | `--iterations` | `-i`  | No       | Positive integer or `all`. Prompted with default `all` if omitted.       |
 | `--runner`     | —     | No       | Agentic CLI runner (`claude`, `codex`). Default from config or `claude`. |
 
@@ -260,10 +260,10 @@ For imported PRDs, the PR body includes a `Closes #<number>` reference to the pa
 
 ## Local PRD structure
 
-All execution reads from `.stonecut/<name>/` directories with this structure:
+All execution reads from `.stonecut/specs/<name>/` directories with this structure:
 
 ```
-.stonecut/my-feature/
+.stonecut/specs/my-feature/
 ├── prd.md              # The full PRD
 ├── issues/
 │   ├── 01-setup.md     # Issue files, numbered for ordering
@@ -279,7 +279,7 @@ PRDs and issues are committed to git; runtime state (`status.json`, `progress.tx
 
 Issue and PRD files support YAML frontmatter for metadata. Locally-authored files don't need frontmatter — it's added automatically by `stonecut import`.
 
-**PRD frontmatter** (`.stonecut/<name>/prd.md`):
+**PRD frontmatter** (`.stonecut/specs/<name>/prd.md`):
 
 ```markdown
 ---
@@ -291,7 +291,7 @@ title: Add user authentication
 The actual PRD content starts here...
 ```
 
-**Issue frontmatter** (`.stonecut/<name>/issues/01-setup.md`):
+**Issue frontmatter** (`.stonecut/specs/<name>/issues/01-setup.md`):
 
 ```markdown
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stonecut",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "CLI that drives PRD-driven development with agentic coding CLIs",
   "license": "MIT",
   "repository": {
@@ -27,6 +27,7 @@
     "lint": "eslint src/ tests/",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
     "test": "bun test",
     "prepare": "husky"
   },

package/src/cli.ts

@@ -3,6 +3,7 @@
 /**
  * Stonecut CLI — PRD-driven development workflow orchestrator.
  *
+ * Commander definitions, validation helpers, wizard prompts, and entry point.
  * Modules throw errors; only this file catches them, formats user-facing
  * messages, and calls process.exit().
  */
@@ -10,27 +11,15 @@
 import * as clack from "@clack/prompts";
 import { Command, InvalidArgumentError } from "commander";
 import { createRequire } from "module";
-import {
-	checkoutOrCreateBranch,
-	createPr,
-	defaultBranch,
-	ensureCleanTree,
-	pushBranch,
-} from "./git";
-import { LocalSource } from "./local";
+import { defaultBranch, ensureCleanTree } from "./git";
 import { slugifyBranchComponent } from "./naming";
-import { renderLocal } from "./prompt";
-import { Logger } from "./logger";
-import { defaultGitOps, runAfkLoop } from "./runner";
-import { getRunner } from "./runners/index";
 import { setupSkills, removeSkills } from "./skills";
 import { init } from "./init";
 import { importSpec } from "./import";
 import { loadConfig } from "./config";
-import { getSourceProvider } from "./sources/index";
-import { existsSync, readdirSync, readFileSync, statSync } from "fs";
-import { join } from "path";
-import type { Issue, IterationResult, Session } from "./types";
+import { existsSync } from "fs";
+import { promptForPrd } from "./prd";
+import { executeLocal } from "./execute";
 
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
@@ -75,292 +64,6 @@ export function validateRunSource(
 	return { kind: "prompt" };
 }
 
-/** A locally available PRD with its completion status. */
-export interface LocalPrdEntry {
-	name: string;
-	completed: number;
-	total: number;
-}
-
-/**
- * Scan .stonecut subdirectories for directories containing prd.md and compute
- * completion counts from status.json.
- */
-export function scanLocalPrds(baseDir: string = ".stonecut/prd"): LocalPrdEntry[] {
-	if (!existsSync(baseDir)) return [];
-
-	const entries: LocalPrdEntry[] = [];
-	for (const name of readdirSync(baseDir)) {
-		const specDir = join(baseDir, name);
-		if (!statSync(specDir).isDirectory()) continue;
-		if (!existsSync(join(specDir, "prd.md"))) continue;
-
-		const issuesDir = join(specDir, "issues");
-		let total = 0;
-		if (existsSync(issuesDir) && statSync(issuesDir).isDirectory()) {
-			total = readdirSync(issuesDir).filter((f) => f.endsWith(".md")).length;
-		}
-
-		let completed = 0;
-		const statusPath = join(specDir, "status.json");
-		if (existsSync(statusPath)) {
-			try {
-				const data = JSON.parse(readFileSync(statusPath, "utf-8"));
-				completed = Array.isArray(data.completed) ? data.completed.length : 0;
-			} catch {
-				// Malformed status.json — treat as 0 completed
-			}
-		}
-
-		entries.push({ name, completed, total });
-	}
-	return entries.sort((a, b) => a.name.localeCompare(b.name));
-}
-
-/**
- * Format a PRD entry for display in the wizard.
- */
-function formatPrdOption(entry: LocalPrdEntry): string {
-	if (entry.total === 0) return `${entry.name} (no issues)`;
-	if (entry.completed === 0) return `${entry.name} (not started)`;
-	return `${entry.name} (${entry.completed}/${entry.total} done)`;
-}
-
-/** Sentinel value for the "Import from GitHub" wizard option. */
-const IMPORT_FROM_GITHUB = "__import_from_github__";
-
-/**
- * Prompt the user to select a local PRD or import from GitHub.
- * Returns the local spec name to run.
- */
-export async function promptForPrd(): Promise<{ kind: "local"; name: string }> {
-	const prds = scanLocalPrds();
-
-	const options: Array<{ value: string; label: string }> = prds.map((entry) => ({
-		value: entry.name,
-		label: formatPrdOption(entry),
-	}));
-	options.push({ value: IMPORT_FROM_GITHUB, label: "Import from GitHub" });
-
-	const selection = await clack.select({
-		message: "Select a PRD:",
-		options,
-	});
-
-	if (clack.isCancel(selection)) {
-		throw new Error("Cancelled.");
-	}
-
-	if (selection === IMPORT_FROM_GITHUB) {
-		const specName = await inlineGitHubImport();
-		return { kind: "local", name: specName };
-	}
-
-	return { kind: "local", name: selection as string };
-}
-
-/**
- * Inline GitHub import flow within the wizard.
- * Lists PRDs by `prd` label, user picks one, import runs.
- * Returns the imported spec name.
- */
-async function inlineGitHubImport(): Promise<string> {
-	const provider = getSourceProvider("github");
-	const prdList = await provider.listPrds();
-
-	if (prdList.length === 0) {
-		throw new Error("No open PRDs with the 'prd' label found on GitHub.");
-	}
-
-	const prdOptions = prdList.map((p) => ({
-		value: String(p.number),
-		label: `#${p.number}: ${p.title}`,
-	}));
-
-	const selected = await clack.select({
-		message: "Select a GitHub PRD to import:",
-		options: prdOptions,
-	});
-
-	if (clack.isCancel(selected)) {
-		throw new Error("Cancelled.");
-	}
-
-	const result = await importSpec({
-		provider: "github",
-		identifier: selected as string,
-	});
-
-	console.log(
-		`Imported PRD #${result.prdIssueNumber} → ${result.specDir}/ (${result.issueCount} issues)`,
-	);
-
-	return result.specName;
-}
-
-// ---------------------------------------------------------------------------
-// Stonecut report
-// ---------------------------------------------------------------------------
-
-/**
- * Build the Stonecut Report section for a PR body.
- */
-export function buildReport(
-	results: IterationResult[],
-	runnerName: string,
-	prdNumber?: number,
-): string {
-	const lines = ["## Stonecut Report", `**Runner:** ${runnerName}`, ""];
-	for (const r of results) {
-		if (r.success) {
-			lines.push(`- #${r.issueNumber} ${r.issueFilename}: completed`);
-		} else {
-			const reason = r.error || "unknown error";
-			lines.push(`- #${r.issueNumber} ${r.issueFilename}: failed — ${reason}`);
-		}
-	}
-
-	if (prdNumber !== undefined && results.every((r) => r.success)) {
-		lines.push("");
-		lines.push(`Closes #${prdNumber}`);
-	}
-
-	return lines.join("\n");
-}
-
-// ---------------------------------------------------------------------------
-// Pre-execution flow
-// ---------------------------------------------------------------------------
-
-/**
- * Run pre-execution prompts and git checks.
- * Returns [branch, baseBranch].
- */
-export async function preExecution(
-	suggestedBranch: string,
-	prefilled?: { branch?: string; baseBranch?: string },
-): Promise<[string, string]> {
-	let branch: string;
-	if (prefilled?.branch) {
-		branch = prefilled.branch;
-	} else {
-		const branchInput = await clack.text({
-			message: "Branch name:",
-			defaultValue: suggestedBranch,
-			placeholder: suggestedBranch,
-		});
-
-		if (clack.isCancel(branchInput)) {
-			throw new Error("Cancelled.");
-		}
-		branch = branchInput;
-	}
-
-	let baseBranch: string;
-	if (prefilled?.baseBranch) {
-		baseBranch = prefilled.baseBranch;
-	} else {
-		const detectedDefault = defaultBranch();
-		const baseBranchInput = await clack.text({
-			message: "Base branch / PR target:",
-			defaultValue: detectedDefault,
-			placeholder: detectedDefault,
-		});
-
-		if (clack.isCancel(baseBranchInput)) {
-			throw new Error("Cancelled.");
-		}
-		baseBranch = baseBranchInput;
-	}
-
-	checkoutOrCreateBranch(branch);
-	console.log("");
-
-	return [branch, baseBranch];
-}
-
-// ---------------------------------------------------------------------------
-// Post-loop: push and conditionally create PR
-// ---------------------------------------------------------------------------
-
-export async function pushAndMaybePr(
-	results: IterationResult[],
-	source: { getRemainingCount(): Promise<[number, number]> },
-	branch: string,
-	baseBranch: string,
-	prTitle: string,
-	runnerName: string,
-	logger: { log(message: string): void },
-	prdNumber?: number,
-): Promise<void> {
-	if (!results.some((r) => r.success)) {
-		return;
-	}
-
-	pushBranch(branch);
-	logger.log(`Pushed branch '${branch}'.`);
-
-	const [remaining, total] = await source.getRemainingCount();
-	if (remaining === 0) {
-		const body = buildReport(results, runnerName, prdNumber);
-		createPr(prTitle, body, baseBranch);
-		logger.log("Created PR.");
-	} else {
-		logger.log(`${remaining}/${total} issues remaining — PR deferred.`);
-	}
-}
-
-// ---------------------------------------------------------------------------
-// Execution paths
-// ---------------------------------------------------------------------------
-
-export async function runLocal(
-	name: string,
-	iterations: number | "all",
-	runnerName: string,
-	prefilled?: { branch?: string; baseBranch?: string },
-): Promise<void> {
-	const runner = getRunner(runnerName);
-	const source = new LocalSource(name);
-	const prdIdentifier = slugifyBranchComponent(name) || "spec";
-	const logger = new Logger(prdIdentifier);
-
-	const session: Session = { logger, git: defaultGitOps, runner, runnerName };
-
-	try {
-		const suggestedBranch = prdIdentifier ? `stonecut/${prdIdentifier}` : "stonecut/spec";
-		const [branch, baseBranch] = await preExecution(suggestedBranch, prefilled);
-
-		const prdContent = await source.getPrdContent();
-		const results = await runAfkLoop<Issue>(
-			source,
-			iterations,
-			(issue) =>
-				renderLocal({
-					prdContent,
-					issueNumber: issue.number,
-					issueFilename: issue.filename,
-					issueContent: issue.content,
-				}),
-			(issue) => issue.filename,
-			(issue) => `Issue ${issue.number}: ${issue.filename}`,
-			session,
-		);
-
-		await pushAndMaybePr(
-			results,
-			source,
-			branch,
-			baseBranch,
-			`Stonecut: ${name}`,
-			runnerName,
-			logger,
-		);
-	} finally {
-		logger.close();
-	}
-}
-
 // ---------------------------------------------------------------------------
 // Program definition
 // ---------------------------------------------------------------------------
@@ -378,17 +81,17 @@ export function buildProgram(): Command {
 	program
 		.command("run", { isDefault: true })
 		.description("Execute issues from a local PRD.")
-		.option("--local <name>", "Local PRD name (.stonecut/prd/<name>/)")
+		.option("--local <name>", "Local PRD name (.stonecut/specs/<name>/)")
 		.option("-i, --iterations <value>", "Number of issues to process, or 'all'")
+		.option("--branch <name>", "Branch name for the run")
+		.option("--base-branch <name>", "Base branch / PR target")
 		.option("--runner <name>", "Agentic CLI runner (claude, codex)")
 		.action(async (opts) => {
 			ensureCleanTree();
-
 			const config = loadConfig();
 
 			const validated = validateRunSource(opts.local);
 			let source: { kind: "local"; name: string };
-
 			if (validated.kind === "local") {
 				source = validated;
 			} else {
@@ -419,40 +122,45 @@ export function buildProgram(): Command {
 			}
 
 			const isWizard = validated.kind === "prompt" || needsIterationPrompt;
-			let prefilled: { branch?: string; baseBranch?: string } | undefined;
-
-			if (isWizard) {
-				if (!existsSync(".stonecut")) {
-					console.log("Hint: run `stonecut init` to set up project config and gitignore.\n");
-				}
+			if (isWizard && !existsSync(".stonecut")) {
+				console.log("Hint: run `stonecut init` to set up project config and gitignore.\n");
+			}
 
+			let branch: string;
+			if (opts.branch) {
+				branch = opts.branch;
+			} else {
 				const branchPrefix = config?.branchPrefix ?? "stonecut/";
 				const suggestedBranch = `${branchPrefix}${slugifyBranchComponent(source.name) || "spec"}`;
-
-				const branch = await clack.text({
+				const branchInput = await clack.text({
 					message: "Branch name:",
 					defaultValue: suggestedBranch,
 					placeholder: suggestedBranch,
 				});
-				if (clack.isCancel(branch)) {
+				if (clack.isCancel(branchInput)) {
 					throw new Error("Cancelled.");
 				}
+				branch = branchInput;
+			}
 
+			let baseBranch: string;
+			if (opts.baseBranch) {
+				baseBranch = opts.baseBranch;
+			} else {
 				const detectedDefault = config?.baseBranch ?? defaultBranch();
-				const baseBranch = await clack.text({
+				const baseBranchInput = await clack.text({
 					message: "Base branch / PR target:",
 					defaultValue: detectedDefault,
 					placeholder: detectedDefault,
 				});
-				if (clack.isCancel(baseBranch)) {
+				if (clack.isCancel(baseBranchInput)) {
 					throw new Error("Cancelled.");
 				}
-
-				prefilled = { branch, baseBranch };
+				baseBranch = baseBranchInput;
 			}
 
 			const runnerName: string = opts.runner ?? config?.runner ?? "claude";
-			await runLocal(source.name, iterations, runnerName, prefilled);
+			await executeLocal(source.name, branch, baseBranch, iterations, runnerName);
 		});
 
 	program
@@ -473,14 +181,12 @@ export function buildProgram(): Command {
 			if (opts.github === undefined) {
 				throw new Error("Specify a source: --github <number>");
 			}
-
 			const result = await importSpec({
 				provider: "github",
 				identifier: String(opts.github),
 				name: opts.name,
 				force: opts.force,
 			});
-
 			console.log(
 				`Imported PRD #${result.prdIssueNumber} → ${result.specDir}/ (${result.issueCount} issues)`,
 			);
@@ -495,12 +201,8 @@ export function buildProgram(): Command {
 		)
 		.action((opts) => {
 			const result = setupSkills(opts.target);
-			for (const msg of result.messages) {
-				console.log(msg);
-			}
-			for (const warn of result.warnings) {
-				console.error(warn);
-			}
+			for (const msg of result.messages) console.log(msg);
+			for (const warn of result.warnings) console.error(warn);
 		});
 
 	program
@@ -512,12 +214,8 @@ export function buildProgram(): Command {
 		)
 		.action((opts) => {
 			const result = removeSkills(opts.target);
-			for (const msg of result.messages) {
-				console.log(msg);
-			}
-			for (const warn of result.warnings) {
-				console.error(warn);
-			}
+			for (const msg of result.messages) console.log(msg);
+			for (const warn of result.warnings) console.error(warn);
 		});
 
 	return program;

package/src/execute.ts

@@ -0,0 +1,142 @@
+/**
+ * Execution orchestration — non-interactive, prompt-free.
+ *
+ * executeLocal: set up session, checkout branch, run loop, push/PR.
+ * pushAndMaybePr: push branch and conditionally create PR.
+ * buildReport: format iteration results for PR body.
+ *
+ * This module never imports @clack/prompts — the interactive/execution
+ * boundary is enforced by module structure.
+ */
+
+import { checkoutOrCreateBranch, createPr, pushBranch } from "./git";
+import { LocalSource } from "./local";
+import { slugifyBranchComponent } from "./naming";
+import { renderLocal } from "./prompt";
+import { Logger } from "./logger";
+import { defaultGitOps, runAfkLoop } from "./runner";
+import { getRunner } from "./runners/index";
+import type { Issue, IterationResult, Session } from "./types";
+
+// ---------------------------------------------------------------------------
+// Stonecut report
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the Stonecut Report section for a PR body.
+ */
+export function buildReport(
+	results: IterationResult[],
+	runnerName: string,
+	closingRefs?: string[],
+): string {
+	const lines = ["## Stonecut Report", `**Runner:** ${runnerName}`, ""];
+	for (const r of results) {
+		if (r.success) {
+			lines.push(`- #${r.issueNumber} ${r.issueFilename}: completed`);
+		} else {
+			const reason = r.error || "unknown error";
+			lines.push(`- #${r.issueNumber} ${r.issueFilename}: failed — ${reason}`);
+		}
+	}
+
+	if (closingRefs && closingRefs.length > 0) {
+		lines.push("");
+		lines.push(closingRefs.join("\n"));
+	}
+
+	return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Post-loop: push and conditionally create PR
+// ---------------------------------------------------------------------------
+
+export async function pushAndMaybePr(
+	results: IterationResult[],
+	source: {
+		getRemainingCount(): Promise<[number, number]>;
+		getClosingRefs?(completedIssueNumbers: number[]): string[];
+	},
+	branch: string,
+	baseBranch: string,
+	prTitle: string,
+	runnerName: string,
+	logger: { log(message: string): void },
+): Promise<void> {
+	if (!results.some((r) => r.success)) {
+		return;
+	}
+
+	pushBranch(branch);
+	logger.log(`Pushed branch '${branch}'.`);
+
+	const [remaining, total] = await source.getRemainingCount();
+	if (remaining === 0) {
+		const completed = results.filter((r) => r.success).map((r) => r.issueNumber);
+		const closingRefs = source.getClosingRefs?.(completed);
+		const body = buildReport(results, runnerName, closingRefs);
+		createPr(prTitle, body, baseBranch);
+		logger.log("Created PR.");
+	} else {
+		logger.log(`${remaining}/${total} issues remaining — PR deferred.`);
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Execution orchestration
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a local PRD run — non-interactive orchestration.
+ *
+ * All parameters are explicit: no interactive prompts, no @clack/prompts.
+ * Handles branch checkout, runner session, loop, push, and PR creation.
+ */
+export async function executeLocal(
+	name: string,
+	branch: string,
+	baseBranch: string,
+	iterations: number | "all",
+	runnerName: string,
+): Promise<void> {
+	const runner = getRunner(runnerName);
+	const source = new LocalSource(name);
+	const prdIdentifier = slugifyBranchComponent(name) || "spec";
+	const logger = new Logger(prdIdentifier);
+
+	const session: Session = { logger, git: defaultGitOps, runner, runnerName };
+
+	try {
+		checkoutOrCreateBranch(branch);
+		console.log("");
+
+		const prdContent = await source.getPrdContent();
+		const results = await runAfkLoop<Issue>(
+			source,
+			iterations,
+			(issue) =>
+				renderLocal({
+					prdContent,
+					issueNumber: issue.number,
+					issueFilename: issue.filename,
+					issueContent: issue.content,
+				}),
+			(issue) => issue.filename,
+			(issue) => `Issue ${issue.number}: ${issue.filename}`,
+			session,
+		);
+
+		await pushAndMaybePr(
+			results,
+			source,
+			branch,
+			baseBranch,
+			`Stonecut: ${name}`,
+			runnerName,
+			logger,
+		);
+	} finally {
+		logger.close();
+	}
+}

package/src/git.ts

@@ -5,28 +5,9 @@
  * All functions throw on failure. No process.exit, no console output.
  */
 
+import { runSync } from "./spawn";
 import type { WorkingTreeSnapshot } from "./types";
 
-/**
- * Run a command synchronously, optionally in a specific working directory.
- * When cwd is omitted, uses the current process working directory.
- */
-function runSync(
-	cmd: string[],
-	cwd?: string,
-): { exitCode: number; stdout: string; stderr: string } {
-	const proc = Bun.spawnSync(cmd, {
-		stdout: "pipe",
-		stderr: "pipe",
-		...(cwd && { cwd }),
-	});
-	return {
-		exitCode: proc.exitCode,
-		stdout: proc.stdout.toString(),
-		stderr: proc.stderr.toString(),
-	};
-}
-
 /** Detect the remote's default branch, falling back to "main". */
 export function defaultBranch(cwd?: string): string {
 	const result = runSync(["git", "symbolic-ref", "refs/remotes/origin/HEAD"], cwd);

package/src/import.ts

@@ -37,7 +37,7 @@ export async function importSpec(options: ImportOptions): Promise<ImportResult>
 		throw new Error("Could not derive a spec name from the PRD title. Use --name to specify one.");
 	}
 
-	const specDir = join(".stonecut", "prd", specName);
+	const specDir = join(".stonecut", "specs", specName);
 
 	if (existsSync(specDir)) {
 		if (!options.force) {

package/src/local.ts

@@ -1,4 +1,4 @@
-/** Local spec source — reads issues from .stonecut/prd/<name>/. */
+/** Local spec source — reads issues from .stonecut/specs/<name>/. */
 
 import { existsSync, readdirSync, readFileSync, writeFileSync, appendFileSync, statSync } from "fs";
 import { join } from "path";
@@ -11,7 +11,7 @@ export class LocalSource implements Source<Issue> {
 
 	constructor(name: string) {
 		this.name = name;
-		this.specDir = join(".stonecut", "prd", name);
+		this.specDir = join(".stonecut", "specs", name);
 		this.validate();
 	}
 
@@ -86,6 +86,32 @@ export class LocalSource implements Source<Issue> {
 		return null;
 	}
 
+	getClosingRefs(completedIssueNumbers: number[]): string[] {
+		const completed = new Set(completedIssueNumbers);
+		const refs: string[] = [];
+		const all = this.allIssues();
+
+		for (const issue of all) {
+			if (!completed.has(issue.number)) continue;
+			const raw = readFileSync(issue.path, "utf-8");
+			const num = parseInt(parseFrontmatter(raw).meta.issue, 10);
+			if (num && !isNaN(num)) {
+				refs.push(`Closes #${num}`);
+			}
+		}
+
+		const allComplete = all.every((i) => completed.has(i.number));
+		if (allComplete) {
+			const raw = readFileSync(join(this.specDir, "prd.md"), "utf-8");
+			const num = parseInt(parseFrontmatter(raw).meta.issue, 10);
+			if (num && !isNaN(num)) {
+				refs.push(`Closes #${num}`);
+			}
+		}
+
+		return refs;
+	}
+
 	async getRemainingCount(): Promise<[number, number]> {
 		const completed = this.readStatus();
 		const all = this.allIssues();

package/src/prd.ts

@@ -0,0 +1,136 @@
+/**
+ * PRD selection UI — filesystem scanning, interactive picker, and inline
+ * GitHub import flow.
+ *
+ * This is the only extracted module that imports @clack/prompts, as it is
+ * part of the interactive UI layer.
+ */
+
+import * as clack from "@clack/prompts";
+import { existsSync, readdirSync, readFileSync, statSync } from "fs";
+import { join } from "path";
+import { importSpec } from "./import";
+import { getSourceProvider } from "./sources/index";
+
+/** A locally available PRD with its completion status. */
+export interface LocalPrdEntry {
+	name: string;
+	completed: number;
+	total: number;
+}
+
+/**
+ * Scan .stonecut subdirectories for directories containing prd.md and compute
+ * completion counts from status.json.
+ */
+export function scanLocalPrds(baseDir: string = ".stonecut/specs"): LocalPrdEntry[] {
+	if (!existsSync(baseDir)) return [];
+
+	const entries: LocalPrdEntry[] = [];
+	for (const name of readdirSync(baseDir)) {
+		const specDir = join(baseDir, name);
+		if (!statSync(specDir).isDirectory()) continue;
+		if (!existsSync(join(specDir, "prd.md"))) continue;
+
+		const issuesDir = join(specDir, "issues");
+		let total = 0;
+		if (existsSync(issuesDir) && statSync(issuesDir).isDirectory()) {
+			total = readdirSync(issuesDir).filter((f) => f.endsWith(".md")).length;
+		}
+
+		let completed = 0;
+		const statusPath = join(specDir, "status.json");
+		if (existsSync(statusPath)) {
+			try {
+				const data = JSON.parse(readFileSync(statusPath, "utf-8"));
+				completed = Array.isArray(data.completed) ? data.completed.length : 0;
+			} catch {
+				// Malformed status.json — treat as 0 completed
+			}
+		}
+
+		entries.push({ name, completed, total });
+	}
+	return entries.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Format a PRD entry for display in the wizard.
+ */
+export function formatPrdOption(entry: LocalPrdEntry): string {
+	if (entry.total === 0) return `${entry.name} (no issues)`;
+	if (entry.completed === 0) return `${entry.name} (not started)`;
+	return `${entry.name} (${entry.completed}/${entry.total} done)`;
+}
+
+/** Sentinel value for the "Import from GitHub" wizard option. */
+const IMPORT_FROM_GITHUB = "__import_from_github__";
+
+/**
+ * Prompt the user to select a local PRD or import from GitHub.
+ * Returns the local spec name to run.
+ */
+export async function promptForPrd(): Promise<{ kind: "local"; name: string }> {
+	const prds = scanLocalPrds();
+
+	const options: Array<{ value: string; label: string }> = prds.map((entry) => ({
+		value: entry.name,
+		label: formatPrdOption(entry),
+	}));
+	options.push({ value: IMPORT_FROM_GITHUB, label: "Import from GitHub" });
+
+	const selection = await clack.select({
+		message: "Select a PRD:",
+		options,
+	});
+
+	if (clack.isCancel(selection)) {
+		throw new Error("Cancelled.");
+	}
+
+	if (selection === IMPORT_FROM_GITHUB) {
+		const specName = await inlineGitHubImport();
+		return { kind: "local", name: specName };
+	}
+
+	return { kind: "local", name: selection as string };
+}
+
+/**
+ * Inline GitHub import flow within the wizard.
+ * Lists PRDs by `prd` label, user picks one, import runs.
+ * Returns the imported spec name.
+ */
+async function inlineGitHubImport(): Promise<string> {
+	const provider = getSourceProvider("github");
+	const prdList = await provider.listPrds();
+
+	if (prdList.length === 0) {
+		throw new Error("No open PRDs with the 'prd' label found on GitHub.");
+	}
+
+	const prdOptions = prdList.map((p) => ({
+		value: String(p.number),
+		label: `#${p.number}: ${p.title}`,
+	}));
+
+	const selected = await clack.select({
+		message: "Select a GitHub PRD to import:",
+		options: prdOptions,
+	});
+
+	if (clack.isCancel(selected)) {
+		throw new Error("Cancelled.");
+	}
+
+	const result = await importSpec({
+		provider: "github",
+		identifier: selected as string,
+	});
+
+	console.log(
+		`Imported PRD #${result.prdIssueNumber} → ${result.specDir}/ (${result.issueCount} issues)`,
+	);
+
+	return result.specName;
+}

package/src/runner.ts

@@ -1,11 +1,12 @@
 /**
- * Runner — commit flow, orchestration loop, and session helpers.
+ * Runner — orchestration loop, commit flow, 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.
  *
+ * Sync-back logic lives in sync-back.ts.
  * Modules throw on failure. No process.exit, no console output.
  */
 
@@ -15,9 +16,8 @@ import {
 	snapshotWorkingTree as realSnapshotWorkingTree,
 	stageChanges as realStageChanges,
 } from "./git";
-import { readFileSync } from "fs";
-import { parseFrontmatter } from "./frontmatter";
-import { getSourceProvider } from "./sources/index";
+import { syncBackIssue, syncBackPrd } from "./sync-back";
+import type { SyncBackConfig } from "./sync-back";
 import type {
 	GitOps,
 	IterationResult,
@@ -42,81 +42,6 @@ export const consoleLogger: LogWriter = {
 	close: () => {},
 };
 
-/**
- * Configuration for syncing issue/PRD completion back to an external source.
- *
- * When provided to runAfkLoop, the runner reads frontmatter from completed
- * issue files. If a `source` field is present, the corresponding provider
- * is resolved and notified of the completion.
- */
-export interface SyncBackConfig<T> {
-	/** Return the file path for a completed issue, or undefined to skip sync-back. */
-	getIssuePath: (issue: T) => string | undefined;
-	/** Path to the PRD file, used for sync-back after all issues complete. */
-	prdPath?: string;
-	/** Read a file's contents. Injectable for testing; defaults to fs.readFileSync. */
-	readFile?: (path: string) => string;
-	/** Resolve a source provider by name. Injectable for testing; defaults to getSourceProvider. */
-	resolveProvider?: (name: string) => {
-		onIssueComplete(id: string): Promise<void>;
-		onPrdComplete(id: string): Promise<void>;
-	};
-}
-
-/**
- * Sync a completed issue back to its external source.
- *
- * Reads frontmatter from the issue file. If `source` and `issue` fields
- * are present, resolves the provider and calls onIssueComplete.
- * Failures are logged as warnings but never thrown.
- */
-export async function syncBackIssue(
-	filePath: string,
-	logger: LogWriter,
-	readFile: (path: string) => string = (p) => readFileSync(p, "utf-8"),
-	resolveProvider: SyncBackConfig<unknown>["resolveProvider"] = getSourceProvider,
-): Promise<void> {
-	try {
-		const content = readFile(filePath);
-		const { meta } = parseFrontmatter(content);
-		if (!meta.source || !meta.issue) return;
-
-		const provider = resolveProvider!(meta.source);
-		await provider.onIssueComplete(meta.issue);
-		logger.log(`Synced issue #${meta.issue} back to ${meta.source}`);
-	} catch (err: unknown) {
-		const message = err instanceof Error ? err.message : String(err);
-		logger.log(`Warning: sync-back failed for issue at ${filePath}: ${message}`);
-	}
-}
-
-/**
- * Sync PRD completion back to its external source.
- *
- * Reads frontmatter from the PRD file. If `source` and `issue` fields
- * are present, resolves the provider and calls onPrdComplete.
- * Failures are logged as warnings but never thrown.
- */
-export async function syncBackPrd(
-	filePath: string,
-	logger: LogWriter,
-	readFile: (path: string) => string = (p) => readFileSync(p, "utf-8"),
-	resolveProvider: SyncBackConfig<unknown>["resolveProvider"] = getSourceProvider,
-): Promise<void> {
-	try {
-		const content = readFile(filePath);
-		const { meta } = parseFrontmatter(content);
-		if (!meta.source || !meta.issue) return;
-
-		const provider = resolveProvider!(meta.source);
-		await provider.onPrdComplete(meta.issue);
-		logger.log(`Synced PRD #${meta.issue} back to ${meta.source}`);
-	} catch (err: unknown) {
-		const message = err instanceof Error ? err.message : String(err);
-		logger.log(`Warning: sync-back failed for PRD at ${filePath}: ${message}`);
-	}
-}
-
 /**
  * Single check → fix cycle.
  *

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

@@ -12,7 +12,7 @@ You are breaking a PRD into issues as part of the Stonecut workflow. Each issue
 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."
+2. **Ask the user** — If no PRD is in context, ask: "Where is the PRD? Give me a local file path (`.stonecut/specs/<name>/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.
@@ -63,7 +63,7 @@ Iterate until the user approves the breakdown.
 
 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 **local file**, default to creating issues under `.stonecut/specs/<name>/issues/`.
 - 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.
@@ -75,7 +75,7 @@ Confirm with the user before creating. If they want a different destination, res
 Create each issue as a markdown file in the issues directory. Use zero-padded numbering with a kebab-case descriptive suffix:
 
 ```
-.stonecut/<name>/issues/
+.stonecut/specs/<name>/issues/
   01-short-descriptive-title.md
   02-another-slice-title.md
   ...
@@ -88,7 +88,7 @@ Create issues in dependency order (blockers first). Use the local issue template
 
 ## Parent PRD
 
-See `.stonecut/<name>/prd.md`
+See `.stonecut/specs/<name>/prd.md`
 
 ## What to build
 

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

@@ -29,7 +29,7 @@ Check with the user that these modules match their expectations. Ask which modul
 
 Ask the user where to save the PRD:
 
-- **Local file** — Save as `.stonecut/<name>/prd.md` in the project. Ask the user: "What should I name this spec?" The name can be anything — a ticket ID (e.g., `ASC-1`), a descriptive slug (e.g., `auth-refactor`), or whatever fits. Create the `.stonecut/<name>/` directory if it doesn't exist.
+- **Local file** — Save as `.stonecut/specs/<name>/prd.md` in the project. Ask the user: "What should I name this spec?" The name can be anything — a ticket ID (e.g., `ASC-1`), a descriptive slug (e.g., `auth-refactor`), or whatever fits. Create the `.stonecut/specs/<name>/` directory if it doesn't exist.
 - **GitHub issue** — Create a GitHub issue using `gh issue create --label prd`. Before creating, ensure the `prd` label exists:
 
   ```bash

package/src/skills/stonecut-review-architecture/SKILL.md

@@ -75,7 +75,7 @@ After comparing, give your own recommendation: which design you think is stronge
 
 Ask the user where to save the RFC:
 
-- **Local file** — Save as `.stonecut/<name>/rfc.md` in the project. Ask the user: "What should I name this spec?" Create the `.stonecut/<name>/` directory if it doesn't exist.
+- **Local file** — Save as `.stonecut/specs/<name>/rfc.md` in the project. Ask the user: "What should I name this spec?" Create the `.stonecut/specs/<name>/` directory if it doesn't exist.
 - **GitHub issue** — Create a GitHub issue using `gh issue create --label rfc`. Before creating, ensure the `rfc` label exists:
 
   ```bash

package/src/sources/github.ts

@@ -5,20 +5,9 @@
  * structured as a stateless SourceProvider.
  */
 
+import { runSync } from "../spawn";
 import type { IssueData, PrdData, PrdSummary, SourceProvider } from "./types.js";
 
-function runSync(cmd: string[]): { exitCode: number; stdout: string; stderr: string } {
-	const proc = Bun.spawnSync(cmd, {
-		stdout: "pipe",
-		stderr: "pipe",
-	});
-	return {
-		exitCode: proc.exitCode,
-		stdout: proc.stdout.toString(),
-		stderr: proc.stderr.toString(),
-	};
-}
-
 export class GitHubSourceProvider implements SourceProvider {
 	readonly owner: string;
 	readonly repo: string;

package/src/spawn.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared synchronous process wrapper used by git.ts and sources/github.ts.
+ *
+ * Single source of truth for Bun.spawnSync stdout/stderr conversion.
+ */
+
+/** Run a command synchronously, optionally in a specific working directory. */
+export function runSync(
+	cmd: string[],
+	cwd?: string,
+): { exitCode: number; stdout: string; stderr: string } {
+	const proc = Bun.spawnSync(cmd, {
+		stdout: "pipe",
+		stderr: "pipe",
+		...(cwd && { cwd }),
+	});
+	return {
+		exitCode: proc.exitCode,
+		stdout: proc.stdout.toString(),
+		stderr: proc.stderr.toString(),
+	};
+}

package/src/sync-back.ts

@@ -0,0 +1,88 @@
+/**
+ * Sync-back — notify external sources when issues or PRDs complete.
+ *
+ * syncBackIssue: read frontmatter from an issue file, resolve provider, call onIssueComplete.
+ * syncBackPrd: read frontmatter from a PRD file, resolve provider, call onPrdComplete.
+ *
+ * Failures are logged as warnings but never thrown — sync-back is best-effort.
+ */
+
+import { readFileSync } from "fs";
+import { parseFrontmatter } from "./frontmatter";
+import { getSourceProvider } from "./sources/index";
+import type { LogWriter } from "./types";
+
+/**
+ * Configuration for syncing issue/PRD completion back to an external source.
+ *
+ * When provided to runAfkLoop, the runner reads frontmatter from completed
+ * issue files. If a `source` field is present, the corresponding provider
+ * is resolved and notified of the completion.
+ */
+export interface SyncBackConfig<T> {
+	/** Return the file path for a completed issue, or undefined to skip sync-back. */
+	getIssuePath: (issue: T) => string | undefined;
+	/** Path to the PRD file, used for sync-back after all issues complete. */
+	prdPath?: string;
+	/** Read a file's contents. Injectable for testing; defaults to fs.readFileSync. */
+	readFile?: (path: string) => string;
+	/** Resolve a source provider by name. Injectable for testing; defaults to getSourceProvider. */
+	resolveProvider?: (name: string) => {
+		onIssueComplete(id: string): Promise<void>;
+		onPrdComplete(id: string): Promise<void>;
+	};
+}
+
+/**
+ * Sync a completed issue back to its external source.
+ *
+ * Reads frontmatter from the issue file. If `source` and `issue` fields
+ * are present, resolves the provider and calls onIssueComplete.
+ * Failures are logged as warnings but never thrown.
+ */
+export async function syncBackIssue(
+	filePath: string,
+	logger: LogWriter,
+	readFile: (path: string) => string = (p) => readFileSync(p, "utf-8"),
+	resolveProvider: SyncBackConfig<unknown>["resolveProvider"] = getSourceProvider,
+): Promise<void> {
+	try {
+		const content = readFile(filePath);
+		const { meta } = parseFrontmatter(content);
+		if (!meta.source || !meta.issue) return;
+
+		const provider = resolveProvider!(meta.source);
+		await provider.onIssueComplete(meta.issue);
+		logger.log(`Synced issue #${meta.issue} back to ${meta.source}`);
+	} catch (err: unknown) {
+		const message = err instanceof Error ? err.message : String(err);
+		logger.log(`Warning: sync-back failed for issue at ${filePath}: ${message}`);
+	}
+}
+
+/**
+ * Sync PRD completion back to its external source.
+ *
+ * Reads frontmatter from the PRD file. If `source` and `issue` fields
+ * are present, resolves the provider and calls onPrdComplete.
+ * Failures are logged as warnings but never thrown.
+ */
+export async function syncBackPrd(
+	filePath: string,
+	logger: LogWriter,
+	readFile: (path: string) => string = (p) => readFileSync(p, "utf-8"),
+	resolveProvider: SyncBackConfig<unknown>["resolveProvider"] = getSourceProvider,
+): Promise<void> {
+	try {
+		const content = readFile(filePath);
+		const { meta } = parseFrontmatter(content);
+		if (!meta.source || !meta.issue) return;
+
+		const provider = resolveProvider!(meta.source);
+		await provider.onPrdComplete(meta.issue);
+		logger.log(`Synced PRD #${meta.issue} back to ${meta.source}`);
+	} catch (err: unknown) {
+		const message = err instanceof Error ? err.message : String(err);
+		logger.log(`Warning: sync-back failed for PRD at ${filePath}: ${message}`);
+	}
+}