Understanding Gas Town

This document provides a conceptual overview of Gas Town's architecture, focusing on the role taxonomy and how different agents interact.

Why Gas Town Exists

As AI agents become central to engineering workflows, teams face new challenges:

• Accountability: Who did what? Which agent introduced this bug?
• Quality: Which agents are reliable? Which need tuning?
• Efficiency: How do you route work to the right agent?
• Scale: How do you coordinate agents across repos and teams?

Gas Town is an orchestration layer that treats AI agent work as structured data. Every action is attributed. Every agent has a track record. Every piece of work has provenance. See Why These Features for the full rationale, and Glossary for terminology.

Role Taxonomy

Gas Town has several agent types, each with distinct responsibilities and lifecycles.

Infrastructure Roles

These roles manage the Gas Town system itself:

Role	Description	Lifecycle
Mayor	Global coordinator at mayor/	Singleton, persistent
Deacon	Background supervisor daemon (watchdog chain)	Singleton, persistent
Witness	Per-rig polecat lifecycle manager	One per rig, persistent
Refinery	Per-rig merge queue processor	One per rig, persistent

Worker Roles

These roles do actual project work:

Role	Description	Lifecycle
Polecat	Worker with persistent identity, ephemeral sessions	Witness-managed (details)
Crew	Persistent worker with own clone	Long-lived, user-managed
Dog	Deacon helper for infrastructure tasks	Persistent identity, Deacon-managed

Convoys: Tracking Work

A convoy (🚚) is how you track batched work in Gas Town. When you kick off work - even a single issue - create a convoy to track it.

# Create a convoy tracking some issues
gt convoy create "Feature X" gt-abc gt-def --notify overseer

# Check progress
gt convoy status hq-cv-abc

# Dashboard of active convoys
gt convoy list

Why convoys matter:

• Single view of "what's in flight"
• Cross-rig tracking (convoy in hq-, issues in gt-, bd-*)
• Auto-notification when work lands
• Historical record of completed work (gt convoy list --all)

The "swarm" is the set of workers currently assigned to a convoy's issues. When issues close, the convoy lands. See Convoys for details.

Crew vs Polecats

Both do project work, but with key differences:

Aspect	Crew	Polecat
Lifecycle	Persistent (user controls)	Transient (Witness controls)
Monitoring	None	Witness watches, nudges, recycles
Work assignment	Human-directed or self-assigned	Slung via gt sling
Git state	Pushes to main directly	Works on branch, Refinery merges
Cleanup	Manual	Automatic on completion
Identity	<rig>/crew/<name>	<rig>/polecats/<name>

When to use Crew:

• Exploratory work
• Long-running projects
• Work requiring human judgment
• Tasks where you want direct control

When to use Polecats:

• Discrete, well-defined tasks
• Batch work (tracked via convoys)
• Parallelizable work
• Work that benefits from supervision

Dogs vs Crew

Dogs are NOT workers. This is a common misconception.

Aspect	Dogs	Crew
Owner	Deacon	Human
Purpose	Infrastructure tasks	Project work
Scope	Narrow, focused utilities	General purpose
Lifecycle	Very short (single task)	Long-lived
Example	Boot (triages Deacon health)	Joe (fixes bugs, adds features)

Dogs are the Deacon's helpers for system-level tasks:

• Boot: Triages Deacon health on daemon tick
• Future dogs might handle: log rotation, health checks, etc.

If you need to do work in another rig, use worktrees, not dogs.

Cross-Rig Work Patterns

When a crew member needs to work on another rig:

Option 1: Worktrees (Preferred)

Create a worktree in the target rig:

# gastown/crew/joe needs to fix a beads bug
gt worktree beads
# Creates ~/gt/beads/crew/gastown-joe/
# Identity preserved: BD_ACTOR = gastown/crew/joe

Directory structure:

~/gt/beads/crew/gastown-joe/     # joe from gastown working on beads
~/gt/gastown/crew/beads-wolf/    # wolf from beads working on gastown

Option 2: Dispatch to Local Workers

For work that should be owned by the target rig:

# Create issue in target rig
bd create --prefix beads "Fix authentication bug"

# Create convoy and sling to target rig
gt convoy create "Auth fix" bd-xyz
gt sling bd-xyz beads

When to Use Which

Scenario	Approach
You need to fix something quick	Worktree
Work should appear in your CV	Worktree
Work should be done by target rig team	Dispatch
Infrastructure/system task	Let Deacon handle it

Directory Structure

The town root (~/gt/) contains infrastructure directories (mayor/, deacon/) and per-project rigs. Each rig holds a bare repo (.repo.git/), a canonical beads database (mayor/rig/.beads/), and agent directories (witness/, refinery/, crew/, polecats/).

For the full directory tree, see architecture.md.

Identity and Attribution

All work is attributed to the actor who performed it:

Git commits:      Author: gastown/crew/joe <[email protected]>
Beads issues:     created_by: gastown/crew/joe
Events:           actor: gastown/crew/joe

Identity is preserved even when working cross-rig:

• gastown/crew/joe working in ~/gt/beads/crew/gastown-joe/
• Commits still attributed to gastown/crew/joe
• Work appears on joe's CV, not beads rig's workers

The Propulsion Principle

All Gas Town agents follow the same core principle:

If you find something on your hook, YOU RUN IT.

This applies regardless of role. The hook is your assignment. Execute it immediately without waiting for confirmation. Gas Town is a steam engine - agents are pistons.

Model Evaluation and A/B Testing

Gas Town's attribution system enables objective model comparison by tracking completion time, quality signals, and revision count per agent. Deploy different models on similar tasks and compare outcomes with bd stats.

See Why These Features for details on work history and capability-based routing.

Common Mistakes

1. Using dogs for user work: Dogs are Deacon infrastructure. Use crew or polecats.
2. Confusing crew with polecats: Crew is persistent and human-managed. Polecats are transient and Witness-managed.
3. Working in wrong directory: Gas Town uses cwd for identity detection. Stay in your home directory.
4. Waiting for confirmation when work is hooked: The hook IS your assignment. Execute immediately.
5. Creating worktrees when dispatch is better: If work should be owned by the target rig, dispatch it instead.