Using Gc

Running AgentOps on Gas City (gc)

This guide GUIDES agents on the `gc` CLI — exactly like the bd protocol guides them on `bd`. ao does NOT wrap gc; gc is a guided out-of-session dependency. AgentOps is the opinions (the rpi/evolve loops, the ratchet rules, the skill corpus, the .agents/ context compiler); Gas City is the substrate (controller/supervisor, Orders, the bead/dolt queue, the Event Bus, runtime providers, mayor/worker agents). The seam: gc (orchestration) invokes ao (the loop) as a subprocess.

When to use gc. In-session, you run the loop yourself (/rpi, /evolve) — you do not need gc. Reach for gc when you want the loop to run out of session: scheduled maintenance, autonomous bead drain, a long-lived team-lead agent that dispatches work and drives PRs to merge. The reference pack at `packs/agentops/` is the canonical AgentOps-on-GC config. North-star framing: `docs/3.0.md`.

gc Availability Pattern

gc is an optional, out-of-session dependency. Skills must degrade gracefully when it is absent (see the shared fallback table).

if command -v gc &>/dev/null; then
  # Out-of-session orchestration available — see the dispatch loop below.
else
  echo "Note: gc not installed. Run the loop in-session with /rpi or /evolve."
  # Fallback: drive the loop yourself; gc adds out-of-session orchestration only.
fi

gc Primitives (the vocabulary)

THE governing boundary (THIN-SEAM). GC dispatches the whole ao rpi loop; it never sees the loop's insides. The loop's internal steps (research → plan → implement → validate) and its ratchet rules (no-self-grade, fresh-agent-on-failure, knowledge→constraints) live INSIDE AgentOps, behind the single command ao rpi. There is deliberately no mol-rpi-cycle 4-step GC formula — that would duplicate the loop shape across the seam and pit GC's check.max_attempts retry against AgentOps's fresh-agent-on-failure invariant.

The AgentOps-on-GC workflow (end to end)

1. Init the City

The reference City consumes the GC substrate and imports the AgentOps pack. Point gc at the City dir that holds city.toml and packs/agentops/:

gc start <path-to-city-dir>          # boots controller + supervisor + always-on mayor
gc rig add <path-to-your-repo>       # register the rig whose beads get worked

The City's [beads] provider = "bd" consumes the same `bd`/dolt store standalone bd uses — gc bd and bd share one tracker (one issue prefix per served DB). Do NOT import a dolt-managing pack: provider is pure client config, not a managed server (the 1,478-flap guard — see references/reference-city.md).

2. The mayor-driven dispatch loop (the honest path today)

A long-lived mayor agent runs bd ready, slings the next bead to a refinery worker, and the worker runs ao rpi <bead>:

# Mayor (city-scoped, always-on): find ready work and route it to the worker pool.
gc bd ready --json
TARGET_RIG="${GC_RIG:-}"                                   # rig that owns the code
gc sling "${TARGET_RIG:+$TARGET_RIG/}refinery" <bead-id>   # route the RAW bead to a worker

# Refinery (rig-scoped worker): run the WHOLE loop — ONE command.
ao rpi <bead-id>                                           # research→plan→implement→validate

# When ao rpi lands green, the worker hands the bead back to the mayor for merge:
BRANCH=$(git rev-parse --abbrev-ref HEAD)
gc bd update <bead-id> --status=open --assignee="mayor" \
  --set-metadata branch="$BRANCH" --set-metadata verdict=PASS \
  --notes "ao rpi green — verdict under .agents/"
gc mail send mayor/ -s "READY-TO-MERGE <bead-id>" -m "rpi cycle green; ready to merge."

The mayor owns the merge gate: CI-green is the merge signal — it drives each PR to merge on main and triggers the knowledge-flywheel feedback. There is no human merge gate in the autonomous loop; the human is on the loop (approvals, strategy, escalations), not in it. Full dispatch walkthrough: references/mayor-dispatch-loop.md.

3. The outer loop (evolve cadence)

