stonecut 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elkin Torres
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# Stonecut
+
+A CLI that drives PRD-driven development with agentic coding CLIs. You write the PRD, Stonecut executes the issues one by one.
+
+## 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:
+
+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 run`** — Execute the issues sequentially with an agentic coding CLI.
+
+Steps 1–3 are Claude Code skills installed via `stonecut setup-skills`. Step 4 is the Stonecut CLI.
+
+### Suggested: managing your idea 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, and execute. See [DESIGN.md](DESIGN.md#suggested-practice-managing-your-idea-backlog-with-github-labels) for the full flow.
+
+## Installation
+
+### Prerequisites
+
+- [Bun](https://bun.sh/) — install with `curl -fsSL https://bun.sh/install | bash`
+- An agentic coding CLI — [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`claude`) is the default runner and must be in your PATH. [OpenAI Codex CLI](https://github.com/openai/codex) (`codex`) is required only when using `--runner codex`.
+- [GitHub CLI](https://cli.github.com/) — `gh`, authenticated. Required for GitHub mode and for pushing branches / creating PRs in local mode.
+
+### Install from npm
+
+```sh
+bun add -g stonecut
+```
+
+This makes the `stonecut` command globally available. Then install the Claude Code skills:
+
+```sh
+stonecut setup-skills
+```
+
+### Install from source
+
+```sh
+git clone https://github.com/elkinjosetm/stonecut.git
+cd stonecut
+bun install
+```
+
+To run the CLI from source:
+
+```sh
+bun run src/cli.ts
+```
+
+### Dev setup
+
+```sh
+bun install
+git config core.hooksPath .githooks
+```
+
+This installs all dependencies and activates a pre-commit hook that runs eslint and prettier checks before each commit.
+
+Run tests:
+
+```sh
+bun test
+```
+
+## Usage
+
+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 --local` — Local PRDs
+
+```sh
+# Run 5 issues, then push and create a PR
+stonecut run --local my-feature -i 5
+
+# Run all remaining issues
+stonecut run --local my-feature -i all
+```
+
+### `stonecut run --github` — GitHub PRDs
+
+```sh
+# Run 5 sub-issues
+stonecut run --github 42 -i 5
+
+# Run all remaining sub-issues
+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.                                            |
+
+### Pre-execution prompts
+
+Before starting, Stonecut:
+
+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
+
+### After a run
+
+Stonecut automatically pushes the branch, creates a PR, and includes a Stonecut Report listing each issue with its status (completed or failed with error reason). The report also shows which runner was used. Timing stats are printed per iteration and for the full session.
+In GitHub mode, the PR title defaults to the PRD issue title with a `PRD #<number>` fallback if the title is unavailable.
+
+## Sources
+
+### Local mode (`stonecut run --local <name>`)
+
+Expects a local PRD directory at `.stonecut/<name>/` with this structure:
+
+```
+.stonecut/my-feature/
+├── prd.md              # The full PRD
+├── issues/
+│   ├── 01-setup.md     # Issue files, numbered for ordering
+│   ├── 02-core.md
+│   └── 03-api.md
+├── status.json         # Auto-created: tracks completed issues
+└── progress.txt        # Auto-created: timestamped completion log
+```
+
+### GitHub mode (`stonecut run --github <number>`)
+
+Works with GitHub issues instead of local files:
+
+- The PRD is a GitHub issue labeled `prd`
+- Tasks are sub-issues of the PRD
+- Progress is tracked by issue state (open/closed)
+- Completed issues are closed via `gh issue close`
+
+## Skills
+
+The repo ships three Claude Code skills for steps 1–3 of 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.
+
+For non-default Claude Code installations, pass `--target` with the Claude root path:
+
+```sh
+stonecut setup-skills --target ~/.claude-acme
+```
+
+To remove the symlinks:
+
+```sh
+stonecut remove-skills              # default (~/.claude)
+stonecut remove-skills --target ~/.claude-acme
+```

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "stonecut",
+  "version": "1.0.0",
+  "description": "CLI that drives PRD-driven development with agentic coding CLIs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/elkinjosetm/stonecut.git"
+  },
+  "keywords": [
+    "cli",
+    "prd",
+    "agentic",
+    "claude-code",
+    "codex"
+  ],
+  "type": "module",
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "bin": {
+    "stonecut": "./src/cli.ts"
+  },
+  "scripts": {
+    "lint": "eslint src/ tests/",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "bun test",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.10.0",
+    "commander": "^13.1.0"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "eslint",
+      "prettier --check"
+    ],
+    "*.{json,md}": "prettier --check"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.9",
+    "eslint": "^9.24.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "prettier": "^3.5.3",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.30.1"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,370 @@
+#!/usr/bin/env bun
+
+/**
+ * Stonecut CLI — PRD-driven development workflow orchestrator.
+ *
+ * Modules throw errors; only this file catches them, formats user-facing
+ * messages, and calls process.exit().
+ */
+
+import * as clack from "@clack/prompts";
+import { Command, InvalidArgumentError } from "commander";
+import { createRequire } from "module";
+import {
+	checkoutOrCreateBranch,
+	createPr,
+	defaultBranch,
+	ensureCleanTree,
+	pushBranch,
+} from "./git";
+import { GitHubSource } from "./github";
+import { LocalSource } from "./local";
+import { slugifyBranchComponent } from "./naming";
+import { renderGithub, renderLocal } from "./prompt";
+import { Logger } from "./logger";
+import { defaultGitOps, runAfkLoop } from "./runner";
+import { getRunner } from "./runners/index";
+import { setupSkills, removeSkills } from "./skills";
+import type { GitHubIssue, Issue, IterationResult, Session } from "./types";
+
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+
+// ---------------------------------------------------------------------------
+// Validation helpers (exported for testing)
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse the --iterations value: positive integer or "all".
+ * Throws InvalidArgumentError on bad input so Commander surfaces it.
+ */
+export function parseIterations(value: string): number | "all" {
+	if (value === "all") return "all";
+	const n = Number(value);
+	if (!Number.isInteger(n) || n <= 0) {
+		throw new InvalidArgumentError(`Must be a positive integer or 'all', got '${value}'`);
+	}
+	return n;
+}
+
+/**
+ * Parse the --github value: must be a positive integer.
+ * Throws InvalidArgumentError on bad input so Commander surfaces it.
+ */
+export function parseGitHubIssueNumber(value: string): number {
+	const n = Number(value);
+	if (!Number.isInteger(n) || n <= 0) {
+		throw new InvalidArgumentError(`Must be a positive integer, got '${value}'`);
+	}
+	return n;
+}
+
+/**
+ * Ensure exactly one of --local or --github was provided.
+ * Returns a tagged tuple so the caller can dispatch.
+ */
+export function validateRunSource(
+	local: string | undefined,
+	github: number | undefined,
+): { kind: "local"; name: string } | { kind: "github"; number: number } {
+	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.");
+	}
+	if (local !== undefined) return { kind: "local", name: local };
+	return { kind: "github", number: github! };
+}
+
+// ---------------------------------------------------------------------------
+// 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");
+}
+
+// ---------------------------------------------------------------------------
+// GitHub comment on no-changes
+// ---------------------------------------------------------------------------
+
+function commentOnIssue(issueNumber: number, runnerOutput: string | undefined): void {
+	let body = "**Stonecut:** Runner completed but produced no file changes.\n";
+	if (runnerOutput) {
+		body +=
+			"\n<details><summary>Runner output</summary>\n\n" +
+			`\`\`\`\n${runnerOutput}\n\`\`\`\n\n</details>`;
+	}
+	Bun.spawnSync(["gh", "issue", "comment", String(issueNumber), "--body", body], {
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Pre-execution flow
+// ---------------------------------------------------------------------------
+
+/**
+ * Run pre-execution prompts and git checks.
+ * Returns [branch, baseBranch].
+ */
+export async function preExecution(suggestedBranch: string): Promise<[string, string]> {
+	ensureCleanTree();
+
+	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.");
+	}
+
+	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,
+): 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);
+
+		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();
+	}
+}
+
+export async function runGitHub(
+	number: number,
+	iterations: number | "all",
+	runnerName: string,
+): Promise<void> {
+	const runner = getRunner(runnerName);
+	const source = new GitHubSource(number);
+	const logger = new Logger(`prd-${number}`);
+
+	const session: Session = { logger, git: defaultGitOps, runner, runnerName };
+
+	try {
+		const prd = source.getPrd();
+		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 prdContent = prd.body;
+		const results = await runAfkLoop<GitHubIssue>(
+			source,
+			iterations,
+			(issue) =>
+				renderGithub({
+					prdContent,
+					issueNumber: issue.number,
+					issueTitle: issue.title,
+					issueContent: issue.body,
+				}),
+			(issue) => issue.title,
+			(issue) => `Issue #${issue.number}: ${issue.title}`,
+			session,
+			(issue, output) => commentOnIssue(issue.number, output),
+		);
+
+		await pushAndMaybePr(results, source, branch, baseBranch, prTitle, runnerName, logger, number);
+	} finally {
+		logger.close();
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Program definition
+// ---------------------------------------------------------------------------
+
+export function buildProgram(): Command {
+	const program = new Command();
+
+	program
+		.name("stonecut")
+		.description("Stonecut — execute PRD-driven development workflows using agentic coding CLIs.")
+		.version(`stonecut ${version}`, "-V, --version");
+
+	program
+		.command("run")
+		.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("--runner <name>", "Agentic CLI runner (claude, codex)", "claude")
+		.action(async (opts) => {
+			const source = validateRunSource(opts.local, opts.github);
+			const iterations = parseIterations(opts.iterations);
+			const runnerName: string = opts.runner;
+
+			if (source.kind === "local") {
+				await runLocal(source.name, iterations, runnerName);
+			} else {
+				await runGitHub(source.number, iterations, runnerName);
+			}
+		});
+
+	program
+		.command("setup-skills")
+		.description("Install Stonecut skills as symlinks into ~/.claude/skills/.")
+		.option(
+			"--target <path>",
+			"Claude root path (e.g. ~/.claude-acme). Skills are installed into <target>/skills/.",
+		)
+		.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);
+			}
+		});
+
+	program
+		.command("remove-skills")
+		.description("Remove Stonecut skill symlinks from ~/.claude/skills/.")
+		.option(
+			"--target <path>",
+			"Claude root path (e.g. ~/.claude-acme). Skills are removed from <target>/skills/.",
+		)
+		.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);
+			}
+		});
+
+	return program;
+}
+
+// ---------------------------------------------------------------------------
+// Entry point — top-level error catching
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+	const program = buildProgram();
+	await program.parseAsync(process.argv);
+}
+
+if (import.meta.main) {
+	main().catch((err: unknown) => {
+		const message = err instanceof Error ? err.message : String(err);
+		console.error(`Error: ${message}`);
+		process.exit(1);
+	});
+}