johno/gastown
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Clarify convoy vs swarm terminology in docs and code

Browse Source 
- 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>
This commit is contained in:
Steve Yegge
2025-12-30 18:55:24 -08:00
parent 3f653a3e9d
commit f8b030b7ca
6 changed files with 292 additions and 266 deletions
Download Patch File Download Diff File Expand all files Collapse all files

198
docs/convoy.md Normal file
View File

@@ -0,0 +1,198 @@
# Convoys
Convoys are the primary unit for tracking batched work across rigs.
## Concept
A **convoy** is a persistent tracking unit that monitors related issues across
multiple rigs. When you kick off work - even a single issue - a convoy tracks it
so you can see when it lands and what was included.
```
Convoy (hq-abc)
│
┌────────────┼────────────┐
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ gt-xyz │ │ gt-def │ │ bd-abc │
│ gastown │ │ gastown │ │ beads │
└────┬────┘ └────┬────┘ └────┬────┘
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ nux │ │ furiosa │ │ amber │
│(polecat)│ │(polecat)│ │(polecat)│
└─────────┘ └─────────┘ └─────────┘
│
"the swarm"
(ephemeral)
```
## Convoy vs Swarm
| Concept | Persistent? | ID | Description |
|---------|-------------|-----|-------------|
| **Convoy** | Yes | hq-* | Tracking unit. What you create, track, get notified about. |
| **Swarm** | No | None | Ephemeral. "The workers currently on this convoy's issues." |
When you "kick off a swarm", you're really:
1. Creating a convoy (the tracking unit)
2. Assigning polecats to the tracked issues
3. The "swarm" is just those polecats while they're working
When issues close, the convoy lands and notifies you. The swarm dissolves.
## Convoy Lifecycle
```
OPEN ──(all issues close)──► LANDED/CLOSED
↑ │
└──(add more issues)───────────┘
(auto-reopens)
```
| State | Description |
|-------|-------------|
| `open` | Active tracking, work in progress |
| `closed` | All tracked issues closed, notification sent |
Adding issues to a closed convoy reopens it automatically.
## Commands
### Create a Convoy
```bash
# Track multiple issues across rigs
gt convoy create "Deploy v2.0" gt-abc bd-xyz --notify gastown/joe
# Track a single issue (still creates convoy for dashboard visibility)
gt convoy create "Fix auth bug" gt-auth-fix
# With default notification (from config)
gt convoy create "Feature X" gt-a gt-b gt-c
```
### Add Issues
```bash
# Add to existing convoy
gt convoy add hq-abc gt-new-issue
# Adding to closed convoy reopens it
gt convoy add hq-abc gt-followup-fix
# → Convoy hq-abc reopened
```
### Check Status
```bash
# Show issues and active workers (the swarm)
gt convoy status hq-abc
# All active convoys (the dashboard)
gt convoy status
```
Example output:
```
Convoy: hq-abc (Deploy v2.0)
════════════════════════════
Progress: 3/5 complete
Issues
✓ gt-xyz: Update API closed
✓ bd-abc: Fix validation closed
→ bd-ghi: Update docs in_progress @beads/amber
○ gt-jkl: Deploy to prod blocked by bd-ghi
Workers (the swarm)
beads/amber bd-ghi running 12m
```
### List Convoys (Dashboard)
```bash
# Active convoys - the primary attention view
gt convoy list --active
# All convoys
gt convoy list
# JSON output
gt convoy list --json
```
## Notifications
When a convoy lands (all tracked issues closed), subscribers are notified:
```bash
# Explicit subscriber
gt convoy create "Feature X" gt-abc --notify gastown/joe
# Multiple subscribers
gt convoy create "Feature X" gt-abc --notify mayor/ --notify --human
```
Notification content:
```
📦 Convoy Landed: Deploy v2.0 (hq-abc)
Issues (3):
✓ gt-xyz: Update API endpoint
✓ gt-def: Add validation
✓ bd-abc: Update docs
Workers: gastown/nux, gastown/furiosa, beads/amber
Duration: 2h 15m
```
## Auto-Convoy on Sling
When you sling a single issue without an existing convoy:
```bash
gt sling bd-xyz beads/amber
```
This auto-creates a convoy so all work appears in the dashboard:
1. Creates convoy: "Work: bd-xyz"
2. Tracks the issue
3. Assigns the polecat
Even "swarm of one" gets convoy visibility.
## Cross-Rig Tracking
Convoys live in town-level beads (hq-* prefix) and can track issues from any rig:
```bash
# Track issues from multiple rigs
gt convoy create "Full-stack feature" \
gt-frontend-abc \
gt-backend-def \
bd-docs-xyz
```
The `tracks` relation is:
- **Non-blocking**: doesn't affect issue workflow
- **Additive**: can add issues anytime
- **Cross-rig**: convoy in hq-*, issues in gt-*, bd-*, etc.
## Convoy vs Rig Status
| View | Scope | Shows |
|------|-------|-------|
| `gt convoy status [id]` | Cross-rig | Issues tracked by convoy + workers |
| `gt rig status <rig>` | Single rig | All workers in rig + their convoy membership |
Use convoys for "what's the status of this batch of work?"
Use rig status for "what's everyone in this rig working on?"
## See Also
- [Propulsion Principle](propulsion-principle.md) - Worker execution model
- [Mail Protocol](mail-protocol.md) - Notification delivery