On a cadence, the mayor runs ao evolve (the OUTER loop): it selects next-best work and drives a wave of ao rpi cycles toward a GOALS.md directive, then post-mortems at the session-scope threshold. evolve's cadence (recurrence) is GC orchestration (a cron Order → evolve-dispatch); evolve's logic (which bead next, N-cycles-toward-a-goal, post-mortem) stays inside ao evolve.

4. Cron exec Orders for maintenance

Deterministic, no-LLM-judgment maintenance runs as GC exec Orders (no agent context burned):

See `packs/agentops/orders/` for the order definitions.

HONEST gap: order-auto-dispatch is upstream-GC, not turnkey here (soc-5jwah)

Be honest about what dispatches, and how. The bead-dispatch cooldown Order CANNOT bind a ready bead to rpi-dispatch on its own: GC Orders have no per-fire variable-binding mechanism, so the formula's required issue var has no value and the order self-fails on every fire:

order.failed  msg=variable validation failed: - variable "issue" is required

Proven against the real gc binary (Tier 3 RED). So:

• Works today (proven): the City is gc-parse-valid; the controller, supervisor, Order engine, and agentops.mayor come up; the skills overlay lands in the spawned workdir; ao inject / ao validate --gate run there with the corpus compounding. The seam-correct manual path — gc sling <rig>/refinery <bead> routing a RAW bead to a worker that runs ao rpi <bead> — succeeds. The honest dispatch path is MAYOR-DRIVEN (a mayor running bd ready then gc sling).
• Not turnkey: order-level autonomous dispatch needs the upstream GC var-binding / next-ready-resolution capability (an upstream Gas City contribution, soc-5jwah), not an AgentOps feature. bead-dispatch.toml ships as a labeled REFERENCE for the intended shape. Do NOT read "gc-parse-valid" as "autonomous-dispatch-functional."

Operator posture: accept what GC offers today and grow with it. Mayor-driven dispatch is the shipped capability; order-auto-dispatch arrives with the upstream GC work.

References

• references/reference-city.md — anatomy of the reference City (city.toml substrate consumption, the [imports.agentops] opinion seam, the dolt 1,478-flap guard, single-prefix posture) and the pack layout.
• references/mayor-dispatch-loop.md — the mayor↔refinery dispatch + merge handoff in full, the THIN-SEAM boundary, the outer evolve loop, and the order-auto-dispatch gap.
• references/using-gc.feature — executable spec: an agent runs the reference City end-to-end with guided gc commands.

Issue Tracking (shared with gc)

gc consumes the same bd/dolt tracker, so the bead protocol is identical whether you call bd or gc bd:

gc bd ready              # unblocked issues (same store as `bd ready`)
gc bd update <id> ...    # claim / hand off / set merge metadata
gc bd prime              # protocol refresher inside a gc-spawned worker

The mayor-driven dispatch loop

Companion to `using-gc/SKILL.md`. This is the dispatch + merge handoff in full. The canonical agent prompts are `packs/agentops/agents/mayor/prompt.template.md` and `packs/agentops/agents/refinery/prompt.template.md`.

The roles

• Mayor — team lead, merge authority, human liaison. Sits above all rigs. Dispatches ready work, owns the merge gate, notifies the human on the loop. Does NOT own the loop's insides.
• Refinery (worker) — runs the ao rpi loop on ONE bead per cycle. Implements one coherent arc, hands the green result back to the mayor. Does NOT merge.

THE governing boundary (THIN-SEAM)

GC dispatched you a whole loop; you run the whole loop. ao rpi is one invocable command, owned by AgentOps. It runs research → plan → implement → validate internally and enforces the ratchet rules (no-self-grade, fresh-agent-on-failure, knowledge→constraints). You do NOT decompose it into GC steps. The loop's internal steps live INSIDE AgentOps, not in GC TOML — which is exactly why there is no mol-rpi-cycle 4-step formula and no default_sling_formula.

Mayor: dispatch ready work

gc bd ready --json                                         # same store as `bd ready`
TARGET_RIG="${GC_RIG:-}"                                   # the rig that owns the code
gc sling "${TARGET_RIG:+$TARGET_RIG/}refinery" <bead-id>   # route the RAW bead to a worker

