Files

Steve Yegge f8b030b7ca Clarify convoy vs swarm terminology in docs and code

- 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>

2025-12-30 18:55:24 -08:00

2.4 KiB

Raw Blame History

Swarm (Ephemeral Worker View)

Note

: "Swarm" is an ephemeral concept, not a persistent entity. For tracking work, see Convoys.

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:

Creating a convoy (persistent tracking)
Assigning polecats to the convoy's issues
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:

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.

2.4 KiB Raw Blame History