| name | gc-architecture |
| description | Gas City multi-agent system architecture overview. Use when reasoning about GT roles, hierarchy, work primitives (beads, molecules, wisps, convoys), or rig configuration. |
| user-invocable | false |
GT Architecture
Two-Tier Structure
Town Level (Orchestration & Management)
Overseer (Human) -> Mayor (Coordinator) -> Deacon (Watchdog) -> Dogs <- Boot (Meta-watchdog)
Rig Level (Per-Project Workers)
Witness (Supervisor) -> Polecats (Ephemeral workers) -> Refinery (Merge manager)
Crew (Persistent collaborators)
Key Roles
| Role | Scope | Function |
|---|
| Mayor | Town | Concierge, convoy initiation, primary interaction point |
| Deacon | Town | Daemon beacon, health monitoring, patrol cycles |
| Dogs | Town | Deacon's helpers for maintenance tasks |
| Boot | Town | Watches the watchdog (Deacon health) |
| Witness | Rig | Per-rig supervisor, unsticks workers |
| Polecats | Rig | Ephemeral workers, swarm execution |
| Refinery | Rig | Merge queue management |
| Crew | Rig | Persistent collaborators (human-directed) |
Core Concepts
GUPP (Gas City Universal Propulsion Principle)
"If there is work on your Hook, YOU MUST RUN IT."
Every worker has a Hook (pinned Bead). GUPP ensures work continues even when sessions end.
Beads
- Atomic unit of work tracking
- Stored in JSONL (one issue per line)
- Tracked in Git alongside project
- Have: ID, description, status, assignee
Molecules
- Durable chained Bead workflows
- Survive agent crashes, compactions, restarts
- New session finds place and continues
Wisps
- Ephemeral Beads (destroyed after run)
- Used for high-velocity orchestration
- Memory only, not persisted
Convoys
- Work-order wrapping system
- Groups related work for tracked delivery
- Multiple swarms can "attack" a convoy
Rig Configuration
Each rig has its own:
- Beads database (
.beads/)
- Witness (supervisor)
- Polecats (workers)
- Refinery (merge manager)
- Optional: Crew members
Current COO Rigs
| Rig | Purpose |
|---|
| DReader | Document reader application |
| DataArchive | Data archiving application |
| claude_monitor | Claude context file monitoring |
| ParseClipmate | Windows clipboard parser |