20
docs/reference.md
View File

@@ -220,18 +220,18 @@ gt sling <bead> <rig> # Assign to polecat
gt sling <bead> <rig> --molecule=<proto>
```
### Swarm Management
### Convoy Management (Work Tracking)
```bash
gt swarm create <rig> --epic <id> --worker <name> # Create swarm
gt swarm create <rig> --epic <id> --worker <name> --start # Create and start
gt swarm start <swarm-id> # Start a created swarm
gt swarm status <swarm-id> # Show swarm status
gt swarm list [rig] # List swarms
gt swarm dispatch <epic-id> # Assign next ready task to idle worker
gt swarm land <swarm-id> # Land completed swarm to main
gt swarm cancel <swarm-id> # Cancel active swarm
gt convoy create "name" [issues...] # Create convoy tracking issues
gt convoy create "name" gt-a bd-b --notify mayor/ # With notification
gt convoy add <convoy-id> <issue-id> # Add issue (reopens if closed)
gt convoy status [convoy-id] # Show progress + workers (the swarm)
gt convoy list # Dashboard of active convoys
gt convoy list --active # Active only
```
Note: "Swarm" is ephemeral (workers on a convoy's issues). See [Convoys](convoy.md).
### Communication
```bash
gt mail inbox
@@ -334,4 +334,4 @@ bd mol bond mol-security-scan $PATROL_ID --var scope="$SCOPE"
**Nondeterministic idempotence**: Any worker can continue any molecule. Steps are atomic checkpoints in beads.
**Swarm coordination**: Swarms parallelize work across multiple polecats. Each swarm has an integration branch where completed tasks merge before landing to main. See [Swarms](swarm.md) for details.
**Convoy tracking**: Convoys track batched work across rigs. A "swarm" is ephemeral - just the workers currently on a convoy's issues. See [Convoys](convoy.md) for details.

253
docs/swarm.md
View File

