gc sling routes work to session configs. Multi-session configs are valid
targets — sling to the config and any eligible session can claim the work.
You do NOT need to find or create an individual session first.
Quick reference
gc sling <bead-id> # Auto-target via rig's default_sling_target
gc sling <session-config> <bead-id> # Route to a specific session config
gc sling <session-config> -f <formula> # Instantiate formula, route its root (v2 → workflow)
gc sling <session-config> <bead-id> --on <formula> # Attach formula to existing bead (v2 → workflow)
Targeting
The <session-config> is a qualified config name from gc session list:
- Single-session config:
mayor,hello-world/refinery - Multi-session config:
hello-world/polecat— routes to the config's shared work queue
1-arg shorthand: When target is omitted, sling derives it from the
bead's rig prefix. The rig's default_sling_target in city.toml determines
where work goes. Example: bead hw-42 → rig hello-world → target
hello-world/polecat.
Rig-scoped beads: gc sling automatically resolves the rig directory
for rig-scoped bead IDs (e.g. hw-abc) and runs gc bd update from there,
so the rig's .beads database is found without manual intervention.
Beads must be in the agent's rig database. Sling operates on the
target agent's rig database — formula cooking, labeling, and convoy
creation all happen there. Create the bead in a specific rig's database
with gc bd create --rig <rig>, which resolves the rig from city config
and uses its database and prefix:
gc bd create "fix the bug" --rig frontend # Creates fe-xxx in frontend's db
gc sling frontend/polecat fe-xxx # Works — bead is in the right db
If the bead is in the wrong database (e.g. gc-xxx in HQ but targeting
a frontend agent), sling's cross-rig guard will block the route.
Direct dispatch (bead to session config)
gc sling <session-config> <bead-id> # Route a bead to a session config
gc sling <bead-id> # Use rig's default_sling_target
The agent receives the bead on its hook and runs it per GUPP.
Formula dispatch (-f, formula creates its own root bead)
gc sling <agent> -f <formula> # Instantiate a formula, route its root bead
Instantiates the formula and routes its root bead to the target. What the
instantiation produces depends on the formula's compiler contract: a v2
formula (one declaring [requires] formula_compiler = ">=2.0.0") starts a
workflow; a v1 formula instantiates a wisp (an ephemeral molecule).
Use -f when the formula defines the work itself — when you already have a work
bead, use --on (below). A formula that references {{convoy_id}} or contains
a drain step cannot be launched bare with -f; route it onto a bead with --on
so a target convoy is created.
Formula-on-bead dispatch (--on, formula runs against an existing bead)
gc sling <agent> <bead-id> --on <formula> # Attach a formula to an existing bead
--on attaches a formula to a bead that already exists — the bead is the
work; the formula supplies the method. What gets created depends on the
formula's compiler contract:
- v2 formula (
[requires] formula_compiler = ">=2.0.0") — starts a workflow. The sling creates a workflow-root bead and an auto-convoy, with your bead tracked as the work member (root + convoy + work bead). The step DAG and handoff metadata (branch,target, …) are persisted as beads, so they survive a session recycle — a recycled agent resumes the same branch instead of stranding it. - v1 formula — instantiates a wisp (an ephemeral molecule) in place on the bead.
Convoy-referencing formulas require a target convoy. A v2 formula that
references {{convoy_id}} or contains a drain step must launch onto a convoy —
routing with --on satisfies that, because the sling normalizes the target into
an input convoy, creating a one-item convoy that tracks your bead when the
target is not already a convoy. That input convoy is not optional: --no-convoy
suppresses only the ordinary routing auto-convoy, not the v2 input convoy. To run
the workflow against a convoy you already have, pass that convoy as the target
(gc formula cook <formula> --attach <convoy-id>). Launching such a formula bare
with -f is rejected.
Formulas
gc formula list # List available formulas
gc formula show <name> # Show formula definition
Choosing a work formula
Work formulas differ by isolation (does the agent get its own worktree and branch?) and handoff (does the agent land the change itself, or hand off to a separate merge-review step?). Reach for the lightest one that fits:
| Formula | Isolation | Lands the change | Use when |
|---|---|---|---|
mol-do-work |
none — works in the CWD | agent commits, then closes the bead | demos, throwaway, or a trivial single-agent fix where isolation and review are overkill |
mol-scoped-work |
worktree + explicit setup/teardown | agent-managed, no refinery — work modeled as a routable step-bead DAG | multi-step work you want decomposed into independently-routable steps under one owner, without a merge-review gate |
mol-polecat-work |
worktree + feature branch | pushes the branch and reassigns to the refinery for merge review | production multi-agent work that must be reviewed before landing on a shared branch — the default for pooled polecats |
Two narrower siblings trade a stage away from mol-polecat-work:
mol-polecat-commit— worktree + quality gates, but commits directly to the base branch (no feature branch, no refinery). For small installs where merge review is unnecessary.mol-polecat-report— no checkout; the agent investigates and writes findings to bead notes. For analysis/investigation beads whose output is a report, not a code change.
Rule of thumb: choose mol-polecat-work for anything that must land through
review or survive a session recycle — its workflow state and branch/target
metadata live in beads, so a recycled agent resumes the branch instead of
stranding it. Use mol-scoped-work when you want worktree isolation and
step-level routing but own the work end-to-end and need no merge-review handoff.
Drop to mol-do-work only for the trivial single-agent case.
When the refinery handoff doesn't apply. mol-polecat-work ends by pushing a
feature branch and reassigning the bead to the refinery, which merges it into the
rig's own repo. Two kinds of work break that contract — model them as plain
beads with a coordinator/mayor handoff instead of attaching this formula:
- Cross-repo / GitHub deliverables. When the change must land in a different
repo than the one the rig's refinery merges (e.g. a change to a GitHub fork PR
rather than the rig's own repo), the refinery has nothing to merge and the
branch/targetmetadata points at the wrong remote. Diverge from the formula: edit the fork clone, push, open the PR yourself, and hand the bead to the coordinator — not the refinery (gas-city precedent: gci-7ti). - Mayor-publish-rail beads. When a bead is shipped-and-closed by a mayor
publish step (not by the formula's own submit step), an attached v2 workflow
leaves its
submit-and-exit/finalizesteps live and routable after the bead closes — an unrelated pool agent then claims the moot step (churn + manual cleanup). Untilmol-port-review(packs#260), whose stage 3 is the mayor publish, lands, use plain beads for mayor-rail work; interim, the mayor drains the attached workflow at publish time.
Built-in formulas
mol-do-work — Simple work lifecycle. Agent reads the bead, implements the solution in the current working directory, and closes the bead. No git branching, no worktree isolation, no refinery handoff. Good for demos and simple single-agent workflows.
gc sling <agent> <bead-id> --on mol-do-work
mol-scoped-work — Graph-first worktree lifecycle (v2 workflow). Models the work as an explicit DAG — a durable scope bead, explicit worktree setup and teardown, and first-class step beads that can be routed independently, with continuation metadata for same-session execution. The opt-in replacement for hierarchy-first single-session formulas; agent-managed, with no refinery handoff.
gc sling <agent> <bead-id> --on mol-scoped-work
mol-polecat-commit — Direct-commit variant. Creates a worktree but commits directly to base_branch with no feature branch or refinery step. Includes preflight tests, implementation, and self-review quality gates. For small installations where merge review is unnecessary.
gc sling <agent> <bead-id> --on mol-polecat-commit
mol-polecat-report — Report-only variant. No git checkout, no feature branch, no push, no PR. The agent investigates, writes findings as bead notes, and exits. Use for analysis or investigation tasks where the output is a written report, not a code change.
gc sling <agent> <bead-id> --on mol-polecat-report
mol-polecat-base — Shared base for polecat work formulas. Defines the common steps (load context, preflight, implement, self-review) that variant formulas extend. Not typically used directly — use a variant like mol-polecat-commit, mol-polecat-report, or mol-polecat-work instead.
mol-prompt-synth — Formula side of gc prompt synth --writer-agent <name>.
Reads a pre-rendered meta-prompt from disk, generates an agent prompt
template, and writes it to a destination path.
mol-review-quorum — Graph-first review quorum scaffold. Fans out two read-only reviewer lanes (lane IDs, providers, models, and dispatch targets supplied by formula variables), then routes a synthesis agent to combine their durable structured outputs.
mol-scoped-work — Graph-first worktree lifecycle; the built-in v2
workflow prototype. Models work as an explicit DAG with a durable body
scope bead, explicit worktree setup/teardown, independently routable step
beads, and continuation metadata for same-session execution. Opt-in
replacement for hierarchy-first single-session formulas.
Gastown pack formulas (work variants)
These require the gastown pack. They extend the built-in
mol-polecat-base.
mol-polecat-work — Feature-branch variant. Creates a worktree and feature branch, implements, then pushes and reassigns to the refinery for merge review. Production default for multi-agent setups.
gc sling <agent> <bead-id> --on mol-polecat-work
The polecat cuts its branch from origin/<base_branch> and stamps
metadata.target for the refinery, so base_branch decides where the
work lands. gc sling resolves it in this order, first match wins:
metadata.targeton the work bead, or on the nearest parent convoy that carries one — the per-bead override.default_branchrecorded for the bead's rig incity.toml.default_branchrecorded for the agent's rig incity.toml.- A live probe of the rig repo's
origin/HEAD.
Tiers 2 and 3 are the knob to reach for when a repo's mainline is not
what origin/HEAD advertises. A repo whose origin/HEAD still points at
a mirror-only main while work belongs on an integration branch sets it
once, per rig:
[[rigs]]
name = "myrig"
default_branch = "develop"
Without that, resolution falls through to the tier-4 probe and every
polecat branch is cut from the mirror. gc rig add captures
default_branch from the repo at add time, so a rig registered before
its mainline moved keeps the stale value until you update it — check
gc rig list --json rather than inferring the answer from
git symbolic-ref refs/remotes/origin/HEAD, which only ever reports
tier 4.
mol-idea-to-plan — Planning workflow for a coordinator session. Turns a
rough idea into a PRD, reviewed design doc, and beads DAG using Gas City's
existing primitives: repo-local artifact files, review task beads, gc sling,
and mail. Best run from a crew worker in the target rig.
gc sling <coordinator-agent> -f mol-idea-to-plan --var problem="..." --var review_target=<rig>/polecat
mol-review-leg — Helper formula used by mol-idea-to-plan review tasks.
Persists the full report to bead notes, mails the coordinator, closes the bead,
and drains the session. Usually not slung by hand.
Gastown pack formulas (patrol loops)
Patrol formulas are auto-poured by agent startup prompts — you typically don't sling these manually:
- mol-refinery-patrol — Refinery merge loop (check for work, merge one branch, repeat)
- mol-witness-patrol — Rig work-health monitor (orphan recovery, stuck polecats, help mail)
- mol-deacon-patrol — Controller sidekick (work-layer health, system diagnostics)
- mol-shutdown-dance — Due process for stuck agents (interrogate → execute → epitaph)
mol-digest-generate (the periodic activity digest mailed to the mayor) is
not a startup patrol pour: it is driven by an order on a schedule (the
digest-generate order — a 24h cooldown trigger). Run or inspect it through
its order (gc order run digest-generate, gc order show digest-generate), not
as a manual sling or a patrol pour.
Convoys (grouped work)
gc convoy create <name> <bead-ids...> # Group beads into a convoy
gc convoy create <name> --owned --target integration/<slug> # Long-lived initiative convoy
gc convoy target <id> <branch> # Set/update convoy target branch
gc convoy list # List active convoys
gc convoy status <id> # Show convoy progress + metadata
gc convoy add <id> <bead-ids...> # Add beads to convoy
gc convoy close <id> # Close convoy
gc convoy check # MUTATING: scans ALL open convoys city-wide and auto-closes any where all children are resolved
gc convoy stranded # Find convoys with no progress
gc convoy autoclose <id> # Internal: invoked by bd's on_close hook to auto-close a closed bead's completed convoys
Migration note:
- Existing epic beads are no longer first-class containers. Migrate open epics to convoys before relying on convoy-only tooling such as
gc convoy target,gc sling <convoy>, or the Gastown refinery convoy flow.
Orders
gc order list # List order rules
gc order show <name> # Show order definition
gc order run <name> # Manually trigger an order
gc order check # Evaluate all orders' trigger conditions and show which are due
gc order history <name> # Show order run history