Swarm
Run two or more coding agents on the same repo in parallel without one stream’s regen or commits overwriting the other’s owned work.
Overview
swarm is an agent skill most often used in Build (also Ship, Operate) that defines an eight-field coordination contract parallel agent streams must write before landing commits on a shared repo.
Install
npx skills add https://github.com/boshu2/agentops --skill swarmWhat is this skill?
- Eight required coordination fields: stream name, branch, base SHA, owned paths, forbidden paths, shared generated files,
- Mandates a written contract artifact (Agent Mail, .agents/coordination/*.md, or NTM pane)—not chat memory
- Explicit ownership of shared generated files such as registry.json and mkdocs nav so only one stream regenerates last
- Forbidden paths prevent sibling streams from touching each other’s Go/cmd trees or loop tooling
- Closeout ties PR merge, bead closure, and sibling consumption of delivered artifacts
- Eight required coordination contract fields before any commit
- Shared generated files must declare which stream regenerates last
Adoption & trust: 911 installs on skills.sh; 384 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You run multiple coding agents on one repo and they keep overwriting shared generated artifacts because nobody wrote down who owns which paths and who regenerates last.
Who is it for?
Indie builders using multi-pane or multi-session agent workflows (Agent Mail, beads, feat branches) on monorepos with generated registry or docs.
Skip if: Single-threaded solo edits with one agent and no parallel branches, or repos with no generated shared artifacts.
When should I use this skill?
Two or more agent streams work in parallel against the same repo and each stream must state its coordination contract before landing any commit.
What do I get? / Deliverables
Each parallel stream publishes a readable coordination contract so owned paths stay isolated, shared regens have a single closer, and siblings hand off when tests and PR conditions are met.
- Written coordination artifact with eight declared fields
- Documented handoff triggers and closeout conditions for sibling streams
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Parallel agent streams most often start when you are actively building or extending an agent-enabled codebase, so Build is the canonical shelf. agent-tooling fits because the contract governs how multiple agent streams partition paths, generated artifacts, and handoffs—not a single feature slice.
Where it fits
Split doctor and wireup beads across two feat branches with forbidden overlap on loop*.go versus doctor*.go.
Pin base SHA and closeout conditions so each stream knows when to ping the sibling after tests/doctor/* is green.
Declare which stream runs final mkdocs nav and registry.json regen so the PR diff does not flip-flop.
Resume a long-running agent maintenance stream by reading .agents/coordination/*.md instead of lost chat history.
How it compares
Use instead of hoping chat context will keep parallel Codex or Claude streams from stepping on each other’s files.
Common Questions / FAQ
Who is swarm for?
Builders orchestrating two or more agent streams on the same codebase who need explicit path ownership and handoff rules before merging.
When should I use swarm?
Use it in Build when splitting beads across parallel branches; in Ship when multiple streams touch CLI docs and registry regen before merge; in Operate when long-running agent maintenance streams share generated contracts.
Is swarm safe to install?
It is process documentation only—review the Security Audits panel on this page; the skill does not by itself execute shell or network actions.
SKILL.md
READMESKILL.md - Swarm
# Agent-Genie Coordination Contract When two or more agent streams work in parallel against the same repo, **each stream MUST state its coordination contract before landing any commit**. The contract is not chat memory — it's an artifact each stream writes and checks. Without it, parallel streams collide on generated artifacts (registry.json, mkdocs nav, CLI docs, embedded copies) and one stream's "final regen" silently overwrites the other's work. ## The Contract — Eight Required Fields Each parallel agent stream declares, before claiming any work: | Field | Example | |---|---| | **Stream name** | `doctor`, `rpi`, `wireup` | | **Branch name** | `feat/<type>/<bead>-<slug>` | | **Base SHA** | `git rev-parse origin/main` at stream start | | **Owned paths** | `cli/cmd/ao/doctor*.go`, `cli/internal/doctor/**` | | **Forbidden paths** | `cli/cmd/ao/loop*.go` (owned by sibling stream) | | **Shared generated files** | `registry.json`, `docs/contracts/context-map.md` — declare which stream regenerates last | | **Handoff triggers** | "ping `<sibling>` when `tests/doctor/*` green" | | **Closeout conditions** | "PR merged + bead closed + `<sibling>` consumes my artifact" | Write these to a coordination file the sibling stream can read — Agent Mail (`mcp__mcp-agent-mail__send_message`), a `.agents/coordination/<topic>.md`, or pinned in a shared NTM pane. **Not in chat memory.** Chat memory doesn't survive the handoff. ## Why This Matters Generated artifacts (registry.json, mkdocs nav, CLI docs, embedded hook copies) are produced by scripts that read the *whole* state of the repo. If two streams both run the regenerator at end-of-stream, the later run overwrites the earlier — silently, with a green diff. The "shared generated files" field is the load-bearing one: it names which stream is allowed to regen last, and the other stream must commit its work *before* the regen and skip the regen entirely. ## Evidence (anchored) > "Parallel agent streams work reliably when each agent states branch > name, base SHA, owned paths, forbidden paths, shared generated files, > handoff triggers, and closeout conditions before landing. … This > prevents collisions on generated artifacts and lets one stream > unblock another without relying on ad hoc chat memory." — `.agents/learnings/2026-05-16-agent-genie-coordination-contract.md` (post-mortem for soc-z3qo.1 / PR #285) The empirical anchor: PR #285. The doctor stream owned doctor/canary drift; the RPI stream owned execution-packet files plus final `registry.json` regeneration. Each stream's contract was explicit about lanes. The streams committed in series; the registry regen happened exactly once at the end of the RPI stream. No collisions. ## How To Apply ### Before claiming work (each stream) 1. **Read the bead** for "owned files" / acceptance criteria. 2. **Write your contract** to one of: - Agent Mail topic (`macro_prepare_thread` then `send_message`) - `.agents/coordination/<topic>.md` (committed; visible to all streams via the file system) - NTM pane title or pinned message 3. **Confirm receipt** with sibling streams. Don't proceed until they have read and replied. ### Sample contract block ```markdown ## Stream: doctor (soc-z3qo.1) - Branch: feat/doctor-soc-z3qo.1-rebuild - Base SHA: abc1234 - Owned: cli/cmd/ao/doctor*.go, cli/internal/doctor/**, tests/doctor/** - Forbidden: cli/cmd/ao/rpi*.go (rpi stream), .agents/rpi/** (rpi stream) - Shared (I do NOT regen): registry.json, cli/docs/COMMANDS.md - Handoff: ping #rpi-stream when tests/doctor/* green - Closeout: PR merged + bead closed + rpi stream consumes my Healable trait ``` ### During work - **Stay in your lane.** If you discover scope outside your owned paths, write a scope-escape note (see [scope-escape-template.md](scope-escape-template.md)). Do not edit. - **Don't run shared-file regenerators** unless your contract names you as the regen owner. Comm