UNRELEASED DEVELOPMENT SNAPSHOT · READ-ONLY EXCERPT
docs/concepts/swarming-work.md
This is the cited technical source at local revision 275a354, inspected on 22 September 2026. It differs from the public release. This reference publishes only the cited sections, not an installable release or the development branch.
Line numbers refer to the complete recorded file. Uncited lines are omitted. Full-file SHA-256: 01475060ff956167daafb594c01b8593346e1a7df7a5800d6f11d811e88ed06f.
1
# Swarming work3
Swarming is Lintel's opt-in execution profile for an approved plan whose work can be divided into4
dependency-independent ownership domains. One coordinator dispatches bounded lanes, workers return5
attributable changes and evidence, and independent reviewers check each lane before the coordinator6
integrates it. The ordinary REVIEW phase then checks the reconciled tree.8
Swarming changes how PLAN, BUILD and REVIEW execute. It does not add a cycle phase, replace the9
authoritative task list, grant new permissions, or run a background scheduler.11
## Decide whether to swarm13
Use a swarm when all of these are true:15
- The work map is approved and contains at least two domains that can become ready independently.16
- Each worker can receive a bounded card with explicit acceptance checks.17
- Writer ownership can be expressed as non-overlapping repository-relative paths.18
- Concurrent writers can produce attributable changes in separate worktrees, patches, or an19
equivalent host-enforced scoped sandbox. Otherwise, the same swarm may run sequentially.20
- One coordinator can own shared state, generated outputs, commits and integration.22
Stay with ordinary sequential BUILD when one shared file or reducer dominates, the task boundaries23
are still uncertain, or the overhead of briefs and lane reviews is larger than the work. Swarming is24
never inferred from task count; the operator opts in during PLAN or invokes `/li:swarm init` for an25
approved work map.27
## The committed contract29
A swarm adds one coordination directory beside the existing cold-executor trio:31
```text32
.claude/plans/<initiative>/33
├── work.json34
├── spec.md35
├── plan.md36
├── prompt.md37
└── swarm/38
├── coordination.json39
├── charter.md40
├── briefs/41
│ └── <card-id>.md42
├── reports/43
│ └── <card-id>.md44
└── reviews/45
└── <card-id>.md46
```48
`work.json` keeps schema version 1 and adds `execution_mode: "swarm"` plus a repository-relative49
`coordination` pointer. The mapped `tasks` artifact remains the only authority for card text,50
dependencies, status and acceptance criteria. `coordination.json` references those task IDs and51
adds execution topology only.53
| Artifact | Authority | Writer |54
|---|---|---|55
| mapped `tasks` artifact | Cards, dependencies, status and acceptance | Coordinator |56
| `work.json` | Artifact mapping and explicit swarm opt-in | Coordinator |57
| `coordination.json` | Waves, roles, write scopes, isolation and evidence pointers | Coordinator |58
| `charter.md` | Ownership, fan-out, fan-in and recovery rules | Coordinator |59
| `briefs/<card>.md` | Card-specific startup, scope, inputs and checks | Coordinator |60
| lane-owned paths | The implementation or documentation for one card | Assigned worker |61
| `reports/<card>.md` | Changed paths, checks, findings and limitations | Assigned worker |62
| `reviews/<card>.md` | Independent specification and quality verdict | Assigned reviewer |63
| shared ledgers, reducers, commits and integration | Reconciled initiative state | Coordinator only |65
A worker may write only its declared `write_scope` plus its own report. A reviewer writes only that66
lane's review. Generated catalogs, synchronized instruction blocks and other fan-in reducers stay67
coordinator-owned even when a worker edits their canonical sources.69
## Start and inspect a swarm71
1. Complete PLAN and approve the mapped cards.72
2. Invoke `/li:swarm init <initiative>` and review the generated charter, topology and briefs.73
3. Confirm that same-wave scopes do not overlap and that every concurrent writer has an accepted74
isolation backend.75
4. Validate both the work map and the coordination contract before dispatch.77
The helpers are read-only. Run them from a trusted Lintel installation, kept separate from the78
repository whose artifacts they inspect:… omitted uncited lines …
138
|---|---|---|139
| `native` | Fan out ready writers up to the operator and topology cap only when every lane has attributable isolation; otherwise sequence them. | Concurrency and independent review only when the host actually produced those records. |140
| `sequenced` | Replay the same lane briefs one at a time, preserving scopes, reports, reviews and gates. | Delegated work and review may be reported, but not concurrent writers. |141
| `none` | The main agent executes cards serially, or exports replayable briefs for manual workers. | Do not label the implementer or self-review as independent. A lane without an independent review stays unclosed. |143
Hooks are a separate capability. Lintel's Claude Code hooks do not activate on other clients, and144
swarming does not emulate them. On hosts without compatible registered hooks, agents must read the145
startup rules and state explicitly. See [multi-CLI support](../multi-cli.md) for the current adapter146
matrix.148
## Recover without guessing150
Committed artifacts and attributable changes are the recovery source; chat history and worker151
process labels are not.153
| Situation | Recovery action |154
|---|---|155
| Worker process or local runtime state disappeared | Re-run `validate` and `status`. Preserve an attributable worktree or patch, scope-check it, then finish its report/review or replay the same brief. |156
| Partial work has no lane attribution | Do not discard or integrate it silently. Quarantine the changes, report the discrepancy, and sequence a fresh attempt after the coordinator accounts for the partial work. |157
| Worker changed an unowned path | Freeze the affected ownership domains. Narrow or reassign the scope, reconcile the isolated patch, or re-run the lane; do not hide the breach in fan-in. |158
| Lane review failed | Return findings to the same card. Later dependent waves remain blocked until a distinct reviewer records passing evidence. |159
| Two passing lanes conflict during integration | Stop integration, preserve both changes, and return to PLAN if ownership was wrong. The coordinator resolves only with an explicit, reviewed reconciliation. |160
| Independent reviewer is unavailable | Record the host limitation and leave the lane open. A self-review can inform rework but cannot manufacture independent PASS evidence. |162
Independent lanes may continue while a blocked lane's ownership domain is isolated and no dependency