stonecut 1.1.1 → 1.2.1

package/README.md

@@ -1,21 +1,31 @@
 # Stonecut
 
+[![CI](https://github.com/elkinjosetm/stonecut/actions/workflows/ci.yml/badge.svg)](https://github.com/elkinjosetm/stonecut/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/stonecut)](https://www.npmjs.com/package/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:
+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 run`** — Execute the issues sequentially with an agentic coding CLI.
+4. **`stonecut import`** _(optional)_ — If the PRD lives in GitHub, import it and its issues into `.stonecut/`.
+5. **`stonecut`** — Execute the issues sequentially with an agentic coding CLI.
+
+**From a technical exploration:** `RFC issue → PRD → issues → execute`
 
-Steps 1–3 are Claude Code skills installed via `stonecut setup-skills`. Step 4 is the Stonecut CLI.
+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.
 
-### Suggested: managing your idea backlog
+Steps 1–3 are Claude Code skills installed via `stonecut setup-skills`. Steps 4–5 are the Stonecut CLI.
 
-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.
+### 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](DESIGN.md#entry-points) for the full flow.
 
 ## Installation
 
@@ -23,7 +33,7 @@ For projects using GitHub issues, we recommend tracking ideas with a `roadmap` l
 
 - [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.
+- [GitHub CLI](https://cli.github.com/) — `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
 
@@ -31,10 +41,11 @@ For projects using GitHub issues, we recommend tracking ideas with a `roadmap` l
 bun add -g stonecut
 ```
 
-This makes the `stonecut` command globally available. Then install the Claude Code skills:
+This makes the `stonecut` command globally available. Then initialize your project and install the Claude Code skills:
 
 ```sh
-stonecut setup-skills
+stonecut init          # scaffold .stonecut/ with config and gitignore
+stonecut setup-skills  # install Claude Code skills
 ```
 
 ### Install from source
@@ -68,26 +79,98 @@ 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.
+Running bare `stonecut` starts the interactive run wizard — the primary workflow for executing PRD issues. Use `stonecut --help` to discover all available commands.
 
-### `stonecut run` — Interactive wizard
+### `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.
 
 When flags are omitted, Stonecut prompts for each missing parameter:
 
 ```sh
-# Full wizard — prompted for source, iterations, branch, and base branch
-stonecut run
+# Full wizard — prompted for PRD, iterations, branch, and base branch
+stonecut
 
 # Partial — only iterations, branch, and base are prompted
-stonecut run --local my-feature
+stonecut --local my-feature
+
+# Partial — only PRD selection, branch, and base are prompted
+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.
+
+Flags provided via CLI skip the corresponding prompts. When all flags are given, the command runs without any prompts.
+
+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:
+
+```sh
+stonecut init
+```
+
+This creates:
 
-# Partial — only source, branch, and base are prompted
-stonecut run -i all
+- **`.stonecut/config.json`** — Project defaults for the run wizard (see [Configuration](#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:
+
+```json
+{
+  "runner": "claude",
+  "baseBranch": "main",
+  "branchPrefix": "stonecut/"
+}
+```
+
+| Field          | Default       | Description                                                                     |
+| -------------- | ------------- | ------------------------------------------------------------------------------- |
+| `runner`       | `"claude"`    | Agentic CLI runner (`claude`, `codex`). Used when `--runner` 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/<name>/` so they can be executed locally with `stonecut run`.
+
+```sh
+# 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
 ```
 
-Flags provided via CLI skip the corresponding prompts. When all flags are given, the command runs without any prompts (the existing behavior).
+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/`.
+5. Creates initial `status.json` and `progress.txt`.
 
-### `stonecut run --local` — Local PRDs
+Import errors if the spec directory already exists (to avoid overwriting in-progress work). Use `--force` to overwrite intentionally.
+
+Imported files include [frontmatter](#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.
 
 ```sh
 # Run 5 issues, then push and create a PR
@@ -97,49 +180,87 @@ stonecut run --local my-feature -i 5
 stonecut run --local my-feature -i all
 ```
 
-### `stonecut run --github` — GitHub PRDs
+### GitHub workflow
+
+For PRDs managed as GitHub issues, use import followed by run:
 
 ```sh
-# Run 5 sub-issues
-stonecut run --github 42 -i 5
+# 1. Import the PRD and its sub-issues
+stonecut import --github 42
 
-# Run all remaining sub-issues
-stonecut run --github 42 -i all
+# 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:
+
+```sh
+stonecut
+# → Select "Import from GitHub"
+# → Pick a PRD from the list (filtered by `prd` label)
+# → Continue with iterations, branch, and base branch 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
 
-| 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.                                             |
+**`run` flags:**
+
+| Flag           | Short | Required | Description                                                              |
+| -------------- | ----- | -------- | ------------------------------------------------------------------------ |
+| `--local`      | —     | No       | Local PRD name (`.stonecut/<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`. |
+
+**`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 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. **PRD** — select from local PRDs or import from GitHub (skipped when `--local` provided)
+2. **Iterations** — number of issues to process, default `all` (skipped when `-i` provided)
+3. **Branch name** — suggests `<branchPrefix><slug>` based on the spec name (prefix from config or `stonecut/`)
+4. **Base branch** — suggests the configured `baseBranch` or the repository's default branch (usually `main`)
+5. Creates or checks out the branch
 
-When all parameters are provided via flags, only the branch and base branch prompts appear (steps 4–5).
+When all parameters are provided via flags, no prompts appear and the command runs non-interactively.
 
 ### 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
+For imported PRDs, the PR body includes a `Closes #<number>` reference to the parent GitHub issue when all issues are complete.
 
-### Local mode (`stonecut run --local <name>`)
+## Local PRD structure
 
-Expects a local PRD directory at `.stonecut/<name>/` with this structure:
+All execution reads from `.stonecut/<name>/` directories with this structure:
 
 ```
 .stonecut/my-feature/
@@ -148,28 +269,92 @@ Expects a local PRD directory at `.stonecut/<name>/` with this structure:
 │   ├── 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
+├── status.json         # Auto-created: tracks completed issues (gitignored)
+└── progress.txt        # Auto-created: timestamped completion log (gitignored)
 ```
 
-### GitHub mode (`stonecut run --github <number>`)
+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/<name>/prd.md`):
+
+```markdown
+---
+source: github
+issue: 42
+title: Add user authentication
+---
+
+The actual PRD content starts here...
+```
+
+**Issue frontmatter** (`.stonecut/<name>/issues/01-setup.md`):
+
+```markdown
+---
+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:
+
+```typescript
+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](https://cli.github.com/) (`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
 
-Works with GitHub issues instead of local files:
+To add a new source provider (e.g. Jira, Linear):
 
-- 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`
+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 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.1.1",
+  "version": "1.2.1",
   "description": "CLI that drives PRD-driven development with agentic coding CLIs",
   "license": "MIT",
   "repository": {