How it works
Durable state + role queues + verification loops — with humans in control.
How we're different
- State lives in Beads (not chat history) so restarts are safe.
- Merge queue prevents parallel work from turning into conflict soup.
- Budgets + audits keep “swarm scale” predictable.
Trust rule: AI drafts; humans decide for sensitive outcomes.
Architecture (plain English)
Beads (task state)
Small, versioned JSON work items with acceptance criteria and evidence links.
Orchestrator
Assigns beads to role queues, enforces budgets, and schedules heartbeats.
Refinery
Stages diffs, runs verification, and merges in order.
Verification harness
Tests + screenshots + lint/typecheck/CI signals. Escalates failures to the Witness.
Audit trail
Immutable timeline: who/what/when/why, plus artifacts (logs, screenshots, diffs).
Example workflow: build a feature
- Mayor collects requirements and creates Beads (scope, acceptance, risks).
- Polecats implement atomic diffs with tests; Witness reviews and requests fixes.
- Refinery stages a merge queue, resolves conflicts, and validates with the harness.
- Archivist records evidence, approvals, and post-merge rollout notes.