f8b030b7ca
- Convoy: Persistent tracking unit for batched work across rigs - Swarm: Ephemeral workers on a convoy (no separate tracking) Changes: - docs/convoy.md: New comprehensive convoy documentation - docs/swarm.md: Updated to explain ephemeral nature - docs/reference.md: Replace swarm section with convoy commands - internal/cmd/convoy.go: Clarify help text - internal/cmd/swarm.go: Mark as deprecated 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
75 lines
2.4 KiB
Markdown
75 lines
2.4 KiB
Markdown
# Swarm (Ephemeral Worker View)
|
|
|
|
> **Note**: "Swarm" is an ephemeral concept, not a persistent entity.
|
|
> For tracking work, see [Convoys](convoy.md).
|
|
|
|
## What is a Swarm?
|
|
|
|
A **swarm** is simply "the workers currently assigned to a convoy's issues."
|
|
It has no separate ID and no persistent state - it's just a view of active workers.
|
|
|
|
| Concept | Persistent? | ID | Description |
|
|
|---------|-------------|-----|-------------|
|
|
| **Convoy** | Yes | hq-* | The tracking unit. What you create and track. |
|
|
| **Swarm** | No | None | The workers. Ephemeral view of who's working. |
|
|
|
|
## The Relationship
|
|
|
|
```
|
|
Convoy hq-abc ─────────tracks───────────► Issues
|
|
│
|
|
│ assigned to
|
|
▼
|
|
Polecats
|
|
│
|
|
────────┴────────
|
|
"the swarm"
|
|
(ephemeral)
|
|
```
|
|
|
|
When you say "kick off a swarm," you're really:
|
|
1. Creating a convoy (persistent tracking)
|
|
2. Assigning polecats to the convoy's issues
|
|
3. The swarm = those polecats while they work
|
|
|
|
When the work completes, the convoy lands and the swarm dissolves.
|
|
|
|
## Viewing the Swarm
|
|
|
|
The swarm appears in convoy status:
|
|
|
|
```bash
|
|
gt convoy status hq-abc
|
|
```
|
|
|
|
```
|
|
Convoy: hq-abc (Deploy v2.0)
|
|
════════════════════════════
|
|
|
|
Progress: 2/3 complete
|
|
|
|
Issues
|
|
✓ gt-xyz: Update API closed
|
|
→ bd-ghi: Update docs in_progress @beads/amber
|
|
○ gt-jkl: Final review open
|
|
|
|
Workers (the swarm) ← this is the swarm
|
|
beads/amber bd-ghi running 12m
|
|
```
|
|
|
|
## Historical Note
|
|
|
|
Earlier Gas Town development used "swarm" as if it were a persistent entity
|
|
with its own lifecycle. The `gt swarm` commands were built on this model.
|
|
|
|
The correct model is:
|
|
- **Convoy** = the persistent tracking unit (what `gt swarm` was trying to be)
|
|
- **Swarm** = ephemeral workers (no separate tracking needed)
|
|
|
|
The `gt swarm` command is being deprecated in favor of `gt convoy`.
|
|
|
|
## See Also
|
|
|
|
- [Convoys](convoy.md) - The persistent tracking unit
|
|
- [Propulsion Principle](propulsion-principle.md) - Worker execution model
|