The worker runs the WHOLE ao rpi loop on that bead. You never drive its internal research→plan→implement→validate steps. Dispatch liberally — keep the machinery busy, preserve your context. Fix-when-fast: edit directly for <5-min fixes; otherwise dispatch.

Refinery: run the loop (ONE command)

# Use $GC_AGENT as your canonical mailbox identity.
gc prime && gc bd prime

# Resume an in-progress bead, else claim ready work from the pool:
WORK=$(gc bd list --assignee="$GC_AGENT" --status=in_progress --json | jq -r '.[0].id // empty')
[ -z "$WORK" ] && WORK=$(gc bd ready --json | jq -r '.[0].id // empty')

ao rpi "$WORK"        # the whole inner loop — research→plan→implement→validate

ao rpi is your brain. Run it; don't re-implement it. Context flows through the rig's .agents/ corpus (ao inject / ao compile) and the bead's notes/metadata — GC formulas have no typed step I/O, which is why the loop lives inside AgentOps. On restart, re-read git + bead state and resume.

Refinery: hand off to the mayor (you do NOT merge)

When ao rpi lands a green verdict:

BRANCH=$(git rev-parse --abbrev-ref HEAD)
gc bd update "$WORK" --status=open --assignee="mayor" \
  --set-metadata branch="$BRANCH" --set-metadata verdict=PASS \
  --notes "rpi green — verdict artifact under .agents/"
gc mail send mayor/ -s "READY-TO-MERGE $WORK" -m "ao rpi cycle green; ready to merge."
gc runtime drain-ack

Mayor: own the merge gate

CI-green is the merge signal. You drive each PR to merge on main. There is no human merge gate in the autonomous loop — you are the orchestrator that merges green work and triggers the knowledge-flywheel feedback (/post-mortem, /harvest into .agents/). The human is on the loop: surface decisions, escalations, and post-mortem triggers via gc mail send human/ ....

Session-scope discipline (an AgentOps ratchet rule)

2-4 PRs per autonomous session. At >=5 shipped or in-flight, stop and run a post-mortem before continuing — reactive-PR spirals (PR-fixes-fallout-from-prior-PR) are the dominant back-half failure mode. Honor it even on "keep going".

Communication

gc mail inbox                                   # check messages
gc mail send <addr> -s "Subject" -m "Message"   # send mail (durable)
gc session nudge <target> "message"             # wake an agent

ALWAYS use gc session nudge, NEVER tmux send-keys (drops Enter).

The outer loop (evolve cadence)

On a cadence (cron Order → evolve-dispatch, routed to the mayor pool), the mayor runs ao evolve — it selects next-best work and drives a wave of ao rpi cycles toward a GOALS.md directive, then post-mortems at the session-scope threshold. evolve's cadence is GC orchestration; evolve's logic stays inside ao evolve. GC fires the cadence; AgentOps runs the wave.

The order-auto-dispatch gap (soc-5jwah)

The intended autonomous shape is a bead-dispatch cooldown Order that binds the next ready bead to rpi-dispatch and routes it to the refinery pool. As shipped by GC today it cannot do that: GC Orders have no per-fire variable-binding mechanism, so the formula's required issue var has no value and the order self-fails:

order.failed  msg=variable validation failed: - variable "issue" is required

So the honest dispatch path today is mayor-driven (the bd ready → gc sling → ao rpi flow above), plus cron exec Orders for scheduled maintenance. The var-binding / next-ready-resolution capability that would make the Order fire autonomously is an upstream Gas City contribution (soc-5jwah), not an AgentOps feature. bead-dispatch.toml ships as a labeled reference; do not claim it dispatches autonomously until the upstream GC capability lands.

The AgentOps Reference City — anatomy

Companion to `using-gc/SKILL.md`. The canonical, parse-valid source is `packs/agentops/` and the City city.toml that imports it. This doc explains the shape so an agent can read, modify, and reason about it.

Thesis: opinions on top of substrate

