| name | deliver |
| description | Inner-loop composer. Takes one backlog item to merge-ready code. Composes
/shape → /implement → {/code-review + /ci + /refactor + /qa} (clean loop)
and stops. Does not push, does not merge, does not deploy. Communicates
with callers via exit code + receipt.json — no stdout parsing.
Every run also ends with a tight operator-facing brief plus a full
/reflect session.
Use when: building a shaped ticket, "deliver this", "make it merge-ready",
driving one backlog item through review + CI + QA.
Trigger: /deliver.
|
| argument-hint | [backlog-item|issue-id] [--resume <ulid>] [--abandon <ulid>] [--state-dir <path>] |
/deliver
Inner-loop composer for Volume (Next.js 16 + Convex + Clerk + Stripe +
OpenRouter/AI SDK v6 on bun). One item from backlog.d/ → merge-ready
code on a feature branch. Delivered ≠ shipped. /settle lands the
PR; /deploy cuts the release. Humans merge.
Invariants
- Compose atomic phase skills. Never inline phase logic.
- Fail loud. A red gate is a red gate — never mask it as "best effort."
Closeout Contract
Every /deliver run ends with two operator-facing outputs, in order:
- A tight delivery brief (5 bullets: what shipped, gates passed,
residual risk, suggested reviewer, follow-up tickets filed under
backlog.d/).
- A full
/reflect session — emits codification suggestions to
~/.claude/projects/-Users-phaedrus-Development-volume/memory/ and
fresh items into backlog.d/.
receipt.json remains the machine source of truth. The brief and
reflection are for the human operator.
The delivery brief must answer:
- Which
backlog.d/ item was worked and what changed.
- Why making it merge-ready matters now (user value + operator value).
- What structurally distinct alternatives existed and why the chosen
design won under current constraints. If it is merely "good enough,"
say so plainly.
- What was verified —
quality:full result, Playwright flow(s) touched,
manual-QA notes (invoke /volume-manual-qa whenever the change touches
health, auth, paywall, Today workspace, or the coach composer).
- Residual risk before merge or deploy (env-var drift, Convex schema
migration, Stripe mode assumptions, etc.).
/reflect is mandatory and separate. Brief explains the delivered
result; reflect captures harness mutations.
Composition
/deliver [backlog-item|issue-id] [--resume <ulid>] [--state-dir <path>]
│
▼
pick (if no arg) — top-priority file in backlog.d/ (skip _done/)
│
▼
/shape → context packet (goal + oracle + sequence)
│
▼
/implement → TDD on feat/<topic> or fix/<topic>
inner loop per edit: bun run test:affected
bun run typecheck
│
▼
┌── CLEAN LOOP (max 3 iterations) ──────────────────────────┐
│ /code-review → critic + philosophy bench │
│ /ci → `dagger call check --source .` (Docker) │
│ fallback: `bun run quality:full` │
│ /refactor → diff-aware simplify │
│ /qa → bun run test:e2e (Playwright) + │
│ /volume-manual-qa when UX touched │
│ + curl localhost:3000/api/health | jq │
└───────────────────────────────────────────────────────────┘
│ all green → merge-ready (exit 0)
│ cap hit or hard fail → fail loud (exit 20/10)
▼
receipt.json written to .agents/worktrees/<cycle>/deliver-receipt.json
Stop. No push. No merge. No deploy. Hand off to /settle or /deploy.
Pre-review batch (runs before /code-review):
bun run lint:fix && bun run format && bun run typecheck && bun run test:coverage
Full gate (equivalent to pre-push): bun run quality:full
= typecheck && lint && architecture:check && test:coverage && build
Phase Routing
| Phase | Skill | What it owns | Skip when |
|---|
| shape | /shape | context packet, oracle, sequence | packet already has executable oracle |
| implement | /implement | TDD red→green→refactor on feat/<topic> or fix/<topic>, Conventional Commits | — |
| review | /code-review | parallel bench review, synthesized findings | — |
| ci | /ci | dagger call check --source ., fallback bun run quality:full | /ci itself decides — do not pre-filter |
| refactor | /refactor | diff-aware simplification | trivial diffs (<20 LOC, single file) |
| qa | /qa | Playwright (e2e/auth.setup.ts, coach-flows.spec.ts, critical-flow.spec.ts, error-scenarios.spec.ts) + /volume-manual-qa + /api/health probe | pure library/refactor with no user-facing surface |
Each skill has its own contract and receipt. /deliver reads those
receipts; it never re-implements the phase.
Cross-Cutting Invariants
- No claims. Single local workspace. Concurrent worktrees coordinate
via state-dir isolation under
.agents/worktrees/<cycle>/.
- Never re-deliver stale backlog. If the target
backlog.d/<item>.md
already carries ## What Was Built, or git log on the current branch
contains Closes backlog:<item-id> / Ships backlog:<item-id>, or the
file has been moved to backlog.d/_done/, stop and route to
/groom tidy. That is drift, not fresh work.
- Never push.
/settle owns git push and PR land.
- Never merge.
gh pr merge is a human decision; release-please
handles master merges for releases.
- Never deploy. Convex prod deploy
(
CONVEX_DEPLOYMENT=prod:whimsical-marten-631 bunx convex deploy -y)
and Vercel promotion are /deploy's concern.
- Never commit to master. Feature branch only (
feat/<topic> or
fix/<topic>). Master moves only through release-please.
- Conventional Commits. commitlint + Lefthook enforce on commit.
Never use
--no-verify. SKIP_QUALITY_GATES=1 is an emergency escape
and must be documented in the PR comment.
- Fail loud. Coverage under threshold (lines 52, branches 83,
functions 73, statements 52) is red.
bun run architecture:check
boundary/cycle violations are red. trufflehog secret hits are red.
- Evidence is out-of-band.
/deliver writes zero artifacts itself;
per-phase skills emit under .agents/worktrees/<cycle>/; receipt
records pointers only.
Contract (exit code + receipt)
/deliver communicates exclusively via its exit code and the receipt at
.agents/worktrees/<cycle>/deliver-receipt.json. Callers — human,
/settle, or an outer loop — do not parse stdout.
| Exit | Meaning | Receipt status |
|---|
| 0 | merge-ready (quality:full green + QA smoke + review clean) | merge_ready |
| 10 | phase handler hard-failed (Docker daemon absent, bunx convex dev out of sync, tool infra error) | phase_failed |
| 20 | clean loop exhausted (3 iterations, still dirty) | clean_loop_exhausted |
| 30 | user/SIGINT abort | aborted |
| 40 | invalid args / missing dep skill | phase_failed |
| 41 | double-invoke on an already-delivered backlog.d/ item | phase_failed |
Resume & Durability
State is filesystem-backed and resumable.
- State root:
.agents/worktrees/<cycle>/ (gitignored). Override
with --state-dir <path>.
- Checkpoint: after each phase,
state.json rewritten atomically
(write → fsync → rename) alongside deliver-receipt.json.
--resume <ulid>: loads state.json, skips completed phases,
re-enters at current_phase. Phase handlers must be idempotent.--abandon <ulid>: removes state-dir; leaves branch as-is.- Double-invoke:
/deliver <already-delivered-item> → exit 41.
Gotchas (judgment, not procedure)
- Retry vs escalate. Dirty on iteration 1 → retry. Dirty on
iteration 3 → exit 20, write receipt, hand to human. The cap is
load-bearing.
- What counts as "dirty".
/code-review blocking verdict, /ci
non-zero (dagger call check fail or quality:full red), /qa
P0/P1 (including Playwright failures and broken /api/health). P2
findings are logged in the receipt and do NOT block. Review "nit"
and "consider" are not blocking.
- Coverage drift.
vitest.config.ts thresholds and
scripts/verify-coverage.ts must stay in sync. If one moves, the
other moves in the same commit — otherwise CI will whiplash.
- Convex types stale. After any
convex/schema.ts change, run
bunx convex dev before bun run typecheck. Stale types are a
classic phase-10 hard fail.
- AI SDK conversation shape. Coach-touching changes must use
ModelMessage[] from 'ai' and append response.messages each
turn. Flat {role, content} pairs will silently re-trigger tools.
- Dagger Docker daemon absent.
/ci falls back to
bun run quality:full and records the fallback in the receipt.
Never silently skip architecture or coverage gates.
- Inlining a missing phase.
/implement missing → exit 40. Do not
fall back to your own TDD build.
- Silent push. A phase skill that "helpfully" runs
git push is a
bug in that phase skill. Surface it.
- Re-shaping mid-delivery. If
/implement or /qa reveals the
shape is wrong (e.g., the ticket asks for a feature that collides
with soft-delete or PaywallGate assumptions), stop the clean loop
and exit with remaining_work pointing at re-shape. Do not spin.
- Skipping shape. Building without a context packet yields
plausible garbage. If the
backlog.d/ item has no oracle, /shape
runs first. Always.
- Review without verdict = dirty. If
/code-review runs but no
refs/verdicts/<branch> points at HEAD afterward, treat the review
phase as failed.
- Stale active item. A
backlog.d/ item can be "open" and still
already shipped because someone landed it manually. Refuse to treat
that as new work; move the file into backlog.d/_done/ first.
- Merging. Never. End-state is merge-ready, not merged.
References
backlog.d/ — input queue (one .md per item); backlog.d/_done/ — archive.agents/worktrees/<cycle>/deliver-receipt.json — per-run receiptvitest.config.ts + scripts/verify-coverage.ts — coverage thresholdssrc/lib/architecture-checker.ts + scripts/verify-architecture.ts — boundaries + cyclese2e/ — Playwright flowsCLAUDE.md — project invariants and pitfalls
Non-Goals
- Deploying —
/deploy owns Convex prod + Vercel promotion
- Merging — humans merge; release-please lands master merges
- Pushing —
/settle owns git push and PR land
- Multi-ticket operation — one
backlog.d/ item per invocation
- Version-controlled evidence — gitignored under
.agents/worktrees/
Related
- Upstream escape hatch:
/ceo-review (invoke before /shape when the
ticket's framing is suspect)
- Phases:
/shape, /implement, /code-review, /ci, /refactor,
/qa, /volume-manual-qa
- Downstream:
/settle (push + PR), /deploy (release), /reflect
(always fires at session end)
