# dev-delivery

Adopt this skill: https://proskills.md/skills/other/ccai40359-wq-multiagents-workflow-skills-dev-delivery

Page: https://proskills.md/skills/other/ccai40359-wq-multiagents-workflow-skills-dev-delivery
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/dev-delivery/SKILL.md
size: 8084
upstream: https://github.com/ccai40359-wq/multiagents-workflow/blob/main/skills/dev-delivery/SKILL.md

```text
---
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".
- **Every workstream declares one exit-code verification command** — a single command whose exit code decides the workstream's pass/fail (test suite, build, lint, script). The writer runs it and cites the command + exit code; the main session re-runs it at acceptance. A subagent *reporting* "tests pass" is a claim, not evidence — the exit code is the evidence. (This is the `world.run` lesson: judgment belongs to a command's exit code, not to a model's self-report.)
- **Every dispatch declares its file boundary** — the list of paths/globs the writer may touch. At acceptance the main session runs the boundary gate: `node <pack-root>/tools/gates/boundary-check.mjs --boundary <patterns> --git-base <base-ref>` (exit 0 required). An out-of-bounds edit is a P0 finding even if the code is perfect — it means two writers now collide.
- Report format: the pack-wide five-section shape (`REPORT-CONTRACT.md`) — files changed + run evidence under **Verified** (command + exit code each) + leftover risks under **Not covered**/**Skipped**.

### 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:

1. **Freeze the interface before dispatch** — function signatures, data shapes, file paths go into every dispatch note. A moving interface turns parallel work into rework.
2. **Freeze each workstream's file boundary** — the path/glob list the writer may touch, recorded with the dispatch. After merge, prove the boundaries held: `node <pack-root>/tools/gates/boundary-check.mjs --boundary <patterns> --git-base <merge-base>` must exit 0.
3. A shared file that must change is **its own workstream**: main session (or one writer) lands it first, the others build on the result.
4. 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*.
5. **Integration belongs to the main session**: merge, run the cross-module check, then re-run every workstream's acceptance items (including the exit-code verification command and the boundary gate) 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.
- **Mechanical gates run at acceptance** (all must exit 0):
  - `node <pack-root>/tools/gates/boundary-check.mjs --boundary <patterns> --git-base <base>` — no file outside the declared boundary was touched.
  - `node <pack-root>/tools/gates/report-lint.mjs <writer-report.md>` — the writer's report satisfies the five-section contract (and no "skipped" check is disguised as blocked).
  - the workstream's declared **exit-code verification command**.

## 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.mjs` in this repo.

## 7. Failure handling — attribute first, then act

"Retry once" is not one rule. The three failure classes have opposite correct actions:

- **`failed-transport`** (timeout, killed for inactivity, turn execution failed, provider 4xx/5xx): retries belong to the host/provider layer. Do not burn a protocol retry — wait, then re-check via the ledger. Record `mark --status failed-transport`.
- **`failed-protocol`** (agent returned malformed output, ignored the contract, edited out-of-bounds files, claimed done without evidence): re-dispatch **once** with a narrower scope; a second protocol failure means the brief is the problem → treat as `failed-definition`.
- **`failed-definition`** (the task itself was misspecified — wrong scope, duplicate of another workstream, unreachable as written): **never re-dispatch as-is.** Void the task, void any work that rested on it, and re-specify as a new dispatch.
- **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 `model` field matches the request (`scripts/verify-model.mjs`) — some endpoints answer with their own default model for unknown ids without saying so.
- Every outcome is recorded with `tools/ledger/dispatch-ledger.mjs` — an unlogged failure is a silent one.

## 8. Dispatch ledger (recommended for anything multi-dispatch)

