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 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/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 backlog

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 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 agent and must be in your PATH. OpenAI Codex CLI (codex) is required only when using --agent codex.
• GitHub CLI — gh, authenticated. Required for importing from GitHub (stonecut import --github), syncing issue completion back to GitHub, and for pushing branches / creating PRs.

Install from npm

bun add -g stonecut

This makes the stonecut command globally available. Then initialize your project and install the Claude Code skills:

stonecut init          # scaffold .stonecut/ with config and gitignore
stonecut setup-skills  # install Claude Code 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

Running bare stonecut starts the interactive run wizard — the primary workflow for executing PRD issues. Use stonecut --help to discover all available commands.

stonecut — Interactive wizard

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:

# Full wizard — prompted for PRD, branch, base branch, PR mode, agent, iterations
stonecut

# Partial — skip PRD selection
stonecut --local my-feature

# Partial — skip branch and base branch prompts
stonecut --branch feat/my-feature --base-branch main

# Partial — skip agent and iterations prompts
stonecut --agent claude -i all

# Draft PR mode
stonecut --draft

# Override a stored draft preference back to ready
stonecut --ready

You can also use stonecut run explicitly — it's identical to bare stonecut.

The wizard scans .stonecut/specs/*/ for local PRDs and presents them with completion counts (e.g. "my-feature (3/7 done)"). Completed PRDs (all issues done) and empty PRDs (no issues) are automatically hidden. 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.

Persistence across runs: The wizard remembers your branch name, base branch, and PR mode (draft/ready) in status.json per PRD. On subsequent runs, stored values are used silently — no prompt is shown. CLI flags override stored values when provided. Agent and iterations are intentionally per-run decisions and are always prompted when not provided via flags.

If no .stonecut/ directory exists, the wizard prints a hint suggesting stonecut init.

stonecut init — Project setup

Scaffolds a .stonecut/ directory with project-level configuration:

stonecut init

This creates:

• .stonecut/config.json — Project defaults for the run wizard (see Configuration below).
• .stonecut/.gitignore — Ignores runtime artifacts (logs/, status.json, progress.txt) so only meaningful files (config, PRDs, issues) are committed.

The command errors if config.json already exists, preventing accidental overwrites. To reconfigure, edit the file directly.

Configuration

.stonecut/config.json controls wizard defaults. All fields are optional:

{
  "agent": "claude",
  "baseBranch": "main",
  "branchPrefix": "stonecut/"
}

| Field | Default | Description | | -------------- | ------------- | ------------------------------------------------------------------------------- | | agent | "claude" | Agentic CLI agent (claude, codex). Used when --agent is omitted. | | baseBranch | "main" | Default PR target branch. Suggested in the wizard's base branch prompt. | | branchPrefix | "stonecut/" | Prefix for suggested branch names (e.g. feat/stonecut/ for team conventions). |

When config is present, the wizard uses these as default values — you can hit enter through prompts for the common case. When config is absent, the current hardcoded defaults apply.

stonecut import — Import from external sources

Pulls a PRD and its sub-issues from an external source into .stonecut/specs/<name>/ so they can be executed locally with stonecut run.

# Import GitHub PRD #42 — spec name derived from PRD title
stonecut import --github 42

# Import with a custom local name
stonecut import --github 42 --name auth-refactor

# Overwrite an existing local spec
stonecut import --github 42 --force

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/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.

Imported files include frontmatter with source metadata, enabling automatic sync-back (e.g. closing GitHub issues on completion).

stonecut run — Execute issues

Executes issues from a local PRD directory. All execution is local-first — use stonecut import to pull in PRDs from external sources first.

# 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

GitHub workflow

For PRDs managed as GitHub issues, use import followed by run:

# 1. Import the PRD and its sub-issues
stonecut import --github 42

# 2. Execute locally (spec name derived from PRD title)
stonecut run --local add-user-authentication -i all

Or use the interactive wizard, which offers inline GitHub import:

stonecut
# → Select "Import from GitHub"
# → Pick a PRD from the list (filtered by `prd` label)
# → Continue with branch, base branch, PR mode, agent, and iterations prompts

When issues imported from GitHub are completed, Stonecut automatically closes the corresponding GitHub issues. When all issues are done, the parent PRD issue is closed as well.

Commands

| Command | Description | | --------------- | ------------------------------------------------------------------ | | (bare) | Start the interactive run wizard (default command). | | run | Alias for bare stonecut — execute issues from a local PRD. | | import | Import a PRD and its issues from an external source. | | init | Scaffold .stonecut/ directory with project config and gitignore. | | setup-skills | Install Stonecut skills as symlinks into ~/.claude/skills/. | | remove-skills | Remove Stonecut skill symlinks from ~/.claude/skills/. |

Flags

run flags:

| Flag | Short | Required | Description | | --------------- | ----- | -------- | ----------------------------------------------------------------------------- | | --local | — | No | Local PRD name (.stonecut/specs/<name>/). Prompted if omitted. | | --iterations | -i | No | Positive integer or all. Prompted with default all if omitted. | | --branch | — | No | Branch name for the run. Persisted per PRD. Prompted if omitted on first run. | | --base-branch | — | No | Base branch / PR target. Persisted per PRD. Prompted if omitted on first run. | | --agent | — | No | Agentic CLI agent (claude, codex). Default from config or claude. | | --draft | — | No | Create PR as draft. | | --ready | — | No | Create PR as ready for review (overrides stored draft preference). |

import flags:

| Flag | Short | Required | Description | | ---------- | ----- | -------- | ------------------------------------- | | --github | — | Yes* | GitHub PRD issue number. | | --name | — | No | Override the auto-derived spec name. | | --force | — | No | Overwrite an existing spec directory. |

*At least one source flag is required. Currently only --github is supported.

Global flags:

| Flag | Short | Description | | ----------- | ----- | ---------------------- | | --version | -V | Show version and exit. |

Pre-execution prompts

Before starting, Stonecut prompts for any missing parameters. Persistent decisions are asked first and remembered across runs; per-run decisions are asked last.

1. PRD — Select from local PRDs or import from GitHub. Completed PRDs and PRDs with no issues are hidden. Skipped when --local is provided.
2. Branch — If you're on a non-default branch, offers to use the current branch or create a new one. If on the default branch (main/master), prompts for a branch name with a suggested default (<branchPrefix><slug>). Persisted per PRD. Skipped on subsequent runs or when --branch is provided.
3. Base branch — Smart select with contextual defaults based on your branch choice:
   • Created a new branch from a non-default branch → defaults to the current branch (enables PR chaining / stacked PRs)
   • Created a new branch from the default branch → defaults to the repo default (main)
   • Using the current branch → defaults to the repo default (main)
   • An "Enter a different branch" option is always available. Persisted per PRD. Skipped on subsequent runs or when --base-branch is provided.
4. PR mode — "Should the PR be opened as a draft?" (y/N). Default: ready. Persisted per PRD. Skipped on subsequent runs, or when --draft / --ready is provided.
5. Agent — "Which agent should execute the issues?" Select from available agents. Default: config value or claude. Not persisted — asked each run unless --agent is provided.
6. Iterations — "How many issues should I tackle this run?" Default: all. Not persisted — asked each run unless -i is provided.

After prompts complete, the branch is created or checked out and execution begins.

When all parameters are provided via flags, no prompts appear and the command runs non-interactively.

After a run

Stonecut automatically pushes the branch and creates a PR (or draft PR, depending on your PR mode preference) with a Stonecut Report listing each issue with its status (completed or failed with error reason). The report also shows which agent was used. Timing stats are printed per iteration and for the full session.

The PR URL is printed to the terminal after creation so you can navigate to it directly.

For imported PRDs, the PR body includes a Closes #<number> reference to the parent GitHub issue when all issues are complete.

Local PRD structure

All execution reads from .stonecut/specs/<name>/ directories with this structure:

.stonecut/specs/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 completion and wizard state (gitignored)
└── progress.txt        # Auto-created: timestamped completion log (gitignored)

status.json stores both issue completion and persistent wizard decisions:

{
  "completed": [1, 2, 3],
  "branch": "stonecut/my-feature",
  "baseBranch": "main",
  "prMode": "ready"
}

The branch, baseBranch, and prMode fields are written after the wizard completes on first run. On subsequent runs, stored values are used silently. Old status files missing these fields are handled gracefully — the wizard prompts as if it's the first run.

PRDs and issues are committed to git; runtime state (status.json, progress.txt, logs/) is gitignored by the .stonecut/.gitignore created during stonecut init.

Frontmatter

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/specs/<name>/prd.md):

---
source: github
issue: 42
title: Add user authentication
---

The actual PRD content starts here...

Issue frontmatter (.stonecut/specs/<name>/issues/01-setup.md):

---
source: github
issue: 101
---

The actual issue content starts here...

| Field | Description | | -------- | ---------------------------------------------------------------------------- | | source | Source provider name (e.g. github). Enables sync-back on completion. | | issue | Issue number in the external system. Used to close the issue when completed. | | title | PRD title from the external source. Present only on prd.md. |

When an issue with source metadata is completed, Stonecut automatically syncs the completion back to the external system (e.g. closes the GitHub issue). Issues without frontmatter (locally-authored) execute normally with no sync-back.

Source providers

Source providers are the abstraction that lets stonecut import pull PRDs from external systems. Each provider implements the SourceProvider interface:

interface SourceProvider {
  fetchPrd(identifier: string): Promise<PrdData>;
  fetchIssues(identifier: string): Promise<IssueData[]>;
  listPrds(): Promise<PrdSummary[]>;
  onIssueComplete(issueId: string): Promise<void>;
  onPrdComplete(prdId: string): Promise<void>;
}

• fetchPrd / fetchIssues — Read-only: fetch data from the external source during import.
• listPrds — Read-only: list available PRDs (used by the wizard's inline import).
• onIssueComplete / onPrdComplete — Side effects: sync completion back to the source (e.g. close a GitHub issue).

Providers are stateless — they talk to external APIs and return data. The provider registry at src/sources/index.ts maps names to implementations.

Built-in: GitHub

The GitHub provider (--github) uses the GitHub CLI (gh). It requires gh to be installed and authenticated.

• PRDs are GitHub issues labeled prd
• Sub-issues are fetched via the GitHub GraphQL API
• Completion syncs back by closing issues via gh issue close

Adding new providers

To add a new source provider (e.g. Jira, Linear):

1. Create src/sources/<name>.ts implementing SourceProvider.
2. Register it in src/sources/index.ts by adding an entry to the PROVIDERS map.
3. Add a --<name> flag to the import command in src/cli.ts.

Skills

The repo ships four Claude Code skills for 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, /stonecut-issues, and /stonecut-review-architecture 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