deliver

name	deliver
description	scry inner-loop composer. Takes one file-driven backlog item from backlog.d/ to merge-ready code by composing /shape -> /implement -> {/code-review + /ci + /refactor + /qa as applicable}. Stops at merge-ready. Does not push, merge, deploy, archive backlog tickets, or inject backlog-closing trailers; /ship owns closure. Use when: building one shaped backlog item, "deliver this", "make it merge-ready", driving one scry ticket through implementation, review, verification, and evidence. Trigger: /deliver.
argument-hint	[backlog-id|backlog-file|issue-id] [--resume <ulid>] [--abandon <ulid>] [--state-dir <path>]

/deliver

One scry backlog item becomes merge-ready code. Delivered is not shipped: /deliver stops with a clean branch, a receipt, and a terse operator brief. /ship owns pushing, PR landing, backlog archival, backlog trailers, and post-merge reflection.

Non-Negotiable Role

• Work exactly one backlog item from backlog.d/ or one explicit GitHub issue.
• Compose phase skills; do not inline /shape, /implement, /code-review, /ci, /refactor, or /qa logic.
• Stop at merge-ready. Never run git push, gh pr merge, deployment commands, production migrations, ticket archival, or git mv backlog.d/<id>-*.md backlog.d/_done/.
• Do not add Closes-backlog:, Ships-backlog:, or Refs-backlog: trailers. /ship injects trailers and archives the backlog file during landing.
• Fail loud. A red phase is a red delivery, not a "best effort" pass.

Scry Ship Gate

