⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

dev-delivery

ccai40359-wq@ccai40359-wq⭐ 5 stars· last commit 1mo ago· 0 open issues

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.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐ 5 on GitHubGitHub ↗

New / niche

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

seanswarm

seanswarm — multi-agent workflow pack for coding agents

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.

中文说明


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:

ScenarioPiecePattern
Web researchskills/web-research-fanoutfan-out lanes → claims table → adversarial lane → cross-family arbitration → anti-scrape ladder (L0–L4)
Document readingskills/dual-readtwo independent channels read the same document, then cross-compare (match / addition / conflict)
Dev deliveryskills/dev-deliveryQA-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 acceptanceagents/visual-judge.md + hooks/ui-screenshot-gate.mjsrender → screenshot → per-page verdict → fix → re-render; a mechanical hook bounces "done" without screenshot evidence
Evidence enforcementtools/gates/ + tools/ledger/ + REPORT-CONTRACT.mdmechanical, 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

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)

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

CommandGateFails when
node tools/gates/claims-lint.mjs <lane-output.md>research claims tablea 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 boundariesa 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|statusdispatch 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.

ProjectWhat it isHow this pack differs
Socialpranker/deepdiveResearch pipeline: parallel sub-agents, claims ledger, 5-role red team, fetch ladderClosest neighbou

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/dev-delivery/SKILL.md7.9 KBupstream ↗
    ---
    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
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/ccai40359-wq-multiagents-workflow-skills-dev-delivery.md

// REPO STATS

5 stars
0 open issues
Last commit: 1mo ago