Spec to pull requests
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.
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
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 mergedReference
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
- Breakdown. The main model reads the spec and a digest of the repository (tracked files by directory, the first lines of
AGENTS.mdandCLAUDE.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). An answer that does not parse is sent back once. - Approve. You answer yes, or no to edit the slices as JSON in
$VISUALor$EDITOR(checked again before anything runs). Nothing is created before you say yes. - 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 runcarries them out (plan then execute). - 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. - 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
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
Before the breakdown (so before anything is spent) the spec goes through the same goal check as scheduled jobs: 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
--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
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
- The breakdown sees a file digest, not the ranked repository map (the slice workers have that tool).
- Slices stack linearly:
dependsOnmust point at earlier slices, and two independent slices still run in order.
Related
- Plan then execute
- Contract-first work
- Stacked pull requests by hand (
venom stack) are documented in the CLI section.