Coming from Gas Town

If you have run Gas Town, you already know its roles, its ~/gt/... layout, and its gt commands. This page carries that knowledge across to Gas City.

Gas City is the platform that machinery was extracted into. Two things changed. First, the orchestrator hardcodes zero roles — every role you knew is now configuration, and you express Gas Town (or any orchestration) on top of a few primitives. Second, and bigger: the orchestrator can now run a formula as a graph across many agents, out of your session — decomposing a job into beads, fanning the ready ones out in parallel, gating each step on its dependencies, and retrying failures to completion. Your single-agent, in-session formulas still run (v1); this fleet orchestration (v2) is what's new. Because it is a platform, a feature added to Gas City lifts every orchestrator built on it — Gas Town included.

For the system-level mental model first, read How Gas City Works.

Mapping tables

The five tables map Gas Town onto Gas City one domain at a time. Every entry on the right is configuration — a user-configured agent plus a prompt template — not a built-in platform type.

Roles

Mechanisms and behaviors

What those roles and features actually do, and where that logic now lives.

Filesystem and state

Gas Town encodes architecture into directories; Gas City treats directories as an implementation detail.

Workflows

The operator verbs — the things you actually type. (Formulas are a mechanism, above; these are day-to-day moves.) The transcripts below show them end to end.

A first work cycle — start the city, hand the mayor a task, watch it land:

gc start                                  # boots the city under the supervisor, reconciles
gc sling mayor "add a /health endpoint"   # creates a task bead from text, routes it to mayor
gc session list                           # see what's running (mayor, pools, …)
gc session attach mayor                    # interactive live view of the mayor working

Triage a stuck agent without attaching:

gc session list                  # find the suspect by name/state
gc session peek mayor --lines 80 # snapshot of recent output (default 50 lines)
gc session reset mayor           # fresh restart; bead, alias, mail, and queued work survive
gc events --follow               # system-wide live feed (or let health patrol act on its own)

Commands

The full gt → gc/bd mapping lives in the Gas Town → Gas City Command Map.

What usually maps cleanly

Roles become pack agents. Adding a role follows an escalation ladder — stop at the first rung that solves your problem:

edit local city.toml  →  include a pack that already solves most of it
  →  override the stamped agent (local-only change)
  →  edit the pack (change the shared default for everyone)
  →  add formulas/orders for workflow automation

Start with the root city pack plus city.toml, not an imported pack. Edit a pack only when the change should become the reusable default for every consumer.

# pack.toml      — imports reusable packs, defines city-specific behavior
# agents/<name>/ — city-owned named agents
# city.toml      — deployment: rigs, substrates, scale
# .gc/           — site bindings such as local rig paths

Plugins become orders — the most important practical translation. "Run something automatically on a schedule, on an event, or when a condition holds" is an order: exec order for shell/orchestrator-side logic, formula order for agent-driven work. Exec orders matter most — they run non-agent commands with no prompt, no session, no extra role agent.

Convoys stay bead-shaped. Keep the convoy mental model for tracking work; the implementation boundary moved. Convoys are bead-backed grouping and lineage, gc sling creates convoy structure while routing, and formulas/orders/waits compose around that bead graph. The orchestration that runs over it is the orchestrator's control dispatcher — it executes the control beads (check, retry, fan-out, tally, drain) that drive a convoy's work to completion across many agents.

Crew and polecats are operating modes, not types. Crew = persistent named agents; polecats = scalable or transient agents, often with worktrees. The platform does not force the distinction — a pack can adopt, relax, or replace it.

Where Gas City deliberately differs

The orchestrator owns infrastructure behavior. It is the canonical owner of reconciling desired→running sessions, session scaling, order evaluation, health patrol, and garbage-collecting ephemeral run beads (the v1 wisp container). If something is fundamentally platform infrastructure, put it on the orchestrator path rather than inventing another deacon-like role.

Filesystem layout is not the architecture. Use dir (in agent.toml, or patched per-rig in city.toml) for scope and identity; work_dir only when the session must run elsewhere; bead metadata for durable handoff state.

Roles are examples, not platform law. The Gastown pack ships familiar roles as an example operating model, not a type system. Adding a behavior means editing a pack, formula, order, or prompt — not adding a hardcoded role. A local city change edits city.toml (rig overrides, patches, a city-specific agent); a shared product change edits the pack for a better default everywhere. Most onboarding work is local.

Common translation patterns

"How do I get to my mayor?"

gc session attach mayor

The Mayor session is the familiar Gas Town entry point — an interactive session with full city context that you coordinate from. It is one window onto the city; the orchestrator is still running the fleet and driving formula graphs to completion behind it. The CLI is plumbing for reaching that session. City-scoped Gastown agents (mayor, deacon, boot) attach the same way; gc session list shows what is running. This replaces gt session at mayor/ or tmux attach -t gt-mayor.

What not to port literally

These Town habits create unnecessary complexity in Gas City:

• exact ~/gt/... directory trees
• path-derived identity
• new hardcoded role names in platform code
• plugin systems when an order is enough
• special helper agents for work that is really a shell command
• duplicating durable state outside beads when labels or metadata suffice

The most common mistake is importing Town's surface area instead of re-expressing the intent in Gas City's primitives.

Editing Gastown config

The common edits — registering rigs, scaling pools, swapping providers, patching agents, tweaking prompts — live in Gastown on Gas City: Config Recipes.

Fast ramp checklist

The shortest path to effective:

1. Read How Gas City Works for the six primitives in user terms.
2. Skim the CLI reference alongside the Command Map so gt → gc muscle memory transfers.
3. Read Tutorial 07 — Orders and remap "plugins" → "orders".
4. Read Tutorial 05 — Formulas: Gas City compiles and instantiates formulas itself; for v2 formulas the orchestrator drives control beads while agents execute work beads.
5. Work through Tutorial 02 — Agents and Shareable Packs for the agents/<name>/ layout end to end.
6. Read A Complete Gastown Example — city, root pack, and nested pack assembled into one runnable topology.