dev-delivery
Dev delivery orchestration — QA-first acceptance checklist → single writer implements (self-verified) → independent read-only review (diff-only input) → fail-closed acceptance → fixes go back to the writer → (visual gate for UI/PPT deliverables); multi-module tasks can run as parallel workstreams on disjoint files. MUST USE for multi-file coding tasks, code delivered for others to run, or changes needing independent acceptance; single-file scripts may use the lite path.
ccai40359-wq · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add ccai40359-wq/seanswarm --skill dev-deliveryAbout this skill
name: dev-delivery description: Dev delivery orchestration — QA-first acceptance checklist → single writer implements (self-verified) → independent read-only review (diff-only input) → fail-closed acceptance → fixes go back to the writer → (visual gate for UI/PPT deliverables); multi-module tasks can run as parallel workstreams on disjoint files. MUST USE for multi-file coding tasks, code delivered for others to run, or changes needing independent acceptance; single-file scripts may use the lite path.
Dev Delivery
Core principles: one writer; independent, read-only review; fail-closed acceptance; fixes go back to the writer. Multi-agent raises the floor (that's what gates are for) — the ceiling is still the main model. So the gates must be real, short, and evidence-backed.
0. Pick the path
- Full flow: multi-file / delivered for the user to run / touches data or security.
- Lite: single-file tools, exploratory scripts → the main session lists acceptance points → implement with self-test coverage → (optional) one static review pass.
1. HITL plan gate (big changes only)
Before spending budget, produce a 3-5 line plan: files touched, module boundaries/contracts, failure modes, how it will be accepted. Get the user's nod first — reworking a plan is far cheaper than reworking a heap of code.
2. QA-first: freeze the acceptance checklist
Dispatch reviewer (read-only) to produce the acceptance checklist: numbered items + the pass bar for each + severity P0-P3. The checklist must be frozen before implementation; changing requirements mid-flight = change the checklist and say so.
3. Single-writer implementation
Dispatch worker-coder, one module per dispatch. "One writer" is a per-workstream rule, not one writer for the whole project — independent workstreams may run in parallel (below).
- verification-before-completion: run verification yourself (tests/command output) before reporting back; no fresh run output → you may not say "done".
- Report format: files changed + run evidence + leftover risks.
Parallel workstreams (multi-module tasks)
Two modules are independent workstreams when their file sets are disjoint. Then dispatch N worker-coders in a single message (so they run in parallel), each carrying its own slice of the frozen checklist.
| Safe to parallelize | Keep as one workstream |
|---|---|
| separate directories / modules / projects | the same file (entry point, router, registry, package.json, lockfile) |
| separate service boundaries behind a frozen interface | DB schema / migrations |
| docs vs code, in separate files | shared i18n / config files |
Rules:
- Freeze the interface before dispatch — function signatures, data shapes, file paths go into every dispatch note. A moving interface turns parallel work into rework.
- A shared file that must change is its own workstream: main session (or one writer) lands it first, the others build on the result.
- Each workstream runs the same pipeline end to end: QA-first checklist slice → writer self-verifies → diff-only review → fail-closed acceptance. Parallelism changes how many writers run, not how each one is gated.
- Integration belongs to the main session: merge, run the cross-module check, then re-run every workstream's acceptance items on the integrated tree — per-workstream review cannot see cross-module breakage.
4. Independent read-only review
Dispatch reviewer. Dispatch notes:
- Feed only the diff + requirements (+ optional commit SHA), never the conversation history — clean perspective, no contamination.
- Output: each finding = location (file:line) + phenomenon + severity (P0-P3); no unsubstantiated generic advice.
- finder ≠ fixer: the reviewer only finds; fixes go back to the single writer; one repair round, no recursion.
5. Fail-closed acceptance
- unknown = fail: anything unconfirmed counts as not-passed unless explicitly waived with a written reason.
- An empty diff needs an explicit waiver to count as "no change needed".
- Numeric assertions must trace to first-hand output (test logs / command output) — "I did run it" is not accepted.
6. Visual gate (when the deliverable is UI / web / PPT)
- Render → screenshot → verdict (pass/fail + evidence, one line per page/screen) → fix → re-render and re-judge.
- Judge with visual-judge (zero write permission; sees only rendered images, never source files).
- Mechanical gate (optional): edited UI files but produced no screenshot evidence this turn → bounce at wrap-up to collect evidence. Example hook:
hooks/ui-screenshot-gate.mjsin this repo.
7. Failure handling
- Sub-agent dispatch failure/timeout → retry once (smaller scope or different model); if it fails again, the main session covers it and states the gap in the final answer.
- Circuit breaker: the same channel/model failing twice in a row → switch channel/model; do not hit it a third time.
- Silent model substitution: for third-party OpenAI-compatible endpoints, verify the response's
modelfield matches the request (scripts/verify-model.mjs) — some endpoints answer with their own default model for unknown ids without saying so.
8. Dispatch ledger (optional; recommended for long tasks)
- Save every dispatch to
<project>/.dispatch/<time>-<role>.md(full task + model + raw output); keep multi-round progress in.dispatch/STATE.mdto resume after interruption. - On first creation, write a one-line
.gitignorecontaining*inside.dispatch/— it never gets committed.
Pre-delivery self-check (all must pass)
- Checklist items all verified? Un-passed ones explicitly waived with reasons?
- Review findings all carry location + evidence? P0/P1 fixed or explicitly declined with reasons?
- Fresh run output exists before any "done" claim?
- Visual deliverables: screenshot evidence + verdicts present?
- Dispatch ledger complete (if enabled)?