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.
• Cheap gates beat clever prompts. The mechanical hook exists because prose alone is not enforcement.

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.

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. 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.1.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.2: machine-checkable evals (including an adversarial-lane behaviour test); dispatch-ledger tooling; cross-round claim reconciliation.

License

MIT — see LICENSE.