seanswarm

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:

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

Architecture

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

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.

Ideas borrowed with gratitude: diff-only review input (superpowers); fail-closed acceptance (eforge); circuit breaker + dispatch ledger + model-substitution check (ai-cross); human plan gate + minority-counsel roles (deepdive); adversarial-behaviour testing (last30days).

Status & roadmap

v0.2.0. Skills ship in English (SKILL.md) with Chinese translations alongside (SKILL.zh.md); agent role templates carry bilingual descriptions. Codex/Cursor adapters are drafts pending verification.

• v0.3: machine-checkable evals (including an adversarial-lane behaviour test); cross-round claim reconciliation on top of the dispatch ledger.

License

MIT — see LICENSE.