The ship gate is GitHub Actions Quality Checks merge-gate: pnpm lint, pnpm typecheck, pnpm audit --audit-level=critical, no focused tests via the .only grep, and pnpm test:ci must pass; local parity is pnpm lint && pnpm tsc --noEmit && pnpm test:ci, with pnpm test:contract for convex/**, pnpm build for build/config/workflow/dependency surfaces, and pnpm audit --audit-level=critical for dependency or lockfile changes.

For delivery, "merge-ready" means the local parity command and every relevant additive check above passed, or the receipt records the exact failure and exits non-zero. Use pnpm only. bun CI files and migration docs are parity evidence, not permission to switch the workflow.

Lefthook is defense in depth, not the gate. Pre-commit runs TruffleHog, topology hygiene, pnpm exec tsc --noEmit, and lint-staged. Pre-push runs scripts/test-changed-batches.sh and pnpm test:contract, but /deliver still does not push.

Composition

/deliver [backlog-id|backlog-file|issue-id] [--resume <ulid>] [--state-dir <path>]
    |
    v
  pick one backlog.d item if no arg
    |
    v
  /shape        -> executable .ctx.md packet with goal, constraints, oracle, sequence
    |
    v
  /implement    -> TDD build on feature branch
    |
    v
  CLEAN LOOP, max 3 iterations
    - /code-review: concrete blocking findings, not style commentary
    - /ci: scry gate parity and additive checks
    - /refactor: diff-aware simplification only where risk or duplication is real
    - /qa: only for user-facing review/library/generation surfaces
    |
    v
  receipt.json + operator brief; stop

Ticket Intake

scry backlog is file-driven:

• Active backlog items are backlog.d/<id>-<slug>.md.
• Context packets are backlog.d/<id>-<slug>.ctx.md.
• _done/ is archival state and belongs to /ship, not /deliver.
• A shaped packet is executable only when it names the spec, constraints, file inventory, implementation sequence, oracle, and verification.
• Existing ## What Was Built means the item has already been delivered or shipped; stop and route to /groom tidy instead of re-delivering stale work.

If no target is supplied, pick the highest-priority active item that is not Status: done and has enough oracle detail to execute. If a .ctx.md packet is missing or stale, run /shape first. Do not improvise around a weak oracle.

Scry Delivery Rules

• Backend-first Convex. For Convex work, implement schema, query, mutation, action, helper, and contract changes under convex/ first. Validate generated API/type readiness before wiring React. Run pnpm test:contract when convex/** changes.
• Pure FSRS. Do not add daily limits, artificial review caps, comfort-mode buttons, "easy" shortcuts, or algorithmic optimizations that change FSRS scheduling. The interval decides.
• Bounded Convex reads. Runtime queries use indexes, .take(), pagination, and truncation signals. No unbounded .collect() in runtime paths.
• Mutation reversibility. Destructive UX needs a reverse path: archive/unarchive, softDelete/restore. Hard delete requires explicit confirmation UX.
• Deploy and migration commands require explicit approval. Never run pnpm build:local, pnpm build:prod, pnpm convex:deploy, ./scripts/deploy-production.sh, production migration scripts, or commands that mutate non-local Convex/Vercel state unless the operator explicitly approves that exact command.
• Source of truth. Trust package.json, .github/workflows/ci.yml, and lefthook.yml over README or older docs. CLAUDE.md is secondary; docs are advisory unless verified against live config.

Branch and Backlog Boundaries

/implement owns branch creation. The scry branch contract is:

<type>/<id>-<slug>

where <type> is one of feat, fix, chore, refactor, docs, test, or perf, and <id> is the bare numeric backlog ID. This branch name is the backlog claim that /ship later reads.

/deliver may reference the backlog ID in the receipt and brief, but it must not close it. Trailer-based closure is a /ship concern: Closes-backlog:, Ships-backlog:, Refs-backlog:, and movement into backlog.d/_done/ happen only there.

Phase Routing

Phase	Skill	scry-specific ownership	Skip when
Shape	/shape	Produce or refresh the .ctx.md packet and executable oracle	Packet is current, concrete, and already executable
Implement	/implement	TDD red -> green -> refactor on the feature branch	Never
Review	/code-review	Blocking risks in Convex contracts, FSRS semantics, bandwidth, auth, review UI, evals, and tests	Never
CI	/ci	Run the scry gate parity plus additive checks	Never
Refactor	/refactor	Remove accidental complexity introduced by this diff	Trivial single-concern diffs with no review/CI pressure
QA	/qa	Browser check for /, /concepts, generation modal, action inbox, settings, or other touched UI	Pure backend/lib/eval changes

Each phase writes its own evidence. /deliver records pointers in the receipt; it does not create version-controlled evidence bundles.

Verification Matrix

Always run:

pnpm lint && pnpm tsc --noEmit && pnpm test:ci

Add checks by touched surface:

Surface touched	Additional check
convex/**	pnpm test:contract
package.json, lockfile	pnpm audit --audit-level=critical
.github/workflows/**, next.config.ts, vercel.json, build config, dependencies	pnpm build
evals/**, prompt templates, generation behavior	relevant promptfoo command, usually pnpm eval or the shaped eval command
User-facing review/library/generation UI	/qa browser evidence plus targeted tests

Do not substitute pnpm qa for the gate unless the receipt also shows the required gate commands above. package.json defines both, but GitHub protects the merge-gate.

Clean Loop

The clean loop runs at most three times. Dirty means any of:

• /code-review returns a blocking finding.
• /ci fails any required or additive gate.
• /qa finds a P0 or P1 in a user-facing path.
• The implementation violates backend-first Convex, pure FSRS, bandwidth, mutation reversibility, or approval-gated command boundaries.
• Review completed but no verdict/evidence points at the current HEAD.

Iteration 1 or 2 can continue after fixes. Iteration 3 exits 20 with status: clean_loop_exhausted and a concrete remaining-work list. Do not invent a fourth loop.

If implementation proves the shape wrong, stop and return to /shape; do not patch around a bad oracle.

Contract

/deliver communicates through <state-dir>/receipt.json, exit code, and a short operator brief. Callers must not parse stdout.

Exit	Meaning	Receipt status
0	Merge-ready by the scry gate	merge_ready
10	Phase handler hard-failed	phase_failed
20	Clean loop exhausted after 3 iterations	clean_loop_exhausted
30	Operator/SIGINT abort	aborted
40	Invalid args or missing phase skill	phase_failed
41	Target was already delivered or shipped	phase_failed

The receipt must include:

• backlog target: ID, markdown path, ctx path if present
• branch and HEAD SHA
• phase receipts and evidence pointers
• commands run, with exit codes
• checks intentionally skipped and the reason
• residual risks and remaining work
• confirmation that no push, merge, deploy, migration, ticket archive, or backlog trailer injection happened

Resume and Durability

State is filesystem-backed and resumable:

• Default root: <worktree-root>/.spellbook/deliver/<ulid>/.
• Override: --state-dir <path>, usually supplied by /flywheel.
• After each phase, rewrite state.json atomically.
• --resume <ulid> loads state, skips completed phases, and re-enters at current_phase.
• --abandon <ulid> removes delivery state and leaves the branch untouched.

Do not depend on conversation memory. If the session dies, state.json, phase receipts, and git state must be enough to resume.

Operator Brief

End every run with a tight brief, not a changelog. It should state:

• backlog item worked and outcome
• user/product value once shipped
• developer/operator value now
• key design choice and rejected alternative
• verification run and residual risk
• whether /ship can take over or what blocks it

When /deliver runs inside /flywheel, keep the same facts but let /flywheel own the cycle-level summary.

Gotchas

• BACKLOG-001 and BACKLOG-002 already contain ## What Was Built; do not redeliver them as fresh work.
• BACKLOG-003 and BACKLOG-004 are eval-first work. Do not change generation behavior before establishing the eval floor called out by the oracle.
• BACKLOG-006 touches question types. Preserve schema, generation contracts, review UI, grading, and eval coverage together.
• BACKLOG-007 is extraction-only. Do not change public Convex API signatures or rewrite behavior while splitting monoliths.
• BACKLOG-008 calls for a thin Zod-validated renderSpec registry, not a general LLM-generated UI framework.

Non-Goals

• Shipping or landing work
• Pushing branches
• Merging PRs
• Deploying Convex or Vercel
• Running production migrations
• Archiving backlog files
• Injecting backlog trailers
• Multi-ticket batching

Related

• Producer: /shape writes executable .ctx.md packets.
• Builder: /implement owns branch and code changes.
• Cleaners: /code-review, /ci, /refactor, /qa.
• Consumer: /flywheel may call /deliver and read receipt.json.
• Closure: /ship pushes, lands, archives backlog, injects trailers, and runs post-merge reflection.