---
name: delivery
description:
  "Plan and execute how scoped work ships: read-only orientation, an approved delivery plan (PR
  shape, base graph, milestone breakdown, validation gates, lane routing), then execution in direct
  or orchestrated mode. Use when scoped milestones are ready to ship, when resuming an executable
  Scratchpad backlog, or when the user asks for a delivery plan. Never merges."
argument-hint: "[<milestone-or-scope>]"
disable-model-invocation: true
---

# Delivery

Turn scoped work into shipped PRs. Delivery plans the shipping topology, gets one approval, then
executes with the standing authorization defined below. It does not create scope — return to
`discovery` when the work itself is unscoped — and it does not organize uncommitted local changes;
use `commit` for that.

Invoking this skill is a deliberate user action. Approval of the delivery plan is the authorization
event for the execution phase; do not begin any mutation before it, and do not exceed the grants it
carries.

## Choose execution topology, worker lifetime, and interaction mode

- **Direct** — the session implements, commits, and ships the lanes itself. Default for a single PR,
  one stack, or roughly one to three related milestones.
- **Orchestrated** — the main agent acts as orchestrator and does not implement. One worker owns
  each milestone lane from implementation through its current-head Greptile exit gate, including
  lane-local commits, pushes, PR lifecycle, branch-local Stack operations, and Scratchpad evidence.
  The orchestrator owns the base graph, cross-lane changes, shared coordination state, independent
  audit, and merge handoff. Fits a full multi-milestone backlog where the related set ships
  together.

For orchestrated delivery, choose the worker lifetime:

- **Ephemeral worker** — one worker ends with its delivery lease. Use for bounded campaigns and
  headless delegation.
- **Durable Codex task** — one user-visible task retains a program stream's conversation context
  across successive, separately leased deliveries. Use only when native task capabilities are
  available and the user has selected this topology; read
  [Codex task leases](references/codex-task-leases.md).

Execution topology, worker lifetime, and interaction mode are independent plan decisions:

- **HITL** — pause at material decision boundaries and check in after a milestone enters review.
  Background review monitoring may continue while the user responds.
- **AFK** — continue through every runnable milestone without progress pauses. Stop only for a real
  decision or blocker that the approved plan does not settle.

Use the harness's structured question tool for every user choice, clarification, or open decision.
Put the relevant evidence and recommendation in the question; use ordinary prose for status and
context only. In AFK, ask only when the unresolved choice blocks safe progress.

Direct and orchestrated differ in who owns a lane. HITL and AFK determine when execution pauses.
Every delivery plan names the applicable axes (for example, `orchestrated-ephemeral-AFK` or
`orchestrated-durable-Codex-task-HITL`). In orchestrated mode, lane-autonomous ownership is the
default; use centralized mutation only as a documented exception when a worker cannot safely hold an
isolated lease or lacks required GitHub/Stack capability. When either choice is unclear, ask one
clarification round with recommended defaults before drafting the plan; do not infer orchestrated or
AFK execution silently.

Discovery's issue-level HITL/AFK field describes decision completeness, not delivery topology. Hand
implementation to a worker only when every product, design, and architecture decision it needs is
locked. A worker that hits an unlocked decision stops and returns it rather than guessing. A
delivery may still be orchestrated-HITL or direct-AFK.

## Phase 1: read-only orientation

Do not edit, stage, commit, push, open PRs, run mutating Stack commands, or delegate implementation
in this phase.

Orient on repo instructions, current backlog/milestone state, git and PR state, and the repo's own
package manager, test gates, and lint/format tooling; prefer local reference repos over web docs.
Two checks are easy to skip and change the plan:

- `git worktree list` — lanes may already exist in linked worktrees.
- the installed `github/gh-stack` extension and relevant `gh stack <command> --help`, read before
  planning anything that touches a stack.

## Phase 2: delivery plan

Produce:

- current branch/worktree/dirty state
- important files/modules, with AST/file-level outlines for key files
- key code paths and call-stack traces; diagrams or pseudocode where they clarify
- risks, gaps, and open decisions
- recommended validation gates per PR and for the stack tips
- milestone breakdown with issue-sized units
- delivery shape: one PR, one or more linear native stacks, parallel worktrees, or milestone lanes —
  plus each stack's bottom-to-top chain and independently delivered work
