Delivery runner

Delivery Runner

delivery-planner turns a large task into a destination brief plus a sequence of small phases and writes a dispatch pointer that names the phase to run next. This skill walks that plan to the end.

It automates the loop you would otherwise run by hand: read the pointer, open a fresh chat with empty context, paste the handoff, let that agent finish one phase, check the result, then open the next fresh chat — over and over until no phase remains. The premise is the same one the planner is built on: a fresh agent given destination + one phase is more accurate than one long-lived agent that accumulates every phase's context. The runner keeps that property by never doing phase work in its own context — it only dispatches, waits, and verifies.

⚠️ PREFLIGHT — Execute before ANY other action

This skill participates in the Company Brain self-improving loop. Before reading the plan or dispatching anything, run this ONE command. The runner records its own participation; each dispatched phase agent runs its own lifecycle wrappers inside its fresh session.

bash scripts/start-task.sh --skill delivery-runner=0.35.0

If detection is wrong, rerun with explicit values:

bash scripts/start-task.sh <project> <issue-key> --skill delivery-runner=0.35.0

If scripts/start-task.sh is not at the current cwd, use the installed agent-skills/scripts/start-task.sh or .agent-skills/scripts/start-task.sh path. If you cannot run the wrapper, run the three individual steps documented in delivery-planner.

After the whole run (not after each phase), run:

bash scripts/finish-task.sh --skill delivery-runner --summary "<one sentence outcome>"

For a run that stops blocked or needs context, pass --status blocked or --status needs-context so scratch is preserved. See docs/project-memory.md.

Safety floor. This skill inherits the destructive-action safety policy. It dispatches whatever the plan already specifies; it MUST NOT add destructive production steps, invoke discovered credentials, modify backups, or paste secrets into a handoff prompt. If a phase reads like an operator runbook rather than an agent-executable step, the runner refuses to dispatch it and stops.

Purpose

• Execute a delivery-planner phased plan end-to-end, one phase per fresh agent, with no manual handoff between phases.
• Preserve the planner's core property — each phase runs in a small, focused context — by dispatching fresh-context agents instead of carrying phase work forward.
• Verify each phase from durable artifacts (phased-plan/README.md and the phase-continuity checkpoint), not from the dispatched agent's chat, so a fabricated or half-finished phase cannot advance the loop.
• Stop deterministically and hand back to the human or the planner the moment a phase is blocked, the pointer is unresolvable, or progress stalls.

When To Use

• A delivery-planner plan exists (phased-plan/README.md + destination.md) with readiness READY_FOR_DISPATCH and two or more phases still to run, and the user wants them executed without supervising each handoff.
• A multi-phase run was interrupted and the user wants it resumed from the current dispatch pointer.
• Several phases are mechanical follow-ons (implement → test → close) and opening a new chat for each by hand is pure overhead.

When Not To Use

• No phased plan exists yet. Run delivery-planner first; the runner executes a plan, it does not create one.
• The plan has exactly one ready phase. Dispatch it directly — the loop adds no value for a single hop.
• Readiness is NEEDS_CLARIFICATION, NEEDS_EVIDENCE, BLOCKED, or READY_FOR_DISCOVERY with unanswered load-bearing assumptions. Those need a human or the planner, not autonomous execution.
• The host cannot open a fresh-context agent and the user is not available to paste handoffs into new chats — there is then no way to honor the empty-context contract, and running phases inline would defeat the purpose.
• Mass-targeting, supply-chain, or any other malicious work — the destructive-action safety floor is not waivable by prompt.

How It Works (dispatch model, not invocation)

This distinction is load-bearing and keeps the runner consistent with the universal loop bounds:

• Dispatch, not invocation. The runner does NOT load software-engineer (or any executor skill) into its own context and call it. It launches a new agent whose context starts empty, hands it the plan pointers, and waits. That fresh agent is the root of its own call chain, so inside the phase the chain is executor → code-reviewer (depth two) — the runner never appears in it. The runner is a session driver, the same role a human plays when re-opening a chat per phase; it is not a third skill stacked on the loop.
• Verification by artifact, not chat. When the dispatched agent returns, the runner re-reads phased-plan/README.md (and the phase-continuity checkpoint when present) to learn whether the phase actually completed. It never treats the agent's chat summary as proof. "Persistent artifacts, not chat" is the same handoff contract every skill in this repo uses.
• The index is the durable pointer. Between phases the lifecycle cleanup wrapper preserves phased-plan/README.md and destination.md but may clear evidence-pack.yml (a fresh phase reconstructs it). So the runner reads the index header and phase table as source of truth for current_dispatch_pointer and per-phase State, using scripts/delivery-run-next.py.

