Deliver issues with /deliver

/deliver takes open PBIs and Bugs and carries each one to a merged PR in release/next, one subagent per step. This guide walks through the common runs. Review file, release review, decision PBIs, parallel runs and roles are in the delivery reference.

Prerequisites

• gh auth status works and you can push to the repository.
• The branch release/next exists (github-release cut creates it).
• A GitHub ruleset on release/next with required checks and no bypass. It is the hard gate: a red check blocks the merge whatever the session does. /deliver warns at the start when there is none.
• Unattended runs need git, gh and your verify commands on the harness allowlist (references/permissions.md of the deliver skill).
• The release guide covers the branch, the milestone and the ruleset.

The loop

Fix rounds are at most 2 per PBI, shared by review and CI; a third is a pause. The merge never asks when the review is clean and the checks are green.

Deliver one PBI

/deliver 42

deliver prints one line per step and ends with a report (shortened). Each line is also reported as a progress event through Report-Progress.ps1, whatever the terminal: herdr and poimen show it in their sidebar, other terminals ignore it.

#42 select: next, claimed
#42 implement: done, 3 commits, tests green
#42 review: 1 blocking -> fix 1/2
#42 review: clean
#42 pr: #57
#42 ci: green
#42 merge: squashed, issue closed
#42 cleanup: 2 removed

delivered: #42 https://github.com/acme/app/pull/57
blocked:   -
paused:    -

A blocked PBI (a red check unrelated to the change, for example) is listed with its reason and open PR; a paused one with its question. Interactive runs ask you right away: retry, skip or give an instruction.

Status of a milestone

With --milestone, deliver prints a status block of at most 10 lines after each PBI and in the report: progress, delivered in this run, ready, waiting, what needs you (decisions, interactive, manual tests, the release PR to merge), release state and the next milestone, every issue as a full URL with its title. /deliver status --milestone M004 prints it without delivering; pwsh scripts/Get-DeliverStatus.ps1 -Milestone M004 [-Text] gives the same as JSON or text.

Deliver a Feature or several issues

/deliver 7
/deliver 9 11 14

A Feature or Epic expands to its open PBIs and Bugs. They are ordered by their blocked-by links and each is delivered once. Issues with a blocking label are skipped (labels: issue model; hint planner refine <nr>). A Feature without PBIs is planned in the same session with planner and grill-me (plan an issue).

Deliver a milestone

/deliver --milestone M004

Name the milestone M<nnn>: M004 finds the open M004 and, after /github-milestone close M004 renamed it, M004 (0.2.0), so the same command and the same release-review state work before and after the rename. A legacy title such as 1.3.0 works as before; to move a repository to M<nnn> see Migrate legacy milestones, the old release-review-<title>.json files stay as history.

