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 for the full flow.

Installation

Prerequisites

• Bun — install with curl -fsSL https://bun.sh/install | bash
• An agentic coding CLI — Claude Code (claude) is the default runner and must be in your PATH. OpenAI Codex CLI (codex) is required only when using --runner codex.
• GitHub CLI — gh, authenticated. Required for GitHub mode and for pushing branches / creating PRs in local mode.

Install from npm

bun add -g stonecut

This makes the stonecut command globally available. Then install the Claude Code skills:

stonecut setup-skills

Install from source

git clone https://github.com/elkinjosetm/stonecut.git
cd stonecut
bun install

To run the CLI from source:

bun run src/cli.ts

Dev setup

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:

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 — Interactive wizard

When flags are omitted, Stonecut prompts for each missing parameter:

# 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

# 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

# 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 | | -------------- | ----- | -------- | ------------------------------------------------------------------ | | --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 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

When all parameters are provided via flags, only the branch and base branch prompts appear (steps 4–5).

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:

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:

stonecut setup-skills --target ~/.claude-acme

To remove the symlinks:

stonecut remove-skills              # default (~/.claude)
stonecut remove-skills --target ~/.claude-acme