- lane routing: which harness/model runs each lane. Cross-harness delegation (Codex, Cursor) is
  proposed here, never assumed; the user confirms or changes routing at plan review.
- execution topology (`direct` or `orchestrated`) and interaction mode (`HITL` or `AFK`)
- for orchestrated delivery, worker lifetime (`ephemeral` or `durable Codex task`)
- the first meaningful, buildable checkpoint that opens each milestone's draft PR

When the scope comes from a Scratchpad backlog, gate each milestone on evidence before planning it
into a lane:

- Invoke the `scratchpad` skill in `backlog` mode to read and validate the active issue/milestone
  graph; that skill owns its representation and lifecycle fields.

- Its issues are not completed under the repository's status vocabulary, and every `depends_on`
  target is satisfied by current code or a merged PR — read each dependency file; do not trust
  milestone ordering or checked boxes.
- Blockers name a real external condition with an owner and an unblock event. Ordinary remaining
  work is work, not a blocker.
- Plan only runnable milestones into lanes; report the exact dependency/blocker graph for the rest.

For an AFK delivery request, run an AFK-readiness pass before plan approval. Resolve bounded HITL
decisions through the structured question tool and use the `scratchpad` skill's `backlog` mode to
update the affected issues. If resolution materially changes product behavior, architecture, scope,
or milestone topology, return to `discovery interview` before continuing.

Orchestrated mode additionally produces:

- the orchestrator goal and a filled [worker prompt](references/worker-prompt.md) per milestone
- an explicit lease per lane: worktree, branch, locked base, PR, code scope, Stack scope,
  validation, canonical Scratchpad root and allowed files, and mutation boundaries
- a Scratchpad ownership plan separating lane-local evidence from shared milestone/index state
- for durable Codex tasks, the stream-to-task mapping and reuse rules from
  [Codex task leases](references/codex-task-leases.md)

Delivery rules:

- Prefer one PR per milestone, not one PR per tiny issue.
- Within a milestone PR, use atomic semantic commits for issue-sized units where practical.
- If milestones form one dependency chain, deliver them as a native GitHub stack. A stack is linear;
  model forks as separate stacks or parallel PRs.
- Record each native stack as one bottom-to-top branch order with one trunk. Split any dependency
  fork into separate stacks or parallel PRs before execution.

Present the plan and stop for review.

## Phase 3: approval gate

Plan approval grants standing authorization, for the planned scope only, to:

- create worktrees (`wt new <branch> [base]`) and branches as planned
- commit atomic semantic commits and push lane branches
- open PRs with `gh pr create --base <base> --head <branch>`, with bases encoding the full graph
- mark a validated milestone PR ready for review and run its Greptile loop to the exit gate
- cascade approved lower-layer changes with `gh stack rebase`, then publish with `gh stack push`
- resolve conflicts inside the planned lanes
- address review findings, reply to review threads, and resolve addressed threads
- rerun failing or stale checks on lane PRs (never cancel them)
- run validation, including a dev server when the change warrants runtime verification
- in orchestrated mode: grant each worker the approved lane-local mutations through its lease

Always excluded, regardless of approval: merging PRs, deleting branches, editing `.git/gh-stack`,
mutating branches or worktrees outside the plan, and discarding unrelated dirty changes. If the
delivery shape changes materially mid-execution (new lane, different base graph), present the
revised plan before continuing.

## Milestone lifecycle

Every milestone follows this state machine in both execution topologies:

1. Create its planned branch and worktree.
2. Implement and validate the planned first meaningful, buildable checkpoint. Do not use an empty
   commit or arbitrary scaffold merely to open a PR.
3. Commit and push that checkpoint. Write the PR body to a file, run the `pr` skill's
   `scripts/validate_pr_body.py`, then use the `pr` skill's open route to open a **draft** PR with
   the planned base.
