GravionLabs/elysion / .agents/skills/deliver
deliver
VerifiedDeliver a PBI, Bug, Feature or Epic item by item with subagents (implement, review, PR, CI, merge). Use for "/deliver 12" or "deliver feature 7".
references/loop.md
View on GitHub# Loop: a fresh session per PBI
```powershell
pwsh <skill-dir>/scripts/Invoke-DeliverLoop.ps1 -Milestone M4 -Max 5
pwsh <skill-dir>/scripts/Invoke-DeliverLoop.ps1 -Target 860,870 -Model opus
```
Or with the shell command `deliver-loop` (`skills-manage` offers it after the `delivery` group): `deliver-loop -Milestone M4 -Max 5`. It resolves the installed script (project, `~/.claude/skills`, `~/.agents/skills`), passes all arguments through and exits 1 with a message when none is installed. In herdr (`HERDR_ENV=1`) it starts the loop in its own workspace `<repo> · deliver` (tab `deliver-loop`, `scripts/Start-LoopWorkspace.ps1`), because the herdr sidebar shows one state per workspace by the selected tab; outside herdr it runs in the current terminal.
## Model per PBI (tier)
Without `-Model`, each iteration takes the model of the picked PBI's tier (`references/roles.md`): `Tier:` line of the body (`fast` haiku, `standard` sonnet, `strong` opus), else its size (S fast, M standard, L strong), else standard (sonnet). The loop logs it before the iteration, e.g. `#51 tier fast (Tier line) → model haiku`, and records the model in `progress.jsonl` (`iteration-start`). One REST read of the PBI body per iteration. `-Model <name>` passes that model for every PBI instead. With `-Harness copilot` the default stays `auto`.
`-Milestone` takes `M<n>` (legacy: the title): the `github-milestone` lookup (`Get-Milestones.ps1 -Mode issues -Name <name>`) resolves `M4` to the title `M4` or, after `/github-milestone close`, `M4 (0.2.0)` (also `M4 Topic`), and the loop passes `--milestone M4` unchanged, so a run started before the rename keeps working after it. The release-review state file `release-review-<key>.json` (`references/release-review.md`) is keyed by `M<n>` as well.
Run `Invoke-DeliverLoop.ps1` from the repository root; the shim `deliver-loop` does that itself from any directory of the repository (it changes to the git toplevel, so state, logs and the herdr workspace are the same everywhere; outside a git repository it keeps the current directory). It starts `claude -p "/deliver <targets> --unattended --max 1" --model <model> --permission-mode auto --output-format stream-json --verbose` once per PBI (`--model` per PBI by tier unless `-Model` overrides it; `-Harness claude` is the default). The allowlist is `references/permissions.md`; the script checks nothing more.
## Harness
| `-Harness` | Command per PBI |
| :----------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `claude` (default) | `claude -p "/deliver <targets> --unattended --max 1" --model <model> --permission-mode auto --output-format stream-json --verbose` |
| `copilot` | `copilot -p "/deliver <targets> --unattended --max 1" --model <model> --allow-all-tools --allow-all-paths --allow-all-urls --no-ask-user --output-format json` (JSONL, one event per line) |
Any other value fails with exit 64 and the list of supported harnesses before the first iteration. Stop rules and exit codes read GitHub only and are the same for both. `-Model` is passed as given. Without `-Model`, `-Harness copilot` uses `auto` (Copilot picks the model of the plan); `sonnet` is a Claude name and Copilot rejects an unavailable `--model` with exit 1 (`Model "x" from --model flag is not available`), so pass a Copilot model of your plan only when you want a fixed one. For long runs set `COPILOT_TASK_WAIT_TIMEOUT_SECONDS=3600` (`references/permissions.md`, Copilot CLI).
Copilot's JSONL (verified live against Copilot CLI 1.0.105, recorded in `test/skills/delivery/fixtures/copilot-cli-1.0.105.jsonl`) feeds the step log, the colored log, the herdr tokens and the notifications from `tool.execution_start` (`data.toolName`, `data.arguments`: tool step), `assistant.message` (`data.content`: text and the `#<nr> <step>: <result>` progress lines; empty while the message only carries `toolRequests`) and `tool.execution_complete` with `success: false` (`data.error.message`: `✗`). Subagents: `subagent.started` (`data.toolCallId`, `data.agentDisplayName`) names the subagent, and every event of its tools carries `data.parentToolCallId` of that call, so steps get the prefix `[<agentDisplayName>]`. The final `result` event carries `exitCode`. Other event types (deltas, reasoning, usage) are written to the jsonl, not to the log. Unverified: the format of other Copilot versions, and events of a `/deliver` run itself (the fixture is a small tool/subagent session).
Permissions on a live `-p` run: `--allow-all-tools` alone denies file access outside the cwd (`view /tmp/…` fails with `Permission denied because no interactive user response was available`, also inside subagents), and URLs in shell commands are denied the same way. The loop therefore passes `--allow-all-tools --allow-all-paths --allow-all-urls` (what `--allow-all` / `--yolo` combine), so subagent worktrees and `gh`/`curl` URLs work. This replaces the per-tool allowlist of `references/permissions.md`.
## Loop or one session
- `--inline` or a few PBIs (up to `deliver.loopThreshold`, default 3): one `/deliver` session delivers them, you watch, questions are welcome.
- Interactive `/deliver --milestone` (or a Feature or Epic with more PBIs): the session starts the loop and stays a thin control session (`references/control.md`). It prints the progress and the status block between PBIs, brings `needs-decision` PBIs to you, delivers `interactive` PBIs itself and runs the release step once after the loop ends `done`. When its own context passes `deliver.controlContextTokens` (default 200000) it prints the status block and the resume command and stops.
- The loop alone (`deliver-loop`): a whole release or a Feature overnight, unattended. Each PBI starts with an empty context, a dead session (sleep, crash, rate limit) costs one PBI, and `deliver` keeps all state in GitHub, so there is no queue file.
## Stop rules
Checked from GitHub (not from the output) before and after each iteration, on the open PBIs of the targets without `needs-decision` / `needs-refinement` / `interactive` (unattended, `deliver` skips `interactive` PBIs; they count as held):
An open `release-test` issue is not part of that set (also when passed explicitly as a Target: `Invoke-DeliverLoop.ps1` drops it from the targets): as the last open item it neither keeps the loop from `done` nor makes it `blocked`. `Get-DeliverStatus.ps1` counts it in `total`, as waiting (`release test`, or `release test, waits for <n> open items`) and, once an RC is posted on it (comment marker `<!-- release-test-rc -->`), as needs you `RC test <issue URL>`.
| Result | When | Exit |
| :---------- | :---------------------------------------------------------------------------------- | :--- |
| done | no open PBI left | 0 |
| max reached | `-Max` iterations ran (delivered, blocked or paused PBIs in total) | 0 |
| blocked | open PBIs remain, all wait on an open blocker or a label | 2 |
| no progress | the set did not change after an iteration; prints the last log lines, never retries | 1 |
## Observability
- `.agents/deliver-loop/<run>/progress.jsonl` (`<run>` is the run id of the events below): one record per `start`, `iteration-start`, `iteration-end` and `result` for a control session; `.agents/deliver-loop/latest.txt` holds the path of the newest run.
- `.agents/deliver-loop/<run>/<nr>.jsonl`: every stream record as it arrives (git-ignored). `<nr>` is the first ready PBI at the start of the iteration.
- `.agents/deliver-loop.log` (plain) and stdout (colored like the `.ansi.log` when stdout is a terminal and neither `-NoColor` nor `NO_COLOR` is set, else plain): the tool lines `HH:MM:SS <tool> <description or file>` and tool errors with `✗` come from the stream; short assistant text is logged uncolored (`»`) and never parsed. The step lines `HH:MM:SS #<nr> <step>: <result>` come from the events: while the harness runs, the loop follows the run's event file and prints every new `step.finished`, `attention` (`<kind>: <reason>`) and `issue.finished` (`<outcome>: <reason>`) event, so a step exists only when the harness reported it through `Report-Progress.ps1`. Subagent steps carry the agent description as prefix (`[Review PBI #401 diff] Bash …`). Long text is cut to the terminal width (minus 40 for time, prefix and tool, at least 120), to 120 characters when stdout is redirected.
- `.agents/deliver-loop.ansi.log`: the same lines with ANSI colors (time dim, tool name cyan, `✗` and tool errors red). A step line is colored by the `tone` of its event: `success` green, `info` cyan, `warning` yellow, `danger` red, `neutral` uncolored. The tone rules live only in `Report-Progress.ps1` (`schema/progress-event.schema.json`); the loop has no rules of its own. `.agents/deliver-loop.log` stays plain text. `-NoColor` or a non-empty `NO_COLOR` writes no `.ansi.log` and colors no stdout.
- Log pane (opt-in with `-LogPane`; herdr, `HERDR_ENV=1`, stdout a terminal): before the first iteration the loop splits a pane labeled `deliver-log` below the session (`herdr pane split --current --direction down --ratio 0.7 --no-focus`) that runs `pwsh -NoProfile -Command "Get-Content -Tail 40 -Wait <log>"` on the `.ansi.log` (on the plain log with `-NoColor`/`NO_COLOR`). A `deliver-log` pane already in the tab is reused, any herdr failure is ignored, the loop never closes the pane, so the last lines stay readable after the run. Without `-LogPane` no pane opens (the console already shows the colored lines); `-NoPane` is a deprecated no-op. The function is `Open-LogPane` in `scripts/TerminalBackend.ps1`. To see the log from another pane, a herdr key toggles it (`scripts/Switch-LogPane.ps1`, `references/terminal-backends.md` "Log pane toggle").
- `.agents/deliver-loop/status.json` (deprecated, removed in the next minor release; read the run events instead): the projection of the run's event file by `ConvertFrom-ProgressEvents.ps1`, rewritten after every event the loop sends, plus `schemaVersion: 1` (run, harness, model of `-Model` or `default`, milestone, `closed`/`total` (PBIs and Bugs only, the stop-rule set), current PBI with step `n/7`, delivered, blocked, paused, needs-you, release review round and PR, `result`). Schema `schema/deliver-loop-status.schema.json`; consumers such as the poimen Deliver panel read it from the published raw URL on `main`: https://raw.githubusercontent.com/GravionLabs/skills/main/skills/delivery/deliver/schema/deliver-loop-status.schema.json. Written atomically (temp file `status.json.tmp`, then rename); the projection's `abandoned` is written as `running`, whose old `updatedAt` marks it stale (a `running` file older than one hour is stale). Needs `-Milestone` and a status block read at the start; written outside herdr and poimen too, git-ignored.
- Progress line after each step and each PBI (log and stdout): `M5 ▓▓▓▓░░░░ 7/19 · #322 review · 1 blocked · 1 needs you` (8 cells for closed/total; the PBI and step, blocked (waiting) and needs-you counts only when set).
- Notifications (macOS `osascript`, Windows toast, else none): from the `attention` events (`pr_opened`, `review_fix`, `ci_red`, `paused`, `blocked`) and `issue.finished` `delivered` (merged) the harness writes, and the loop result. The urgency comes from the event's `tone`: on macOS `danger` plays a sound (Basso), `warning` another (Ping), the rest is silent.
- Terminal (herdr `HERDR_ENV=1`, poimen; deprecated, removed in v3.4.0): the loop owns the terminal sink of `Report-Progress.ps1` and never calls the token or agent-state functions itself; `DELIVER_TERMINAL_SINK=0` skips the sink in both the loop and `Report-Progress.ps1`, the events are written either way. Use the herdr event watcher or poimen#480 instead; the owner rule and `Set-LoopTokens`/`Set-LoopAgentState` are deprecated with it. The sink sets the tokens of `references/terminal-backends.md` from the events (`deliver=#401`, `deliver_step=4/7 review: clean`, `deliver_pr=#55` once the PR exists, `deliver_progress=7/19`, `deliver_tone`, TTL one hour) and clears them with `run.finished` (also on Ctrl+C and error). The harness runs with `HERDR_ENV` and `AGENT_EVENTS_TERMINAL` empty and reports nothing itself.
- herdr agent state (`HERDR_ENV=1`): herdr tracks the agent of the pane, not the `claude -p` children, so a bare loop shows `idle`. The sink reports the loop's lifecycle with `herdr pane report-agent <pane> --state <s> --source deliver-loop --agent deliver`: `working` on `issue.started`, `blocked` on `attention` `paused` or `blocked` and when the run ends `blocked` or `no progress`, otherwise `idle`; then `herdr pane release-agent <pane> --source deliver-loop --agent deliver` with `run.finished`. The pane id follows the subcommand directly (live herdr rejects it as trailing positional for `release-agent`). Any herdr failure is ignored; without herdr nothing is called. Another agent in the pane would compete (verified live, `terminal-backends.md` "Verified against a live herdr"): the sink reads `herdr pane get <pane>` and sets no state when it names an agent other than `deliver`; the loop checks it once before the first iteration and prints one step line saying so. Best run in its own pane. "Terminal" (colors, log pane) is `Test-LoopTerminal` in `scripts/TerminalBackend.ps1`: stdout not redirected, or `DELIVER_LOOP_ASSUME_TTY=1` (tests only). `-NoPane` prints a one-line deprecation warning.
- Progress events (ADR 0001): `scripts/Report-Progress.ps1 -Type <t> …` appends one JSON line per event to `<git-common-dir>/.agents/events/<run>.jsonl` (`$AGENT_EVENTS_DIR/<run>.jsonl` when set). The run id is `AGENT_EVENTS_RUN`; `-Type run.started` without it creates one and prints `AGENT_EVENTS_RUN=<id>`, other types without a run do nothing. `seq` is gapless per run, `tone` (neutral, info, success, warning, danger) is decided by the script, the host (`POIMEN_TERMINAL_ID`, `HERDR_PANE_ID`) comes from the environment. It never fails the caller. Schema and tone table: `schema/progress-event.schema.json`. `SKILL.md` calls it for every step, attention and PBI end; the loop emits the rest:
- Run events of the loop: at the start `run.started` (`source: loop`, harness, model, repository, milestone key, title and URL) opens a new run (an `AGENT_EVENTS_RUN` of the calling shell is dropped). The loop exports `AGENT_EVENTS_RUN`, `AGENT_EVENTS_TERMINAL=owner` and `AGENT_EVENTS_DIR` (`<git-common-dir>/.agents/events/`, outside a repository `.agents/events/`) and passes the run to the harness without the owner marker (nested). Per iteration `issue.started`; the steps (`step.finished`) and `attention` events (`pr_opened`, `review_fix`, `ci_red`, `paused`, `blocked`) come from the harness, which writes them nested into the loop's file; the loop follows the file (console, log, notifications) and shows each one through the terminal sink (`Report-Progress.ps1 -SinkEvent`); after each status read (`Get-DeliverStatus.ps1`, at the start and after each iteration) `milestone.progress` and the changes of its waiting items (`issue.finished` `blocked`), needs-you items (`attention` `needs_you`) and release round and PR (`release.updated`), an item that left the block reset with `issue.finished` `skipped`. After the iteration `issue.finished` from the GitHub state: closed `delivered`; `needs-decision` or `interactive` `paused`; `needs-refinement` or an open blocker `blocked`; else the `paused`/`blocked` attention event of the iteration, else `skipped`. At the end exactly one `run.finished` with the loop result; on an error or Ctrl+C the `finally` sends it with `no progress`.
- Run state: `scripts/ConvertFrom-ProgressEvents.ps1 -Path <run>.jsonl [-Now <iso>] [-NoPidCheck]` (or the lines on the pipeline) is the reference reducer and prints the fold of a run's events as JSON, schema `schema/deliver-run-state.schema.json` (the status schema without `schemaVersion`, plus `result` `abandoned` and `release` `rcUrl`, `rcVersion`, `testIssue`; the open RC test is a needs-you item `RC test` until the test issue finishes). Without `run.finished` the run is `running`, or `abandoned` when its pid does not live or the last event is older than one hour. Unknown types and fields are ignored, an incomplete last line is skipped, a `seq` gap is reported on stderr. Paired fixtures for other readers (poimen): `test/skills/delivery/fixtures/progress-events/<case>.jsonl` with `<case>.state.json`, folded with `-Now '2026-11-07 12:00:00Z' -NoPidCheck`.
- Retention (ADR 0001): on `run.started`, `Report-Progress.ps1` (`scripts/ProgressRetention.ps1`) deletes event files `<events dir>/<run>.jsonl` and run directories `.agents/deliver-loop/<run>/` of finished and abandoned runs older than `AGENT_EVENTS_KEEP_DAYS` (default 7, by last write time) and keeps at most the newest `AGENT_EVENTS_KEEP` (default 100) runs per location. A run is abandoned when it has no `run.finished` and its `pid` does not live or its file has not changed for one hour. Running runs (live `pid`) and the current run are never deleted; a failed delete is skipped silently.
## Reading a run
An agent with a shell reads runs through `scripts/Get-RunState.ps1` instead of locating and parsing the event files itself (read-only; the events directory is resolved as in `Report-Progress.ps1`: `AGENT_EVENTS_DIR`, else the git common dir):
```powershell
pwsh <skill-dir>/scripts/Get-RunState.ps1 -List
pwsh <skill-dir>/scripts/Get-RunState.ps1 -Run <run>
pwsh <skill-dir>/scripts/Get-RunState.ps1 -Run <run> -After <seq>
pwsh <skill-dir>/scripts/Get-RunState.ps1 -NeedsAttention
```
`-List` prints the runs newest first (`run`, `startedAt`, `result`, `lastType`, `lastTs`); `-Run` prints the fold (`schema/deliver-run-state.schema.json`, the same reducer as above); `-Run … -After <seq>` prints the newer events, one JSON line each, for polling; `-NeedsAttention` lists the open needs-you items of the running runs. An unknown run exits 1 with one line on stderr; no events directory is an empty list.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |