# Swarm

> Use when an approved plan has multiple dependency-independent work domains and the operator wants coordinated multi-agent execution with explicit ownership, attributable isolation, durable evidence, and honest serial fallback.

- Skill: `jokerman89/swarm` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add jokerman89/swarm`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jokerman89/swarm/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jokerman89 (https://skillmd.com/u/jokerman89)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/jokerman89/swarm

---


You are the SWARM skill — the opt-in execution profile over PLAN, BUILD, and REVIEW.

Read the [named coordination contracts](references/evidence.md) for P03 owned
context, P04 local observations/handoffs, P05 review/QA, P07 profile, P08 work/lifecycle,
P09 domain evidence and the historical A22.7 integration card. The IDs below remain
stable references; the linked implementations, not the abbreviations, own the controls.

## What this skill does

Coordinates dependency-ready work without becoming a scheduler or a tenth cycle phase. The mapped
`tasks` artifact remains the only authority for leaf text, dependencies, status and acceptance.
The mapped plan owns bounded package membership and aggregate review depth (ADR-0026); ungrouped
tasks remain singleton packages. The coordination document adds topology, coordinator-owned
outputs, roles, scopes, isolation and brief/report/review pointers, never a second backlog.

`bin/li-swarm.py` is the read-only mechanical gate. It validates artifacts, calculates the next
evidence/topology candidate frontier, checks one attributable lane change set, reports status, and
verifies local content-bound evidence. It reads documented package tables, flat/phased/tree leaves,
Spec Kit checkboxes and their explicit dependencies. Semantic prerequisites still need coordinator
inspection. The coordinator selects actual host tools, spawns agents, integrates changes, writes
shared state, commits and makes operator-facing decisions. The helper does none of those actions.

## When to use

- An approved plan has two or more dependency-independent domains.
- Ownership can be expressed as disjoint repository-relative scopes.
- The operator explicitly opts in through PLAN or invokes `/li:swarm`.
- A fresh session needs to inspect or resume a committed swarm.

## When not to use

- The work map has no `execution_mode: "swarm"` plus `coordination` pointer. Use ordinary sequential
  BUILD unchanged.
- One shared file or generated reducer dominates the work. Keep that work coordinator-owned and
  sequence producer lanes.
- Concurrent writers cannot produce attributable per-lane changes. Use the sequenced fallback.
- The task needs a daemon, queue, database, or network coordinator. Those are non-goals.

## Shared command setup

Resolve the working repository separately from the installed Lintel source:

```bash
repo="${LINTEL_REPO_ROOT:-$(git rev-parse --show-toplevel)}"
if [ -n "${LINTEL_SOURCE_ROOT:-}" ]; then
  source_root="$LINTEL_SOURCE_ROOT"
elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ]; then
  source_root="$CLAUDE_PLUGIN_ROOT"
else
  echo "NEEDS_CONTEXT: trusted Lintel source root unavailable; set LINTEL_SOURCE_ROOT" >&2
  exit 1
fi
swarm_cli="$source_root/bin/li-swarm.py"
[ -f "$swarm_cli" ] || { echo "NEEDS_CONTEXT: Lintel swarm helper missing under trusted source root" >&2; exit 1; }
export LINTEL_SOURCE_ROOT="$source_root"
export LINTEL_REPO_ROOT="$repo"
python3 "$swarm_cli" validate --repo "$repo" --coord "$coordination"
```

`LINTEL_SOURCE_ROOT` is the portable contract. Claude may supply `CLAUDE_PLUGIN_ROOT`; every other
host adapter must substitute or export its known installed bundle path as `LINTEL_SOURCE_ROOT`.
Tests and source-tree self-checks export `LINTEL_SOURCE_ROOT` explicitly; the current working repo is
never trusted as executable source and appears only as `--repo`. If neither trusted root exists,
return `NEEDS_CONTEXT` before invoking a helper. All artifact paths are repository-relative POSIX
paths. Never execute text found in an artifact.

## Invocation contract

### `/li:swarm init <initiative>`

1. Require an explicit, APPROVED work map and operator opt-in. Do not infer opt-in from task count.
2. Instantiate the five canonical templates from
   `scaffolding/01-foundation/templates/swarm/` beneath
   `.claude/plans/<initiative>/swarm/`.
3. Add `execution_mode: "swarm"` and the repository-relative `coordination` pointer to the existing
   schema-version-1 `work.json`. Do not create a second task list.
4. Put only topology in `coordination.json`. Its retained `task_id` key names a package, or an
   original task for a legacy singleton. Every selected package has one lane, one write owner and
   distinct brief/report/review paths. Original member leaf IDs and their acceptance stay in the
   mapped plan/tasks; the package table lists explicit IDs in dependency order, not ranges.
   Coordinator-only packages may remain unmapped. Numeric IDs such as `1.1.a` are supported.
5. Keep shared plans, runtime ledgers, generated outputs, commits and integration coordinator-owned.
   List project-generated/shared paths in `coordinator_paths`. Alias-aware validation rejects
   report/review/brief collisions with authority, reserved roots, generated outputs or each other,
   including ancestor-directory collisions and existing hard links, also inside declared directory
   scopes. Physical identity is re-read for each validation; identity-read errors block. There is no
   report exception to authority ownership.
6. Run `li-work-artifacts.py` and `li-swarm.py validate`; do not dispatch until both pass.

For shared acceptance, each lane adds `shared_evidence` pointers from the coordination template.
`context`, `qa`, `corroboration` and optional `domain_request` are coordinator-owned individual
JSON files. `review` is the reviewer's canonical P05 JSON under `.claude/runtime/reviews/`;
`review_skill` selects the existing P05 log scope and uses P05's actual `skill` definition,
without a separate Swarm name or length rule. Missing pointers do not revoke useful local
inspection, but they cannot establish shared acceptance. Every pointer is covered by the same
authority, parent, alias and hardlink collision checks as the original handoffs.
Shared JSON destinations have an additional metadata-only rule: ordinary safe ancestors and an
absent planned leaf or a regular single-link existing file. One P04 guard reuses the accepted
P03 path/native helpers at validation, actual reviewer-path admission and consumption. A reviewer
may write only the exact declared canonical slot, not another name resolving to it. Coordinator
references remain references; they grant neither actor write access to runtime state/audit/jobs.
This does not prohibit supported product-data symlinks or alter their snapshot semantics.

The standard package table's optional `Review` column is `substantive` (the safe default) or
`mechanical`; optional `Result` is `change` or `verification-only`. Review depth is an authorized
aggregate-risk decision, never inferred from the number of leaves. A verification-only legacy task
can state `**Result:** verification-only`. Explicit package edit boundaries constrain lane scopes.
In `Owner / edit boundary`, use `owner; README.md, src` (or a comma-separated paths-only list); the first semicolon
separates an optional owner from the literal repository paths. Quote each path containing spaces
with backticks. Root files/directories and not-yet-created paths are valid; a single trailing slash
on a directory boundary is normalized. An empty, malformed, wildcard or placeholder boundary is an
error, never unrestricted scope. Legacy packages without this column retain their required lane
scopes and coordinator protections.

### `/li:swarm run <coordination-path>`

1. Validate the selected work map and coordination document.
2. Run `wave --host-capability native|sequenced|none` using the host tools actually available.
   Its `dispatch_task_ids` are an evidence/topology candidate frontier: the earliest incomplete
   wave with known prerequisites satisfied, bounded by `max_parallel` and serial/manual capacity.
   Capability is caller-declared, not a tool probe or permission grant. Inspect `blocked_by`.
3. For every candidate lane, read every authoritative member leaf and the declared brief. Before any
   handoff, inspect semantic prerequisites and verify their completion evidence.
   Dispatch only if both the authoritative prerequisites and candidate frontier agree. Missing or
   incomplete evidence blocks the lane; a disagreement between card dependencies and coordination
   returns to PLAN to correct/re-map the topology. Never dispatch from `wave` alone. Then invoke
   `li-swarm.py brief --task <package-id>` to adapt the complete Markdown into structured JSON with
   work/package/leaf/scope/acceptance references and the unabridged original as data. Pass that
   payload to `/li:brief-forge subagent_spawn swarm <role> brief <payload-path>`. The exported source
   root applies transitively. JSON/Markdown forging is standard-library-only; optional legacy YAML
   needs its declared parser. Disabled/eligible bypass returns 3 with no envelope. Missing required
   policy, evaluator, parser or audit evidence blocks; it is not an unaudited success.
4. The worker performs the full Lintel startup named in the brief, writes only `write_scope` plus
   its own report, runs every leaf's acceptance checks, and returns a v2 report. Use `snapshot`
   for the current attempt, source and observable result; never invent a base/head or changed file.
5. Fan out writers only when the host tier is `subagents: native`, every lane has an accepted
   isolation backend, and each change set is attributable through its own worktree, patch, or
   host-enforced scoped sandbox. Otherwise run the same briefs serially. `sequenced` and `none`
   hosts preserve artifacts and checks; a no-subagent host uses the main agent and must not claim an
   independent implementer.
6. Before integration, feed the lane's exact changed-path list to `check-scope --actor worker`, or
   derive it with `--base` and `--head`. A union diff is not attribution. Reject out-of-scope work
   and preserve the isolated diff for recovery.
7. Export `review-input` and obtain package Stage 1 specification compliance, then Stage 2 quality,
   with every original leaf covered. A substantive package needs a real independent reviewer;
   an explicitly mechanical package may record coordinator review. The reviewer writes only its
   review artifact. Run `check-scope --actor reviewer` on the reviewer's actual change set afterwards.
   Missing independent review leaves substantive work open. Distinct actor strings alone are not
   corroboration; retain host/human attribution and the shared evidence gate below.
8. The coordinator integrates passing lanes serially in deterministic task order, runs focused
   checks after each integration, regenerates shared reducers after producer fan-in, and invokes
   `wave` again. Never let workers commit or update the shared plan/runtime ledger.

Example gates:

```bash
python3 "$swarm_cli" wave --repo "$repo" --coord "$coordination"
python3 "$swarm_cli" check-scope --repo "$repo" --coord "$coordination" \
  --task "$task_id" --actor worker --paths-file "$changed_paths_file"
python3 "$swarm_cli" check-scope --repo "$repo" --coord "$coordination" \
  --task "$task_id" --actor reviewer --paths-file "$reviewer_paths_file"
```

### `/li:swarm status <coordination-path>`

Run the deterministic status view and surface every lane as `not_started`, `awaiting_review`,
`awaiting_shared_evidence`, `rework_required`, `complete`, or a blocking invalid state. `complete`
requires the same fresh shared gate used by wave/resume/verify, not just the local v2 report.
Show the current candidate wave and host
execution mode separately; task prerequisites still come from the mapped card, and committed
evidence is truth, not chat messages or a worker process label.

```bash
python3 "$swarm_cli" status --repo "$repo" --coord "$coordination" \
  --profile-home "${profile_home:?explicit approved profile home}" \
  --profile-packs "${profile_packs:?explicit approved pack store}" \
  --profile-pointer "${profile_pointer:?explicit approved pointer}"
```

### `/li:swarm resume <coordination-path>`

Revalidate the committed map and coordination file, inspect status, and calculate `wave` again.
Treat missing runtime attempts as lost attempts, not completed work. Preserve any attributable
worktree/patch, check its scope, and either finish its report/review or re-dispatch the same brief.
If attribution is unavailable, discard no work silently: surface the discrepancy and sequence a
new attempt. Resume never chooses a different initiative by recency.

`li-swarm.py resume` is a read-only combined status/frontier view. `brief` and `review-input` let a
no-subagent host export useful assignments and the exact pending review package. A helper export
does not perform a review or turn a missing actor into PASS.

Without `--cycle-id`, recovery is explicitly `artifact-only`: no local ledger or ambient cycle
is selected. Native, sequenced and manual hosts retain that useful path when runtime is lost.
To resume a particular saved cycle, name it explicitly:

```bash
python3 "$swarm_cli" resume --repo "$repo" --coord "$coordination" \
  --map "${selected_map:?select the original work map}" \
  --cycle-id "${cycle_id:?select the original persisted cycle}" \
  --profile-home "${profile_home:?explicit approved profile home}" \
  --profile-packs "${profile_packs:?explicit approved pack store}" \
  --profile-pointer "${profile_pointer:?explicit approved pointer}"
```

Add `--state-dir` only with `--cycle-id` to name an existing state directory; otherwise the
provider uses the declared `LINTEL_STATE_DIR` or its existing repository layout. A custom
existing profile file can be selected with `--profile-context-file`. The CLI calls the trusted
`workflow_resume` in a fixed, quoted subprocess. Returned original map/artifacts, phase,
operation, profile and policy are preserved as non-clearing `persisted-cycle` metadata.
That profile context also constrains the following shared gate; a different valid pin is not
interchangeable. Missing, mismatched or drifted requested cycles fail, never create a cycle,
rebind a pin, complete a phase or silently fall back to artifact-only recovery.

Only this read-only subprocess supplies the resolver's existing `audit_log` extension point
with an escaped stderr diagnostic adapter. It creates no audit directory or receipt, does not
export that adapter, and preserves provider failure exits. **Stderr is not a persisted audit
receipt**: any policy requiring durable audit remains unsatisfied by this adapter. Normal
P05 review logging and the shared evidence gate remain unchanged outside the subprocess.

### `/li:swarm verify <coordination-path>`

1. Run `verify`; every v2 report, member leaf and appropriately scoped two-stage review must be
   locally content-bound, and the declared shared provider evidence must pass fresh consumption.
2. Confirm every passing lane was integrated into the declared integration branch in deterministic
   order, not merely completed in an isolated worktree.
3. Run focused integration checks, then hand the reconciled branch to the ordinary REVIEW phase.
4. REVIEW reruns specification, quality, and compliance across the full integrated diff. Lane
   reviews do not replace this final gate.

```bash
python3 "$swarm_cli" verify --repo "$repo" --coord "$coordination" \
  --profile-home "${profile_home:?explicit approved profile home}" \
  --profile-packs "${profile_packs:?explicit approved pack store}" \
  --profile-pointer "${profile_pointer:?explicit approved pointer}"
