stonecut 1.0.0 → 1.1.0

package/README.md

@@ -70,6 +70,23 @@ bun test
 
 Stonecut has one execution command (`run`) with two sources (`--local` for local PRDs, `--github` for GitHub PRDs). All execution is headless — Stonecut runs the issues autonomously and creates a PR when done.
 
+### `stonecut run` — Interactive wizard
+
+When flags are omitted, Stonecut prompts for each missing parameter:
+
+```sh
+# Full wizard — prompted for source, iterations, branch, and base branch
+stonecut run
+
+# Partial — only iterations, branch, and base are prompted
+stonecut run --local my-feature
+
+# Partial — only source, branch, and base are prompted
+stonecut run -i all
+```
+
+Flags provided via CLI skip the corresponding prompts. When all flags are given, the command runs without any prompts (the existing behavior).
+
 ### `stonecut run --local` — Local PRDs
 
 ```sh
@@ -92,20 +109,26 @@ stonecut run --github 42 -i all
 
 ### Flags
 
-| Flag           | Short | Required | Description                                                       |
-| -------------- | ----- | -------- | ----------------------------------------------------------------- |
-| `--iterations` | `-i`  | Always   | Positive integer or `all`.                                        |
-| `--runner`     | —     | No       | Agentic CLI runner to use (`claude`, `codex`). Default: `claude`. |
-| `--version`    | `-V`  | —        | Show version and exit.                                            |
+| Flag           | Short | Required | Description                                                        |
+| -------------- | ----- | -------- | ------------------------------------------------------------------ |
+| `--local`      | —     | No       | Local PRD name (`.stonecut/<name>/`). Prompted if omitted.         |
+| `--github`     | —     | No       | GitHub PRD issue number. Prompted if omitted.                      |
+| `--iterations` | `-i`  | No       | Positive integer or `all`. Prompted with default `all` if omitted. |
+| `--runner`     | —     | No       | Agentic CLI runner (`claude`, `codex`). Default: `claude`.         |
+| `--version`    | `-V`  | —        | Show version and exit.                                             |
 
 ### Pre-execution prompts
 
-Before starting, Stonecut:
+Before starting, Stonecut prompts for any missing parameters in order:
+
+1. **Source** — `--local` or `--github` (skipped when provided via flag)
+2. **Spec name / issue number** — free-text input for the chosen source (skipped when provided via flag)
+3. **Iterations** — number of issues to process, default `all` (skipped when `-i` provided)
+4. **Branch name** — suggests `stonecut/<slug>` based on the source
+5. **Base branch** — suggests the repository's default branch (usually `main`)
+6. Creates or checks out the branch
 
-1. Checks for a clean working tree
-2. Prompts for a branch name (suggests `stonecut/<slug>` — local uses the spec name, GitHub uses the PRD title slug, with `stonecut/issue-<number>` fallback)
-3. Prompts for a base branch / PR target (suggests `main`)
-4. Creates or checks out the branch
+When all parameters are provided via flags, only the branch and base branch prompts appear (steps 4–5).
 
 ### After a run
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stonecut",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "CLI that drives PRD-driven development with agentic coding CLIs",
   "license": "MIT",
   "repository": {
@@ -39,7 +39,7 @@
       "eslint",
       "prettier --check"
     ],
-    "*.{json,md}": "prettier --check"
+    "*.{json,md,yml,yaml,css,html}": "prettier --check"
   },
   "devDependencies": {
     "@types/bun": "^1.2.9",

package/src/cli.ts

@@ -66,17 +66,64 @@ export function parseGitHubIssueNumber(value: string): number {
 export function validateRunSource(
 	local: string | undefined,
 	github: number | undefined,
-): { kind: "local"; name: string } | { kind: "github"; number: number } {
+): { kind: "local"; name: string } | { kind: "github"; number: number } | { kind: "prompt" } {
 	if (local !== undefined && github !== undefined) {
 		throw new Error("Use exactly one of --local or --github.");
 	}
 	if (local === undefined && github === undefined) {
-		throw new Error("One of --local or --github is required.");
+		return { kind: "prompt" };
 	}
 	if (local !== undefined) return { kind: "local", name: local };
 	return { kind: "github", number: github! };
 }
 
+/**
+ * Prompt the user interactively for the source type and value.
+ * Returns a tagged tuple matching the shape of validateRunSource().
+ */
+export async function promptForSource(): Promise<
+	{ kind: "local"; name: string } | { kind: "github"; number: number }
+> {
+	const sourceType = await clack.select({
+		message: "Source type:",
+		options: [
+			{ value: "local", label: "Local PRD (.stonecut/<name>/)" },
+			{ value: "github", label: "GitHub PRD (issue number)" },
+		],
+	});
+
+	if (clack.isCancel(sourceType)) {
+		throw new Error("Cancelled.");
+	}
+
+	if (sourceType === "local") {
+		const name = await clack.text({
+			message: "Spec name:",
+			placeholder: "my-spec",
+			validate: (value) => {
+				if (!value.trim()) return "Spec name is required.";
+			},
+		});
+		if (clack.isCancel(name)) {
+			throw new Error("Cancelled.");
+		}
+		return { kind: "local", name };
+	}
+
+	const issueStr = await clack.text({
+		message: "GitHub issue number:",
+		placeholder: "42",
+		validate: (value) => {
+			const n = Number(value);
+			if (!Number.isInteger(n) || n <= 0) return "Must be a positive integer.";
+		},
+	});
+	if (clack.isCancel(issueStr)) {
+		throw new Error("Cancelled.");
+	}
+	return { kind: "github", number: Number(issueStr) };
+}
+
 // ---------------------------------------------------------------------------
 // Stonecut report
 // ---------------------------------------------------------------------------
@@ -132,28 +179,43 @@ function commentOnIssue(issueNumber: number, runnerOutput: string | undefined):
  * Run pre-execution prompts and git checks.
  * Returns [branch, baseBranch].
  */
-export async function preExecution(suggestedBranch: string): Promise<[string, string]> {
+export async function preExecution(
+	suggestedBranch: string,
+	prefilled?: { branch?: string; baseBranch?: string },
+): Promise<[string, string]> {
 	ensureCleanTree();
 
-	const branch = await clack.text({
-		message: "Branch name:",
-		defaultValue: suggestedBranch,
-		placeholder: suggestedBranch,
-	});
+	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(branch)) {
-		throw new Error("Cancelled.");
+		if (clack.isCancel(branchInput)) {
+			throw new Error("Cancelled.");
+		}
+		branch = branchInput;
 	}
 
-	const detectedDefault = defaultBranch();
-	const baseBranch = await clack.text({
-		message: "Base branch / PR target:",
-		defaultValue: detectedDefault,
-		placeholder: detectedDefault,
-	});
+	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(baseBranch)) {
-		throw new Error("Cancelled.");
+		if (clack.isCancel(baseBranchInput)) {
+			throw new Error("Cancelled.");
+		}
+		baseBranch = baseBranchInput;
 	}
 
 	checkoutOrCreateBranch(branch);
@@ -201,6 +263,7 @@ 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);
@@ -211,7 +274,7 @@ export async function runLocal(
 
 	try {
 		const suggestedBranch = prdIdentifier ? `stonecut/${prdIdentifier}` : "stonecut/spec";
-		const [branch, baseBranch] = await preExecution(suggestedBranch);
+		const [branch, baseBranch] = await preExecution(suggestedBranch, prefilled);
 
 		const prdContent = await source.getPrdContent();
 		const results = await runAfkLoop<Issue>(
@@ -247,6 +310,7 @@ export async function runGitHub(
 	number: number,
 	iterations: number | "all",
 	runnerName: string,
+	prefilled?: { branch?: string; baseBranch?: string },
 ): Promise<void> {
 	const runner = getRunner(runnerName);
 	const source = new GitHubSource(number);
@@ -259,7 +323,7 @@ export async function runGitHub(
 		const prdSlug = slugifyBranchComponent(prd.title);
 		const suggestedBranch = prdSlug ? `stonecut/${prdSlug}` : `stonecut/issue-${number}`;
 		const prTitle = prd.title || `PRD #${number}`;