- Mechanical record: `node <pack-root>/tools/ledger/dispatch-ledger.mjs append|mark|status` — append-only JS
```

## File: README.md
upstream: https://github.com/ccai40359-wq/multiagents-workflow/blob/main/README.md

````text
# seanswarm

![seanswarm — multi-agent workflow pack for coding agents](assets/banner.png)

**A lightweight multi-agent workflow pack for mainstream coding agents — Claude Code, Codex, Cursor, ZCode, and other compatible hosts.**
Turn your coding agent into a supervised small team: research fan-out with evidence governance, dual-channel document reading, and dev delivery with independent review and visual acceptance.

[中文说明](README.zh.md)

---

## What this is

A pack of **agent skills + role templates** that install into mainstream coding agents (Claude Code, Codex, Cursor, ZCode). No runtime, no server, no framework — the host agent executes the protocols; the skills describe *how to organize the work*.

It covers four recurring scenarios:

| Scenario | Piece | Pattern |
|---|---|---|
| Web research | `skills/web-research-fanout` | fan-out lanes → claims table → adversarial lane → cross-family arbitration → anti-scrape ladder (L0–L4) |
| Document reading | `skills/dual-read` | two independent channels read the same document, then cross-compare (match / addition / conflict) |
| Dev delivery | `skills/dev-delivery` | QA-first acceptance list → single writer → independent read-only review (diff-only) → fail-closed acceptance → fixes go back to the single writer; disjoint modules run as parallel workstreams |
| Visual acceptance | `agents/visual-judge.md` + `hooks/ui-screenshot-gate.mjs` | render → screenshot → per-page verdict → fix → re-render; a mechanical hook bounces "done" without screenshot evidence |
| Evidence enforcement | `tools/gates/` + `tools/ledger/` + `REPORT-CONTRACT.md` | mechanical, zero-dependency checks: claims-table lint, file-boundary check, report-contract lint; append-only dispatch ledger with three-way fault attribution |

Role templates live in `agents/`: `researcher`, `reviewer`, `worker-coder`, `visual-judge`.

## Architecture

![seanswarm architecture at a glance](assets/architecture.png)

## Design principles

- **Evidence over consensus.** Claims need sources; conflicts are resolved by arbitration, never by majority vote. Independent-source count > vote count; primary > secondary; newer > older.
- **Role separation, not one super-agent.** A zero-write reviewer, a single writer, and a dedicated adversarial lane that hunts for counter-evidence.
- **Clean-context review.** The reviewer receives the diff + requirements — never the conversation history.
- **Fail-closed acceptance.** "Unknown" counts as failed; an empty diff needs an explicit waiver.
- **finder ≠ fixer.** The reviewer only finds; fixes go back to the single writer; one repair round, no recursion.
- **One writer *per workstream*.** Modules whose files are disjoint run as parallel workstreams — each still goes through the full gated pipeline, and the main session owns integration.
- **Verification before completion.** No "done" without fresh run output.
- **Judgment belongs to exit codes, not self-reports.** Every workstream declares one command whose exit code decides pass/fail; a subagent *reporting* "tests pass" is a claim, the exit code is the evidence. Ported from watching deterministic gate runners: the model answers questions, the command renders verdicts.
- **Frozen briefs, recorded knobs.** A dispatch's invariant brief never changes after dispatch — gaps are handled by adding lanes, not editing briefs — and tunable parameters (budget, model, tier) are recorded in the ledger, not embedded in the prompt. Every conclusion stays traceable to the parameter set that produced it.
- **Faults are attributed, not just retried.** `failed-transport` (host/provider layer — wait), `failed-protocol` (contract broken — re-dispatch once, narrower), `failed-definition` (the task itself was wrong — never re-dispatch; void downstream and re-specify). One flat "retry once" rule conflates three opposite situations.
- **Cheap gates beat clever prompts.** The mechanical hook exists because prose alone is not enforcement — v0.2 extends the idea from one hook to a gate suite (see below).

## Install

### Manual (any host with skills support)

```bash
# skills → your skills directory
cp -r skills/* <skills-dir>/
# roles → your agents directory
cp agents/*.md <agents-dir>/
```

Common locations: ZCode `~/.agents/skills` + `~/.zcode/agents`; Claude Code `~/.claude/skills` + `~/.claude/agents`; Codex `~/.codex/skills`. See `adapters/` for per-platform notes.

### Plugin (ZCode)

The repo ships a plugin manifest at `.zcode-plugin/plugin.json`. Add the repo as a plugin source and enable it.

### Hook (optional)

`hooks/ui-screenshot-gate.mjs` is a Stop-event hook: when UI files were edited in a turn that produced no screenshot evidence, it sends the turn back to collect evidence. Wiring instructions in `hooks/README.md`.

### Mechanical gates & ledger (new in v0.2)

`tools/` ships the mechanical layer of the protocols — deliberately dumb (no LLM, no judgment, just bookkeeping), zero npm dependencies, Node 18+:

| Command | Gate | Fails when |
|---|---|---|
| `node tools/gates/claims-lint.mjs <lane-output.md>` | research claims table | a row lacks a public URL / date / primary-secondary marker / counter-evidence; a conflict never reached an arbitration section |
| `node tools/gates/boundary-check.mjs --boundary <patterns> --git-base <ref>` | dev-delivery file boundaries | a changed file falls outside the workstream's declared boundary |
| `node tools/gates/report-lint.mjs <report.md>` | the five-section report contract (`REPORT-CONTRACT.md`) | a required section is missing; a "skipped" check is disguised as blocked; a *Verified* item carries no evidence marker |
| `node tools/ledger/dispatch-ledger.mjs append\|mark\|status` | dispatch bookkeeping | (not a gate) — append-only JSONL answering "which conclusions are not yet verified", with `failed-transport` / `failed-protocol` / `failed-definition` attribution |

All gates: exit `0` pass · `1` violation · `2` cannot-judge; `--json` for machines; `--strict` promotes warnings. 175 tests cover the suite (`node tests/*.test.mjs`).

## Quick start

- Research: *"Research X across official docs, GitHub, and community — fan out, then verify."*
- Document: *"Read this contract with a second independent pass and cross-compare."*
- Dev delivery: *"Implement feature Y: QA-first, single writer, independent review. Unknown counts as failed."*
- Visual acceptance: *"Render the deck to PNGs and run the visual judge page by page; fix fails and re-judge."*

Skills trigger on these kinds of requests; you can also name them explicitly.

## Design notes

**Orchestration vs channels.** The pack separates *how work is organized* (lanes, tiers, contracts, arbitration) from *how data is actually fetched* (APIs, search-index layer, direct fetch, browsers). Many failures people blame on "the model" are channel failures.

**Why fan-out isn't cloning.** N agents with the same question pick the same pages and reinforce the same error. Lanes must differ in at least one dimension: source type, language, stance, or model family.

**Output shape.** Every workstream reports in the same five sections — Conclusion / Findings / Verified / Not covered / Skipped — so merging becomes bookkeeping instead of prose-reading. See `REPORT-CONTRACT.md`; the claims-table contract every lane must return is shown in `examples/claims-table-sample.md`.

**Cost, measured (4-lane run — the low end of the standard tier — single host):** ≈0.56M tokens total, ≈5 min wall clock (parallel) + ≈1 min arbitration. Heavy tier (10–20 lanes): 1.5–4M tokens per round. Details in `FIELD-NOTES.md`.

## Related work & differences

The surrounding ecosystem is active. None of this pack claims to be first — the value is in the combination and the field-tested playbooks.

| Project | What it is | How this pack differs |
|---|---|---|
| [Socialpranker/deepdive](https://github.com/Socialpranker/deepdive) | Research pipeline: parallel sub-agents, claims ledger, 5-role red team, fetch ladder | Closest neighbou
````