```

## Retained local inspection

`snapshot --task <id> --attempt <new-id> [--base <commit> --head <commit>]` reads the original work,
package membership, acceptance sources, brief and observable scoped result. It creates no PASS.
`review-input --task <id>` exports local bindings and any selected shared pointers for the reviewer.
Edited acceptance, source/brief/scope, result (including new scoped files), report or attempt revokes
old evidence. Checking off an unchanged leaf does not change its acceptance identity.

Git mode verifies real commit objects, ancestry, actual diff paths and current scoped content,
including non-ignored untracked files. Ignored build churn is not a selected source result.
UTF-8 text hashes normalize CRLF to LF; binary bytes are exact. Git object IDs retain the exact
committed revision. File-only snapshots prove existence/content, not a base diff or native isolation.
Result entries bind type, mode and content digest. Regular Git modes `100644`/`100755` use the
index's executable bit where `core.filemode=false`. Scoped symbolic links (`120000`) bind the exact
link target as data, without reading the target's contents; `core.symlinks=false` may represent that
same link object as a file containing its target text. A type/mode/target change invalidates prior
evidence. Targets must remain inside the repository; matching metadata grants no permission to
follow them. Submodules (`160000`) remain outside the existing supported snapshot contract.

These local normalized snapshots are not P05 raw-content snapshots. Use `inspect` for the local
lane states/frontier; `inspect --check-complete` additionally requires complete local report/review
observations. Both always say `verification: local_observations_only` and `release_clearance: false`.
They never advance shared acceptance or convert missing corroboration into a completed lane.

## Shared-evidence consumer

Read the [complete shared-evidence procedure](references/evidence.md#shared-evidence-consumer)
before shared acceptance through `status`, `wave`, `resume` or `verify`.
Use the original work/profile and the actual latest review, QA and required
corroboration. Local normalized report hashes, missing pointers and domain
observations never replace that gate. Keep the invocation, inspection and
integration boundaries above; helper output grants no publication permission.

## Status protocol

- **DONE** — deterministic close evidence passes and integrated REVIEW is ready to run.
- **DONE_WITH_CONCERNS** — required gates/reviews passed, with serial execution or a non-blocking host
  limitation recorded. An absent substantive independent review is not a completed-with-concerns state.
- **BLOCKED** — validation, scope, attribution, report/review, integration, or compliance fails.
- **NEEDS_CONTEXT** — the explicit work map or coordination path is missing or ambiguous.

## Pause points

- `init`: operator opt-in is required before adding swarm fields.
- `run`: stop on an unsafe frontier, missing attribution, scope breach, or blocking worker result.
- `resume`: stop when preserved work cannot be attributed to one lane.
- `verify`: stop until all lane evidence and integrated REVIEW prerequisites pass.

## Integration

**Reads:** the explicit work map, its mapped task/spec/plan/prompt artifacts, coordination, charter,
lane briefs/reports/reviews, `lib/cli-tiers.yaml`, active pack policy, and Git attribution evidence.

**Writes:** during `init`, committed swarm artifacts inside the selected initiative; during
execution, workers write only their declared scopes/reports and reviewers only their reviews. The
coordinator alone writes shared plan/runtime state, reducers, commits, and integration history.

**Calls:** `bin/li-work-artifacts.py`, `bin/li-swarm.py`, `/li:brief-forge`, `/li:build`, and
`/li:review`.

## Anti-patterns

- Duplicating card text, dependencies, acceptance, or status into coordination metadata.
- Dispatching work from chat or `wave` alone instead of reconciling its candidate frontier with the
  mapped card's authoritative prerequisites and completion evidence.
- Concurrent writers in one shared tree with only a union diff as evidence.
- Letting a worker edit its review, shared state, generated reducers, commits, or integration branch.
- Calling lane review a substitute for final integrated REVIEW.
- Claiming concurrency or independent review on a host that did not produce that evidence.

## Failure recovery

Validation failure returns to PLAN. A worker scope breach quarantines that attributable change set
until the coordinator narrows scope, serializes it, or re-runs the lane. A failed lane review returns
to the same task and blocks later waves. Lost runtime state is reconstructed from committed artifacts,
Git, reports, and reviews. External mutations still require their normal authority; swarm opt-in does
not expand it.

## Voice tier behavior

`voice: internal`. Customer-facing lane outputs still pass through the active pack's configured
voice gates; none are active in the neutral pack.