Gas City supplies the SUBSTRATE — controller/supervisor, Orders, the bead/dolt queue, the Event Bus, runtime providers, mayor/worker agents. AgentOps supplies the OPINIONS — the ao rpi/ao evolve loops, the ratchet rules, the skill corpus, the .agents/ context compiler. A single [imports.agentops] line is where ALL the opinion lives; every other city.toml block is pure substrate consumption.

The decoupling: the in-CLI gc-bridge (runtime=gc) was REMOVED from ao in a prior wave. This reference City is an external GC pack consumed by the standalone gc binary — it does NOT depend on the removed in-CLI bridge. The seam is gc (orchestration) → ao (the loop) as a subprocess.

city.toml — substrate consumption

[workspace]
name = "agentops"
provider = "claude"
global_fragments = ["agentops-doctrine", "operating-loop", "standards-brief"]

[daemon]
formula_v2 = true            # enable graph.v2 formulas from the imported pack

[beads]
provider = "bd"              # consume GC's bd/dolt substrate — do NOT reimplement

[session]
provider = "tmux"            # swap to exec/k8s without touching agents

[mail]
provider = "bd"              # mail = a bead (messaging is GC-derived)

[imports.agentops]           # ← the ONLY opinion. Expands the pack's agents/orders.

Two load-bearing guards (do not violate)

• Dolt 1,478-flap guard (consume-only). [beads] provider is pure CLIENT config (which CLI to shell out to), NOT a managed server. Do not add an [imports] of the dolt pack or any dolt-managing Order: that would make GC's reconciler claim exclusive ownership of a Dolt server an operator already runs and flap it (the Olympus 1,478-restart failure mode). For cross-host dolt, point provider at the already-running server's CLI; never let GC own it.
• Single-prefix posture. The rig's .beads/ owns the issue prefix (e.g. soc). The City does NOT use GC's two-level hq-* / routes.jsonl split — that would need a second served DB and fork the tracker. One prefix per served DB; gc bd and standalone bd share the same store.

Pack layout (packs/agentops/)

pack.toml                                named_session bindings: mayor + refinery
agents/mayor/{agent.toml,prompt.template.md}      team-lead: orchestrate/merge/notify
agents/refinery/{agent.toml,prompt.template.md}   worker: runs `ao rpi` (one unit)
formulas/rpi-dispatch.toml               THIN 1-step dispatch → `ao rpi <bead>`
formulas/evolve-dispatch.toml            THIN 1-step dispatch → `ao evolve`
orders/bead-dispatch.toml                cooldown sweep → rpi-dispatch (REFERENCE — see gap)
orders/evolve-cadence.toml               cron → evolve-dispatch (mayor pool)
orders/compile-corpus.toml               exec order → ao compile
orders/maturity-scan.toml                exec order → ao maturity --scan
template-fragments/{agentops-doctrine,operating-loop,standards-brief}.template.md
assets/scripts/{install-ao.sh,worktree-setup.sh,ao-compile.sh,sync-overlay-skills.sh}
overlay/.claude/settings.json            GC substrate hooks only (hookless-first)
overlay/.claude/skills/                  PINNED curated skill snapshot + PROVENANCE.md

The two agents

The refinery's pre_start prepares an isolated git worktree and installs the AgentOps runtime (ao + skills scaffolding) into it; overlay_dir copies the skill corpus + harness hook config into the working dir. There is deliberately NO default_sling_formula — a slung bead routes the RAW bead to the worker, whose prompt runs ao rpi <bead> (one command). A default_sling_formula would re-introduce a GC-side 4-step decomposition, which the THIN-SEAM correction forbids.

Hookless-first overlay

overlay/.claude/settings.json ships ONLY the GC coordination substrate hooks (gc prime / gc handoff / gc mail check / gc hook). Per docs/3.0.md, AgentOps 3.0 ships zero AgentOps hooks: context flows through the explicit ao CLI channel — ao rpi runs ao inject inside its Research phase and the mayor calls ao corpus inject --query directly, so no harness hook is needed.

The overlay skills are a PINNED, curated core-loop subset (the loop runtime an agent actually invokes), regenerated by assets/scripts/sync-overlay-skills.sh (--check = drift detector). Source of truth stays skills/; the overlay is a derived snapshot.