4. Adopt or extend the linear chain with `gh stack init` / `gh stack add`, then use
   `gh stack submit` to create or update the native hosted stack. Never put ancestry in PR prose.
5. Finish the milestone, validate it, commit, cascade lower-layer changes with `gh stack rebase`,
   and publish the stack with `gh stack push`.
6. Use the `pr` skill to mark the PR ready for review and start its Greptile loop in the background.
7. Exit review only when the current head has score 5/5, zero unresolved threads, no outstanding
   Comments Outside Diff defects, and required checks pass. A cosmetic 4/5 that Greptile explicitly
   calls safe to merge remains the `pr` skill's documented exception. This is the exit gate every
   milestone is measured against, in both topologies.

HITL reports the milestone handoff and checks in while background review continues. AFK immediately
starts the next runnable milestone. Neither mode auto-merges.

## Phase 4: execute (direct)

Execute the milestone lifecycle in-session with atomic issue-sized commits, then validate each PR
and the relevant stack tips.

## Phase 4: execute (orchestrated)

Read [lane-autonomy](references/lane-autonomy.md) before launching workers — it defines the lease,
worker and orchestrator authority, and the state-transition reports to expect instead of diff
handoffs. Create or switch to each milestone worktree (`wt new <branch> [base]`), then delegate that
milestone to exactly one worker using the filled [worker prompt](references/worker-prompt.md); the
worker runs the milestone lifecycle end to end under its lease. In HITL, check in after each
milestone enters review; in AFK, begin the next runnable milestone while the prior worker waits on
Greptile. The orchestrator serializes repository-wide `gh stack` mutations and performs
parent-driven or cross-lane operations itself. Keep `.scratchpad` uncommitted unless explicitly
requested and preserve unrelated dirty changes.

For durable Codex tasks, use the worker prompt plus the durable addendum in
[Codex task leases](references/codex-task-leases.md): task identity persists, but delivery authority
expires with each lease. Reconcile the finished delivery before redispatching the task on a fresh
worktree from a freshly verified base.

## Backlog closure

When the scope came from a Scratchpad backlog, use the `scratchpad` skill's `backlog` mode to record
PR URLs, validation evidence, issue state, and milestone state. Delivery decides when execution
gates are met; Scratchpad owns how that evidence and lifecycle are represented. GitHub remains
authoritative for PR state.

## Stack rules

- Use only the official `github/gh-stack` extension; stacks are linear, same-repository chains.
- Inspect with `gh stack view --json`. `gh stack sync` is a broad mutating command, not a preview;
  use it only when fetch, rebase, push, PR sync, and hosted-stack sync are all authorized.
- Propagate a lower-layer fix with `gh stack rebase`, resolve with `--continue` or restore with
  `--abort`, then publish rewritten heads with `gh stack push`.
- Never pass `gh stack sync --prune` without separate local branch-deletion authorization.
- Merge only a contiguous bottom-through-selected range with `gh stack merge`, and only when the
  user separately authorizes merge.

## Review loop

For Greptile and human review work on the opened PRs:

- Greptile is the PR reviewer; do not create a separate review worker.
- Fix PRs in dependency order, lowest branch first, then cascade under the Stack rules above. A
  lower-layer fix invalidates upper-layer head-bound CI and review evidence: rebase and push the
  chain, then re-run each affected review loop against its refreshed hosted head.
- Reply to and resolve addressed threads.
- Poll Greptile passively: reviewing/in-progress means wait; act on a score only when its
  last-reviewed commit matches the PR head. Report stale review state if Greptile has not rerun.
- An approved delivery plan opts every milestone into the iterate-to-5/5 loop; no additional per-PR
  opt-in is required.
- Do not auto-merge. Report merge-readiness instead; merging requires separate authorization through
  `pr`.

## Final report

- PRs: `#N branch -> base` in bottom-to-top order
- stack topology: linear chain and which layers were rebased
- milestone/commit mapping
- validation run
- stack preview/apply result
- GitHub checks and Greptile/review status
- Scratchpad files updated (orchestrated mode)
- remaining risks/open decisions
- what was intentionally not merged or not automated