docs: clarify stream engine model, reduce swarm terminology (gt-wexr)
Gas Town is a stream engine, not a swarm engine. Polecats can start and land independently at any time. "Swarm" is used lightly for batch coordination, but there are no swarm IDs or batch boundaries. Changes: - architecture.md: Add stream engine intro paragraph, update references from "swarming" to "parallel polecats" or "batch" - prompts.md: Rename SWARM_* messages to BATCH_*, update terminology - crew.md.tmpl: Replace "swarm" references with "transient worker pool" and "batch work" The gt swarm command and internal/swarm/ package remain as-is since they provide the tooling for batch operations. 🤖 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
@@ -2,6 +2,8 @@
|
||||
|
||||
Gas Town is a multi-agent workspace manager that coordinates AI coding agents working on software projects. It provides the infrastructure for spawning workers, processing work through a priority queue, and coordinating agents through mail and issue tracking.
|
||||
|
||||
**Gas Town is a stream engine, not a swarm engine.** Polecats (workers) can start and land at any time, independently. They're ephemeral - once their work merges, they evaporate. You can spawn a batch of polecats to tackle parallelizable work, but there's no "swarm ID" or batch boundary. The merge queue optionally serializes landing, preventing monkey-knife-fights when parallel polecats touch the same code. A single polecat is just a batch of one.
|
||||
|
||||
**Key insight**: Work is a stream, not discrete batches. The Refinery's merge queue is the coordination mechanism. Beads (issues) are the data plane. There are no "swarm IDs" - just epics with children, processed by workers, merged through the queue.
|
||||
|
||||
**Molecule-first paradigm**: Gas Town is fundamentally a molecule execution engine. Workers don't just "work on issues" - they execute molecules. The issue is seed data; the molecule defines the workflow. This enables nondeterministic idempotence: any worker can pick up where another left off, surviving crashes, context compaction, and restarts. If a process requires cognition, it should be a molecule. See [Molecules](#molecules-composable-workflow-templates) for full details.
|
||||
@@ -867,7 +869,7 @@ mol-graceful-shutdown
|
||||
**Key principle**: If a multi-step process requires cognition and can fail partway through, it should be a molecule. This applies to:
|
||||
- Agent lifecycle (startup, work, shutdown)
|
||||
- System operations (activation, deactivation)
|
||||
- Batch processing (swarm coordination)
|
||||
- Batch processing (parallel worker coordination)
|
||||
- Recovery procedures (doctor --fix)
|
||||
|
||||
### Pluggable Molecules
|
||||
@@ -974,7 +976,7 @@ These are the work that "feeds the beast" - the review molecule generates fix be
|
||||
You don't need convergence built into the molecule. Just run it again:
|
||||
|
||||
1. Run `gt molecule instantiate code-review`
|
||||
2. Swarm closes all review beads, generates fix beads
|
||||
2. Workers close all review beads, generate fix beads
|
||||
3. Fix beads get closed
|
||||
4. Run `gt molecule instantiate code-review` again
|
||||
5. Fewer findings this time
|
||||
@@ -1291,7 +1293,7 @@ sequenceDiagram
|
||||
4. Tests pass (skippable with --skip-tests)
|
||||
|
||||
**When direct landing makes sense:**
|
||||
- Mayor is doing sequential, non-swarming work (like GGT scaffolding)
|
||||
- Mayor is doing sequential work without parallel polecats
|
||||
- Single worker completed an isolated task
|
||||
- Hotfix needs to land immediately
|
||||
- Refinery agent is down or unavailable
|
||||
@@ -1344,7 +1346,7 @@ sequenceDiagram
|
||||
M->>O: Report results
|
||||
```
|
||||
|
||||
**Note**: There is no "swarm ID" or batch boundary. Workers process issues independently. The merge queue handles coordination. "Swarming an epic" is just spawning multiple workers for the epic's child issues.
|
||||
**Note**: There is no "swarm ID" or batch boundary. Workers process issues independently. The merge queue handles coordination. Tackling an epic with parallel polecats is just spawning multiple workers for the epic's child issues.
|
||||
|
||||
### Worker Cleanup (Witness-Owned)
|
||||
|
||||
@@ -1556,7 +1558,7 @@ export BEADS_DIR=/path/to/rig/.beads
|
||||
|
||||
**Rationale**:
|
||||
- **Flexibility**: Not all work needs merge queue overhead
|
||||
- **Sequential work**: Mayor doing non-swarming work (like GGT scaffolding) shouldn't need Refinery
|
||||
- **Sequential work**: Mayor doing single-polecat work shouldn't need Refinery
|
||||
- **Emergency path**: Hotfixes can land immediately
|
||||
- **Resilience**: System works even if Refinery is down
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ Delivered via `gt prime` command. These establish agent identity and capabilitie
|
||||
|
||||
| Role | Template | Purpose |
|
||||
|------|----------|---------|
|
||||
| Mayor | `mayor.md` | Global coordination, swarm dispatch, cross-rig decisions |
|
||||
| Mayor | `mayor.md` | Global coordination, work dispatch, cross-rig decisions |
|
||||
| Witness | `witness.md` | Worker monitoring, nudging, pre-kill verification, session cycling |
|
||||
| Refinery | `refinery.md` | Merge queue processing, PR review, integration |
|
||||
| Polecat | `polecat.md` | Implementation work on assigned issues |
|
||||
@@ -27,16 +27,16 @@ Delivered via `gt prime` command. These establish agent identity and capabilitie
|
||||
|
||||
### 2. Mail Templates (Structured Messages)
|
||||
|
||||
Parseable messages for swarm pipeline communication.
|
||||
Parseable messages for worker coordination.
|
||||
|
||||
| Template | Flow | Purpose |
|
||||
|----------|------|---------|
|
||||
| `SWARM_STARTED` | Refinery → Mayor | Swarm initialized, workers ready |
|
||||
| `BATCH_STARTED` | Refinery → Mayor | Batch initialized, workers ready |
|
||||
| `WORKER_READY` | Worker → Refinery | Worker setup complete |
|
||||
| `WORK_COMPLETE` | Worker → Refinery | Task finished, ready for merge |
|
||||
| `MERGE_CONFLICT` | Refinery → Worker/Mayor | Merge failed, needs resolution |
|
||||
| `SWARM_COMPLETE` | Refinery → Mayor | All tasks done |
|
||||
| `SWARM_FAILED` | Refinery → Mayor | Swarm failed, needs intervention |
|
||||
| `BATCH_COMPLETE` | Refinery → Mayor | All tasks done |
|
||||
| `BATCH_FAILED` | Refinery → Mayor | Batch failed, needs intervention |
|
||||
|
||||
### 3. Spawn Injection (Work Assignment)
|
||||
|
||||
@@ -86,7 +86,7 @@ Templates for session cycling and handoffs.
|
||||
- Polecat management commands
|
||||
- Work management and sync commands
|
||||
- Workflow steps (inbox → ready → spawn → monitor → report)
|
||||
- Swarm management commands
|
||||
- Worker management commands
|
||||
- Session end checklist
|
||||
|
||||
**unknown.md.j2** (~20 lines)
|
||||
@@ -420,7 +420,7 @@ Unlike polecats, crew workers have no Witness oversight:
|
||||
|
||||
### Phase 2: Mail Templates
|
||||
1. Define mail template format in Go
|
||||
2. Port swarm pipeline templates
|
||||
2. Port worker coordination templates
|
||||
3. Add handoff and escalation templates
|
||||
|
||||
### Phase 3: Spawn & Lifecycle
|
||||
|
||||
Reference in New Issue
Block a user