diff --git a/docs/convoy.md b/docs/convoy.md new file mode 100644 index 00000000..db57aecd --- /dev/null +++ b/docs/convoy.md @@ -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 ` | 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 diff --git a/docs/reference.md b/docs/reference.md index 6094e61e..50385547 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -220,18 +220,18 @@ gt sling # Assign to polecat gt sling --molecule= ``` -### Swarm Management +### Convoy Management (Work Tracking) ```bash -gt swarm create --epic --worker # Create swarm -gt swarm create --epic --worker --start # Create and start -gt swarm start # Start a created swarm -gt swarm status # Show swarm status -gt swarm list [rig] # List swarms -gt swarm dispatch # Assign next ready task to idle worker -gt swarm land # Land completed swarm to main -gt swarm cancel # 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 # 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. diff --git a/docs/swarm.md b/docs/swarm.md index a2d3bfac..a8268cc4 100644 --- a/docs/swarm.md +++ b/docs/swarm.md @@ -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/ │ │ -│ └───────────────────┬──────────────────┘ │ -└──────────────────────┼────────────────────┘ - │ - ▼ 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/` - -- 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 ` | -| "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 diff --git a/docs/understanding-gas-town.md b/docs/understanding-gas-town.md index e11f940b..180640f2 100644 --- a/docs/understanding-gas-town.md +++ b/docs/understanding-gas-town.md @@ -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 diff --git a/internal/cmd/convoy.go b/internal/cmd/convoy.go index 84e675f3..cab51285 100644 --- a/internal/cmd/convoy.go +++ b/internal/cmd/convoy.go @@ -26,26 +26,34 @@ var ( var convoyCmd = &cobra.Command{ Use: "convoy", GroupID: GroupWork, - Short: "Manage cross-rig issue tracking", - Long: `Manage convoys for tracking issues across multiple rigs. + Short: "Track batches of work across rigs", + Long: `Manage convoys - the primary unit for tracking batched work. -A convoy is a tracking unit that monitors issues across project chains. -Unlike swarms (which coordinate parallel work), convoys simply track -related issues and auto-close when all tracked issues complete. +A convoy is a persistent tracking unit that monitors related issues across +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 VS SWARM: - Swarm: Multiple polecats working on tasks from a shared base commit - Convoy: Cross-rig issue tracker, monitors progress without spawning workers +WHAT IS A CONVOY: + - Persistent tracking unit with an ID (hq-*) + - Tracks issues across rigs (frontend+backend, beads+gastown, etc.) + - Auto-closes when all tracked issues complete → notifies subscribers + - Can be reopened by adding more issues + +WHAT IS A SWARM: + - Ephemeral: "the workers currently assigned to a convoy's issues" + - No separate ID - uses the convoy ID + - Dissolves when work completes TRACKING SEMANTICS: - 'tracks' relation is non-blocking (tracked issues don't block convoy) - Cross-prefix capable (convoy in hq-* tracks issues in gt-*, bd-*) - - Reactive completion: convoy auto-closes when all tracked issues close + - Landed: all tracked issues closed → notification sent to subscribers COMMANDS: - create Create a new convoy tracking specified issues - status Show convoy progress and tracked issues - list List all convoys`, + create Create a convoy tracking specified issues + add Add issues to an existing convoy (reopens if closed) + status Show convoy progress, tracked issues, and active workers + list List convoys (the dashboard view)`, } var convoyCreateCmd = &cobra.Command{ diff --git a/internal/cmd/swarm.go b/internal/cmd/swarm.go index 1b9a6be1..67ca6f48 100644 --- a/internal/cmd/swarm.go +++ b/internal/cmd/swarm.go @@ -36,48 +36,25 @@ var ( ) var swarmCmd = &cobra.Command{ - Use: "swarm", - GroupID: GroupWork, - Short: "Manage multi-agent swarms", - Long: `Manage coordinated multi-agent work units (swarms). + Use: "swarm", + GroupID: GroupWork, + Short: "[DEPRECATED] Use 'gt convoy' instead", + Deprecated: "Use 'gt convoy' for work tracking. A 'swarm' is now just the ephemeral workers on a convoy.", + Long: `DEPRECATED: Use 'gt convoy' instead. -A swarm coordinates multiple polecats working on related tasks from a shared -base commit. Work is merged to an integration branch, then landed to main. +The term "swarm" now refers to the ephemeral set of workers on a convoy's issues, +not a persistent tracking unit. Use 'gt convoy' for creating and tracking batched work. -SWARM LIFECYCLE: - epic (tasks) - │ - ▼ - ┌────────────────────────────────────────────┐ - │ SWARM │ - │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ - │ │ Polecat │ │ Polecat │ │ Polecat │ │ - │ │ Toast │ │ Nux │ │ Capable │ │ - │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ - │ │ │ │ │ - │ ▼ ▼ ▼ │ - │ ┌──────────────────────────────────────┐ │ - │ │ integration/ │ │ - │ └───────────────────┬──────────────────┘ │ - └──────────────────────┼────────────────────┘ - │ - ▼ land - main +TERMINOLOGY: + Convoy: Persistent tracking unit (what this command was trying to be) + Swarm: Ephemeral workers on a convoy (no separate tracking needed) -STATES: - creating → Swarm being set up - active → Workers executing tasks - merging → Work being integrated - landed → Successfully merged to main - cancelled → Swarm aborted +MIGRATION: + gt swarm create → gt convoy create + gt swarm status → gt convoy status + gt swarm list → gt convoy list -COMMANDS: - create Create a new swarm from an epic - status Show swarm progress - list List swarms in a rig - land Manually land completed swarm - cancel Cancel an active swarm - dispatch Assign next ready task to a worker`, +See 'gt convoy --help' for the new workflow.`, } var swarmCreateCmd = &cobra.Command{