deliver-pr

Files (1)

• SKILL.md

SKILL.md (first lines)

# Deliver PR

Drive one change from a task to an open PR by orchestrating the foundation skills, one phase at a time,
with durable resumable state. You are a **router, not a worker**: you read state, dispatch the next
phase as a sub-agent, record the result, and move on. You do not do the phase work yourself, and you
stay context-light — you read digests and state, never file dumps.

## Session goal

In every agent harness, set `/goal` to the user's requested outcome. The `deliver-pr` workflow is the
execution method, not the goal. Keep `task.md`, requirements, and `relay state` as the durable
definition and progress record across resumes.

## Managed assignment — before state routing

Bind the invocation argument to `$SLUG`, then check
`$HOME/.relay/projects/active/$SLUG/assignment.md`. If it exists, read it completely before asking
`relay state` for the next phase. This is a managed program worker: the assignment's contracts and
escalation commands are binding, while the worker still owns independent `clarify` and `plan` work.
Bind the exact `Program:` and `Work item:` values from the assignment to `$PROGRAM` and `$ITEM`, then
run and read:

```bash
relay program message inbox <program> <item> --json
```

Use the exact program and item from the assignment in place of the placeholders. Act on every unread
decision, feedback, or instruction before state routing. Acknowledge each message only after its
requested action or resulting state/artifact update is durable:

```bash
relay program message ack <program> <item> <inbox-id>
```

An open-PR grant instruction is the exception: keep it unread until `open-pr` succeeds and the PR is
recorded. If `open-pr` fails, do not acknowledge the grant.

A `feedback` message about a change the CEO asked for on your open pull request is work, not review
chatter: make the change on the branch and pull request you already have. Never open a second pull
request for this item and never start unrelated work from it. Acknowledge it once the change is
pushed.

After your pull request merges, the tech lead retires this session: it stops the pull request watcher
and sends `/exit`. Exiting on `/exit` is the expected end of a managed run, so leave nothing
uncommitted you still need — the child worktree is force-removed once the session is gone.

Herdr notification is only a payload-free doorbell and may be lost, so this inbox check is mandatory
even when no prompt arrived. Managed child sessions always run under Herdr: if `relay resume` reports
a Herdr readiness failure, report its exact setup or start instructions and stop instead of working
outside Herdr. If `assignment.md` does not exist, this is a standalone project: follow the standalone
path below exactly as before, with no Herdr requirement.

## Resume-first — always start here

`<slug>` is the argument this skill was invoked with — bind it to `$SLUG` before anything else. Every
invocation (first run or resume) then begins by asking the binary where this run is. State is owned by
`relay state`; never hand-edit it.

```bash
PHASE=$(relay state next "$SLUG" 2>/dev/null)
if [ $? -ne 0 ]; then                       # no state yet → first run: initialize, then ask again
  relay state init "$SLUG" --workflow deliver-pr \
    --phases "clarify,plan,implement,simplify,review,validate,open-pr"
  PHASE=$(relay state next "$SLUG")
fi
```

Never assume a fresh start: an interrupted run returns its in-progress phase and continues it. When
`relay state next` prints empty, every phase is done — go to **Done**.

## The phase pipeline

Each phase is a foundation skill. Run the one `relay state next` reports, in this order:

| Phase | Skill | Consumes | Produces |
|---|---|---|---|
| clarify | `clarify` | the task | requirements + acceptance criteria |
| plan | `plan` | requirements | a blueprint + phased build sequence |
| implement | `implement` | the plan | code + tests, green (commits as it goes) |
| simplify | `simplify` | the diff | a cleaner diff, behavior unchanged |
| review | `review` (report mode) | the diff + criteria | a severity-ranked findings report |
| validate | `validate` | the diff + criteria | a pass verdict on the repo's gates |
| open-pr | `open-pr` | the committed branch | an open PR |

## Per-phase loop (the router contract)

For the phase `relay state next` reported:

1. For a managed assignment, run and process
   `relay program message inbox <program> <item> --json` again at the top of every loop. Use the exact
   program and item from `assignment.md`, and acknowledge each message only after its action is
   durable.
2. If `PHASE` is `open-pr` and this is a managed assignment:
   - Inspect `relay program message outbox <program> <item> --json`. If an unread `pr-open` request
     exists and no grant-approved inbox instruction exists, stop without sending another request.
   - If neither a request nor grant-approved instruction exists, send exactly one `pr-open` message
     using the assignment's command and stop.
   - Only after reading the tech lead's grant-approved inbox instruction, leave that message unread and
     run
     the exact `relay program can-open-pr <program> <item>` command from `assignment.md`. If it fails,
     keep `open-pr` pending and stop. If it passes, continue to the `open-pr` phase.
   - If a previously recorded pull request was closed without merging, Relay clears the stale reference
     during `program tick`. Request a fresh `pr-open` grant and open a replacement pull request through
     the same gate; never reopen or reuse the closed reference yourself.
3. `relay state set "$SLUG" "$PHASE" in-progress`
4. **Dispatch a sub-agent** (when available; otherwise run inline) to run the `$PHASE` skill on this
   project. Hand it the task and the **upstream artifact only** — not your own conclusions. It does the
   work and returns a **structured digest**: what it produced, the artifact path, test/gate results,
   and any blocking question — never a file dump.
5. **On a blocking author-decision** (the sub-agent surfaces a real design/scope choice it shouldn't
   guess): surface it to the author (use an interactive prompt when available; otherwise write it to
   `questions.md` in the project dir, alongside `task.md`/`notes.md`, and stop). Do not advance. Resume
   when the author answers. For a managed assignment, never prompt the worker or write
   `questions.md`: run the exact `relay program message send <program> <item> --kind
   question|conflict --body ...` command from `assignment.md`, then stop. Contract, scope,
   dependency, and risk conflicts stop the affected work; tech lead-worker conflicts escalate to the CEO.
   Never run `relay program decision open` or otherwise write program state.
6. **On success:** for a managed `open-pr`, first verify the PR is open and recorded, then acknowledge
   the grant-approved inbox message. Never acknowledge it after a failed `open-pr`. Next run

From ronaknnathani/relay, MIT.

More from ronaknnathani/relay