@@ -1,231 +1,74 @@
# Swarms
# Swarm (Ephemeral Worker View)
Swarms coordinate multiple polecats working on related tasks from a shared base commit.
> **Note**: "Swarm" is an ephemeral concept, not a persistent entity.
> For tracking work, see [Convoys](convoy.md).
## Concept
## What is a Swarm?
A swarm is a coordinated multi-agent work unit. When you have an epic with multiple
independent tasks, a swarm lets you:
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.
1. **Parallelize** - Multiple polecats work simultaneously
2. **Isolate** - Each worker branches from the same base commit
3. **Integrate** - All work merges to an integration branch before landing
4. **Coordinate** - Task dispatch respects dependencies
| 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
```
epic (tasks)
│
▼
┌────────────────────────────────────────────┐
│ SWARM │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Polecat │ │ Polecat │ │ Polecat │ │
│ │ Toast │ │ Nux │ │ Capable │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ integration/<epic> │ │
│ └───────────────────┬──────────────────┘ │
└──────────────────────┼────────────────────┘
│
▼ land
main
Convoy hq-abc ─────────tracks───────────► Issues
│
│ assigned to
▼
Polecats
│
────────┴────────
"the swarm"
(ephemeral)
```
## Swarm Lifecycle
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
| State | Description |
|-------|-------------|
| `created` | Swarm set up, not yet started |
| `active` | Workers actively executing tasks |
| `merging` | All work done, integration in progress |
| `landed` | Successfully merged to main |
| `cancelled` | Swarm aborted |
| `failed` | Swarm failed and cannot recover |
When the work completes, the convoy lands and the swarm dissolves.
## Commands
## Viewing the Swarm
### Create a Swarm
The swarm appears in convoy status:
```bash
# Create swarm from existing epic
gt swarm create greenplace --epic gp-abc --worker Toast --worker Nux
# Create and start immediately
gt swarm create greenplace --epic gp-abc --worker Toast --start
# Specify target branch (defaults to main)
gt swarm create greenplace --epic gp-abc --worker Toast --target develop
gt convoy status hq-abc
```
The epic should already exist in beads with child tasks. The swarm will track
which tasks are ready, in-progress, and complete.
```
Convoy: hq-abc (Deploy v2.0)
════════════════════════════
### Start a Swarm
Progress: 2/3 complete
```bash
# Start a previously created swarm
gt swarm start gp-abc
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
```
This transitions the swarm from `created` to `active` and begins dispatching
tasks to workers.
## Historical Note
### Check Swarm Status
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.
```bash
# Human-readable status
gt swarm status gp-abc
The correct model is:
- **Convoy** = the persistent tracking unit (what `gt swarm` was trying to be)
- **Swarm** = ephemeral workers (no separate tracking needed)
# JSON output
gt swarm status gp-abc --json
```
Shows:
- Swarm metadata (epic, rig, target branch)
- Ready front (tasks with no blockers)
- Active tasks (in-progress with assignees)
- Blocked tasks (waiting on dependencies)
- Completed tasks
### List Swarms
```bash
# All swarms across all rigs
gt swarm list
# Swarms in specific rig
gt swarm list greenplace
# Filter by status
gt swarm list --status=active
gt swarm list greenplace --status=landed
# JSON output
gt swarm list --json
```
### Dispatch Tasks
```bash
# Auto-dispatch next ready task to idle polecat
gt swarm dispatch gp-abc
# Dispatch in specific rig
gt swarm dispatch gp-abc --rig greenplace
```
Finds the first unassigned ready task and assigns it to an available polecat.
Uses `gt sling` internally.
### Land a Swarm
```bash
# Manually land completed swarm
gt swarm land gp-abc
```
This:
1. Verifies all tasks are complete
2. Stops any running polecat sessions
3. Audits git state (checks for uncommitted/unpushed code)
4. Merges integration branch to target (main)
5. Cleans up branches
6. Closes the epic in beads
**Note**: Normally the Refinery handles landing automatically.
### Cancel a Swarm
```bash
gt swarm cancel gp-abc
```
Marks the swarm as cancelled. Does not automatically stop sessions or clean up
branches - use `gt swarm land` for full cleanup if needed.
## How It Works
### Beads Integration
Swarms are built on beads molecules:
- The epic is marked as `mol_type=swarm`
- Tasks are child issues of the epic
- Task dependencies are beads dependencies
- State is queried from beads, not cached
### Task Flow
1. **Ready front**: Tasks with no uncompleted dependencies are "ready"
2. **Dispatch**: `gt swarm dispatch` or `gt sling` assigns ready tasks
3. **Execution**: Polecat works the task, commits, signals `gt done`
4. **Merge**: Refinery merges to integration branch
5. **Next**: When dependencies clear, new tasks become ready
### Integration Branch
Each swarm has an integration branch: `swarm/<epic-id>`
- Created from the base commit when swarm starts
- Each completed task merges here
- Avoids merge conflicts from landing directly to main
- Final landing merges integration → main
### Git Safety
Before landing, the swarm manager audits each worker's git state:
| Check | Risk |
|-------|------|
| Uncommitted changes | Code loss if not in .beads/ |
| Unpushed commits | Code not in remote |
| Stashes | Forgotten work |
If code is at risk, landing blocks and notifies Mayor.
## Swarm vs Single Assignment
| Scenario | Use |
|----------|-----|
| Single task, one polecat | `gt sling` |
| Multiple independent tasks | `gt swarm create` |
| Sequential dependent tasks | Molecule (not swarm) |
| Large feature with subtasks | Swarm with dependencies |
## Example Workflow
```bash
# 1. Create epic with tasks in beads
bd create --type=epic --title="Add authentication" --id gp-auth
bd create --title="Add login form" --parent gp-auth
bd create --title="Add session management" --parent gp-auth
bd create --title="Add logout flow" --parent gp-auth
# 2. Create swarm
gt swarm create greenplace --epic gp-auth --worker Toast --worker Nux --start
# 3. Monitor progress
gt swarm status gp-auth
# 4. Dispatch more as tasks complete
gt swarm dispatch gp-auth
# 5. Land when complete
gt swarm land gp-auth
```
## Troubleshooting
| Problem | Solution |
|---------|----------|
| "No ready tasks" | Check dependencies with `bd show <epic>` |
| "No idle polecats" | Create more with `gt polecat create` |
| "Code at risk" | Workers need to commit/push before landing |
| "Swarm not found" | Epic may not be marked `mol_type=swarm` |
The `gt swarm` command is being deprecated in favor of `gt convoy`.
## See Also
- [Molecules](molecules.md) - Workflow templates
- [Convoys](convoy.md) - The persistent tracking unit
- [Propulsion Principle](propulsion-principle.md) - Worker execution model
- [Mail Protocol](mail-protocol.md) - Agent communication

2
docs/understanding-gas-town.md
View File

@@ -49,7 +49,7 @@ Both do project work, but with key differences:
**When to use Polecats**:
- Discrete, well-defined tasks
- Batch work (via swarms)
- Batch work (tracked via convoys)
- Parallelizable work
- Work that benefits from supervision