stonecut 1.2.0 → 1.3.0

package/README.md

@@ -7,19 +7,25 @@ A CLI that drives PRD-driven development with agentic coding CLIs. You write the
 
 ## Workflow
 
-Ideas can come from anywhere — Jira tickets, Slack threads, MCP servers, or just a conversation. The pipeline starts once you're ready to act on one:
+Ideas can come from anywhere — Jira tickets, Slack threads, MCP servers, or just a conversation. The pipeline has two entry points depending on where work originates:
+
+**From a raw idea:** `roadmap issue → interview → PRD → issues → execute`
 
 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`
+
+Architecture decisions and refactoring plans that emerge from a technical investigation (e.g. a codebase review) skip the interview — the exploration itself produces the design decisions. Capture the outcome as an `rfc`-labeled GitHub issue, then write the PRD referencing it.
+
 Steps 1–3 are Claude Code skills installed via `stonecut setup-skills`. Steps 4–5 are the Stonecut CLI.
 
-### Suggested: managing your idea backlog
+### Suggested: managing your backlog
 
-For projects using GitHub issues, we recommend tracking ideas with a `roadmap` label. When an idea is ready, interview it, write the PRD (which closes the roadmap issue), break it into sub-issues, import with `stonecut import --github`, and execute. See [DESIGN.md](DESIGN.md#suggested-practice-managing-your-idea-backlog-with-github-labels) for the full flow.
+For projects using GitHub issues, we recommend tracking ideas with a `roadmap` label and architecture decisions with an `rfc` label. When an idea is ready, interview it, write the PRD (which closes the roadmap issue), break it into sub-issues, import with `stonecut import --github`, and execute. See [DESIGN.md](DESIGN.md#entry-points) for the full flow.
 
 ## Installation
 
@@ -77,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:
 
@@ -94,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.
 
@@ -137,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
@@ -155,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.
@@ -214,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`. |
 
@@ -254,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
@@ -273,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
 ---
@@ -285,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
 ---
@@ -342,13 +348,13 @@ To add a new source provider (e.g. Jira, Linear):
 
 ## Skills
 
-The repo ships three Claude Code skills for steps 1–3 of the workflow. Install them with:
+The repo ships four Claude Code skills for the workflow. Install them with:
 
 ```sh
 stonecut setup-skills
 ```
 
-This creates symlinks in `~/.claude/skills/` pointing to the installed package. Once linked, they're available as `/stonecut-interview`, `/stonecut-prd`, and `/stonecut-issues` in any Claude Code session.
+This creates symlinks in `~/.claude/skills/` pointing to the installed package. Once linked, they're available as `/stonecut-interview`, `/stonecut-prd`, `/stonecut-issues`, and `/stonecut-review-architecture` in any Claude Code session.
 
 For non-default Claude Code installations, pass `--target` with the Claude root path:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stonecut",
-  "version": "1.2.0",
+  "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,294 +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"): 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]> {
-	ensureCleanTree();
-
-	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
 // ---------------------------------------------------------------------------
@@ -380,15 +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/<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;