-		const [branch, baseBranch] = await preExecution(suggestedBranch);
+		const [branch, baseBranch] = await preExecution(suggestedBranch, prefilled);
 
 		const prdContent = prd.body;
 		const results = await runAfkLoop<GitHubIssue>(
@@ -301,17 +365,72 @@ export function buildProgram(): Command {
 		.description("Execute issues from a local PRD or GitHub PRD.")
 		.option("--local <name>", "Local PRD name (.stonecut/<name>/)")
 		.option("--github <number>", "GitHub PRD issue number", parseGitHubIssueNumber)
-		.requiredOption("-i, --iterations <value>", "Number of issues to process, or 'all'")
+		.option("-i, --iterations <value>", "Number of issues to process, or 'all'")
 		.option("--runner <name>", "Agentic CLI runner (claude, codex)", "claude")
 		.action(async (opts) => {
-			const source = validateRunSource(opts.local, opts.github);
-			const iterations = parseIterations(opts.iterations);
+			const validated = validateRunSource(opts.local, opts.github);
+			const source = validated.kind === "prompt" ? await promptForSource() : validated;
+
+			let iterations: number | "all";
+			const needsIterationPrompt = opts.iterations === undefined;
+			if (!needsIterationPrompt) {
+				iterations = parseIterations(opts.iterations);
+			} else {
+				const iterationsInput = await clack.text({
+					message: "Iterations:",
+					defaultValue: "all",
+					placeholder: "all",
+					validate: (value) => {
+						try {
+							parseIterations(value);
+						} catch {
+							return "Must be a positive integer or 'all'.";
+						}
+					},
+				});
+				if (clack.isCancel(iterationsInput)) {
+					throw new Error("Cancelled.");
+				}
+				iterations = parseIterations(iterationsInput);
+			}
+
+			const isWizard = validated.kind === "prompt" || needsIterationPrompt;
+			let prefilled: { branch?: string; baseBranch?: string } | undefined;
+
+			if (isWizard) {
+				const suggestedBranch =
+					source.kind === "local"
+						? `stonecut/${slugifyBranchComponent(source.name) || "spec"}`
+						: `stonecut/issue-${source.number}`;
+
+				const branch = await clack.text({
+					message: "Branch name:",
+					defaultValue: suggestedBranch,
+					placeholder: suggestedBranch,
+				});
+				if (clack.isCancel(branch)) {
+					throw new Error("Cancelled.");
+				}
+
+				const detectedDefault = defaultBranch();
+				const baseBranch = await clack.text({
+					message: "Base branch / PR target:",
+					defaultValue: detectedDefault,
+					placeholder: detectedDefault,
+				});
+				if (clack.isCancel(baseBranch)) {
+					throw new Error("Cancelled.");
+				}
+
+				prefilled = { branch, baseBranch };
+			}
+
 			const runnerName: string = opts.runner;
 
 			if (source.kind === "local") {
-				await runLocal(source.name, iterations, runnerName);
+				await runLocal(source.name, iterations, runnerName, prefilled);
 			} else {
-				await runGitHub(source.number, iterations, runnerName);
+				await runGitHub(source.number, iterations, runnerName, prefilled);
 			}
 		});
 

package/src/logger.ts

@@ -6,7 +6,7 @@
  */
 
 import { appendFileSync, mkdirSync } from "fs";
-import { join } from "path";
+import { join, resolve } from "path";
 import type { LogWriter } from "./types";
 
 export class Logger implements LogWriter {
@@ -14,7 +14,7 @@ export class Logger implements LogWriter {
 
 	constructor(prdIdentifier: string) {
 		const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-		const logDir = join(".stonecut", "logs");
+		const logDir = resolve(".stonecut", "logs");
 		mkdirSync(logDir, { recursive: true });
 		this.filePath = join(logDir, `${prdIdentifier}-${timestamp}.log`);
 	}

package/src/runner.ts

@@ -120,6 +120,7 @@ export async function runAfkLoop<T extends { number: number }>(
 	const { logger, git, runner, runnerName } = session;
 
 	logger.log(`Session started — runner: ${runnerName}, iterations: ${iterations}`);
+	runner.logEnvironment(logger);
 	logger.log("");
 	const results: IterationResult[] = [];
 	const sessionStart = performance.now();

package/src/runners/claude.ts

@@ -6,7 +6,7 @@
  * human-readable messages.
  */
 
-import type { Runner, RunResult } from "../types.js";
+import type { LogWriter, Runner, RunResult } from "../types.js";
 
 const ERROR_MESSAGES: Record<string, string> = {
 	error_max_turns: "max turns exceeded",
@@ -14,6 +14,11 @@ const ERROR_MESSAGES: Record<string, string> = {
 };
 
 export class ClaudeRunner implements Runner {
+	logEnvironment(logger: LogWriter): void {
+		const configDir = process.env.CLAUDE_CONFIG_DIR || "~/.claude (default)";
+		logger.log(`Claude config: ${configDir}`);
+	}
+
 	async run(prompt: string): Promise<RunResult> {
 		const start = performance.now();
 

package/src/runners/codex.ts

@@ -6,7 +6,7 @@
  * output on failure.
  */
 
-import type { Runner, RunResult } from "../types.js";
+import type { LogWriter, Runner, RunResult } from "../types.js";
 
 function extractError(stdout: string): string {
 	for (const raw of stdout.split("\n")) {
@@ -43,6 +43,10 @@ function extractError(stdout: string): string {
 }
 
 export class CodexRunner implements Runner {
+	logEnvironment(_logger: LogWriter): void {
+		// No environment-specific config to log for Codex.
+	}
+
 	async run(prompt: string): Promise<RunResult> {
 		const start = performance.now();
 

package/src/types.ts

@@ -23,6 +23,7 @@ export interface IterationResult {
 /** Protocol that all runner adapters must satisfy. */
 export interface Runner {
 	run(prompt: string): Promise<RunResult>;
+	logEnvironment(logger: LogWriter): void;
 }
 
 /** Snapshot of the working tree state before a runner session. */