Using Gc

Using GC

Use Gas City only when the caller explicitly selects it. Treat it as a replaceable execution adapter, not a correctness or completion boundary. The adapter cannot select AgentOps semantics, issue a binding verdict, or turn factory completion into delivery or validation proof.

The operator lane

The operator lane into a city is a closed set:

• author source intent beads;
• gc mail to the Mayor, for work dispatch and for city tending;
• gc session wake <run_target>, once, for a routed bead whose worker stalled;
• gc doctor [--fix], and supervisor start/stop from outside the city;
• ao gc prepare|check|recover-affinity;
• reading run, session, bead, pane and artifact state.

The Mayor authors workflow beads and dispatches them; it owns retries, re-dispatch and tending for that work. Never create, scale or repair pack-owned sessions by hand: gc session new for a singleton or scaled agent (core.control-dispatcher, role workers) makes a mis-scoped session that squats the canonical name in start-pending and blocks the reconciler from spawning the real one. Session lifecycle belongs to the reconciler and demand scaling. Direct gc sling is a debugging tool for a city with no live Mayor; a run started that way has no coordinator, and the operator inherits its tending.

Choose the factory first

AgentOps supports both Gas City and the Agentic Coding Flywheel as external software-factory runtimes. Use this skill only for Gas City. If the caller selects the Flywheel, follow its native workflow instead of wrapping it in Gas City.

AgentOps supplies skills and evidence contracts to either factory. It does not need its own Gas City formula or role pack. Install or link AgentOps skills into the provider runtime before starting workers; the upstream Mayor, coordinator, and workers can then discover and select plan, implement, test, validate, and other AgentOps skills normally.

Version facts

Status on 2026-10-04: the gascity pin (0.1.6, commit 3b3b89f2011e06d84459aa7bea1552382f13930a) is the commit ao gc enforces, and it matches the registry's 0.1.6 release. The Gas City 1.4.0 command facts in this skill were not re-verified for this release. When gc version reports anything other than 1.4.0, confirm each command with gc <command> --help before relying on it.

Gas City 1.4 operating model

Gas City 1.4 is run-centered. The supervisor serves the dashboard and typed, paginated session/run APIs. Every graph-owning city or rig scope needs its own core.control-dispatcher; that deterministic worker advances formula control beads. Agent workers claim routed work. The upstream gc.mayor skill is the guided coordinator; gc.run-operator launches and supervises formulas.

The normal AgentOps path is:

1. Install and pin the upstream gascity workflow and rig-role imports.
2. Add the project as a rig, prepare its stock maintainer runtime, and make AgentOps skills visible to its provider sessions.
3. Create a caller-owned source intent bead and hand its id to the Mayor, which authors the workflow beads and dispatches the upstream build-basic, continuation, review, or implementation formula that matches the available artifacts.
4. Read run, session, bead, artifact, and verdict state. Completion is never inferred from chat or pane prose.

Prepare and check a rig

Prepare and qualify a rig before its first build with the shipped AgentOps CLI (no repo checkout required):

ao gc prepare --city /path/to/city --rig /path/to/rig
ao gc check --city /path/to/city --rig /path/to/rig

prepare verifies the exact official workflow and role pins, stages a contained maintainer runtime inside the rig's .gc directory, links the AgentOps skills into the city and rig Codex sinks, and pre-seeds Codex workspace and hook trust for every session directory that exists when it runs. Hook trust needs the Codex CLI on PATH (or --codex-bin). check is read-only, runs no Codex subprocess, and fails before model spend when that runtime contract is missing or drifted.

Run prepare, start the city, then run prepare again (it is idempotent) before dispatching. Two limitations make that order necessary: check cannot see a stale trust hash, so green means trust is recorded, not fresh; and a session home created after prepare is not covered. Codex trust pre-seed has the mechanism.

Preferred pack and registries

The built-in main registry catalogs official packs. The community registry is optional configuration:

gc pack registry list
gc pack registry refresh
gc pack registry search --all
gc pack registry show main:gascity
gc pack registry add community https://registry.gascity.com/registry.toml
gc pack registry search --registry community --all

search reads the local registry cache; show reports release provenance and exact import commands. gc import add declares a source/version, and gc import install resolves it into packs.lock. Prefer an exact accepted release for reproducible cities.

AgentOps prefers the official gascity build pack, the workflow family visible in the public Maintainer City factory, at the accepted reference above:

• dashboard: https://factory.gascity.com;
• workflows: build-basic, build-from-*, implement, review, issue, and PR flows;
• stock rig roles: gc.run-operator, gc.implementation-worker, planners, reviewers, and publisher;
• scope-local formula control: core.control-dispatcher;
• guided coordination: the upstream gc.mayor skill.

Install the workflow pack at city scope and its sibling roles pack on every rig that runs work, following the exact commands returned by gc pack registry show main:gascity. Keep the stock gc.* namespace; do not nest or rename the roles behind an AgentOps pack.

Hand work to the Mayor

Work enters the city through the Mayor. The caller authors ONE source intent bead with acceptance, then hands the Mayor its id; the Mayor decomposes, authors the workflow beads, and dispatches.

gc bd create "Add a --json flag to the export command"
gc mail send mayor -s "Build ago-XXXX" \
  -m "Decompose and launch build-basic for bead ago-XXXX with push=true open_pr=true." --notify

Or, in an interactive Mayor session:

Use skill gc.mayor

AgentOps skills are tools available to those factory agents, not a replacement workflow. Explicitly name a skill in the bead or prompt when its behavior is required. The current upstream decomposition does not automatically propagate a free-form Required Skills section from the caller-owned source bead into every generated work item. Inspect the decomposition before implementation; put a required skill name on the actual work item or worker prompt when its use is an acceptance condition. Skill presence and skill invocation are different facts.

Upgrade an existing city to 1.4

Before starting its orchestrator, run once per city:

gc doctor --fix
gc import install
gc supervisor stop --wait   # macOS when an older direct supervisor remains
gc start

Then confirm:

• gc version reports 1.4.0 from the intended path;
• gc doctor has no blocking failures;
• each graph-owning rig has an unsuspended core.control-dispatcher;
• imports and packs.lock resolve;
• ao gc check accepts the contained maintainer runtime and AgentOps skill links;
• on macOS, the supervisor LaunchAgent resolves to the same executable as the selected gc binary;
• old standalone-dashboard bookmarks or reverse proxies are removed.

A stale registered city may block every start. Repair that city with gc doctor --fix, or explicitly unregister it if it is intentionally retired.

Retire an old HQ/canary by exact registered name or path, without stopping the machine-wide supervisor needed by its replacement:

gc cities --json
gc stop /path/to/old-city --timeout 45s
gc unregister /path/to/old-city
gc cities --json

unregister fails rather than silently accepting an unknown target. Preserve the city directory until its Beads state is backed up or confirmed disposable. Create the replacement from the upstream Gas City template, install its pinned imports, and verify it with gc cities --json, gc --city <new-city> status, and gc --city <new-city> doctor --json.

Orchestrating through the Mayor: the tending loop

After handing intent to the Mayor, the orchestrator runs five verbs. Each verb has one owner; crossing owners is the recurring failure class this section exists to stop.

Rework the orchestrator performs by hand (editing a failed run's worktree, re-slinging its formula, closing its beads) creates a second uncoordinated author for the same intent; the Mayor's relaunch then races it.