---
title: Spec to pull requests
description: Turn a design doc or a GitHub issue into a stack of small, reviewed pull requests with venom spec, then keep the stack current as earlier slices merge.
section: automation
order: 30
audience: [user, agent]
sources: [docs/spec-to-pr.md, cli/src/spec.ts, cli/src/spec-io.ts]
features: [automation.spec]
---

`venom spec` reads a design doc, proposes ordered slices, and after you approve them works through the slices one by one, each as its own pull request stacked on the previous one. It can take days; it stops and resumes cleanly.

## Example {#example}

```bash
venom spec docs/retries.md                     # propose slices, you approve, then run them
venom spec https://github.com/o/r/issues/7     # the spec is a GitHub issue (read with gh)
venom spec status                              # the stack: slices, PRs, spend
venom spec resume                              # continue after a failure, a limit, a reboot or the cap
venom spec sync                                # refresh from GitHub after earlier PRs merged
```

## Reference {#reference}

```text
venom spec <file.md|github-issue-url> [--max-usd <n>] [--base <branch>] [--yes] [--plan-only]
venom spec status [id]
venom spec resume [id]
venom spec sync [id]
```

| Flag | Default | What it does |
|---|---|---|
| `--max-usd <n>` | `10` | The spend cap for the whole stack, at list price. |
| `--base <branch>` | the branch you are on | The branch the first slice builds on and the stack merges into. |
| `--yes` | off | Approve the proposed breakdown without asking. |
| `--plan-only` | off | Stop after the approved breakdown; `venom spec resume` runs it later. |

With no arguments the command prints its help and exits 2.

## What happens {#steps}

1. **Breakdown.** The main model reads the spec and a digest of the repository (tracked files by directory, the first lines of `AGENTS.md` and `CLAUDE.md`) and proposes at most 12 ordered slices. Each has a goal, the files it touches, acceptance checks and the earlier slices it builds on. Where two components meet, the first slice is the contract alone ([contract-first](/docs/automation/contract-first.md)). An answer that does not parse is sent back once.
2. **Approve.** You answer yes, or no to edit the slices as JSON in `$VISUAL` or `$EDITOR` (checked again before anything runs). Nothing is created before you say yes.
3. **Run.** Each slice gets a branch `spec/<id>/NN-<title>` in its own worktree under `~/.venom/specs/<id>/wt/`, based on the previous slice's branch. The model turns the slice into plan steps with checks, and a headless `/plan-exec run` carries them out ([plan then execute](/docs/automation/plan-execute.md)).
4. **Review.** `venom review --base <parent>` reads what the slice added. Its finding counts go in the PR body. Blockers do not stop the stack; they are listed for you.
5. **Pull request.** The branch is pushed and a PR opened against its parent with `gh`. The first slice is ready for review; the rest are drafts until their parent merges. Every body links the spec, the slice's goal and checks, and the sibling PRs.

The stack stops at the first slice whose plan-execute run fails its checks, and at the spend cap. `venom spec resume` skips finished slices and continues the interrupted one from its plan-execute checkpoint without planning it again.

## After earlier PRs merge {#sync}

`venom spec sync` (and `resume`, which syncs first) asks `gh` about each PR. A merged slice is marked `merged`; the next one is rebased with `git rebase --onto origin/<base> <merged branch> <its branch>` (the merged parent was squashed away), pushed with `--force-with-lease`, retargeted to the base and marked ready. A rebase that conflicts is aborted and left for you, with the worktree path in the slice's reason.

## Vague specs {#vague}

Before the breakdown (so before anything is spent) the spec goes through the same goal check as [scheduled jobs](/docs/automation/schedules.md#vague-goals): at least 40 characters and a concrete target, such as a file path, a `` `symbol` ``, a test name, a URL or an issue like `#123`. A spec that fails exits 2 and says what to add. `[open-ended]` anywhere in the text always passes.

## Spend {#spend}

`--max-usd` covers the breakdown, each slice's planning call, its plan-execute run and its review. It is checked before each slice starts, so one slice can overshoot by its own cost. The stack then pauses with `status: paused`; `venom spec resume --max-usd <n>` raises the cap.

## Files {#files}

State is `~/.venom/specs/<id>.json`, written at every step with mode 0600. Worktrees are removed after their PR opens; the branches stay. Nothing is contacted but your model and, for PRs and issues, `gh`. Only a GitHub issue URL is accepted as a remote spec; save other documents to a file first.

## Limits {#limits}

- The breakdown sees a file digest, not the ranked repository map (the slice workers have that tool).
- Slices stack linearly: `dependsOn` must point at earlier slices, and two independent slices still run in order.

## Related

- [Plan then execute](/docs/automation/plan-execute.md)
- [Contract-first work](/docs/automation/contract-first.md)
- Stacked pull requests by hand (`venom stack`) are documented in the [CLI section](/docs/cli.md).