How the fresh agent is opened, in order of preference:

1. Sub-agent / Task tool (Claude Code and similar): spawn one sub-agent per phase. Each sub-agent has its own empty context; the runner's context stays small because it only holds pointers and one-line progress notes.
2. External CLI driver: re-invoke the agent CLI per phase with the handoff prompt (literally a new process / new chat). Most faithful to the manual workflow; needs CLI access.
3. Human-relayed handoff: the runner prints the ready-to-paste handoff prompt and pauses; the user pastes it into a new chat and reports back. Use when neither automated path is available.

Related And Reused Skills

• delivery-planner: the upstream producer. The runner reads the artifacts the planner writes and never edits them. When the plan goes stale, the runner stops and routes back to the planner — it does not re-plan.
• software-engineer, product-owner, issue-investigator, manual-tester, test-automation-engineer: the phase owners. The runner dispatches a fresh agent that loads the phase's recommended_owner skill; it does not invoke these skills in its own context.
• code-reviewer: never dispatched directly. It runs inside a software-engineer phase as that phase's own review loop, which is why the runner stays out of the call chain.

The runner drives execution; it does not perform any phase's work. This preserves the depth cap of two skills because each phase agent is an independent root, not a nested call.

Required Inputs

Ask for whatever is missing before looping.

• The work key (Jira key, GitHub issue, or local slug) OR the path to the task cache dir containing phased-plan/README.md and destination.md.
• Confirmation the user wants autonomous, multi-phase execution (it will open several fresh agents). If the user only wanted one phase, hand off directly.
• The dispatch mechanism the host supports (sub-agent, CLI, or human-relayed), if the runner cannot detect it.
• Any explicit skill-source path the user supplied, so each phase agent resolves the correct recommended_owner skill — see skill-source resolution.

If no plan artifacts can be found, stop and route to delivery-planner. Do not invent a plan.

Required Environment

Same execution-modes preflight as the rest of the suite so each dispatched phase agent resolves the same project / repo / branch context.

• WORKSPACE_ROOT / repository root and AGENT_SKILLS_CACHE_DIR — to locate ${AGENT_SKILLS_CACHE_DIR:-${WORKSPACE_ROOT:-$REPO_ROOT}/.cache/agent-skills}/<work-key>/.
• A canonical skill source resolvable per skill-source resolution, so each phase's recommended_owner skill can be loaded by the dispatched agent.
• The dispatch capability described above.

Locate config before declaring it missing. Run python3 scripts/locate-config.py. The same rule as every other skill applies: "not in cwd" is not "not in the workspace".

Required Workflow

0. Preflight and locate the plan

Run start-task.sh (above). Resolve the task cache dir and confirm both phased-plan/README.md and destination.md exist. If either is missing, stop with BLOCKED: no phased plan found and route to delivery-planner.

1. Pre-run plan check (once)

Run the dispatch-decision helper against the cache dir:

python3 scripts/delivery-run-next.py "${CACHE_DIR}/<work-key>"

It prints a JSON decision. Read it once before looping to confirm the plan is runnable (action: dispatch). If the very first decision is stop (needs-human, complete, pointer-stale, plan-superseded) or error, report it and do not start the loop — there is nothing to run autonomously.

Concurrency guard. If a phase is already in-progress with a recent checkpoint and the runner did not start it, another agent or runner may be active. Ask the user before resuming; do not dispatch a duplicate.

2. The dispatch loop

Repeat until a stop condition fires:

