# Gc Dispatch > Routing work to agents with gc sling and formulas - Skill: `gastownhall/gc-dispatch` (Agent Skill) - Install (CLI): `npx skillmds@latest add gastownhall/gc-dispatch` - Raw SKILL.md: https://api.skillmd.com/api/skills/gastownhall/gc-dispatch/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: gastownhall (https://skillmd.com/u/gastownhall) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/gastownhall/gc-dispatch --- # Dispatching Work `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 # Auto-target via rig's default_sling_target gc sling # Route to a specific session config gc sling -f # Instantiate formula, route its root (v2 → workflow) gc sling --on # Attach formula to existing bead (v2 → workflow) ``` ## Targeting The `` 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 `, 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 # Route a bead to a session config gc sling # 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 -f # 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 --on # 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 --attach `). Launching such a formula bare with `-f` is rejected. ## Formulas ``` gc formula list # List available formulas gc formula show # 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`/`target` metadata 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`/`finalize` steps live and routable *after* the bead closes — an unrelated pool agent then claims the moot step (churn + manual cleanup). Until `mol-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 --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 --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 --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 --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 `. 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 --on mol-polecat-work ``` The polecat cuts its branch from `origin/` 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: 1. `metadata.target` on the work bead, or on the nearest parent convoy that carries one — the per-bead override. 2. `default_branch` recorded for the bead's rig in `city.toml`. 3. `default_branch` recorded for the agent's rig in `city.toml`. 4. 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: ```toml [[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 -f mol-idea-to-plan --var problem="..." --var review_target=/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 # Group beads into a convoy gc convoy create --owned --target integration/ # Long-lived initiative convoy gc convoy target # Set/update convoy target branch gc convoy list # List active convoys gc convoy status # Show convoy progress + metadata gc convoy add # Add beads to convoy gc convoy close # 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 # 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 `, or the Gastown refinery convoy flow. ## Orders ``` gc order list # List order rules gc order show # Show order definition gc order run # Manually trigger an order gc order check # Evaluate all orders' trigger conditions and show which are due gc order history # Show order run history ```