Delivers every open PBI and Bug of the milestone. A PBI or Bug that you reach only through a Feature or Epic of the milestone, and that has no or another milestone, is reported (#42 select: outside M004, skipped) and not delivered: set its milestone, or move it into M004. /deliver <feature> without --milestone still delivers all the PBIs of the Feature. The rule is explained in the issue model. When none is left, deliver runs a release review of the whole release diff. Without blocking findings it cuts the release candidate, posts it on the release-test issue and opens the release PR into main without waiting for the RC test (release.test.gate: true in .agents/config.json waits for it) and stops: you review and merge that one. With blocking findings it files one Bug per finding in the milestone; run the command again to deliver them. With the release PR deliver ends with the hint to run /github-milestone close M004 once that PR is merged and tagged.

Interactive or unattended

By default an unclear criterion, extra scope or a blocker asks you in the chat. With --unattended (claude -p, opencode run, copilot -p) nothing is asked: deliver comments on the issue, adds needs-decision and continues with the next independent PBI.

/deliver 7 --unattended

Example of a pause, the comment on #43:

deliver paused: criterion 2 ("export in the usual format") does not say which format.
Options: CSV or JSON. Answer here and remove the label needs-decision.

To continue: answer in the issue, remove the label (gh issue edit 43 --remove-label needs-decision) and run /deliver 43 again. The report lists the paused PBI under paused with the question.

Resume after a stop

State lives in GitHub only (issue, branch, PR, checks). After a crash, a closed terminal or a pause, run the same command again: an existing branch is continued, an existing PR skips straight to the checks, closed issues are not selected. /deliver <nr> on a single PBI continues it even when another session claimed it.

Limit a run with --max

/deliver --milestone M004 --max 3

--max <n> stops after n delivered, blocked or paused PBIs and prints the report. Run it again for the next batch.

A milestone as a control session

An interactive /deliver --milestone M004 (or a Feature or Epic with more than three PBIs, deliver.loopThreshold in .agents/config.json) does not deliver the PBIs in your session. It starts the loop below in the background (in herdr in its own workspace), prints the progress and the status block between PBIs, and stays small:

• a needs-decision PBI is shown to you; after your answer the label is removed and the loop continues
• interactive PBIs are delivered by this session, because they cannot run unattended
• the release review and release PR run once in this session after the loop ends done
• past deliver.controlContextTokens (default 200000) it prints the status block and the resume command and stops; run /deliver --milestone M004 again

/deliver --milestone M004 --inline keeps the old behavior: this session delivers every PBI itself. Details: references/control.md of the deliver skill.

Feedback during a run

Tell the session what you see while testing (a defect, a UI wish, an idea) and it drafts an issue per finding instead of changing code: [Bug] with repro or [PBI] with acceptance criteria, Tier: and Size:, shown in at most 6 lines. After your confirmation it is created in the current milestone (or the one you name) with github-issue; screenshots are referenced in the body. Small, clear items are ready and the same run picks them up; unclear ones get needs-refinement (planner refine <nr>). "Fix it now" delivers a PBI through the normal steps. Details: references/feedback.md of the deliver skill.

Preflight

Before the first PBI deliver checks the repository and prints one line per check (ok, fixed or action needed): the stack skills of detect-techstack are installed in the project and not older than the global ones (missing: skills-manage, after one question; unattended the run continues with the global skills), git, gh, pwsh <skill-dir>/scripts/* and the verify commands of AGENTS.md are on the allowlist (missing lines are listed, interactive offers to add them), and worktrees of merged or deleted PBI branches are removed (others are listed). --no-preflight skips it. Details: references/preflight.md of the deliver skill.

A release in fresh sessions

One session over a whole release grows large. Invoke-DeliverLoop.ps1 starts a fresh claude -p "/deliver … --unattended --max 1" per PBI and reads the progress from GitHub. skills-manage offers the deliver-loop shim (Install-LoopShim.ps1), so you start it from any shell:

deliver-loop -Milestone M004 -Max 5

Without the shim, call the script by its full path:

pwsh .claude/skills/deliver/scripts/Invoke-DeliverLoop.ps1 -Milestone M004 -Max 5

It stops when everything is done or -Max is reached (exit 0), when no progress is made (1) or a PBI is blocked (2). The stream log is in .agents/deliver-loop/.

• -Harness copilot runs copilot -p … --unattended --max 1 instead. Without -Model it uses auto (Copilot picks the model); -Model overrides it and is passed as given, so pass a Copilot model such as gpt-5, not a Claude name.
• Console: stdout is colored on a terminal (-NoColor or NO_COLOR turn it off) and lines are cut to the terminal width (at least 120). The herdr log pane is opt-in with -LogPane.
• -Objective <owner>/<repo>#<nr> runs an [Objective] in rounds over its ready repositories, on exactly one runner: a marker comment on the objective with a heartbeat every 10 minutes. A foreign live marker ends the run handed over (exit 4); deliver-loop takeover <objective> takes a marker whose heartbeat is older than 30 minutes (-Force also a live one), deliver-loop release <objective> ends the round, pushes the branches, posts a status comment and releases the marker.
• In herdr the shim opens its own workspace and reports the loop as an agent: herdr with the skills.

Details: references/loop.md of the deliver skill.

Troubleshooting

Pause, skipped PBI, missing ruleset or red check: see troubleshooting.

Next

Delivery reference: review file, release review, decision PBIs, parallel runs, herdr and roles. After a run, learn from it with retro and lessons: learn from runs. Options: /deliver help. In herdr: herdr with the skills.