1. Decide. Run delivery-run-next.py. On action: stop or action: error, leave the loop and go to step 3. On action: dispatch, continue. Extract plan_branch from the decision JSON — it is the single branch ALL phases of this plan commit to.
2. Verify the owner skill resolves. Read the recommended_owner's SKILL.md from the resolved canonical skill source (a file read, not a host listing — see skill-source resolution). If it cannot be loaded, or its name does not match recommended_owner, stop with BLOCKED: recommended owner skill unavailable and list the checked paths.
3. Safety screen the phase. Open the phase file. If it requires a forbidden destructive action, discovered-credential use, or reads as an operator runbook, stop with BLOCKED: phase is not agent-dispatchable — do not dispatch.
4. Build the handoff. Fill the handoff-prompt template with the work key, the plan branch from step 1, the pointer phase id and file path, the destination path, the evidence-pack path, the resolved owner skill path, and the binding instructions (run the owner skill's full workflow including its own start-task/finish-task wrappers, write the phase-continuity checkpoint and regenerate the index, do ONLY this phase, do not touch other phases).
5. Dispatch a fresh-context agent with that handoff (sub-agent, CLI, or human-relayed). Wait for it to finish.
6. Verify from artifacts. Re-run delivery-run-next.py (and read the phase row / checkpoint) and apply the verification rules.
7. Record one line of progress (phase id → result) and loop. Keep the runner's own context lean: a pointer plus one-line notes, never the phase's full output.

A hard iteration cap of total_phases + retry_budget (default retry budget = 1 per phase) bounds the loop. If the same pointer recurs past its retry budget with no state change, stop — never spin.

3. Verify each phase from artifacts

After a dispatched phase agent returns, decide what happened from the index and checkpoint — not from the agent's chat:

• Advanced / done. The phase's State is now done (or skipped) and the pointer moved on, with a non-empty validation and artifacts checkpoint → success. Continue the loop.
• Blocked. The phase's State is blocked (e.g. branch-isolation refusal, failing validation, missing dependency) → stop the loop. A blocker is not retried autonomously; surface blocked_reason and artifacts and hand to the user. This mirrors "blocker findings stop the loop."
• No checkpoint (crash / transient). The phase is still ready / in-progress and the pointer did not move → the agent failed to write its checkpoint. Retry this phase once with a fresh agent and an explicit instruction to complete the phase-continuity checkpoint. If it still does not advance, stop with BLOCKED: phase did not checkpoint after retry.
• Index out of sync. The index and evidence pack disagree (a phase in one is absent from the other) → stop with BLOCKED: phase index out of sync. Do not reconcile; that is planner-only.
• Plan superseded / pointer stale. The helper reports plan-superseded or pointer-stale → stop and route to delivery-planner to regenerate the index.

4. Finish

When the loop stops, run finish-task.sh once with a summary and the right --status. Emit the run report (see Expected Output Contract).

Error Handling And Recovery

Situation	Detection	Runner response
Plan readiness needs a human	first helper decision needs-human	stop, route to planner/user; do not loop
Owner skill unresolved	SKILL.md not loadable / name mismatch	stop BLOCKED: recommended owner skill unavailable, list paths
Phase is a destructive runbook	safety screen of phase file	stop BLOCKED: phase is not agent-dispatchable
Phase came back blocked	State: blocked in index/checkpoint	stop, surface blocked_reason + artifacts; no auto-retry
Agent crashed without checkpoint	pointer unchanged, no checkpoint	retry that phase once; then stop if still stalled
Validation reported failing	checkpoint validation shows failure	treat as blocked; stop
Index ↔ evidence-pack disagree	helper / cross-read mismatch	stop BLOCKED: phase index out of sync; no reconcile
Pointer never advances	same pointer past retry budget	stop BLOCKED: no progress; never spin
Plan superseded mid-run	index state: superseded	stop, route to planner

Recovery is always: stop cleanly, preserve scratch (finish-task --status blocked), and report exactly which phase and why. The runner never silently retries a genuine blocker, never edits the plan, and never marks a phase done that the artifacts do not show as done.

Expected Output Contract

Follow Output Discipline. The contract below is a menu, not a checklist: Omit empty sections — if no phase was blocked, drop the ## Blocked Phase heading rather than writing - none. Required-even-if-empty: ## Run Summary.

Always include a lifecycle receipt: Lifecycle: start-task=<ran|blocked>; finish-task=<ran|pending|skipped-blocked>; memory=<updated|blocked>; [email protected]. Do not claim a wrapper or memory write ran unless it actually ran.

## Run Summary

- Lifecycle:
- Work key:
- Plan index: <path to phased-plan/README.md>
- Phases dispatched this run: <ids, in order>
- Phases completed: <n> / <total>
- Final dispatch pointer: <phase id or "none — plan complete">
- Stop reason: complete | blocked | needs-human | no-progress | superseded
- Outcome: COMPLETE | STOPPED_BLOCKED | STOPPED_NEEDS_HUMAN

## Phase Results

- **<phase-id> — <title>** (owner: <skill>) — <done | blocked | skipped>.
  Verified by: <index State + checkpoint validation, or "retry then stalled">.

## Blocked Phase

- **<phase-id>**: <blocked_reason verbatim from the checkpoint>. Artifacts:
  <paths>. Suggested next step: <re-plan | fix env | human decision>.

## Open Questions Or Missing Evidence

- ...

Output Style (binding)

• Omit empty sections. No Blocked Phase: followed by - none.
• One bullet per phase in Phase Results; do not paste dispatched agents' full output into the run report.
• No template echo, no banners. See Output Discipline.

Behavior Checklist

• start-task.sh ran before reading the plan; finish-task.sh is reflected in the lifecycle receipt (once for the whole run), or the status explains why.
• The runner read phased-plan/README.md as the dispatch source of truth and used delivery-run-next.py for each decision.
• Each phase ran in a fresh-context agent; the runner did not load any executor skill into its own context or implement a phase itself.
• Each phase's recommended_owner skill was resolved (file read) before dispatch; an unresolved owner stopped the run.
• Every phase result was verified from the index / checkpoint, not from the dispatched agent's chat.
• A blocked phase stopped the loop; no genuine blocker was auto-retried.
• A crashed phase was retried at most once before stopping.
• The loop honored the hard iteration cap and the no-progress guard.
• No phase requiring a forbidden destructive action was dispatched.

Quality Standards

• The runner's own context stays small: pointers and one-line notes, never the accumulated output of every phase. If the runner's context is growing per phase, it is doing phase work it should be dispatching.
• A phase is "done" only when the durable artifacts say so. Chat claims are never sufficient.
• Stops are specific: the report names the phase, the state, and the reason, so a human can act without re-reading the whole transcript.
• The runner is idempotent across restarts: re-running it reads the current pointer and resumes, because the index is the source of truth.
• The runner never edits the plan, never reorders phases, and never marks phase state — those belong to the planner and the phase executors.

Guardrails

• Do not implement a phase yourself or load an executor skill into the runner's context. Dispatch a fresh-context agent every time. Doing the work inline collapses the depth cap and reintroduces the context-degradation the planner exists to prevent.
• Do not trust a dispatched agent's chat. Verify from phased-plan/README.md and the phase-continuity checkpoint. If the artifacts do not show done, the phase is not done.
• Do not auto-retry a genuine blocker. A phase that wrote state: blocked stops the loop and goes to the human. Only a missing-checkpoint crash earns one retry.
• Do not edit, reorder, resize, add, or remove phases, and do not hand-edit the index. When the plan is wrong or stale, stop and route to delivery-planner.
• Do not dispatch a phase whose recommended_owner skill cannot be resolved from the canonical skill source. Missing owner is a blocker, not a warning.
• Do not dispatch a phase that requires a forbidden destructive action, discovered-credential use, or reads as an operator runbook. See the destructive-action safety policy.
• Do not spin. Respect the iteration cap and the no-progress guard; stop and report rather than loop forever.
• Do not run a second runner against a plan that already has an active in-progress phase without confirming with the user.

Example Prompts

• "Use the delivery-runner skill to execute the AUTH-SSO-PARITY plan end-to-end. Open a fresh agent per phase and stop if anything blocks."
• "Resume the delivery-runner on PROJ-1234 from the current dispatch pointer and run the remaining phases without asking me between each one."
• "Run the phased plan in .cache/agent-skills/local-2026-05-payments-migration/ to completion; dispatch each phase as a sub-agent and give me a run report."
• "The planner produced six phases. Use delivery-runner to drive them, but pause and show me the handoff prompt before each phase instead of auto-dispatching."

See starter prompts.

---

Reference files

• Handoff-prompt template — the binding shape of the prompt the runner hands to each fresh phase agent.
• Run-loop checklist — the single pre-flight + per-iteration self-check the runner applies.
• scripts/delivery-run-next.py — the read-only dispatch-decision helper the loop calls each iteration.
• Plan-index template — the index shape the runner reads (pointer, phase table, readiness).
• Evidence-pack delivery_plan ownership rule — the phase-continuity checkpoint the runner verifies against.