The hand-rolled system has predictable friction
Most multi-agent teams improvise a system that looks like this: a shared repo with multiple worktrees, one or more coordinator humans keeping the branch story straight, specialist agents doing bounded tasks in parallel, and prompts, scripts, notes, and checklists scattered between files and chat. It works — and it leaks:
Gas City makes those moving parts first-class pack and city content, and
puts an orchestrator behind them — so coordination no longer lives in one
person’s head and chat window.
The primitives let an orchestrator run your team’s work
New to the core vocabulary? Read the six primitives first — Agent, Bead, Formula, Rig, Pack, and Event are the model everything below configures.- Formulas (HOW the work gets done) become methods the orchestrator compiles into a graph of beads and drives to completion — decomposing a job, fanning ready steps out to many agents at once, gating each step on its dependencies, retrying failures. Orders (WHEN) trigger those formulas on a schedule or event.
- Agents (WHO does the work) become explicit directories with prompt and local assets.
- A pack (what CONFIGURES the above) declares those agents, formulas, and orders. The City is the local root pack; it imports shared packs.
.gc/ becomes the machine-local site-binding and runtime layer. The working
style becomes orchestrator-driven instead of hand-driven, and the method itself
becomes reproducible, legible, shareable, and version-controlled.
Everything sorts into three layers
The City is the local root pack; it imports shared packs. A pack and a city are the same kind of container at different scopes. Each piece of your workflow belongs to exactly one of three layers:
Formulas and orders live in layer 1 because they are portable method: a
formula compiles to a graph the orchestrator runs across many agents; an
order triggers it on a schedule or event. Layer 3 is the stuff that must
never be mistaken for portable definition.
A useful first city is small
You do not need a perfect city on day one. A good first version:- one root city pack
- a small set of named agents for the human and agent roles you already have
- one or two commands that encode common team operations
- one migration guide or working note you actively use
- a habit of running the real work through the city instead of beside it
Real roles get real places to live
Imagine a release-wave team with three humans and several agents. The humans divide into an operational/tutorial owner, a product/engineering connector, and an implementation-heavy technical lead. The agents divide into audit/review, migration, release-shape validation, docs-truth/schema alignment, and targeted implementation workers.
The point is not to freeze your team shape forever. It is to stop
pretending a real multi-agent workflow is just “some prompts somewhere”
plus shell history. The method that coordinates the agents becomes a formula the
orchestrator executes for you, not a routine you perform by hand every time.
Move the parts you already repeat
Start with the parts you are already repeating.
Turn repeated operations into pack commands
A pack command is a directory undercommands/ holding a run.sh script
plus an optional command.toml (its description). The command surfaces under
the name the city imports the pack as — a pack imported with
[imports.team] gets gc team <command>; a city’s own root pack uses its
[pack].name:
Encode known mistakes as doctor checks
If your team keeps rediscovering the same mistakes — stale file naming after a migration, a required prompt file missing from an agent directory, contradictory config across pack and city layers, known release-shape mismatches — encode them. A doctor check is a directory underdoctor/
with a doctor.toml description and a run.sh that exits non-zero on
failure; gc doctor runs every check the city’s packs supply:
Dogfooding is your highest-signal feedback loop
If your team is building Gas City, using Gas City to do that work surfaces problems nothing else will: awkward workflow you feel, docs that lie, migration paths that turn out shaky. Not every hour must run through the city — but when you want meaningful product signal, use a branch you are actually trying to trust, not a throwaway sandbox.Adopt by writing down what you already do
You do not need to start from scratch:- write down the working style you already have
- identify the parts you keep doing by hand
- move the repeated parts into pack-owned content
- give the team a city that reflects how you actually work
- let the friction teach you what to improve next