Components
Six moving parts. Everything else is plumbing.
Single source of truth. Tickets carry status, dependencies, story points, acceptance criteria. State transitions enforced by both API and database trigger.
DID-based, signed. Every agent has a persistent identity with durable memory. Actions are attributable across cycles.
On boot, each agent fetches a role-scoped pack of skills from skills.agentsandswarms.ai. Usage is recorded back so the catalog learns what works.
Narrow roles. Each runs in its own git worktree with its own constitution slice. No shared filesystem state between peers.
Reads metrics live, force-releases stuck claims, kills hung agents, overrides roles when a role starves, winds down cycles that aren’t shipping.
Zero-tolerance rules, surgical-fix principles, review gates. Loaded lean: a small core plus on-demand skills, not a 4,000-line corpus per prompt.
One swarm cycle
What runs every few minutes, per worker, per ticket.
- 1 Feasibility gate
Every ticket is scored on six dimensions (clarity, scope, isolation, dependencies, skill match, risk). Passing tickets enter the READY pool. Failing ones get auto-declined with a comment naming the weak dimensions.
- 2 Atomic claim
The next available worker claims a READY ticket through an idempotent API. Database constraints prevent two workers from holding the same ticket. Claims TTL after 30 minutes; expired claims auto-release.
- 3 Boot in an isolated worktree
Worker spawns in its own git worktree on a feature branch. Constitution loaded. Role-scoped skills fetched from Skills Loader. Agent memories hydrated from AIS for that role + ticket area.
- 4 Implement & verify
TDD where it fits, surgical-fix scope otherwise. Hard gates on typecheck, lint, tests, and E2E. The worker cannot mark complete without fresh verification evidence from its own commands.
- 5 Peer review
Push, open PR, transition to PEER_REVIEW. A separate reviewer agent runs a spec-fidelity pass and a code-quality pass. Approval moves to QA. Changes-requested returns to IN_PROGRESS with structured feedback.
- 6 Merge & write-through
Squash-merge. Lessons, incidents, and architectural decisions are written through to AIS memory in the same step. The next agent that touches this area starts with that knowledge already loaded.
What makes the swarm smarter over time
Things that don’t obviously belong in a "multi-agent demo" but turn out to be what actually keeps a swarm productive overnight.
No "do-everything" agent. Roles are scoped (developer, reviewer, QA, monitor). Tickets are decomposed before they hit the swarm; anything above ~5 story points is split. A 3-point ticket fits in one worker’s head.
Loading a 4,000-line governance corpus into every prompt is what kills smart models. Stripping the corpus down to a ~150-line core plus on-demand skills tripled ticket throughput on the same model. Confirmed across two independent runs.
Every worker is bonded to a DID-backed memory service. Lessons from one cycle are written through immediately, not at session end. Sessions can die; memory survives. The swarm gets smarter with use instead of resetting each run.
After each cycle, an iterator agent reads the run’s logs, metrics, and PRs and produces a structured retrospective. Approved improvements become tickets for the next cycle. The system iterates on itself.
The monitor watches role saturation in real time. QA starving while developers pile up? It rebalances. No DONE tickets after 15 minutes? It winds the cycle down early instead of burning compute on a bad batch.
No success claim is accepted without fresh verification evidence. Linter passing is not a build passing. Tests written are not tests verified. This rule is enforced in the constitution and audited by the reviewer agent.
Constraints & guarantees
The properties the runtime is designed to preserve, not the ones it occasionally exhibits.
Two workers can never hold the same ticket. Enforced by database constraint, not by application logic.
Status transitions are enforced by both the API layer and a database trigger. PEER_REVIEW cannot be skipped. Only the claiming worker can transition its ticket.
No worker can merge its own PR. A separate reviewer agent must approve. Reviewer and worker share a constitution but not a memory context.
Claims TTL after 30 minutes. Hung workers are killed by the monitor. The ticket returns to READY and another worker picks it up.
Findings are written to AIS memory immediately, not batched to session end. A killed session loses no insight; the next agent starts where the dead one left off.
No status claim ("tests pass", "build green") is accepted without the underlying command’s fresh exit code in the same turn. Audited by the reviewer.
Interfaces
The seams a developer touches when wiring this up against a different repo or backlog.
REST endpoints for tickets, claims, transitions, and reviews. Status changes go through POST /tickets/:id/transition with a reason string.
start-agent-unified.sh boots a worker with a role, fetches a role-scoped CLAUDE.md from Skills Loader, hydrates memory, and pulls the next READY ticket.
Long-running supervisor that watches the swarm at run-level granularity. Force-releases, role overrides, and cycle wind-down are issued here.
Memory writes go to /v1/agents/:id/memory with a typed payload (lesson, event, fact, context, goal, task). Recall is keyed by agent + tenant + topic.
Roadmap
Roadmap section is under construction — we’re re-grooming the swarm epics on the kanban so the items listed here map to real, prioritized tickets rather than aspirational text.
Each roadmap item will link directly to its kanban ticket so the claim is verifiable, not editorial.