Skip to content
Docs menu

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.

View .md

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 merged

Reference

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

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

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: dependsOn must point at earlier slices, and two independent slices still run in order.