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>
This commit is contained in:
Steve Yegge
198
docs/convoy.md
Normal file
198
docs/convoy.md
Normal 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
|
||||||
@@ -220,18 +220,18 @@ gt sling <bead> <rig> # Assign to polecat
|
|||||||
gt sling <bead> <rig> --molecule=<proto>
|
gt sling <bead> <rig> --molecule=<proto>
|
||||||
```
|
```
|
||||||
|
|
||||||
### Swarm Management
|
### Convoy Management (Work Tracking)
|
||||||
```bash
|
```bash
|
||||||
gt swarm create <rig> --epic <id> --worker <name> # Create swarm
|
gt convoy create "name" [issues...] # Create convoy tracking issues
|
||||||
gt swarm create <rig> --epic <id> --worker <name> --start # Create and start
|
gt convoy create "name" gt-a bd-b --notify mayor/ # With notification
|
||||||
gt swarm start <swarm-id> # Start a created swarm
|
gt convoy add <convoy-id> <issue-id> # Add issue (reopens if closed)
|
||||||
gt swarm status <swarm-id> # Show swarm status
|
gt convoy status [convoy-id] # Show progress + workers (the swarm)
|
||||||
gt swarm list [rig] # List swarms
|
gt convoy list # Dashboard of active convoys
|
||||||
gt swarm dispatch <epic-id> # Assign next ready task to idle worker
|
gt convoy list --active # Active only
|
||||||
gt swarm land <swarm-id> # Land completed swarm to main
|
|
||||||
gt swarm cancel <swarm-id> # Cancel active swarm
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Note: "Swarm" is ephemeral (workers on a convoy's issues). See [Convoys](convoy.md).
|
||||||
|
|
||||||
### Communication
|
### Communication
|
||||||
```bash
|
```bash
|
||||||
gt mail inbox
|
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.
|
**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
253
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
|
A **swarm** is simply "the workers currently assigned to a convoy's issues."
|
||||||
independent tasks, a swarm lets you:
|
It has no separate ID and no persistent state - it's just a view of active workers.
|
||||||
|
|
||||||
1. **Parallelize** - Multiple polecats work simultaneously
|
| Concept | Persistent? | ID | Description |
|
||||||
2. **Isolate** - Each worker branches from the same base commit
|
|---------|-------------|-----|-------------|
|
||||||
3. **Integrate** - All work merges to an integration branch before landing
|
| **Convoy** | Yes | hq-* | The tracking unit. What you create and track. |
|
||||||
4. **Coordinate** - Task dispatch respects dependencies
|
| **Swarm** | No | None | The workers. Ephemeral view of who's working. |
|
||||||
|
|
||||||
|
## The Relationship
|
||||||
|
|
||||||
```
|
```
|
||||||
epic (tasks)
|
Convoy hq-abc ─────────tracks───────────► Issues
|
||||||
│
|
│
|
||||||
▼
|
│ assigned to
|
||||||
┌────────────────────────────────────────────┐
|
▼
|
||||||
│ SWARM │
|
Polecats
|
||||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
│
|
||||||
│ │ Polecat │ │ Polecat │ │ Polecat │ │
|
────────┴────────
|
||||||
│ │ Toast │ │ Nux │ │ Capable │ │
|
"the swarm"
|
||||||
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
|
(ephemeral)
|
||||||
│ │ │ │ │
|
|
||||||
│ ▼ ▼ ▼ │
|
|
||||||
│ ┌──────────────────────────────────────┐ │
|
|
||||||
│ │ integration/<epic> │ │
|
|
||||||
│ └───────────────────┬──────────────────┘ │
|
|
||||||
└──────────────────────┼────────────────────┘
|
|
||||||
│
|
|
||||||
▼ land
|
|
||||||
main
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## 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 |
|
When the work completes, the convoy lands and the swarm dissolves.
|
||||||
|-------|-------------|
|
|
||||||
| `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 |
|
|
||||||
|
|
||||||
## Commands
|
## Viewing the Swarm
|
||||||
|
|
||||||
### Create a Swarm
|
The swarm appears in convoy status:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Create swarm from existing epic
|
gt convoy status hq-abc
|
||||||
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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
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
|
Issues
|
||||||
# Start a previously created swarm
|
✓ gt-xyz: Update API closed
|
||||||
gt swarm start gp-abc
|
→ 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
|
## Historical Note
|
||||||
tasks to workers.
|
|
||||||
|
|
||||||
### 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
|
The correct model is:
|
||||||
# Human-readable status
|
- **Convoy** = the persistent tracking unit (what `gt swarm` was trying to be)
|
||||||
gt swarm status gp-abc
|
- **Swarm** = ephemeral workers (no separate tracking needed)
|
||||||
|
|
||||||
# JSON output
|
The `gt swarm` command is being deprecated in favor of `gt convoy`.
|
||||||
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` |
|
|
||||||
|
|
||||||
## See Also
|
## See Also
|
||||||
|
|
||||||
- [Molecules](molecules.md) - Workflow templates
|
- [Convoys](convoy.md) - The persistent tracking unit
|
||||||
- [Propulsion Principle](propulsion-principle.md) - Worker execution model
|
- [Propulsion Principle](propulsion-principle.md) - Worker execution model
|
||||||
- [Mail Protocol](mail-protocol.md) - Agent communication
|
|
||||||
|
|||||||
@@ -49,7 +49,7 @@ Both do project work, but with key differences:
|
|||||||
|
|
||||||
**When to use Polecats**:
|
**When to use Polecats**:
|
||||||
- Discrete, well-defined tasks
|
- Discrete, well-defined tasks
|
||||||
- Batch work (via swarms)
|
- Batch work (tracked via convoys)
|
||||||
- Parallelizable work
|
- Parallelizable work
|
||||||
- Work that benefits from supervision
|
- Work that benefits from supervision
|
||||||
|
|
||||||
|
|||||||
@@ -26,26 +26,34 @@ var (
|
|||||||
var convoyCmd = &cobra.Command{
|
var convoyCmd = &cobra.Command{
|
||||||
Use: "convoy",
|
Use: "convoy",
|
||||||
GroupID: GroupWork,
|
GroupID: GroupWork,
|
||||||
Short: "Manage cross-rig issue tracking",
|
Short: "Track batches of work across rigs",
|
||||||
Long: `Manage convoys for tracking issues across multiple rigs.
|
Long: `Manage convoys - the primary unit for tracking batched work.
|
||||||
|
|
||||||
A convoy is a tracking unit that monitors issues across project chains.
|
A convoy is a persistent tracking unit that monitors related issues across
|
||||||
Unlike swarms (which coordinate parallel work), convoys simply track
|
rigs. When you kick off work (even a single issue), a convoy tracks it so
|
||||||
related issues and auto-close when all tracked issues complete.
|
you can see when it lands and what was included.
|
||||||
|
|
||||||
CONVOY VS SWARM:
|
WHAT IS A CONVOY:
|
||||||
Swarm: Multiple polecats working on tasks from a shared base commit
|
- Persistent tracking unit with an ID (hq-*)
|
||||||
Convoy: Cross-rig issue tracker, monitors progress without spawning workers
|
- 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:
|
TRACKING SEMANTICS:
|
||||||
- 'tracks' relation is non-blocking (tracked issues don't block convoy)
|
- 'tracks' relation is non-blocking (tracked issues don't block convoy)
|
||||||
- Cross-prefix capable (convoy in hq-* tracks issues in gt-*, bd-*)
|
- 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:
|
COMMANDS:
|
||||||
create Create a new convoy tracking specified issues
|
create Create a convoy tracking specified issues
|
||||||
status Show convoy progress and tracked issues
|
add Add issues to an existing convoy (reopens if closed)
|
||||||
list List all convoys`,
|
status Show convoy progress, tracked issues, and active workers
|
||||||
|
list List convoys (the dashboard view)`,
|
||||||
}
|
}
|
||||||
|
|
||||||
var convoyCreateCmd = &cobra.Command{
|
var convoyCreateCmd = &cobra.Command{
|
||||||
|
|||||||
@@ -36,48 +36,25 @@ var (
|
|||||||
)
|
)
|
||||||
|
|
||||||
var swarmCmd = &cobra.Command{
|
var swarmCmd = &cobra.Command{
|
||||||
Use: "swarm",
|
Use: "swarm",
|
||||||
GroupID: GroupWork,
|
GroupID: GroupWork,
|
||||||
Short: "Manage multi-agent swarms",
|
Short: "[DEPRECATED] Use 'gt convoy' instead",
|
||||||
Long: `Manage coordinated multi-agent work units (swarms).
|
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
|
The term "swarm" now refers to the ephemeral set of workers on a convoy's issues,
|
||||||
base commit. Work is merged to an integration branch, then landed to main.
|
not a persistent tracking unit. Use 'gt convoy' for creating and tracking batched work.
|
||||||
|
|
||||||
SWARM LIFECYCLE:
|
TERMINOLOGY:
|
||||||
epic (tasks)
|
Convoy: Persistent tracking unit (what this command was trying to be)
|
||||||
│
|
Swarm: Ephemeral workers on a convoy (no separate tracking needed)
|
||||||
▼
|
|
||||||
┌────────────────────────────────────────────┐
|
|
||||||
│ SWARM │
|
|
||||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
|
||||||
│ │ Polecat │ │ Polecat │ │ Polecat │ │
|
|
||||||
│ │ Toast │ │ Nux │ │ Capable │ │
|
|
||||||
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
|
|
||||||
│ │ │ │ │
|
|
||||||
│ ▼ ▼ ▼ │
|
|
||||||
│ ┌──────────────────────────────────────┐ │
|
|
||||||
│ │ integration/<epic> │ │
|
|
||||||
│ └───────────────────┬──────────────────┘ │
|
|
||||||
└──────────────────────┼────────────────────┘
|
|
||||||
│
|
|
||||||
▼ land
|
|
||||||
main
|
|
||||||
|
|
||||||
STATES:
|
MIGRATION:
|
||||||
creating → Swarm being set up
|
gt swarm create → gt convoy create
|
||||||
active → Workers executing tasks
|
gt swarm status → gt convoy status
|
||||||
merging → Work being integrated
|
gt swarm list → gt convoy list
|
||||||
landed → Successfully merged to main
|
|
||||||
cancelled → Swarm aborted
|
|
||||||
|
|
||||||
COMMANDS:
|
See 'gt convoy --help' for the new workflow.`,
|
||||||
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`,
|
|
||||||
}
|
}
|
||||||
|
|
||||||
var swarmCreateCmd = &cobra.Command{
|
var swarmCreateCmd = &cobra.Command{
|
||||||
|
|||||||
Reference in New Issue
Block a user