Gas Town Naming Conventions

Type: Convention / Style guide
Related: gas-town-daemon-architecture, steve-yegge-gas-town, steve-yegge-hierarchy

Naming Philosophy

Gas Town names are not arbitrary. Every name in the system follows three principles:

  1. Evocative, not descriptive — names should suggest the role, not spell it out. "Deacon" patrols (like a church deacon checking on the congregation). "Refinery" routes and processes (like an oil refinery). "Witness" watches and audits.

  2. Nouns or short phrases — never technical abbreviations, never camelCase, never agent_v2_final. Names are words a human would recognize and remember.

  3. From the Gas Town / Kelly universe — names are drawn from the world Steve Yegge built: Gas Town (the product), the Wasteland (the federation), Gas City (the SDK), and the Kelly methodology's own naming traditions.

The Full Naming Map

Infrastructure Daemons

Name Role Evocation
Deacon Patrol daemon — liveness, timeout, completion hooks A church deacon who checks on every member of the congregation; if someone's missing, they go find them
Boot Triage daemon — heartbeat handling, ephemeral tasks The boot sequence that gets the system running; lightweight, fast, gets out of the way
Witness Quality auditor — fuzzing, invariants, drift detection A witness who watches everything and testifies to what they saw; can't be bribed, can't be skipped
Refinery Routing daemon — decomposition, scheduling, agent selection An oil refinery that takes crude input (vague epics) and produces refined output (specific beads)

Agent Roles

Name Role Evocation
Mayor Information filter — reads everything, surfaces what matters The mayor of a town who knows everything happening and tells you only what you need to act on
Polecats Ephemeral workers — given a bead, let loose Fierce, independent creatures that hunt alone; assigned a target and left to get it
Crew Named, long-lived agents — persistent domain specialists The crew of a ship; each has a role, they know each other, they work together over time
PR Sheriff Crew role — autonomous PR triage and merging The sheriff who keeps order without being asked; sees a problem, handles it

Work Concepts

Name Concept Evocation
Beads Atomic work items — git-versioned, SQL-queryable Beads on a string; each one small, but together they form something meaningful
Hooks Agent work queues — pending beads assigned to an agent A fishhook with bait on it; if there's something on your hook, you must deal with it
Stamps Reputation attestations — multi-dimensional quality ratings Stamps in a passport; each one proves you were somewhere and did something
Convoys Coordinated batch execution — swarm well-specified epics A convoy of trucks moving together; coordinated, parallel, heading to the same destination

Principles and Protocols

Name Principle Evocation
GUPP Gas Town Universal Propulsion Principle — if work on hook, must run The engine that keeps everything moving; universal because it applies to every agent
MEOW Molecular Expression of Work — work as first-class system primitive Work is the atom; everything else (knowledge, coordination, reputation) is built from it
Heresies Wrong assumptions that propagate through agent code Heresies in a church — beliefs that spread if not actively stamped out by the Deacon/Witness

Ecosystem

Name Concept Evocation
Gas Town The orchestrator — manages concurrent agents A town with infrastructure; not glamorous, but everything works because the plumbing is solid
Gas City The SDK — composable building blocks for custom orchestrators A city is bigger than a town; more infrastructure, more composability, more residents
The Wasteland Federated trust network — shared work across organizations The frontier; open, vast, with its own rules and reputation economy
Wanted Board Public work queue — anyone can post, rigs claim A bounty board in a Western town; post what you need done, someone will claim it

Prefix Convention

gas-town- prefix for cross-cutting concerns

Names that span multiple components or are not specific to a single daemon use the gas-town- prefix:

  • gas-town-daemon-architecture — the daemon layer (cross-cutting)
  • gas-town-naming-conventions — this document (cross-cutting)
  • gas-town-mayor-pattern — the Mayor pattern (cross-cutting, applies to multiple implementations)

Role-specific names stand alone

Names that are specific to a single component do not need a prefix:

  • kelly-deacon-architecture — Kelly's Deacon implementation (specific)
  • deacon.toml — Deacon configuration (specific)
  • refinery-config — Refinery configuration (specific)

The prefix disambiguates: gas-town-daemon-architecture is the general daemon architecture; kelly-deacon-architecture is Kelly's specific Deacon implementation.

Anti-Patterns (What NOT to Do)

❌ Technical Abbreviations

BAD:  agent-mgr-v2
BAD:  qa-daemon-final
BAD:  subagent-handler-3
GOOD: Deacon
GOOD: Witness
GOOD: Refinery

❌ Generic Descriptive Names

BAD:  work-item-processor
BAD:  quality-check-service
BAD:  routing-engine
GOOD: Refinery
GOOD: Witness
GOOD: Mayor

❌ Acronyms Without Meaning

BAD:  GUPS
BAD:  MWFS
BAD:  AQRH
GOOD: GUPP (Gas Town Universal Propulsion Principle — acronym expands to meaning)
GOOD: MEOW (Molecular Expression of Work — acronym expands to meaning)

❌ Version Numbers in Names

BAD:  deacon-v3
BAD:  witness-2.0
GOOD: Deacon
GOOD: Witness

The version belongs in the implementation, not the name. "Deacon" is the concept; version 3 of the Deacon binary is still "the Deacon."

Naming Process

When introducing a new component to the Gas Town ecosystem:

  1. Identify the role — what does this component do in one sentence?
  2. Find the evocation — what real-world thing does this role resemble?
  3. Check the universe — is there a Gas Town / Kelly name that fits?
  4. Verify uniqueness — does this name collide with any existing component?
  5. Test with humans — can someone unfamiliar with the system guess the role from the name?

If no existing Gas Town name fits, the name should come from the same world — industrial, civic, or ecclesiastical metaphors that evoke infrastructure, community, and reliability.

gas-town-daemon-architecture, kelly-deacon-architecture, gas-town-mayor-pattern, steve-yegge-gas-town, steve-yegge-hierarchy

Source Attribution