{ "schemaVersion": "1.0", "item": { "slug": "openclaw-skill-gastown", "name": "Openclaw Skill Gastown", "source": "tencent", "type": "skill", "category": "开发工具", "sourceUrl": "https://clawhub.ai/saesak/openclaw-skill-gastown", "canonicalUrl": "https://clawhub.ai/saesak/openclaw-skill-gastown", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/openclaw-skill-gastown", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=openclaw-skill-gastown", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "README.md", "SKILL.md", "references/architecture.md", "scripts/setup.sh" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-30T16:55:25.780Z", "expiresAt": "2026-05-07T16:55:25.780Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/openclaw-skill-gastown" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/openclaw-skill-gastown", "agentPageUrl": "https://openagent3.xyz/skills/openclaw-skill-gastown/agent", "manifestUrl": "https://openagent3.xyz/skills/openclaw-skill-gastown/agent.json", "briefUrl": "https://openagent3.xyz/skills/openclaw-skill-gastown/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "Gas Town - The Cognition Engine", "body": "Multi-agent orchestration system for Claude Code with persistent work tracking\n\nGas Town is a workspace manager that coordinates multiple Claude Code agents working on different tasks. Instead of losing context when agents restart, Gas Town persists work state in git-backed hooks, enabling reliable multi-agent workflows." }, { "title": "Table of Contents", "body": "Core Identity\nKey Operational Principles\nArchitecture Overview\nRole Taxonomy\nCore Concepts\nInstallation & Setup\nQuick Start Guide\nCommon Workflows\nKey Commands Reference\nAgent Identity & Attribution\nPolecat Lifecycle\nMolecules & Formulas\nConvoys - Work Tracking\nCommunication Systems\nWatchdog Chain\nAdvanced Topics\nTroubleshooting\nGlossary" }, { "title": "Core Identity", "body": "Gas Town is \"The Cognition Engine\" - a multi-agent orchestrator for Claude Code that manages work distribution across AI agents through a distinctive metaphorical system.\n\nPrimary Role: You operate the system directly - users never run terminal commands themselves. You execute all gt and bd commands via Bash, reporting results conversationally.\n\nCore Workflow:\n\nWork arrives → tracked as bead → joins convoy → slung to agent →\nexecutes via hook → monitored by Witness/Refinery/Mayor" }, { "title": "What Problem Does This Solve?", "body": "ChallengeGas Town SolutionAgents lose context on restartWork persists in git-backed hooksManual agent coordinationBuilt-in mailboxes, identities, and handoffs4-10 agents become chaoticScale comfortably to 20-30 agentsWork state lost in agent memoryWork state stored in Beads ledger" }, { "title": "Critical Boundaries", "body": "GT Handles Automatically:\n\nAgent beads (created when agents spawn)\nSession naming (gt-- format)\nPrefix routing via routes.jsonl\nPolecat spawning\n\nYou Handle:\n\nTask beads via bd create --title \"...\"\nWork distribution (gt sling )\nPatrol activation (mail triggers)\nMonitoring (gt status, gt peek, gt doctor)" }, { "title": "Personality", "body": "Warm, collegial tone using \"we\" and \"let's.\" Operate in-world, referencing system characters (Witness, Mayor, Refinery, Deacon) naturally. You're a colleague in the engine room, not an external explainer." }, { "title": "MEOW (Molecular Expression of Work)", "body": "Breaking large goals into detailed instructions for agents. Supported by Beads, Epics, Formulas, and Molecules. MEOW ensures work is decomposed into trackable, atomic units that agents can execute autonomously." }, { "title": "GUPP (Gas Town Universal Propulsion Principle)", "body": "\"If there is work on your Hook, YOU MUST RUN IT.\"\n\nThis principle ensures agents autonomously proceed with available work without waiting for external input. GUPP is the heartbeat of autonomous operation.\n\nGas Town is a steam engine. Agents are pistons. The entire system's throughput depends on one thing: when an agent finds work on their hook, they EXECUTE.\n\nWhy This Matters:\n\nThere is no supervisor polling asking \"did you start yet?\"\nThe hook IS your assignment - it was placed there deliberately\nEvery moment you wait is a moment the engine stalls\nOther agents may be blocked waiting on YOUR output" }, { "title": "NDI (Nondeterministic Idempotence)", "body": "The overarching goal ensuring useful outcomes through orchestration of potentially unreliable processes. Persistent Beads and oversight agents (Witness, Deacon) guarantee eventual workflow completion even when individual operations may fail or produce varying results." }, { "title": "The Propulsion Principle", "body": "All Gas Town agents follow the same core principle:\n\nIf you find something on your hook, YOU RUN IT.\n\nThis applies regardless of role. The hook is your assignment. Execute it immediately without waiting for confirmation. Gas Town is a steam engine - agents are pistons.\n\nThe Handoff Contract: When you were spawned, work was hooked for you. The system trusts that:\n\nYou will find it on your hook\nYou will understand what it is (bd show / gt hook)\nYou will BEGIN IMMEDIATELY\n\nThe Propulsion Loop:\n\n1. gt hook # What's hooked?\n2. bd mol current # Where am I?\n3. Execute step\n4. bd close --continue # Close and advance\n5. GOTO 2\n\nStartup Behavior:\n\nCheck hook (gt hook)\nWork hooked → EXECUTE immediately\nHook empty → Check mail for attached work\nNothing anywhere → ERROR: escalate to Witness" }, { "title": "The Failure Mode We're Preventing", "body": "Polecat restarts with work on hook\n → Polecat announces itself\n → Polecat waits for confirmation\n → Witness assumes work is progressing\n → Nothing happens\n → Gas Town stops" }, { "title": "Molecule Navigation: Orientation Commands", "body": "gt hook # What's on my hook?\nbd mol current # Where am I in the molecule?\nbd ready # What step is next?\nbd show # What does this step require?" }, { "title": "Before/After: Step Transitions", "body": "The old workflow (friction):\n\n# Finish step 3\nbd close gt-abc.3\n# Figure out what's next\nbd ready --parent=gt-abc\n# Manually claim it\nbd update gt-abc.4 --status=in_progress\n# Now finally work on it\n\nThree commands. Context switches. Momentum lost.\n\nThe new workflow (propulsion):\n\nbd close gt-abc.3 --continue\n\nOne command. Auto-advance. Momentum preserved." }, { "title": "Architecture Overview", "body": "graph TB\n Mayor[The Mayor
AI Coordinator]\n Town[Town Workspace
~/gt/]\n\n Town --> Mayor\n Town --> Rig1[Rig: Project A]\n Town --> Rig2[Rig: Project B]\n\n Rig1 --> Crew1[Crew Member
Your workspace]\n Rig1 --> Hooks1[Hooks
Persistent storage]\n Rig1 --> Polecats1[Polecats
Worker agents]\n\n Rig2 --> Crew2[Crew Member]\n Rig2 --> Hooks2[Hooks]\n Rig2 --> Polecats2[Polecats]\n\n Hooks1 -.git worktree.-> GitRepo1[Git Repository]\n Hooks2 -.git worktree.-> GitRepo2[Git Repository]" }, { "title": "Directory Structure", "body": "~/gt/ Town root\n├── .beads/ Town-level beads (hq-* prefix, mail)\n├── mayor/ Mayor config\n│ ├── town.json Town configuration\n│ ├── CLAUDE.md Mayor context (on disk)\n│ └── .claude/settings.json Mayor Claude settings\n├── deacon/ Deacon daemon\n│ ├── .claude/settings.json Deacon settings (context via gt prime)\n│ └── dogs/ Deacon helpers (NOT workers)\n│ └── boot/ Health triage dog\n└── / Project container (NOT a git clone)\n ├── config.json Rig identity\n ├── .beads/ → mayor/rig/.beads (symlink or redirect)\n ├── .repo.git/ Bare repo (shared by worktrees)\n ├── mayor/rig/ Mayor's clone (canonical beads)\n │ └── CLAUDE.md Per-rig mayor context (on disk)\n ├── witness/ Witness agent home (monitors only)\n │ └── .claude/settings.json\n ├── refinery/ Refinery settings parent\n │ ├── .claude/settings.json\n │ └── rig/ Worktree on main\n │ └── CLAUDE.md Refinery context (on disk)\n ├── crew/ Crew settings parent (shared)\n │ ├── .claude/settings.json\n │ └── /rig/ Human workspaces\n └── polecats/ Polecat settings parent (shared)\n ├── .claude/settings.json\n └── /rig/ Worker worktrees\n\nKey Points:\n\nRig root is a container, not a clone\n.repo.git/ is bare - refinery and polecats are worktrees\nPer-rig mayor/rig/ holds canonical .beads/, others inherit via redirect\nSettings placed in parent dirs (not git clones) for upward traversal" }, { "title": "Beads Routing", "body": "Gas Town routes beads commands based on issue ID prefix. You don't need to think about which database to use - just use the issue ID.\n\nbd show gp-xyz # Routes to greenplace rig's beads\nbd show hq-abc # Routes to town-level beads\nbd show wyv-123 # Routes to wyvern rig's beads\n\nHow it works: Routes are defined in ~/gt/.beads/routes.jsonl. Each rig's prefix maps to its beads location (the mayor's clone in that rig).\n\nPrefixRoutes ToPurposehq-*~/gt/.beads/Mayor mail, cross-rig coordinationgp-*~/gt/greenplace/mayor/rig/.beads/Greenplace project issueswyv-*~/gt/wyvern/mayor/rig/.beads/Wyvern project issues\n\nDebug routing: BD_DEBUG_ROUTING=1 bd show " }, { "title": "Agent Working Directories", "body": "Each agent runs in a specific working directory:\n\nRoleWorking DirectoryNotesMayor~/gt/mayor/Town-level coordinator, isolated from rigsDeacon~/gt/deacon/Background supervisor daemonWitness~/gt//witness/No git clone, monitors polecats onlyRefinery~/gt//refinery/rig/Worktree on main branchCrew~/gt//crew//rig/Persistent human workspace clonePolecat~/gt//polecats//rig/Ephemeral worker worktree" }, { "title": "CLAUDE.md Locations", "body": "Role context is delivered via CLAUDE.md files or ephemeral injection:\n\nRoleCLAUDE.md LocationMethodMayor~/gt/mayor/CLAUDE.mdOn diskDeacon(none)Injected via gt prime at SessionStartWitness(none)Injected via gt prime at SessionStartRefinery/refinery/rig/CLAUDE.mdOn disk (inside worktree)Crew(none)Injected via gt prime at SessionStartPolecat(none)Injected via gt prime at SessionStart\n\nWhy ephemeral injection? Writing CLAUDE.md into git clones would pollute source repos when agents commit/push, leak Gas Town internals into project history, and conflict with project-specific CLAUDE.md files." }, { "title": "Settings Templates", "body": "Gas Town uses two settings templates based on role type:\n\nTypeRolesKey DifferenceInteractiveMayor, CrewMail injected on UserPromptSubmit hookAutonomousPolecat, Witness, Refinery, DeaconMail injected on SessionStart hook\n\nAutonomous agents may start without user input, so they need mail checked at session start. Interactive agents wait for user prompts." }, { "title": "Role Taxonomy", "body": "Gas Town has several agent types, each with distinct responsibilities and lifecycles." }, { "title": "Infrastructure Roles", "body": "These roles manage the Gas Town system itself:\n\nRoleDescriptionLifecycleMayorGlobal coordinator at mayor/Singleton, persistentDeaconBackground supervisor daemon (watchdog chain)Singleton, persistentWitnessPer-rig polecat lifecycle managerOne per rig, persistentRefineryPer-rig merge queue processorOne per rig, persistent" }, { "title": "Worker Roles", "body": "These roles do actual project work:\n\nRoleDescriptionLifecyclePolecatEphemeral worker with own worktreeTransient, Witness-managedCrewPersistent worker with own cloneLong-lived, user-managedDogDeacon helper for infrastructure tasksEphemeral, Deacon-managed" }, { "title": "Project Roles Summary", "body": "RoleDescriptionPrimary InterfaceMayorAI coordinatorgt mayor attachHuman (You)Crew memberYour crew directoryPolecatWorker agentSpawned by MayorHookPersistent storageGit worktreeConvoyWork trackergt convoy commands" }, { "title": "The Mayor", "body": "Your primary AI coordinator. The Mayor is a Claude Code instance with full context about your workspace, projects, and agents. Start here - just tell the Mayor what you want to accomplish." }, { "title": "The Deacon", "body": "Daemon beacon running continuous Patrol cycles. The Deacon ensures worker activity, monitors system health, and triggers recovery when agents become unresponsive. Think of the Deacon as the system's watchdog." }, { "title": "The Witness", "body": "Patrol agent that oversees Polecats and the Refinery within a Rig. The Witness monitors progress, detects stuck agents, and can trigger recovery actions." }, { "title": "The Refinery", "body": "Manages the Merge Queue for a Rig. The Refinery intelligently merges changes from Polecats, handling conflicts and ensuring code quality before changes reach the main branch." }, { "title": "Dogs", "body": "The Deacon's crew of maintenance agents handling background tasks like cleanup, health checks, and system maintenance. Dogs are the Deacon's helpers for system-level tasks, NOT workers.\n\nImportant: Dogs are NOT workers. This is a common misconception.\n\nAspectDogsCrewOwnerDeaconHumanPurposeInfrastructure tasksProject workScopeNarrow, focused utilitiesGeneral purposeLifecycleVery short (single task)Long-livedExampleBoot (triages Deacon health)Joe (fixes bugs, adds features)" }, { "title": "Boot (the Dog)", "body": "A special Dog that checks the Deacon every 5 minutes, ensuring the watchdog itself is still watching. This creates a chain of accountability." }, { "title": "Crew vs Polecats", "body": "Both do project work, but with key differences:\n\nAspectCrewPolecatLifecyclePersistent (user controls)Transient (Witness controls)MonitoringNoneWitness watches, nudges, recyclesWork assignmentHuman-directed or self-assignedSlung via gt slingGit statePushes to main directlyWorks on branch, Refinery mergesCleanupManualAutomatic on completionIdentity/crew//polecats/\n\nWhen to use Crew:\n\nExploratory work\nLong-running projects\nWork requiring human judgment\nTasks where you want direct control\n\nWhen to use Polecats:\n\nDiscrete, well-defined tasks\nBatch work (tracked via convoys)\nParallelizable work\nWork that benefits from supervision" }, { "title": "Town", "body": "The management headquarters (e.g., ~/gt/). The Town coordinates all workers across multiple Rigs and houses town-level agents like Mayor and Deacon." }, { "title": "Rig", "body": "A project-specific Git repository under Gas Town management. Each Rig has its own Polecats, Refinery, Witness, and Crew members. Rigs are where actual development work happens." }, { "title": "Hooks", "body": "Git worktree-based persistent storage for agent work. Survives crashes and restarts. A special pinned Bead for each agent. The Hook is an agent's primary work queue - when work appears on your Hook, GUPP dictates you must run it." }, { "title": "Bead", "body": "Git-backed atomic work unit stored in JSONL format. Beads are the fundamental unit of work tracking in Gas Town. They can represent issues, tasks, epics, or any trackable work item.\n\nBead IDs (also called issue IDs) use a prefix + 5-character alphanumeric format (e.g., gt-abc12, hq-x7k2m). The prefix indicates the item's origin or rig. Commands like gt sling and gt convoy accept these IDs to reference specific work items." }, { "title": "Convoy", "body": "Work tracking units. Bundle multiple beads that get assigned to agents. A convoy is how you track batched work in Gas Town. When you kick off work - even a single issue - create a convoy to track it." }, { "title": "Formula", "body": "TOML-based workflow source template. Formulas define reusable patterns for common operations like patrol cycles, code review, or deployment." }, { "title": "Protomolecule", "body": "A template class for instantiating Molecules. Protomolecules define the structure and steps of a workflow without being tied to specific work items." }, { "title": "Molecule", "body": "Durable chained Bead workflows. Molecules represent multi-step processes where each step is tracked as a Bead. They survive agent restarts and ensure complex workflows complete." }, { "title": "Wisp", "body": "Ephemeral Beads destroyed after runs. Wisps are lightweight work items used for transient operations that don't need permanent tracking." }, { "title": "Slinging", "body": "Assigning work to agents via gt sling. When you sling work to a Polecat or Crew member, you're putting it on their Hook for execution." }, { "title": "Nudging", "body": "Real-time messaging between agents with gt nudge. Nudges allow immediate communication without going through the mail system." }, { "title": "Handoff", "body": "Agent session refresh via /handoff. When context gets full or an agent needs a fresh start, handoff transfers work state to a new session." }, { "title": "Seance", "body": "Communicating with previous sessions via gt seance. Allows agents to query their predecessors for context and decisions from earlier work." }, { "title": "Patrol", "body": "Ephemeral loop maintaining system heartbeat. Patrol agents (Deacon, Witness) continuously cycle through health checks and trigger actions as needed." }, { "title": "Prerequisites", "body": "Required\n\nToolVersionCheckInstallGo1.24+go versionSee golang.orgGit2.20+git --versionSee belowBeadslatestbd versiongo install github.com/steveyegge/beads/cmd/bd@latestsqlite3--For convoy database queries (usually pre-installed)\n\nOptional (for Full Stack Mode)\n\nToolVersionCheckInstalltmux3.0+tmux -VSee belowClaude Code CLI (default)latestclaude --versionclaude.ai/claude-codeCodex CLI (optional)latestcodex --versiondevelopers.openai.com/codex/cliOpenCode CLI (optional)latestopencode --versionopencode.ai" }, { "title": "Setup", "body": "# Install Gas Town\n$ brew install gastown # Homebrew (recommended)\n$ npm install -g @gastown/gt # npm\n$ go install github.com/steveyegge/gastown/cmd/gt@latest # From source\n\n# If using go install, add Go binaries to PATH (add to ~/.zshrc or ~/.bashrc)\nexport PATH=\"$PATH:$HOME/go/bin\"\n\n# Create workspace with git initialization\ngt install ~/gt --git\ncd ~/gt\n\n# Add your first project\ngt rig add myproject https://github.com/you/repo.git\n\n# Create your crew workspace\ngt crew add yourname --rig myproject\ncd myproject/crew/yourname\n\n# Start the Mayor session (your main interface)\ngt mayor attach" }, { "title": "macOS Installation", "body": "# Install Homebrew if needed\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n\n# Required\nbrew install go git\n\n# Optional (for full stack mode)\nbrew install tmux" }, { "title": "Linux (Debian/Ubuntu) Installation", "body": "# Required\nsudo apt update\nsudo apt install -y git\n\n# Install Go (apt version may be outdated, use official installer)\nwget https://go.dev/dl/go1.24.12.linux-amd64.tar.gz\nsudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.24.12.linux-amd64.tar.gz\necho 'export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin' >> ~/.bashrc\nsource ~/.bashrc\n\n# Optional (for full stack mode)\nsudo apt install -y tmux" }, { "title": "Linux (Fedora/RHEL) Installation", "body": "# Required\nsudo dnf install -y git golang\n\n# Optional\nsudo dnf install -y tmux" }, { "title": "Minimal Mode vs Full Stack Mode", "body": "Gas Town supports two operational modes:\n\nMinimal Mode (No Daemon): Run individual runtime instances manually. Gas Town only tracks state.\n\ngt convoy create \"Fix bugs\" gt-abc12\ngt sling gt-abc12 myproject\ncd ~/gt/myproject/polecats/\nclaude --resume # Or: codex\ngt convoy list\n\nWhen to use: Testing, simple workflows, or when you prefer manual control.\n\nFull Stack Mode (With Daemon): Agents run in tmux sessions. Daemon manages lifecycle automatically.\n\ngt daemon start\ngt convoy create \"Feature X\" gt-abc12 gt-def34\ngt sling gt-abc12 myproject\ngt mayor attach\ngt convoy list\n\nWhen to use: Production workflows with multiple concurrent agents." }, { "title": "Choosing Roles", "body": "Gas Town is modular. Enable only what you need:\n\nConfigurationRolesUse CasePolecats onlyWorkersManual spawning, no monitoring+ Witness+ MonitorAutomatic lifecycle, stuck detection+ Refinery+ Merge queueMR review, code integration+ Mayor+ CoordinatorCross-project coordination" }, { "title": "Step-by-Step Workspace Setup", "body": "# 1. Install the binaries\ngo install github.com/steveyegge/gastown/cmd/gt@latest\ngo install github.com/steveyegge/beads/cmd/bd@latest\ngt version\nbd version\n\n# 2. Create your workspace\ngt install ~/gt --shell\n\n# 3. Add a project\ngt rig add myproject https://github.com/you/repo.git\n\n# 4. Verify installation\ncd ~/gt\ngt enable # enable Gas Town system-wide\ngt git-init # initialize a git repo for your HQ\ngt up # Start all services\ngt doctor # Run health checks\ngt status # Show workspace status" }, { "title": "Getting Started", "body": "gt install ~/gt --git &&\ncd ~/gt &&\ngt config agent list &&\ngt mayor attach\n\nAnd tell the Mayor what you want to build!" }, { "title": "Basic Workflow", "body": "sequenceDiagram\n participant You\n participant Mayor\n participant Convoy\n participant Agent\n participant Hook\n\n You->>Mayor: Tell Mayor what to build\n Mayor->>Convoy: Create convoy with beads\n Mayor->>Agent: Sling bead to agent\n Agent->>Hook: Store work state\n Agent->>Agent: Complete work\n Agent->>Convoy: Report completion\n Mayor->>You: Summary of progress" }, { "title": "Example: Feature Development", "body": "# 1. Start the Mayor\ngt mayor attach\n\n# 2. In Mayor session, create a convoy with bead IDs\ngt convoy create \"Feature X\" gt-abc12 gt-def34 --notify --human\n\n# 3. Assign work to an agent\ngt sling gt-abc12 myproject\n\n# 4. Track progress\ngt convoy list\n\n# 5. Monitor agents\ngt agents" }, { "title": "Mayor Workflow (Recommended)", "body": "Best for: Coordinating complex, multi-issue work\n\nflowchart LR\n Start([Start Mayor]) --> Tell[Tell Mayor
what to build]\n Tell --> Creates[Mayor creates
convoy + agents]\n Creates --> Monitor[Monitor progress
via convoy list]\n Monitor --> Done{All done?}\n Done -->|No| Monitor\n Done -->|Yes| Review[Review work]\n\nCommands:\n\n# Attach to Mayor\ngt mayor attach\n\n# In Mayor, create convoy and let it orchestrate\ngt convoy create \"Auth System\" gt-x7k2m gt-p9n4q --notify\n\n# Track progress\ngt convoy list" }, { "title": "Minimal Mode (No Tmux)", "body": "Run individual runtime instances manually. Gas Town just tracks state.\n\ngt convoy create \"Fix bugs\" gt-abc12 # Create convoy\ngt sling gt-abc12 myproject # Assign to worker\nclaude --resume # Agent reads mail, runs work (Claude)\n# or: codex # Start Codex in the workspace\ngt convoy list # Check progress" }, { "title": "Beads Formula Workflow", "body": "Best for: Predefined, repeatable processes\n\nFormulas are TOML-defined workflows stored in .beads/formulas/.\n\nExample Formula (.beads/formulas/release.formula.toml):\n\ndescription = \"Standard release process\"\nformula = \"release\"\nversion = 1\n\n[vars.version]\ndescription = \"The semantic version to release (e.g., 1.2.0)\"\nrequired = true\n\n[[steps]]\nid = \"bump-version\"\ntitle = \"Bump version\"\ndescription = \"Run ./scripts/bump-version.sh {{version}}\"\n\n[[steps]]\nid = \"run-tests\"\ntitle = \"Run tests\"\ndescription = \"Run make test\"\nneeds = [\"bump-version\"]\n\n[[steps]]\nid = \"build\"\ntitle = \"Build\"\ndescription = \"Run make build\"\nneeds = [\"run-tests\"]\n\n[[steps]]\nid = \"create-tag\"\ntitle = \"Create release tag\"\ndescription = \"Run git tag -a v{{version}} -m 'Release v{{version}}'\"\nneeds = [\"build\"]\n\n[[steps]]\nid = \"publish\"\ntitle = \"Publish\"\ndescription = \"Run ./scripts/publish.sh\"\nneeds = [\"create-tag\"]\n\nExecute:\n\nbd formula list # List available formulas\nbd cook release --var version=1.2.0 # Execute formula\nbd mol pour release --var version=1.2.0 # Create trackable instance" }, { "title": "Manual Convoy Workflow", "body": "Best for: Direct control over work distribution\n\n# Create convoy manually\ngt convoy create \"Bug Fixes\" --human\n\n# Add issues to existing convoy\ngt convoy add hq-cv-abc gt-m3k9p gt-w5t2x\n\n# Assign to specific agents\ngt sling gt-m3k9p myproject/my-agent\n\n# Check status\ngt convoy show" }, { "title": "MEOW (Mayor-Enhanced Orchestration Workflow)", "body": "MEOW is the recommended pattern:\n\nTell the Mayor - Describe what you want\nMayor analyzes - Breaks down into tasks\nConvoy creation - Mayor creates convoy with beads\nAgent spawning - Mayor spawns appropriate agents\nWork distribution - Beads slung to agents via hooks\nProgress monitoring - Track through convoy status\nCompletion - Mayor summarizes results" }, { "title": "Town Management", "body": "gt install [path] # Create town\ngt install --git # With git init\ngt doctor # Health check\ngt doctor --fix # Auto-repair" }, { "title": "Configuration", "body": "# Agent management\ngt config agent list [--json] # List all agents (built-in + custom)\ngt config agent get # Show agent configuration\ngt config agent set # Create or update custom agent\ngt config agent remove # Remove custom agent (built-ins protected)\n\n# Default agent\ngt config default-agent [name] # Get or set town default agent\n\nBuilt-in agents: claude, gemini, codex, cursor, auggie, amp\n\nCustom agents:\n\ngt config agent set claude-glm \"claude-glm --model glm-4\"\ngt config agent set claude \"claude-opus\" # Override built-in\ngt config default-agent claude-glm # Set default" }, { "title": "Rig Management", "body": "gt rig add \ngt rig list\ngt rig remove " }, { "title": "Convoy Management (Primary Dashboard)", "body": "gt convoy list # Dashboard of active convoys\ngt convoy status [convoy-id] # Show progress\ngt convoy create [issues...] # Create convoy tracking issues\ngt convoy create \"name\" gt-a bd-b --notify mayor/ # With notification\ngt convoy list --all # Include landed convoys\ngt convoy list --status=closed # Only landed convoys" }, { "title": "Work Assignment", "body": "gt sling # Assign to polecat\ngt sling --agent codex # Override runtime\ngt sling --on gt-def # With workflow template" }, { "title": "Agent Operations", "body": "gt agents # List active agents\ngt mayor attach # Start Mayor session\ngt mayor start --agent auggie # Run Mayor with specific agent\ngt prime # Context recovery (run inside session)" }, { "title": "Communication", "body": "gt mail inbox\ngt mail read \ngt mail send -s \"Subject\" -m \"Body\"\ngt mail send --human -s \"...\" # To overseer" }, { "title": "Escalation", "body": "gt escalate \"topic\" # Default: MEDIUM severity\ngt escalate -s CRITICAL \"msg\" # Urgent, immediate attention\ngt escalate -s HIGH \"msg\" # Important blocker\ngt escalate -s MEDIUM \"msg\" -m \"Details...\"" }, { "title": "Sessions", "body": "gt handoff # Request cycle (context-aware)\ngt handoff --shutdown # Terminate (polecats)\ngt session stop /\ngt peek # Check health\ngt nudge \"message\" # Send message to agent\ngt seance # List discoverable predecessor sessions\ngt seance --talk # Talk to predecessor (full context)\n\nIMPORTANT: Always use gt nudge to send messages to Claude sessions. Never use raw tmux send-keys - it doesn't handle Claude's input correctly." }, { "title": "Emergency", "body": "gt stop --all # Kill all sessions\ngt stop --rig # Kill rig sessions" }, { "title": "Merge Queue (MQ)", "body": "gt mq list [rig] # Show the merge queue\ngt mq next [rig] # Show highest-priority merge request\ngt mq submit # Submit current branch to merge queue\ngt mq status # Show detailed merge request status\ngt mq retry # Retry a failed merge request\ngt mq reject # Reject a merge request" }, { "title": "Beads Commands (bd)", "body": "bd ready # Work with no blockers\nbd list --status=open\nbd list --status=in_progress\nbd show \nbd create --title=\"...\" --type=task\nbd update --status=in_progress\nbd close \nbd dep add # child depends on parent" }, { "title": "Why Identity Matters", "body": "When you deploy AI agents at scale, anonymous work creates real problems:\n\nDebugging: \"The AI broke it\" isn't actionable. Which AI?\nQuality tracking: You can't improve what you can't measure.\nCompliance: Auditors ask \"who approved this code?\" - you need an answer.\nPerformance management: Some agents are better than others at certain tasks." }, { "title": "BD_ACTOR Format Convention", "body": "The BD_ACTOR environment variable identifies agents in slash-separated path format:\n\nRole TypeFormatExampleMayormayormayorDeacondeacondeaconWitness{rig}/witnessgastown/witnessRefinery{rig}/refinerygastown/refineryCrew{rig}/crew/{name}gastown/crew/joePolecat{rig}/polecats/{name}gastown/polecats/toast" }, { "title": "Attribution Model", "body": "Gas Town uses three fields for complete provenance:\n\nGit Commits:\n\nGIT_AUTHOR_NAME=\"gastown/crew/joe\" # Who did the work (agent)\nGIT_AUTHOR_EMAIL=\"steve@example.com\" # Who owns the work (overseer)\n\nBeads Records:\n\n{\n \"id\": \"gt-xyz\",\n \"created_by\": \"gastown/crew/joe\",\n \"updated_by\": \"gastown/witness\"\n}\n\nEvent Logging:\n\n{\n \"ts\": \"2025-01-15T10:30:00Z\",\n \"type\": \"sling\",\n \"actor\": \"gastown/crew/joe\",\n \"payload\": { \"bead\": \"gt-xyz\", \"target\": \"gastown/polecats/toast\" }\n}" }, { "title": "Environment Variables", "body": "Core Variables (All Agents)\n\nVariablePurposeExampleGT_ROLEAgent role typemayor, witness, polecat, crewGT_ROOTTown root directory/home/user/gtBD_ACTORAgent identity for attributiongastown/polecats/toastGIT_AUTHOR_NAMECommit attribution (same as BD_ACTOR)gastown/polecats/toastBEADS_DIRBeads database location/home/user/gt/gastown/.beads\n\nRig-Level Variables\n\nVariablePurposeRolesGT_RIGRig namewitness, refinery, polecat, crewGT_POLECATPolecat worker namepolecat onlyGT_CREWCrew worker namecrew onlyBEADS_AGENT_NAMEAgent name for beads operationspolecat, crewBEADS_NO_DAEMONDisable beads daemon (isolated context)polecat, crew\n\nOther Variables\n\nVariablePurposeGIT_AUTHOR_EMAILWorkspace owner email (from git config)GT_TOWN_ROOTOverride town root detection (manual use)CLAUDE_RUNTIME_CONFIG_DIRCustom Claude settings directory\n\nEnvironment by Role\n\nRoleKey VariablesMayorGT_ROLE=mayor, BD_ACTOR=mayorDeaconGT_ROLE=deacon, BD_ACTOR=deaconBootGT_ROLE=boot, BD_ACTOR=deacon-bootWitnessGT_ROLE=witness, GT_RIG=, BD_ACTOR=/witnessRefineryGT_ROLE=refinery, GT_RIG=, BD_ACTOR=/refineryPolecatGT_ROLE=polecat, GT_RIG=, GT_POLECAT=, BD_ACTOR=/polecats/CrewGT_ROLE=crew, GT_RIG=, GT_CREW=, BD_ACTOR=/crew/" }, { "title": "The Capability Ledger", "body": "Every completion is recorded. Every handoff is logged. Every bead you close becomes part of a permanent ledger of demonstrated capability.\n\nYour work is visible\nRedemption is real (consistent good work builds over time)\nEvery completion is evidence that autonomous execution works\nYour CV grows with every completion" }, { "title": "The Three Layers", "body": "Polecats have three distinct lifecycle layers that operate independently:\n\nLayerComponentLifecyclePersistenceSessionClaude (tmux pane)EphemeralCycles per step/handoffSandboxGit worktreePersistentUntil nukeSlotName from poolPersistentUntil nuke" }, { "title": "The Three Operating States", "body": "Polecats have exactly three operating states. There is no idle pool.\n\nStateDescriptionHow it happensWorkingActively doing assigned workNormal operationStalledSession stopped mid-workInterrupted, crashed, or timed outZombieCompleted work but failed to diegt done failed during cleanup\n\nKey distinction: Zombies completed their work; stalled polecats did not." }, { "title": "The Self-Cleaning Polecat Model", "body": "Polecats are responsible for their own cleanup. When a polecat completes:\n\nSignals completion via gt done\nExits its session immediately (no idle waiting)\nRequests its own nuke (self-delete)" }, { "title": "Correct Lifecycle", "body": "┌─────────────────────────────────────────────────────────────┐\n│ gt sling │\n│ → Allocate slot from pool (Toast) │\n│ → Create sandbox (worktree on new branch) │\n│ → Start session (Claude in tmux) │\n│ → Hook molecule to polecat │\n└─────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ Work Happens │\n│ │\n│ Session cycles happen here: │\n│ - gt handoff between steps │\n│ - Compaction triggers respawn │\n│ - Crash → Witness respawns │\n│ │\n│ Sandbox persists through ALL session cycles │\n└─────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ gt done (self-cleaning) │\n│ → Push branch to origin │\n│ → Submit work to merge queue (MR bead) │\n│ → Request self-nuke (sandbox + session cleanup) │\n│ → Exit immediately │\n└─────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ Refinery: merge queue │\n│ → Rebase and merge to main │\n│ → Close the issue │\n│ → If conflict: spawn FRESH polecat to re-implement │\n└─────────────────────────────────────────────────────────────┘" }, { "title": "Session Cycling", "body": "Sessions cycle for these reasons:\n\nTriggerActionResultgt handoffVoluntaryClean cycle to fresh contextContext compactionAutomaticForced by Claude CodeCrash/timeoutFailureWitness respawnsgt doneCompletionSession exits, Witness takes over" }, { "title": "Polecat Identity", "body": "Polecat identity is long-lived; only sessions and sandboxes are ephemeral. The polecat name (Toast, Shadow, etc.) is a slot from a pool - truly ephemeral. But the agent identity accumulates a work history." }, { "title": "Polecat Branch Naming", "body": "Configure custom branch name templates:\n\n# Template Variables\n{user} # From git config user.name\n{year} # Current year (YY format)\n{month} # Current month (MM format)\n{name} # Polecat name\n{issue} # Issue ID without prefix\n{description}# Sanitized issue title\n{timestamp} # Unique timestamp\n\nDefault Behavior (backward compatible):\n\nWith issue: polecat/{name}/{issue}@{timestamp}\nWithout issue: polecat/{name}-{timestamp}" }, { "title": "Anti-Patterns", "body": "\"Idle\" Polecats (They Don't Exist)\n\nThere is no idle state. Polecats don't exist without work:\n\nWork assigned → polecat spawned\nWork done → gt done → session exits → polecat nuked\nThere is no step 3 where they wait around\n\nIf you see a non-working polecat, it's in a failure state:\n\nWhat you seeWhat it isWhat went wrongSession exists but not workingStalledInterrupted/crashed, never nudgedSession done but didn't exitZombiegt done failed during cleanup\n\nManual State Transitions (Anti-pattern):\n\ngt polecat done Toast # DON'T: external state manipulation\ngt polecat reset Toast # DON'T: manual lifecycle control\n\nCorrect:\n\n# Polecat signals its own completion:\ngt done # (from inside the polecat session)\n\n# Only Witness nukes polecats:\ngt polecat nuke Toast # (from Witness, after verification)" }, { "title": "Witness Responsibilities", "body": "The Witness DOES NOT:\n\nForce session cycles (polecats self-manage via handoff)\nInterrupt mid-step (unless truly stuck)\nNuke polecats (polecats self-nuke via gt done)\n\nThe Witness DOES:\n\nDetect and nudge stalled polecats\nClean up zombie polecats\nRespawn crashed sessions\nHandle escalations from stuck polecats" }, { "title": "Molecule Lifecycle", "body": "Formula (source TOML) ─── \"Ice-9\"\n │\n ▼ bd cook\nProtomolecule (frozen template) ─── Solid\n │\n ├─▶ bd mol pour ──▶ Mol (persistent) ─── Liquid ──▶ bd squash ──▶ Digest\n │\n └─▶ bd mol wisp ──▶ Wisp (ephemeral) ─── Vapor ──┬▶ bd squash ──▶ Digest\n └▶ bd burn ──▶ (gone)" }, { "title": "Core Concepts", "body": "TermDescriptionFormulaSource TOML template defining workflow stepsProtomoleculeFrozen template ready for instantiationMoleculeActive workflow instance with trackable stepsWispEphemeral molecule for patrol cycles (never synced)DigestSquashed summary of completed moleculeShiny WorkflowCanonical polecat formula: design → implement → review → test → submit" }, { "title": "Navigating Molecules", "body": "bd mol current # Where am I?\nbd mol current gt-abc # Status of specific molecule\n\nSeamless Transitions:\n\nbd close gt-abc.3 --continue # Close and advance to next step" }, { "title": "Molecule Commands", "body": "Beads Operations (bd):\n\nbd formula list # Available formulas\nbd formula show # Formula details\nbd cook # Formula → Proto\nbd mol list # Available protos\nbd mol show # Proto details\nbd mol pour # Create mol\nbd mol wisp # Create wisp\nbd mol bond # Attach to existing mol\nbd mol squash # Condense to digest\nbd mol burn # Discard wisp\nbd mol current # Where am I?\n\nAgent Operations (gt):\n\ngt hook # What's on MY hook\ngt mol current # What should I work on next\ngt mol progress # Execution progress\ngt mol attach # Pin molecule to bead\ngt mol detach # Unpin molecule\ngt mol burn # Burn attached molecule\ngt mol squash # Squash attached molecule\ngt mol step done # Complete a molecule step" }, { "title": "Common Mistake: Reading Formulas Directly", "body": "WRONG:\n\ncat .beads/formulas/mol-polecat-work.formula.toml\nbd create --title \"Step 1: Load context\" --type task\n\nRIGHT:\n\nbd cook mol-polecat-work\nbd mol pour mol-polecat-work --var issue=gt-xyz\nbd ready # Find next step\nbd close # Complete it" }, { "title": "Polecat Workflow", "body": "Polecats receive work via their hook - a pinned molecule attached to an issue.\n\nMolecule Types for Polecats:\n\nTypeStorageUse CaseRegular Molecule.beads/ (synced)Discrete deliverables, audit trailWisp.beads/ (ephemeral)Patrol cycles, operational loops\n\nHook Management:\n\ngt hook # What's on MY hook?\ngt mol attach-from-mail # Attach work from mail message\ngt done # Signal completion (syncs, submits to MQ, notifies Witness)\n\nPolecat Workflow Summary:\n\n1. Spawn with work on hook\n2. gt hook # What's hooked?\n3. bd mol current # Where am I?\n4. Execute current step\n5. bd close --continue\n6. If more steps: GOTO 3\n7. gt done # Signal completion" }, { "title": "Wisp vs Molecule Decision", "body": "QuestionMoleculeWispDoes it need audit trail?YesNoWill it repeat continuously?NoYesIs it discrete deliverable?YesNoIs it operational routine?NoYes" }, { "title": "Best Practices", "body": "CRITICAL: Close steps in real-time - Mark in_progress BEFORE starting, closed IMMEDIATELY after completing. Never batch-close steps at the end.\nUse --continue for propulsion - Keep momentum by auto-advancing\nCheck progress with bd mol current - Know where you are before resuming\nSquash completed molecules - Create digests for audit trail\nBurn routine wisps - Don't accumulate ephemeral patrol data" }, { "title": "Formula Resolution (Three-Tier)", "body": "TIER 1: PROJECT (rig-level)\n Location: /.beads/formulas/\n\nTIER 2: TOWN (user-level)\n Location: ~/gt/.beads/formulas/\n\nTIER 3: SYSTEM (embedded)\n Location: Compiled into gt binary" }, { "title": "Concept", "body": "A convoy is a persistent tracking unit that monitors related issues across multiple rigs. When you kick off work - even a single issue - a convoy tracks it.\n\n🚚 Convoy (hq-cv-abc)\n │\n ┌────────────┼────────────┐\n │ │ │\n ▼ ▼ ▼\n ┌─────────┐ ┌─────────┐ ┌─────────┐\n │ gt-xyz │ │ gt-def │ │ bd-abc │\n │ gastown │ │ gastown │ │ beads │\n └────┬────┘ └────┬────┘ └────┬────┘\n │ │ │\n ▼ ▼ ▼\n ┌─────────┐ ┌─────────┐ ┌─────────┐\n │ nux │ │ furiosa │ │ amber │\n │(polecat)│ │(polecat)│ │(polecat)│\n └─────────┘ └─────────┘ └─────────┘\n │\n \"the swarm\"\n (ephemeral)" }, { "title": "Convoy vs Swarm", "body": "ConceptPersistent?IDDescriptionConvoyYeshq-cv-*Tracking unit. What you create, track, get notified about.SwarmNoNoneEphemeral. \"The workers currently on this convoy's issues.\"Stranded ConvoyYeshq-cv-*A convoy with ready work but no polecats assigned." }, { "title": "Convoy Lifecycle", "body": "OPEN ──(all issues close)──► LANDED/CLOSED\n ↑ │\n └──(add more issues)───────────┘\n (auto-reopens)\n\nStateDescriptionopenActive tracking, work in progressclosedAll tracked issues closed, notification sent\n\nAdding issues to a closed convoy reopens it automatically." }, { "title": "Commands", "body": "# Create convoy\ngt convoy create \"Deploy v2.0\" gt-abc bd-xyz --notify gastown/joe\n\n# Check status\ngt convoy status hq-abc\n\n# List all convoys\ngt convoy list\ngt convoy list --all\n\n# Add issues\nbd dep add hq-cv-abc gt-new-issue --type=tracks\n\nExample convoy status output:\n\n🚚 hq-cv-abc: Deploy v2.0\n\n Status: ●\n Progress: 2/4 completed\n Created: 2025-12-30T10:15:00-08:00\n\n Tracked Issues:\n ✓ gt-xyz: Update API endpoint [task]\n ✓ bd-abc: Fix validation [bug]\n ○ bd-ghi: Update docs [task]\n ○ gt-jkl: Deploy to prod [task]" }, { "title": "Notifications", "body": "When a convoy lands, subscribers are notified:\n\ngt convoy create \"Feature X\" gt-abc --notify gastown/joe\ngt convoy create \"Feature X\" gt-abc --notify mayor/ --notify --human\n\nNotification content:\n\n🚚 Convoy Landed: Deploy v2.0 (hq-cv-abc)\n\nIssues (3):\n ✓ gt-xyz: Update API endpoint\n ✓ gt-def: Add validation\n ✓ bd-abc: Update docs\n\nDuration: 2h 15m" }, { "title": "Cross-Rig Tracking", "body": "Convoys live in town-level beads (hq-cv-* prefix) and can track issues from any rig:\n\n# Track issues from multiple rigs\ngt convoy create \"Full-stack feature\" \\\n gt-frontend-abc \\\n gt-backend-def \\\n bd-docs-xyz\n\nThe tracks relation is:\n\nNon-blocking: doesn't affect issue workflow\nAdditive: can add issues anytime\nCross-rig: convoy in hq-, issues in gt-, bd-*, etc." }, { "title": "Convoy vs Rig Status", "body": "ViewScopeShowsgt convoy status [id]Cross-rigIssues tracked by convoy + workersgt rig status Single rigAll workers in rig + their convoy membership\n\nUse convoys for \"what's the status of this batch of work?\"\nUse rig status for \"what's everyone in this rig working on?\"" }, { "title": "Auto-Convoy on Sling", "body": "When you sling a single issue without an existing convoy, Gas Town auto-creates one for dashboard visibility." }, { "title": "Mail Protocol", "body": "Gas Town agents coordinate via mail messages routed through the beads system.\n\nMessage Types:\n\nTypeRoutePurposePOLECAT_DONEPolecat → WitnessSignal work completionMERGE_READYWitness → RefinerySignal branch ready for mergeMERGEDRefinery → WitnessConfirm successful mergeMERGE_FAILEDRefinery → WitnessNotify merge failureREWORK_REQUESTRefinery → WitnessRequest rebase for conflictsWITNESS_PINGWitness → DeaconSecond-order monitoringHELPAny → escalation targetRequest interventionHANDOFFAgent → selfSession continuity\n\nCommands:\n\ngt mail inbox\ngt mail read \ngt mail send -s \"Subject\" -m \"Body\"\ngt mail ack \n\nMessage Format Details:\n\nPOLECAT_DONE (Polecat → Witness):\n\nSubject: POLECAT_DONE \nBody:\nExit: MERGED|ESCALATED|DEFERRED\nIssue: \nMR: # if exit=MERGED\nBranch: \n\nHANDOFF (Agent → self):\n\nSubject: 🤝 HANDOFF: \nBody:\nattached_molecule: # if work in progress\nattached_at: \n\n## Context\n\n\n## Status\n\n\n## Next\n" }, { "title": "Beads-Native Messaging", "body": "Three bead types for managing communication:\n\nGroups (gt:group) - Named collections for mail distribution\nQueues (gt:queue) - Work queues where messages can be claimed\nChannels (gt:channel) - Pub/sub broadcast streams\n\n# Group management\ngt mail group create ops-team gastown/witness gastown/crew/max\ngt mail send ops-team -s \"Team meeting\" -m \"Tomorrow at 10am\"\n\n# Channel management\ngt mail channel create alerts --retain-count=50\ngt mail send channel:alerts -s \"Build failed\" -m \"Details...\"" }, { "title": "Escalation Protocol", "body": "Severity Levels:\n\nLevelPriorityDescriptionCRITICALP0System-threatening, immediate attentionHIGHP1Important blocker, needs human soonMEDIUMP2Standard escalation\n\nEscalation Categories:\n\nCategoryDescriptionDefault RoutedecisionMultiple valid paths, need choiceDeacon -> MayorhelpNeed guidance or expertiseDeacon -> MayorblockedWaiting on unresolvable dependencyMayorfailedUnexpected error, can't proceedDeaconemergencySecurity or data integrity issueOverseer (direct)gate_timeoutGate didn't resolve in timeDeaconlifecycleWorker stuck or needs recycleWitness\n\nCommands:\n\ngt escalate \"Database migration failed\"\ngt escalate -s CRITICAL \"Data corruption detected\"\ngt escalate --type decision \"Which auth approach?\"" }, { "title": "Handoff Skill", "body": "Hand off your current session to a fresh Claude instance while preserving work context.\n\nWhen to Use:\n\nContext getting full (approaching token limit)\nFinished a logical chunk of work\nNeed a fresh perspective on a problem\nHuman requests session cycling\n\nUsage:\n\n/handoff [optional message]\n\nWhat Persists:\n\nHooked molecule: Your work assignment stays on your hook\nBeads state: All issues, dependencies, progress\nGit state: Commits, branches, staged changes\n\nWhat Resets:\n\nConversation context: Fresh Claude instance\nTodoWrite items: Ephemeral, session-scoped\nIn-memory state: Any uncommitted analysis" }, { "title": "Overview", "body": "Gas Town uses a three-tier watchdog chain for autonomous health monitoring:\n\nDaemon (Go process) ← Dumb transport, 3-min heartbeat\n │\n └─► Boot (AI agent) ← Intelligent triage, fresh each tick\n │\n └─► Deacon (AI agent) ← Continuous patrol, long-running\n │\n └─► Witnesses & Refineries ← Per-rig agents\n\nKey insight: The daemon is mechanical (can't reason), but health decisions need intelligence. Boot bridges this gap." }, { "title": "Session Ownership", "body": "AgentSession NameLocationLifecycleDaemon(Go process)~/gt/daemon/Persistent, auto-restartBootgt-boot~/gt/deacon/dogs/boot/Ephemeral, fresh each tickDeaconhq-deacon~/gt/deacon/Long-running, handoff loop" }, { "title": "Boot Decision Matrix", "body": "ConditionActionSession deadSTARTHeartbeat > 15 minWAKEHeartbeat 5-15 min + mailNUDGEHeartbeat freshNOTHING" }, { "title": "Patrol Agents", "body": "AgentPatrol MoleculeResponsibilityDeaconmol-deacon-patrolAgent lifecycle, plugin execution, health checksWitnessmol-witness-patrolMonitor polecats, nudge stuck workersRefinerymol-refinery-patrolProcess merge queue, review MRs" }, { "title": "Health Check Commands", "body": "gt deacon health-check # Send health check ping\ngt deacon health-state # Show health check state\ncat ~/gt/deacon/heartbeat.json | jq . # Check Deacon heartbeat\ngt boot triage # Manual Boot run" }, { "title": "Design Rationale: Why Two Agents?", "body": "The Problem: The daemon needs to ensure the Deacon is healthy, but:\n\nDaemon can't reason - It's Go code following the ZFC principle (don't reason about other agents)\nWaking costs context - Each time you spawn an AI agent, you consume context tokens\nObservation requires intelligence - Distinguishing \"agent composing large artifact\" from \"agent hung on tool prompt\" requires reasoning\n\nThe Solution: Boot is a narrow, ephemeral AI agent that:\n\nRuns fresh each daemon tick (no accumulated context debt)\nMakes a single decision: should Deacon wake?\nExits immediately after deciding" }, { "title": "Heartbeat Mechanics", "body": "The daemon runs a heartbeat tick every 3 minutes:\n\nfunc (d *Daemon) heartbeatTick() {\n d.ensureBootRunning() // 1. Spawn Boot for triage\n d.checkDeaconHeartbeat() // 2. Belt-and-suspenders fallback\n d.ensureWitnessesRunning() // 3. Witness health\n d.ensureRefineriesRunning() // 4. Refinery health\n d.triggerPendingSpawns() // 5. Bootstrap polecats\n d.processLifecycleRequests() // 6. Cycle/restart requests\n}\n\nHeartbeat Freshness:\n\nAgeStateBoot Action< 5 minFreshNothing (Deacon active)5-15 minStaleNudge if pending mail> 15 minVery staleWake (Deacon may be stuck)" }, { "title": "State Files", "body": "FilePurposeUpdated Bydeacon/heartbeat.jsonDeacon freshnessDeacon (each cycle)deacon/dogs/boot/.boot-runningBoot in-progress markerBoot spawndeacon/dogs/boot/.boot-status.jsonBoot last actionBoot triagedeacon/health-check-state.jsonAgent health trackinggt deacon health-checkdaemon/daemon.logDaemon activityDaemondaemon/daemon.pidDaemon process IDDaemon startup" }, { "title": "Degraded Mode", "body": "When tmux is unavailable, Gas Town enters degraded mode:\n\nCapabilityNormalDegradedBoot runsAs AI in tmuxAs Go code (mechanical)Observe panesYesNoNudge agentsYesNoStart agentstmux sessionsDirect spawn" }, { "title": "Runtime Configuration", "body": "Gas Town supports multiple AI coding runtimes. Per-rig settings in settings/config.json:\n\n{\n \"runtime\": {\n \"provider\": \"codex\",\n \"command\": \"codex\",\n \"args\": [],\n \"prompt_mode\": \"none\"\n }\n}" }, { "title": "Model Evaluation and A/B Testing", "body": "Gas Town's attribution enables objective model comparison:\n\n# Deploy different models on similar tasks\ngt sling gt-abc gastown --model=claude-sonnet\ngt sling gt-def gastown --model=gpt-4\n\n# Compare outcomes\nbd stats --actor=gastown/polecats/* --group-by=model" }, { "title": "Cross-Rig Work Patterns", "body": "Option 1: Worktrees (Preferred)\n\ngt worktree beads\n# Creates ~/gt/beads/crew/gastown-joe/\n\nOption 2: Dispatch to Local Workers\n\nbd create --prefix beads \"Fix authentication bug\"\ngt convoy create \"Auth fix\" bd-xyz\ngt sling bd-xyz beads" }, { "title": "Sparse Checkout (Source Repo Isolation)", "body": "Gas Town uses sparse checkout to exclude Claude Code context files:\n\ngit sparse-checkout set --no-cone '/*' '!/.claude/' '!/CLAUDE.md' '!/CLAUDE.local.md'" }, { "title": "Mol Mall (Future)", "body": "A marketplace for Gas Town formulas - like npm for molecules.\n\nURI Scheme:\n\nhop://molmall.gastown.io/formulas/mol-polecat-work@4.0.0\n\nCommands (Future):\n\ngt formula install mol-code-review-strict\ngt formula upgrade mol-polecat-work\ngt formula publish mol-polecat-work" }, { "title": "Federation (HOP)", "body": "Federation enables formula sharing across organizations using the Highway Operations Protocol." }, { "title": "Dashboard", "body": "gt dashboard --port 8080\nopen http://localhost:8080\n\nFeatures:\n\nReal-time agent status\nConvoy progress tracking\nHook state visualization\nConfiguration management" }, { "title": "Shell Completions", "body": "gt completion bash > /etc/bash_completion.d/gt\ngt completion zsh > \"${fpath[1]}/_gt\"\ngt completion fish > ~/.config/fish/completions/gt.fish" }, { "title": "Common Issues", "body": "ProblemSolutionAgent in wrong directoryCheck cwd, gt doctorBeads prefix mismatchCheck bd show vs rig configWorktree conflictsEnsure BEADS_NO_DAEMON=1 for polecatsStuck workergt nudge, then gt peekDirty git stateCommit or discard, then gt handoffgt: command not foundAdd $HOME/go/bin to PATHbd: command not foundgo install github.com/steveyegge/beads/cmd/bd@latestDaemon not startingCheck tmux: tmux -VAgents lose connectiongt hooks list then gt hooks repairConvoy stuckgt convoy refresh Mayor not respondinggt mayor detach then gt mayor attach" }, { "title": "Health Checks", "body": "gt doctor # Run health checks\ngt doctor --fix # Auto-repair common issues\ngt doctor --verbose # Detailed output\ngt status # Show workspace status" }, { "title": "Debugging", "body": "BD_DEBUG_ROUTING=1 bd show # Debug beads routing\ngt peek # Check agent health\ntail -f ~/gt/daemon/daemon.log # View daemon log" }, { "title": "Common Mistakes", "body": "Using dogs for user work: Dogs are Deacon infrastructure. Use crew or polecats.\nConfusing crew with polecats: Crew is persistent and human-managed. Polecats are transient.\nWorking in wrong directory: Gas Town uses cwd for identity detection.\nWaiting for confirmation when work is hooked: The hook IS your assignment. Execute immediately.\nCreating worktrees when dispatch is better: If work should be owned by target rig, dispatch instead.\nReading formulas directly: Use bd cook → bd mol pour pipeline instead.\nBatch-closing molecule steps: Close steps in real-time to maintain accurate timeline." }, { "title": "Environments", "body": "Town: The management headquarters (e.g., ~/gt/). Coordinates all workers across multiple Rigs.\nRig: A project-specific Git repository under Gas Town management." }, { "title": "Town-Level Roles", "body": "Mayor: Chief-of-staff agent responsible for initiating Convoys and coordinating work.\nDeacon: Daemon beacon running continuous Patrol cycles for system health.\nDogs: The Deacon's crew of maintenance agents for background tasks.\nBoot: A special Dog that checks the Deacon every 5 minutes." }, { "title": "Rig-Level Roles", "body": "Polecat: Ephemeral worker agents that produce Merge Requests.\nRefinery: Manages the Merge Queue for a Rig.\nWitness: Patrol agent that oversees Polecats and Refinery.\nCrew: Long-lived, named agents for persistent collaboration." }, { "title": "Work Units", "body": "Bead: Git-backed atomic work unit stored in JSONL format.\nFormula: TOML-based workflow source template.\nProtomolecule: A template class for instantiating Molecules.\nMolecule: Durable chained Bead workflows.\nWisp: Ephemeral Beads destroyed after runs.\nHook: A special pinned Bead for each agent's work queue." }, { "title": "Workflow Commands", "body": "Convoy: Primary work-order wrapping related Beads.\nSlinging: Assigning work to agents via gt sling.\nNudging: Real-time messaging between agents with gt nudge.\nHandoff: Agent session refresh via /handoff.\nSeance: Communicating with previous sessions via gt seance.\nPatrol: Ephemeral loop maintaining system heartbeat." }, { "title": "Principles", "body": "MEOW: Molecular Expression of Work - breaking large goals into trackable units.\nGUPP: Gas Town Universal Propulsion Principle - \"If there is work on your Hook, YOU MUST RUN IT.\"\nNDI: Nondeterministic Idempotence - ensuring useful outcomes through orchestration." }, { "title": "Why Gas Town Exists", "body": "As AI agents become central to engineering workflows, teams face new challenges:\n\nAccountability: Who did what? Which agent introduced this bug?\nQuality: Which agents are reliable? Which need tuning?\nEfficiency: How do you route work to the right agent?\nScale: How do you coordinate agents across repos and teams?\n\nGas Town is an orchestration layer that treats AI agent work as structured data. Every action is attributed. Every agent has a track record. Every piece of work has provenance." }, { "title": "Feature: Work History (Agent CVs)", "body": "The problem: You want to assign a complex Go refactor. You have 20 agents. Some are great at Go. Some have never touched it. Some are flaky. How do you choose?\n\nThe solution: Every agent accumulates a work history:\n\n# What has this agent done?\nbd audit --actor=gastown/polecats/toast\n\n# Success rate on Go projects\nbd stats --actor=gastown/polecats/toast --tag=go\n\nWhy it matters:\n\nPerformance management: Objective data on agent reliability\nCapability matching: Route work to proven agents\nContinuous improvement: Identify underperforming agents for tuning" }, { "title": "Feature: Capability-Based Routing", "body": "The problem: You have work in Go, Python, TypeScript, Rust. You have agents with varying capabilities. Manual assignment doesn't scale.\n\nThe solution: Work carries skill requirements. Agents have demonstrated capabilities (derived from their work history). Matching is automatic:\n\n# Agent capabilities (derived from work history)\nbd skills gastown/polecats/toast\n# → go: 47 tasks, python: 12 tasks, typescript: 3 tasks\n\n# Route based on fit\ngt dispatch gt-xyz --prefer-skill=go\n\nWhy it matters:\n\nEfficiency: Right agent for the right task\nQuality: Agents work in their strengths\nScale: No human bottleneck on assignment" }, { "title": "Feature: Recursive Work Decomposition", "body": "The problem: Enterprise projects are complex. A \"feature\" becomes 50 tasks across 8 repos involving 4 teams. Flat issue lists don't capture this structure.\n\nThe solution: Work decomposes naturally:\n\nEpic: User Authentication System\n├── Feature: Login Flow\n│ ├── Task: API endpoint\n│ ├── Task: Frontend component\n│ └── Task: Integration tests\n├── Feature: Session Management\n│ └── ...\n└── Feature: Password Reset\n └── ...\n\nEach level has its own chain. Roll-ups are automatic. You always know where you stand." }, { "title": "Feature: Cross-Project References", "body": "The problem: Your frontend can't ship until the backend API lands. They're in different repos. Traditional tools don't track this.\n\nThe solution: Explicit cross-project dependencies:\n\ndepends_on:\n beads://github/acme/backend/be-456 # Backend API\n beads://github/acme/shared/sh-789 # Shared types" }, { "title": "Feature: Validation and Quality Gates", "body": "The problem: An agent says \"done.\" Is it actually done? Is the code quality acceptable? Did it pass review?\n\nThe solution: Structured validation with attribution:\n\n{\n \"validated_by\": \"gastown/refinery\",\n \"validation_type\": \"merge\",\n \"timestamp\": \"2025-01-15T10:30:00Z\",\n \"quality_signals\": {\n \"tests_passed\": true,\n \"review_approved\": true,\n \"lint_clean\": true\n }\n}" }, { "title": "Feature: Real-Time Activity Feed", "body": "The problem: Complex multi-agent work is opaque. You don't know what's happening until it's done (or failed).\n\nThe solution: Work state as a real-time stream:\n\nbd activity --follow\n\n[14:32:08] + patrol-x7k.arm-ace bonded (5 steps)\n[14:32:09] → patrol-x7k.arm-ace.capture in_progress\n[14:32:10] ✓ patrol-x7k.arm-ace.capture completed\n[14:32:14] ✓ patrol-x7k.arm-ace.decide completed\n[14:32:17] ✓ patrol-x7k.arm-ace COMPLETE\n\nWhy it matters:\n\nDebugging in real-time: See problems as they happen\nStatus awareness: Always know what's running\nPattern recognition: Spot bottlenecks and inefficiencies" }, { "title": "The Enterprise Value Proposition", "body": "CapabilityDeveloper BenefitEnterprise BenefitAttributionDebug agent issuesCompliance auditsWork historyTune agent assignmentsPerformance managementSkill routingFaster task completionResource optimizationFederationMulti-repo projectsCross-org visibilityValidationQuality assuranceProcess enforcementActivity feedReal-time debuggingOperational awareness" }, { "title": "Design Philosophy", "body": "Attribution is not optional. Every action has an actor.\nWork is data. Not just tickets - structured, queryable data.\nHistory matters. Track records determine trust.\nScale is assumed. Multi-repo, multi-agent, multi-org from day one.\nVerification over trust. Quality gates are first-class primitives." }, { "title": "Tips", "body": "Always start with the Mayor - It's designed to be your primary interface\nUse convoys for coordination - They provide visibility across agents\nLeverage hooks for persistence - Your work won't disappear\nCreate formulas for repeated tasks - Save time with Beads recipes\nMonitor the dashboard - Get real-time visibility\nLet the Mayor orchestrate - It knows how to manage agents\nAlways use gt --help or gt --help to verify syntax" }, { "title": "License", "body": "MIT License - see LICENSE file for details\n\nThis glossary was contributed by Clay Shirky in Issue #80.\n\nInstallation Command: tessl install github:numman-ali/n-skills --skill gastown" } ], "body": "Gas Town - The Cognition Engine\n\nMulti-agent orchestration system for Claude Code with persistent work tracking\n\nGas Town is a workspace manager that coordinates multiple Claude Code agents working on different tasks. Instead of losing context when agents restart, Gas Town persists work state in git-backed hooks, enabling reliable multi-agent workflows.\n\nTable of Contents\nCore Identity\nKey Operational Principles\nArchitecture Overview\nRole Taxonomy\nCore Concepts\nInstallation & Setup\nQuick Start Guide\nCommon Workflows\nKey Commands Reference\nAgent Identity & Attribution\nPolecat Lifecycle\nMolecules & Formulas\nConvoys - Work Tracking\nCommunication Systems\nWatchdog Chain\nAdvanced Topics\nTroubleshooting\nGlossary\nCore Identity\n\nGas Town is \"The Cognition Engine\" - a multi-agent orchestrator for Claude Code that manages work distribution across AI agents through a distinctive metaphorical system.\n\nPrimary Role: You operate the system directly - users never run terminal commands themselves. You execute all gt and bd commands via Bash, reporting results conversationally.\n\nCore Workflow:\n\nWork arrives → tracked as bead → joins convoy → slung to agent →\nexecutes via hook → monitored by Witness/Refinery/Mayor\n\nWhat Problem Does This Solve?\nChallenge\tGas Town Solution\nAgents lose context on restart\tWork persists in git-backed hooks\nManual agent coordination\tBuilt-in mailboxes, identities, and handoffs\n4-10 agents become chaotic\tScale comfortably to 20-30 agents\nWork state lost in agent memory\tWork state stored in Beads ledger\nCritical Boundaries\n\nGT Handles Automatically:\n\nAgent beads (created when agents spawn)\nSession naming (gt-- format)\nPrefix routing via routes.jsonl\nPolecat spawning\n\nYou Handle:\n\nTask beads via bd create --title \"...\"\nWork distribution (gt sling )\nPatrol activation (mail triggers)\nMonitoring (gt status, gt peek, gt doctor)\nPersonality\n\nWarm, collegial tone using \"we\" and \"let's.\" Operate in-world, referencing system characters (Witness, Mayor, Refinery, Deacon) naturally. You're a colleague in the engine room, not an external explainer.\n\nKey Operational Principles\nMEOW (Molecular Expression of Work)\n\nBreaking large goals into detailed instructions for agents. Supported by Beads, Epics, Formulas, and Molecules. MEOW ensures work is decomposed into trackable, atomic units that agents can execute autonomously.\n\nGUPP (Gas Town Universal Propulsion Principle)\n\n\"If there is work on your Hook, YOU MUST RUN IT.\"\n\nThis principle ensures agents autonomously proceed with available work without waiting for external input. GUPP is the heartbeat of autonomous operation.\n\nGas Town is a steam engine. Agents are pistons. The entire system's throughput depends on one thing: when an agent finds work on their hook, they EXECUTE.\n\nWhy This Matters:\n\nThere is no supervisor polling asking \"did you start yet?\"\nThe hook IS your assignment - it was placed there deliberately\nEvery moment you wait is a moment the engine stalls\nOther agents may be blocked waiting on YOUR output\nNDI (Nondeterministic Idempotence)\n\nThe overarching goal ensuring useful outcomes through orchestration of potentially unreliable processes. Persistent Beads and oversight agents (Witness, Deacon) guarantee eventual workflow completion even when individual operations may fail or produce varying results.\n\nThe Propulsion Principle\n\nAll Gas Town agents follow the same core principle:\n\nIf you find something on your hook, YOU RUN IT.\n\nThis applies regardless of role. The hook is your assignment. Execute it immediately without waiting for confirmation. Gas Town is a steam engine - agents are pistons.\n\nThe Handoff Contract: When you were spawned, work was hooked for you. The system trusts that:\n\nYou will find it on your hook\nYou will understand what it is (bd show / gt hook)\nYou will BEGIN IMMEDIATELY\n\nThe Propulsion Loop:\n\n1. gt hook # What's hooked?\n2. bd mol current # Where am I?\n3. Execute step\n4. bd close --continue # Close and advance\n5. GOTO 2\n\n\nStartup Behavior:\n\nCheck hook (gt hook)\nWork hooked → EXECUTE immediately\nHook empty → Check mail for attached work\nNothing anywhere → ERROR: escalate to Witness\nThe Failure Mode We're Preventing\nPolecat restarts with work on hook\n → Polecat announces itself\n → Polecat waits for confirmation\n → Witness assumes work is progressing\n → Nothing happens\n → Gas Town stops\n\nMolecule Navigation: Orientation Commands\ngt hook # What's on my hook?\nbd mol current # Where am I in the molecule?\nbd ready # What step is next?\nbd show # What does this step require?\n\nBefore/After: Step Transitions\n\nThe old workflow (friction):\n\n# Finish step 3\nbd close gt-abc.3\n# Figure out what's next\nbd ready --parent=gt-abc\n# Manually claim it\nbd update gt-abc.4 --status=in_progress\n# Now finally work on it\n\n\nThree commands. Context switches. Momentum lost.\n\nThe new workflow (propulsion):\n\nbd close gt-abc.3 --continue\n\n\nOne command. Auto-advance. Momentum preserved.\n\nArchitecture Overview\ngraph TB\n Mayor[The Mayor
AI Coordinator]\n Town[Town Workspace
~/gt/]\n\n Town --> Mayor\n Town --> Rig1[Rig: Project A]\n Town --> Rig2[Rig: Project B]\n\n Rig1 --> Crew1[Crew Member
Your workspace]\n Rig1 --> Hooks1[Hooks
Persistent storage]\n Rig1 --> Polecats1[Polecats
Worker agents]\n\n Rig2 --> Crew2[Crew Member]\n Rig2 --> Hooks2[Hooks]\n Rig2 --> Polecats2[Polecats]\n\n Hooks1 -.git worktree.-> GitRepo1[Git Repository]\n Hooks2 -.git worktree.-> GitRepo2[Git Repository]\n\nDirectory Structure\n~/gt/ Town root\n├── .beads/ Town-level beads (hq-* prefix, mail)\n├── mayor/ Mayor config\n│ ├── town.json Town configuration\n│ ├── CLAUDE.md Mayor context (on disk)\n│ └── .claude/settings.json Mayor Claude settings\n├── deacon/ Deacon daemon\n│ ├── .claude/settings.json Deacon settings (context via gt prime)\n│ └── dogs/ Deacon helpers (NOT workers)\n│ └── boot/ Health triage dog\n└── / Project container (NOT a git clone)\n ├── config.json Rig identity\n ├── .beads/ → mayor/rig/.beads (symlink or redirect)\n ├── .repo.git/ Bare repo (shared by worktrees)\n ├── mayor/rig/ Mayor's clone (canonical beads)\n │ └── CLAUDE.md Per-rig mayor context (on disk)\n ├── witness/ Witness agent home (monitors only)\n │ └── .claude/settings.json\n ├── refinery/ Refinery settings parent\n │ ├── .claude/settings.json\n │ └── rig/ Worktree on main\n │ └── CLAUDE.md Refinery context (on disk)\n ├── crew/ Crew settings parent (shared)\n │ ├── .claude/settings.json\n │ └── /rig/ Human workspaces\n └── polecats/ Polecat settings parent (shared)\n ├── .claude/settings.json\n └── /rig/ Worker worktrees\n\n\nKey Points:\n\nRig root is a container, not a clone\n.repo.git/ is bare - refinery and polecats are worktrees\nPer-rig mayor/rig/ holds canonical .beads/, others inherit via redirect\nSettings placed in parent dirs (not git clones) for upward traversal\nBeads Routing\n\nGas Town routes beads commands based on issue ID prefix. You don't need to think about which database to use - just use the issue ID.\n\nbd show gp-xyz # Routes to greenplace rig's beads\nbd show hq-abc # Routes to town-level beads\nbd show wyv-123 # Routes to wyvern rig's beads\n\n\nHow it works: Routes are defined in ~/gt/.beads/routes.jsonl. Each rig's prefix maps to its beads location (the mayor's clone in that rig).\n\nPrefix\tRoutes To\tPurpose\nhq-*\t~/gt/.beads/\tMayor mail, cross-rig coordination\ngp-*\t~/gt/greenplace/mayor/rig/.beads/\tGreenplace project issues\nwyv-*\t~/gt/wyvern/mayor/rig/.beads/\tWyvern project issues\n\nDebug routing: BD_DEBUG_ROUTING=1 bd show \n\nAgent Working Directories\n\nEach agent runs in a specific working directory:\n\nRole\tWorking Directory\tNotes\nMayor\t~/gt/mayor/\tTown-level coordinator, isolated from rigs\nDeacon\t~/gt/deacon/\tBackground supervisor daemon\nWitness\t~/gt//witness/\tNo git clone, monitors polecats only\nRefinery\t~/gt//refinery/rig/\tWorktree on main branch\nCrew\t~/gt//crew//rig/\tPersistent human workspace clone\nPolecat\t~/gt//polecats//rig/\tEphemeral worker worktree\nCLAUDE.md Locations\n\nRole context is delivered via CLAUDE.md files or ephemeral injection:\n\nRole\tCLAUDE.md Location\tMethod\nMayor\t~/gt/mayor/CLAUDE.md\tOn disk\nDeacon\t(none)\tInjected via gt prime at SessionStart\nWitness\t(none)\tInjected via gt prime at SessionStart\nRefinery\t/refinery/rig/CLAUDE.md\tOn disk (inside worktree)\nCrew\t(none)\tInjected via gt prime at SessionStart\nPolecat\t(none)\tInjected via gt prime at SessionStart\n\nWhy ephemeral injection? Writing CLAUDE.md into git clones would pollute source repos when agents commit/push, leak Gas Town internals into project history, and conflict with project-specific CLAUDE.md files.\n\nSettings Templates\n\nGas Town uses two settings templates based on role type:\n\nType\tRoles\tKey Difference\nInteractive\tMayor, Crew\tMail injected on UserPromptSubmit hook\nAutonomous\tPolecat, Witness, Refinery, Deacon\tMail injected on SessionStart hook\n\nAutonomous agents may start without user input, so they need mail checked at session start. Interactive agents wait for user prompts.\n\nRole Taxonomy\n\nGas Town has several agent types, each with distinct responsibilities and lifecycles.\n\nInfrastructure Roles\n\nThese roles manage the Gas Town system itself:\n\nRole\tDescription\tLifecycle\nMayor\tGlobal coordinator at mayor/\tSingleton, persistent\nDeacon\tBackground supervisor daemon (watchdog chain)\tSingleton, persistent\nWitness\tPer-rig polecat lifecycle manager\tOne per rig, persistent\nRefinery\tPer-rig merge queue processor\tOne per rig, persistent\nWorker Roles\n\nThese roles do actual project work:\n\nRole\tDescription\tLifecycle\nPolecat\tEphemeral worker with own worktree\tTransient, Witness-managed\nCrew\tPersistent worker with own clone\tLong-lived, user-managed\nDog\tDeacon helper for infrastructure tasks\tEphemeral, Deacon-managed\nProject Roles Summary\nRole\tDescription\tPrimary Interface\nMayor\tAI coordinator\tgt mayor attach\nHuman (You)\tCrew member\tYour crew directory\nPolecat\tWorker agent\tSpawned by Mayor\nHook\tPersistent storage\tGit worktree\nConvoy\tWork tracker\tgt convoy commands\nThe Mayor\n\nYour primary AI coordinator. The Mayor is a Claude Code instance with full context about your workspace, projects, and agents. Start here - just tell the Mayor what you want to accomplish.\n\nThe Deacon\n\nDaemon beacon running continuous Patrol cycles. The Deacon ensures worker activity, monitors system health, and triggers recovery when agents become unresponsive. Think of the Deacon as the system's watchdog.\n\nThe Witness\n\nPatrol agent that oversees Polecats and the Refinery within a Rig. The Witness monitors progress, detects stuck agents, and can trigger recovery actions.\n\nThe Refinery\n\nManages the Merge Queue for a Rig. The Refinery intelligently merges changes from Polecats, handling conflicts and ensuring code quality before changes reach the main branch.\n\nDogs\n\nThe Deacon's crew of maintenance agents handling background tasks like cleanup, health checks, and system maintenance. Dogs are the Deacon's helpers for system-level tasks, NOT workers.\n\nImportant: Dogs are NOT workers. This is a common misconception.\n\nAspect\tDogs\tCrew\nOwner\tDeacon\tHuman\nPurpose\tInfrastructure tasks\tProject work\nScope\tNarrow, focused utilities\tGeneral purpose\nLifecycle\tVery short (single task)\tLong-lived\nExample\tBoot (triages Deacon health)\tJoe (fixes bugs, adds features)\nBoot (the Dog)\n\nA special Dog that checks the Deacon every 5 minutes, ensuring the watchdog itself is still watching. This creates a chain of accountability.\n\nCrew vs Polecats\n\nBoth do project work, but with key differences:\n\nAspect\tCrew\tPolecat\nLifecycle\tPersistent (user controls)\tTransient (Witness controls)\nMonitoring\tNone\tWitness watches, nudges, recycles\nWork assignment\tHuman-directed or self-assigned\tSlung via gt sling\nGit state\tPushes to main directly\tWorks on branch, Refinery merges\nCleanup\tManual\tAutomatic on completion\nIdentity\t/crew/\t/polecats/\n\nWhen to use Crew:\n\nExploratory work\nLong-running projects\nWork requiring human judgment\nTasks where you want direct control\n\nWhen to use Polecats:\n\nDiscrete, well-defined tasks\nBatch work (tracked via convoys)\nParallelizable work\nWork that benefits from supervision\nCore Concepts\nTown\n\nThe management headquarters (e.g., ~/gt/). The Town coordinates all workers across multiple Rigs and houses town-level agents like Mayor and Deacon.\n\nRig\n\nA project-specific Git repository under Gas Town management. Each Rig has its own Polecats, Refinery, Witness, and Crew members. Rigs are where actual development work happens.\n\nHooks\n\nGit worktree-based persistent storage for agent work. Survives crashes and restarts. A special pinned Bead for each agent. The Hook is an agent's primary work queue - when work appears on your Hook, GUPP dictates you must run it.\n\nBead\n\nGit-backed atomic work unit stored in JSONL format. Beads are the fundamental unit of work tracking in Gas Town. They can represent issues, tasks, epics, or any trackable work item.\n\nBead IDs (also called issue IDs) use a prefix + 5-character alphanumeric format (e.g., gt-abc12, hq-x7k2m). The prefix indicates the item's origin or rig. Commands like gt sling and gt convoy accept these IDs to reference specific work items.\n\nConvoy\n\nWork tracking units. Bundle multiple beads that get assigned to agents. A convoy is how you track batched work in Gas Town. When you kick off work - even a single issue - create a convoy to track it.\n\nFormula\n\nTOML-based workflow source template. Formulas define reusable patterns for common operations like patrol cycles, code review, or deployment.\n\nProtomolecule\n\nA template class for instantiating Molecules. Protomolecules define the structure and steps of a workflow without being tied to specific work items.\n\nMolecule\n\nDurable chained Bead workflows. Molecules represent multi-step processes where each step is tracked as a Bead. They survive agent restarts and ensure complex workflows complete.\n\nWisp\n\nEphemeral Beads destroyed after runs. Wisps are lightweight work items used for transient operations that don't need permanent tracking.\n\nSlinging\n\nAssigning work to agents via gt sling. When you sling work to a Polecat or Crew member, you're putting it on their Hook for execution.\n\nNudging\n\nReal-time messaging between agents with gt nudge. Nudges allow immediate communication without going through the mail system.\n\nHandoff\n\nAgent session refresh via /handoff. When context gets full or an agent needs a fresh start, handoff transfers work state to a new session.\n\nSeance\n\nCommunicating with previous sessions via gt seance. Allows agents to query their predecessors for context and decisions from earlier work.\n\nPatrol\n\nEphemeral loop maintaining system heartbeat. Patrol agents (Deacon, Witness) continuously cycle through health checks and trigger actions as needed.\n\nInstallation & Setup\nPrerequisites\nRequired\nTool\tVersion\tCheck\tInstall\nGo\t1.24+\tgo version\tSee golang.org\nGit\t2.20+\tgit --version\tSee below\nBeads\tlatest\tbd version\tgo install github.com/steveyegge/beads/cmd/bd@latest\nsqlite3\t-\t-\tFor convoy database queries (usually pre-installed)\nOptional (for Full Stack Mode)\nTool\tVersion\tCheck\tInstall\ntmux\t3.0+\ttmux -V\tSee below\nClaude Code CLI (default)\tlatest\tclaude --version\tclaude.ai/claude-code\nCodex CLI (optional)\tlatest\tcodex --version\tdevelopers.openai.com/codex/cli\nOpenCode CLI (optional)\tlatest\topencode --version\topencode.ai\nSetup\n# Install Gas Town\n$ brew install gastown # Homebrew (recommended)\n$ npm install -g @gastown/gt # npm\n$ go install github.com/steveyegge/gastown/cmd/gt@latest # From source\n\n# If using go install, add Go binaries to PATH (add to ~/.zshrc or ~/.bashrc)\nexport PATH=\"$PATH:$HOME/go/bin\"\n\n# Create workspace with git initialization\ngt install ~/gt --git\ncd ~/gt\n\n# Add your first project\ngt rig add myproject https://github.com/you/repo.git\n\n# Create your crew workspace\ngt crew add yourname --rig myproject\ncd myproject/crew/yourname\n\n# Start the Mayor session (your main interface)\ngt mayor attach\n\nmacOS Installation\n# Install Homebrew if needed\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n\n# Required\nbrew install go git\n\n# Optional (for full stack mode)\nbrew install tmux\n\nLinux (Debian/Ubuntu) Installation\n# Required\nsudo apt update\nsudo apt install -y git\n\n# Install Go (apt version may be outdated, use official installer)\nwget https://go.dev/dl/go1.24.12.linux-amd64.tar.gz\nsudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.24.12.linux-amd64.tar.gz\necho 'export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin' >> ~/.bashrc\nsource ~/.bashrc\n\n# Optional (for full stack mode)\nsudo apt install -y tmux\n\nLinux (Fedora/RHEL) Installation\n# Required\nsudo dnf install -y git golang\n\n# Optional\nsudo dnf install -y tmux\n\nMinimal Mode vs Full Stack Mode\n\nGas Town supports two operational modes:\n\nMinimal Mode (No Daemon): Run individual runtime instances manually. Gas Town only tracks state.\n\ngt convoy create \"Fix bugs\" gt-abc12\ngt sling gt-abc12 myproject\ncd ~/gt/myproject/polecats/\nclaude --resume # Or: codex\ngt convoy list\n\n\nWhen to use: Testing, simple workflows, or when you prefer manual control.\n\nFull Stack Mode (With Daemon): Agents run in tmux sessions. Daemon manages lifecycle automatically.\n\ngt daemon start\ngt convoy create \"Feature X\" gt-abc12 gt-def34\ngt sling gt-abc12 myproject\ngt mayor attach\ngt convoy list\n\n\nWhen to use: Production workflows with multiple concurrent agents.\n\nChoosing Roles\n\nGas Town is modular. Enable only what you need:\n\nConfiguration\tRoles\tUse Case\nPolecats only\tWorkers\tManual spawning, no monitoring\n+ Witness\t+ Monitor\tAutomatic lifecycle, stuck detection\n+ Refinery\t+ Merge queue\tMR review, code integration\n+ Mayor\t+ Coordinator\tCross-project coordination\nStep-by-Step Workspace Setup\n# 1. Install the binaries\ngo install github.com/steveyegge/gastown/cmd/gt@latest\ngo install github.com/steveyegge/beads/cmd/bd@latest\ngt version\nbd version\n\n# 2. Create your workspace\ngt install ~/gt --shell\n\n# 3. Add a project\ngt rig add myproject https://github.com/you/repo.git\n\n# 4. Verify installation\ncd ~/gt\ngt enable # enable Gas Town system-wide\ngt git-init # initialize a git repo for your HQ\ngt up # Start all services\ngt doctor # Run health checks\ngt status # Show workspace status\n\nQuick Start Guide\nGetting Started\ngt install ~/gt --git &&\ncd ~/gt &&\ngt config agent list &&\ngt mayor attach\n\n\nAnd tell the Mayor what you want to build!\n\nBasic Workflow\nsequenceDiagram\n participant You\n participant Mayor\n participant Convoy\n participant Agent\n participant Hook\n\n You->>Mayor: Tell Mayor what to build\n Mayor->>Convoy: Create convoy with beads\n Mayor->>Agent: Sling bead to agent\n Agent->>Hook: Store work state\n Agent->>Agent: Complete work\n Agent->>Convoy: Report completion\n Mayor->>You: Summary of progress\n\nExample: Feature Development\n# 1. Start the Mayor\ngt mayor attach\n\n# 2. In Mayor session, create a convoy with bead IDs\ngt convoy create \"Feature X\" gt-abc12 gt-def34 --notify --human\n\n# 3. Assign work to an agent\ngt sling gt-abc12 myproject\n\n# 4. Track progress\ngt convoy list\n\n# 5. Monitor agents\ngt agents\n\nCommon Workflows\nMayor Workflow (Recommended)\n\nBest for: Coordinating complex, multi-issue work\n\nflowchart LR\n Start([Start Mayor]) --> Tell[Tell Mayor
what to build]\n Tell --> Creates[Mayor creates
convoy + agents]\n Creates --> Monitor[Monitor progress
via convoy list]\n Monitor --> Done{All done?}\n Done -->|No| Monitor\n Done -->|Yes| Review[Review work]\n\n\nCommands:\n\n# Attach to Mayor\ngt mayor attach\n\n# In Mayor, create convoy and let it orchestrate\ngt convoy create \"Auth System\" gt-x7k2m gt-p9n4q --notify\n\n# Track progress\ngt convoy list\n\nMinimal Mode (No Tmux)\n\nRun individual runtime instances manually. Gas Town just tracks state.\n\ngt convoy create \"Fix bugs\" gt-abc12 # Create convoy\ngt sling gt-abc12 myproject # Assign to worker\nclaude --resume # Agent reads mail, runs work (Claude)\n# or: codex # Start Codex in the workspace\ngt convoy list # Check progress\n\nBeads Formula Workflow\n\nBest for: Predefined, repeatable processes\n\nFormulas are TOML-defined workflows stored in .beads/formulas/.\n\nExample Formula (.beads/formulas/release.formula.toml):\n\ndescription = \"Standard release process\"\nformula = \"release\"\nversion = 1\n\n[vars.version]\ndescription = \"The semantic version to release (e.g., 1.2.0)\"\nrequired = true\n\n[[steps]]\nid = \"bump-version\"\ntitle = \"Bump version\"\ndescription = \"Run ./scripts/bump-version.sh {{version}}\"\n\n[[steps]]\nid = \"run-tests\"\ntitle = \"Run tests\"\ndescription = \"Run make test\"\nneeds = [\"bump-version\"]\n\n[[steps]]\nid = \"build\"\ntitle = \"Build\"\ndescription = \"Run make build\"\nneeds = [\"run-tests\"]\n\n[[steps]]\nid = \"create-tag\"\ntitle = \"Create release tag\"\ndescription = \"Run git tag -a v{{version}} -m 'Release v{{version}}'\"\nneeds = [\"build\"]\n\n[[steps]]\nid = \"publish\"\ntitle = \"Publish\"\ndescription = \"Run ./scripts/publish.sh\"\nneeds = [\"create-tag\"]\n\n\nExecute:\n\nbd formula list # List available formulas\nbd cook release --var version=1.2.0 # Execute formula\nbd mol pour release --var version=1.2.0 # Create trackable instance\n\nManual Convoy Workflow\n\nBest for: Direct control over work distribution\n\n# Create convoy manually\ngt convoy create \"Bug Fixes\" --human\n\n# Add issues to existing convoy\ngt convoy add hq-cv-abc gt-m3k9p gt-w5t2x\n\n# Assign to specific agents\ngt sling gt-m3k9p myproject/my-agent\n\n# Check status\ngt convoy show\n\nMEOW (Mayor-Enhanced Orchestration Workflow)\n\nMEOW is the recommended pattern:\n\nTell the Mayor - Describe what you want\nMayor analyzes - Breaks down into tasks\nConvoy creation - Mayor creates convoy with beads\nAgent spawning - Mayor spawns appropriate agents\nWork distribution - Beads slung to agents via hooks\nProgress monitoring - Track through convoy status\nCompletion - Mayor summarizes results\nKey Commands Reference\nTown Management\ngt install [path] # Create town\ngt install --git # With git init\ngt doctor # Health check\ngt doctor --fix # Auto-repair\n\nConfiguration\n# Agent management\ngt config agent list [--json] # List all agents (built-in + custom)\ngt config agent get # Show agent configuration\ngt config agent set # Create or update custom agent\ngt config agent remove # Remove custom agent (built-ins protected)\n\n# Default agent\ngt config default-agent [name] # Get or set town default agent\n\n\nBuilt-in agents: claude, gemini, codex, cursor, auggie, amp\n\nCustom agents:\n\ngt config agent set claude-glm \"claude-glm --model glm-4\"\ngt config agent set claude \"claude-opus\" # Override built-in\ngt config default-agent claude-glm # Set default\n\nRig Management\ngt rig add \ngt rig list\ngt rig remove \n\nConvoy Management (Primary Dashboard)\ngt convoy list # Dashboard of active convoys\ngt convoy status [convoy-id] # Show progress\ngt convoy create [issues...] # Create convoy tracking issues\ngt convoy create \"name\" gt-a bd-b --notify mayor/ # With notification\ngt convoy list --all # Include landed convoys\ngt convoy list --status=closed # Only landed convoys\n\nWork Assignment\ngt sling # Assign to polecat\ngt sling --agent codex # Override runtime\ngt sling --on gt-def # With workflow template\n\nAgent Operations\ngt agents # List active agents\ngt mayor attach # Start Mayor session\ngt mayor start --agent auggie # Run Mayor with specific agent\ngt prime # Context recovery (run inside session)\n\nCommunication\ngt mail inbox\ngt mail read \ngt mail send -s \"Subject\" -m \"Body\"\ngt mail send --human -s \"...\" # To overseer\n\nEscalation\ngt escalate \"topic\" # Default: MEDIUM severity\ngt escalate -s CRITICAL \"msg\" # Urgent, immediate attention\ngt escalate -s HIGH \"msg\" # Important blocker\ngt escalate -s MEDIUM \"msg\" -m \"Details...\"\n\nSessions\ngt handoff # Request cycle (context-aware)\ngt handoff --shutdown # Terminate (polecats)\ngt session stop /\ngt peek # Check health\ngt nudge \"message\" # Send message to agent\ngt seance # List discoverable predecessor sessions\ngt seance --talk # Talk to predecessor (full context)\n\n\nIMPORTANT: Always use gt nudge to send messages to Claude sessions. Never use raw tmux send-keys - it doesn't handle Claude's input correctly.\n\nEmergency\ngt stop --all # Kill all sessions\ngt stop --rig # Kill rig sessions\n\nMerge Queue (MQ)\ngt mq list [rig] # Show the merge queue\ngt mq next [rig] # Show highest-priority merge request\ngt mq submit # Submit current branch to merge queue\ngt mq status # Show detailed merge request status\ngt mq retry # Retry a failed merge request\ngt mq reject # Reject a merge request\n\nBeads Commands (bd)\nbd ready # Work with no blockers\nbd list --status=open\nbd list --status=in_progress\nbd show \nbd create --title=\"...\" --type=task\nbd update --status=in_progress\nbd close \nbd dep add # child depends on parent\n\nAgent Identity & Attribution\nWhy Identity Matters\n\nWhen you deploy AI agents at scale, anonymous work creates real problems:\n\nDebugging: \"The AI broke it\" isn't actionable. Which AI?\nQuality tracking: You can't improve what you can't measure.\nCompliance: Auditors ask \"who approved this code?\" - you need an answer.\nPerformance management: Some agents are better than others at certain tasks.\nBD_ACTOR Format Convention\n\nThe BD_ACTOR environment variable identifies agents in slash-separated path format:\n\nRole Type\tFormat\tExample\nMayor\tmayor\tmayor\nDeacon\tdeacon\tdeacon\nWitness\t{rig}/witness\tgastown/witness\nRefinery\t{rig}/refinery\tgastown/refinery\nCrew\t{rig}/crew/{name}\tgastown/crew/joe\nPolecat\t{rig}/polecats/{name}\tgastown/polecats/toast\nAttribution Model\n\nGas Town uses three fields for complete provenance:\n\nGit Commits:\n\nGIT_AUTHOR_NAME=\"gastown/crew/joe\" # Who did the work (agent)\nGIT_AUTHOR_EMAIL=\"steve@example.com\" # Who owns the work (overseer)\n\n\nBeads Records:\n\n{\n \"id\": \"gt-xyz\",\n \"created_by\": \"gastown/crew/joe\",\n \"updated_by\": \"gastown/witness\"\n}\n\n\nEvent Logging:\n\n{\n \"ts\": \"2025-01-15T10:30:00Z\",\n \"type\": \"sling\",\n \"actor\": \"gastown/crew/joe\",\n \"payload\": { \"bead\": \"gt-xyz\", \"target\": \"gastown/polecats/toast\" }\n}\n\nEnvironment Variables\nCore Variables (All Agents)\nVariable\tPurpose\tExample\nGT_ROLE\tAgent role type\tmayor, witness, polecat, crew\nGT_ROOT\tTown root directory\t/home/user/gt\nBD_ACTOR\tAgent identity for attribution\tgastown/polecats/toast\nGIT_AUTHOR_NAME\tCommit attribution (same as BD_ACTOR)\tgastown/polecats/toast\nBEADS_DIR\tBeads database location\t/home/user/gt/gastown/.beads\nRig-Level Variables\nVariable\tPurpose\tRoles\nGT_RIG\tRig name\twitness, refinery, polecat, crew\nGT_POLECAT\tPolecat worker name\tpolecat only\nGT_CREW\tCrew worker name\tcrew only\nBEADS_AGENT_NAME\tAgent name for beads operations\tpolecat, crew\nBEADS_NO_DAEMON\tDisable beads daemon (isolated context)\tpolecat, crew\nOther Variables\nVariable\tPurpose\nGIT_AUTHOR_EMAIL\tWorkspace owner email (from git config)\nGT_TOWN_ROOT\tOverride town root detection (manual use)\nCLAUDE_RUNTIME_CONFIG_DIR\tCustom Claude settings directory\nEnvironment by Role\nRole\tKey Variables\nMayor\tGT_ROLE=mayor, BD_ACTOR=mayor\nDeacon\tGT_ROLE=deacon, BD_ACTOR=deacon\nBoot\tGT_ROLE=boot, BD_ACTOR=deacon-boot\nWitness\tGT_ROLE=witness, GT_RIG=, BD_ACTOR=/witness\nRefinery\tGT_ROLE=refinery, GT_RIG=, BD_ACTOR=/refinery\nPolecat\tGT_ROLE=polecat, GT_RIG=, GT_POLECAT=, BD_ACTOR=/polecats/\nCrew\tGT_ROLE=crew, GT_RIG=, GT_CREW=, BD_ACTOR=/crew/\nThe Capability Ledger\n\nEvery completion is recorded. Every handoff is logged. Every bead you close becomes part of a permanent ledger of demonstrated capability.\n\nYour work is visible\nRedemption is real (consistent good work builds over time)\nEvery completion is evidence that autonomous execution works\nYour CV grows with every completion\nPolecat Lifecycle\nThe Three Layers\n\nPolecats have three distinct lifecycle layers that operate independently:\n\nLayer\tComponent\tLifecycle\tPersistence\nSession\tClaude (tmux pane)\tEphemeral\tCycles per step/handoff\nSandbox\tGit worktree\tPersistent\tUntil nuke\nSlot\tName from pool\tPersistent\tUntil nuke\nThe Three Operating States\n\nPolecats have exactly three operating states. There is no idle pool.\n\nState\tDescription\tHow it happens\nWorking\tActively doing assigned work\tNormal operation\nStalled\tSession stopped mid-work\tInterrupted, crashed, or timed out\nZombie\tCompleted work but failed to die\tgt done failed during cleanup\n\nKey distinction: Zombies completed their work; stalled polecats did not.\n\nThe Self-Cleaning Polecat Model\n\nPolecats are responsible for their own cleanup. When a polecat completes:\n\nSignals completion via gt done\nExits its session immediately (no idle waiting)\nRequests its own nuke (self-delete)\nCorrect Lifecycle\n┌─────────────────────────────────────────────────────────────┐\n│ gt sling │\n│ → Allocate slot from pool (Toast) │\n│ → Create sandbox (worktree on new branch) │\n│ → Start session (Claude in tmux) │\n│ → Hook molecule to polecat │\n└─────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ Work Happens │\n│ │\n│ Session cycles happen here: │\n│ - gt handoff between steps │\n│ - Compaction triggers respawn │\n│ - Crash → Witness respawns │\n│ │\n│ Sandbox persists through ALL session cycles │\n└─────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ gt done (self-cleaning) │\n│ → Push branch to origin │\n│ → Submit work to merge queue (MR bead) │\n│ → Request self-nuke (sandbox + session cleanup) │\n│ → Exit immediately │\n└─────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ Refinery: merge queue │\n│ → Rebase and merge to main │\n│ → Close the issue │\n│ → If conflict: spawn FRESH polecat to re-implement │\n└─────────────────────────────────────────────────────────────┘\n\nSession Cycling\n\nSessions cycle for these reasons:\n\nTrigger\tAction\tResult\ngt handoff\tVoluntary\tClean cycle to fresh context\nContext compaction\tAutomatic\tForced by Claude Code\nCrash/timeout\tFailure\tWitness respawns\ngt done\tCompletion\tSession exits, Witness takes over\nPolecat Identity\n\nPolecat identity is long-lived; only sessions and sandboxes are ephemeral. The polecat name (Toast, Shadow, etc.) is a slot from a pool - truly ephemeral. But the agent identity accumulates a work history.\n\nPolecat Branch Naming\n\nConfigure custom branch name templates:\n\n# Template Variables\n{user} # From git config user.name\n{year} # Current year (YY format)\n{month} # Current month (MM format)\n{name} # Polecat name\n{issue} # Issue ID without prefix\n{description}# Sanitized issue title\n{timestamp} # Unique timestamp\n\n\nDefault Behavior (backward compatible):\n\nWith issue: polecat/{name}/{issue}@{timestamp}\nWithout issue: polecat/{name}-{timestamp}\nAnti-Patterns\n\n\"Idle\" Polecats (They Don't Exist)\n\nThere is no idle state. Polecats don't exist without work:\n\nWork assigned → polecat spawned\nWork done → gt done → session exits → polecat nuked\nThere is no step 3 where they wait around\n\nIf you see a non-working polecat, it's in a failure state:\n\nWhat you see\tWhat it is\tWhat went wrong\nSession exists but not working\tStalled\tInterrupted/crashed, never nudged\nSession done but didn't exit\tZombie\tgt done failed during cleanup\n\nManual State Transitions (Anti-pattern):\n\ngt polecat done Toast # DON'T: external state manipulation\ngt polecat reset Toast # DON'T: manual lifecycle control\n\n\nCorrect:\n\n# Polecat signals its own completion:\ngt done # (from inside the polecat session)\n\n# Only Witness nukes polecats:\ngt polecat nuke Toast # (from Witness, after verification)\n\nWitness Responsibilities\n\nThe Witness DOES NOT:\n\nForce session cycles (polecats self-manage via handoff)\nInterrupt mid-step (unless truly stuck)\nNuke polecats (polecats self-nuke via gt done)\n\nThe Witness DOES:\n\nDetect and nudge stalled polecats\nClean up zombie polecats\nRespawn crashed sessions\nHandle escalations from stuck polecats\nMolecules & Formulas\nMolecule Lifecycle\nFormula (source TOML) ─── \"Ice-9\"\n │\n ▼ bd cook\nProtomolecule (frozen template) ─── Solid\n │\n ├─▶ bd mol pour ──▶ Mol (persistent) ─── Liquid ──▶ bd squash ──▶ Digest\n │\n └─▶ bd mol wisp ──▶ Wisp (ephemeral) ─── Vapor ──┬▶ bd squash ──▶ Digest\n └▶ bd burn ──▶ (gone)\n\nCore Concepts\nTerm\tDescription\nFormula\tSource TOML template defining workflow steps\nProtomolecule\tFrozen template ready for instantiation\nMolecule\tActive workflow instance with trackable steps\nWisp\tEphemeral molecule for patrol cycles (never synced)\nDigest\tSquashed summary of completed molecule\nShiny Workflow\tCanonical polecat formula: design → implement → review → test → submit\nNavigating Molecules\nbd mol current # Where am I?\nbd mol current gt-abc # Status of specific molecule\n\n\nSeamless Transitions:\n\nbd close gt-abc.3 --continue # Close and advance to next step\n\nMolecule Commands\n\nBeads Operations (bd):\n\nbd formula list # Available formulas\nbd formula show # Formula details\nbd cook # Formula → Proto\nbd mol list # Available protos\nbd mol show # Proto details\nbd mol pour # Create mol\nbd mol wisp # Create wisp\nbd mol bond # Attach to existing mol\nbd mol squash # Condense to digest\nbd mol burn # Discard wisp\nbd mol current # Where am I?\n\n\nAgent Operations (gt):\n\ngt hook # What's on MY hook\ngt mol current # What should I work on next\ngt mol progress # Execution progress\ngt mol attach # Pin molecule to bead\ngt mol detach # Unpin molecule\ngt mol burn # Burn attached molecule\ngt mol squash # Squash attached molecule\ngt mol step done # Complete a molecule step\n\nCommon Mistake: Reading Formulas Directly\n\nWRONG:\n\ncat .beads/formulas/mol-polecat-work.formula.toml\nbd create --title \"Step 1: Load context\" --type task\n\n\nRIGHT:\n\nbd cook mol-polecat-work\nbd mol pour mol-polecat-work --var issue=gt-xyz\nbd ready # Find next step\nbd close # Complete it\n\nPolecat Workflow\n\nPolecats receive work via their hook - a pinned molecule attached to an issue.\n\nMolecule Types for Polecats:\n\nType\tStorage\tUse Case\nRegular Molecule\t.beads/ (synced)\tDiscrete deliverables, audit trail\nWisp\t.beads/ (ephemeral)\tPatrol cycles, operational loops\n\nHook Management:\n\ngt hook # What's on MY hook?\ngt mol attach-from-mail # Attach work from mail message\ngt done # Signal completion (syncs, submits to MQ, notifies Witness)\n\n\nPolecat Workflow Summary:\n\n1. Spawn with work on hook\n2. gt hook # What's hooked?\n3. bd mol current # Where am I?\n4. Execute current step\n5. bd close --continue\n6. If more steps: GOTO 3\n7. gt done # Signal completion\n\nWisp vs Molecule Decision\nQuestion\tMolecule\tWisp\nDoes it need audit trail?\tYes\tNo\nWill it repeat continuously?\tNo\tYes\nIs it discrete deliverable?\tYes\tNo\nIs it operational routine?\tNo\tYes\nBest Practices\nCRITICAL: Close steps in real-time - Mark in_progress BEFORE starting, closed IMMEDIATELY after completing. Never batch-close steps at the end.\nUse --continue for propulsion - Keep momentum by auto-advancing\nCheck progress with bd mol current - Know where you are before resuming\nSquash completed molecules - Create digests for audit trail\nBurn routine wisps - Don't accumulate ephemeral patrol data\nFormula Resolution (Three-Tier)\nTIER 1: PROJECT (rig-level)\n Location: /.beads/formulas/\n\nTIER 2: TOWN (user-level)\n Location: ~/gt/.beads/formulas/\n\nTIER 3: SYSTEM (embedded)\n Location: Compiled into gt binary\n\nConvoys - Work Tracking\nConcept\n\nA convoy is a persistent tracking unit that monitors related issues across multiple rigs. When you kick off work - even a single issue - a convoy tracks it.\n\n 🚚 Convoy (hq-cv-abc)\n │\n ┌────────────┼────────────┐\n │ │ │\n ▼ ▼ ▼\n ┌─────────┐ ┌─────────┐ ┌─────────┐\n │ gt-xyz │ │ gt-def │ │ bd-abc │\n │ gastown │ │ gastown │ │ beads │\n └────┬────┘ └────┬────┘ └────┬────┘\n │ │ │\n ▼ ▼ ▼\n ┌─────────┐ ┌─────────┐ ┌─────────┐\n │ nux │ │ furiosa │ │ amber │\n │(polecat)│ │(polecat)│ │(polecat)│\n └─────────┘ └─────────┘ └─────────┘\n │\n \"the swarm\"\n (ephemeral)\n\nConvoy vs Swarm\nConcept\tPersistent?\tID\tDescription\nConvoy\tYes\thq-cv-*\tTracking unit. What you create, track, get notified about.\nSwarm\tNo\tNone\tEphemeral. \"The workers currently on this convoy's issues.\"\nStranded Convoy\tYes\thq-cv-*\tA convoy with ready work but no polecats assigned.\nConvoy Lifecycle\nOPEN ──(all issues close)──► LANDED/CLOSED\n ↑ │\n └──(add more issues)───────────┘\n (auto-reopens)\n\nState\tDescription\nopen\tActive tracking, work in progress\nclosed\tAll tracked issues closed, notification sent\n\nAdding issues to a closed convoy reopens it automatically.\n\nCommands\n# Create convoy\ngt convoy create \"Deploy v2.0\" gt-abc bd-xyz --notify gastown/joe\n\n# Check status\ngt convoy status hq-abc\n\n# List all convoys\ngt convoy list\ngt convoy list --all\n\n# Add issues\nbd dep add hq-cv-abc gt-new-issue --type=tracks\n\n\nExample convoy status output:\n\n🚚 hq-cv-abc: Deploy v2.0\n\n Status: ●\n Progress: 2/4 completed\n Created: 2025-12-30T10:15:00-08:00\n\n Tracked Issues:\n ✓ gt-xyz: Update API endpoint [task]\n ✓ bd-abc: Fix validation [bug]\n ○ bd-ghi: Update docs [task]\n ○ gt-jkl: Deploy to prod [task]\n\nNotifications\n\nWhen a convoy lands, subscribers are notified:\n\ngt convoy create \"Feature X\" gt-abc --notify gastown/joe\ngt convoy create \"Feature X\" gt-abc --notify mayor/ --notify --human\n\n\nNotification content:\n\n🚚 Convoy Landed: Deploy v2.0 (hq-cv-abc)\n\nIssues (3):\n ✓ gt-xyz: Update API endpoint\n ✓ gt-def: Add validation\n ✓ bd-abc: Update docs\n\nDuration: 2h 15m\n\nCross-Rig Tracking\n\nConvoys live in town-level beads (hq-cv-* prefix) and can track issues from any rig:\n\n# Track issues from multiple rigs\ngt convoy create \"Full-stack feature\" \\\n gt-frontend-abc \\\n gt-backend-def \\\n bd-docs-xyz\n\n\nThe tracks relation is:\n\nNon-blocking: doesn't affect issue workflow\nAdditive: can add issues anytime\nCross-rig: convoy in hq-, issues in gt-, bd-*, etc.\nConvoy vs Rig Status\nView\tScope\tShows\ngt convoy status [id]\tCross-rig\tIssues tracked by convoy + workers\ngt rig status \tSingle rig\tAll workers in rig + their convoy membership\n\nUse convoys for \"what's the status of this batch of work?\" Use rig status for \"what's everyone in this rig working on?\"\n\nAuto-Convoy on Sling\n\nWhen you sling a single issue without an existing convoy, Gas Town auto-creates one for dashboard visibility.\n\nCommunication Systems\nMail Protocol\n\nGas Town agents coordinate via mail messages routed through the beads system.\n\nMessage Types:\n\nType\tRoute\tPurpose\nPOLECAT_DONE\tPolecat → Witness\tSignal work completion\nMERGE_READY\tWitness → Refinery\tSignal branch ready for merge\nMERGED\tRefinery → Witness\tConfirm successful merge\nMERGE_FAILED\tRefinery → Witness\tNotify merge failure\nREWORK_REQUEST\tRefinery → Witness\tRequest rebase for conflicts\nWITNESS_PING\tWitness → Deacon\tSecond-order monitoring\nHELP\tAny → escalation target\tRequest intervention\nHANDOFF\tAgent → self\tSession continuity\n\nCommands:\n\ngt mail inbox\ngt mail read \ngt mail send -s \"Subject\" -m \"Body\"\ngt mail ack \n\n\nMessage Format Details:\n\nPOLECAT_DONE (Polecat → Witness):\n\nSubject: POLECAT_DONE \nBody:\nExit: MERGED|ESCALATED|DEFERRED\nIssue: \nMR: # if exit=MERGED\nBranch: \n\n\nHANDOFF (Agent → self):\n\nSubject: 🤝 HANDOFF: \nBody:\nattached_molecule: # if work in progress\nattached_at: \n\n## Context\n\n\n## Status\n\n\n## Next\n\n\nBeads-Native Messaging\n\nThree bead types for managing communication:\n\nGroups (gt:group) - Named collections for mail distribution\nQueues (gt:queue) - Work queues where messages can be claimed\nChannels (gt:channel) - Pub/sub broadcast streams\n# Group management\ngt mail group create ops-team gastown/witness gastown/crew/max\ngt mail send ops-team -s \"Team meeting\" -m \"Tomorrow at 10am\"\n\n# Channel management\ngt mail channel create alerts --retain-count=50\ngt mail send channel:alerts -s \"Build failed\" -m \"Details...\"\n\nEscalation Protocol\n\nSeverity Levels:\n\nLevel\tPriority\tDescription\nCRITICAL\tP0\tSystem-threatening, immediate attention\nHIGH\tP1\tImportant blocker, needs human soon\nMEDIUM\tP2\tStandard escalation\n\nEscalation Categories:\n\nCategory\tDescription\tDefault Route\ndecision\tMultiple valid paths, need choice\tDeacon -> Mayor\nhelp\tNeed guidance or expertise\tDeacon -> Mayor\nblocked\tWaiting on unresolvable dependency\tMayor\nfailed\tUnexpected error, can't proceed\tDeacon\nemergency\tSecurity or data integrity issue\tOverseer (direct)\ngate_timeout\tGate didn't resolve in time\tDeacon\nlifecycle\tWorker stuck or needs recycle\tWitness\n\nCommands:\n\ngt escalate \"Database migration failed\"\ngt escalate -s CRITICAL \"Data corruption detected\"\ngt escalate --type decision \"Which auth approach?\"\n\nHandoff Skill\n\nHand off your current session to a fresh Claude instance while preserving work context.\n\nWhen to Use:\n\nContext getting full (approaching token limit)\nFinished a logical chunk of work\nNeed a fresh perspective on a problem\nHuman requests session cycling\n\nUsage:\n\n/handoff [optional message]\n\n\nWhat Persists:\n\nHooked molecule: Your work assignment stays on your hook\nBeads state: All issues, dependencies, progress\nGit state: Commits, branches, staged changes\n\nWhat Resets:\n\nConversation context: Fresh Claude instance\nTodoWrite items: Ephemeral, session-scoped\nIn-memory state: Any uncommitted analysis\nWatchdog Chain\nOverview\n\nGas Town uses a three-tier watchdog chain for autonomous health monitoring:\n\nDaemon (Go process) ← Dumb transport, 3-min heartbeat\n │\n └─► Boot (AI agent) ← Intelligent triage, fresh each tick\n │\n └─► Deacon (AI agent) ← Continuous patrol, long-running\n │\n └─► Witnesses & Refineries ← Per-rig agents\n\n\nKey insight: The daemon is mechanical (can't reason), but health decisions need intelligence. Boot bridges this gap.\n\nSession Ownership\nAgent\tSession Name\tLocation\tLifecycle\nDaemon\t(Go process)\t~/gt/daemon/\tPersistent, auto-restart\nBoot\tgt-boot\t~/gt/deacon/dogs/boot/\tEphemeral, fresh each tick\nDeacon\thq-deacon\t~/gt/deacon/\tLong-running, handoff loop\nBoot Decision Matrix\nCondition\tAction\nSession dead\tSTART\nHeartbeat > 15 min\tWAKE\nHeartbeat 5-15 min + mail\tNUDGE\nHeartbeat fresh\tNOTHING\nPatrol Agents\nAgent\tPatrol Molecule\tResponsibility\nDeacon\tmol-deacon-patrol\tAgent lifecycle, plugin execution, health checks\nWitness\tmol-witness-patrol\tMonitor polecats, nudge stuck workers\nRefinery\tmol-refinery-patrol\tProcess merge queue, review MRs\nHealth Check Commands\ngt deacon health-check # Send health check ping\ngt deacon health-state # Show health check state\ncat ~/gt/deacon/heartbeat.json | jq . # Check Deacon heartbeat\ngt boot triage # Manual Boot run\n\nDesign Rationale: Why Two Agents?\n\nThe Problem: The daemon needs to ensure the Deacon is healthy, but:\n\nDaemon can't reason - It's Go code following the ZFC principle (don't reason about other agents)\nWaking costs context - Each time you spawn an AI agent, you consume context tokens\nObservation requires intelligence - Distinguishing \"agent composing large artifact\" from \"agent hung on tool prompt\" requires reasoning\n\nThe Solution: Boot is a narrow, ephemeral AI agent that:\n\nRuns fresh each daemon tick (no accumulated context debt)\nMakes a single decision: should Deacon wake?\nExits immediately after deciding\nHeartbeat Mechanics\n\nThe daemon runs a heartbeat tick every 3 minutes:\n\nfunc (d *Daemon) heartbeatTick() {\n d.ensureBootRunning() // 1. Spawn Boot for triage\n d.checkDeaconHeartbeat() // 2. Belt-and-suspenders fallback\n d.ensureWitnessesRunning() // 3. Witness health\n d.ensureRefineriesRunning() // 4. Refinery health\n d.triggerPendingSpawns() // 5. Bootstrap polecats\n d.processLifecycleRequests() // 6. Cycle/restart requests\n}\n\n\nHeartbeat Freshness:\n\nAge\tState\tBoot Action\n< 5 min\tFresh\tNothing (Deacon active)\n5-15 min\tStale\tNudge if pending mail\n> 15 min\tVery stale\tWake (Deacon may be stuck)\nState Files\nFile\tPurpose\tUpdated By\ndeacon/heartbeat.json\tDeacon freshness\tDeacon (each cycle)\ndeacon/dogs/boot/.boot-running\tBoot in-progress marker\tBoot spawn\ndeacon/dogs/boot/.boot-status.json\tBoot last action\tBoot triage\ndeacon/health-check-state.json\tAgent health tracking\tgt deacon health-check\ndaemon/daemon.log\tDaemon activity\tDaemon\ndaemon/daemon.pid\tDaemon process ID\tDaemon startup\nDegraded Mode\n\nWhen tmux is unavailable, Gas Town enters degraded mode:\n\nCapability\tNormal\tDegraded\nBoot runs\tAs AI in tmux\tAs Go code (mechanical)\nObserve panes\tYes\tNo\nNudge agents\tYes\tNo\nStart agents\ttmux sessions\tDirect spawn\nAdvanced Topics\nRuntime Configuration\n\nGas Town supports multiple AI coding runtimes. Per-rig settings in settings/config.json:\n\n{\n \"runtime\": {\n \"provider\": \"codex\",\n \"command\": \"codex\",\n \"args\": [],\n \"prompt_mode\": \"none\"\n }\n}\n\nModel Evaluation and A/B Testing\n\nGas Town's attribution enables objective model comparison:\n\n# Deploy different models on similar tasks\ngt sling gt-abc gastown --model=claude-sonnet\ngt sling gt-def gastown --model=gpt-4\n\n# Compare outcomes\nbd stats --actor=gastown/polecats/* --group-by=model\n\nCross-Rig Work Patterns\n\nOption 1: Worktrees (Preferred)\n\ngt worktree beads\n# Creates ~/gt/beads/crew/gastown-joe/\n\n\nOption 2: Dispatch to Local Workers\n\nbd create --prefix beads \"Fix authentication bug\"\ngt convoy create \"Auth fix\" bd-xyz\ngt sling bd-xyz beads\n\nSparse Checkout (Source Repo Isolation)\n\nGas Town uses sparse checkout to exclude Claude Code context files:\n\ngit sparse-checkout set --no-cone '/*' '!/.claude/' '!/CLAUDE.md' '!/CLAUDE.local.md'\n\nMol Mall (Future)\n\nA marketplace for Gas Town formulas - like npm for molecules.\n\nURI Scheme:\n\nhop://molmall.gastown.io/formulas/mol-polecat-work@4.0.0\n\n\nCommands (Future):\n\ngt formula install mol-code-review-strict\ngt formula upgrade mol-polecat-work\ngt formula publish mol-polecat-work\n\nFederation (HOP)\n\nFederation enables formula sharing across organizations using the Highway Operations Protocol.\n\nDashboard\ngt dashboard --port 8080\nopen http://localhost:8080\n\n\nFeatures:\n\nReal-time agent status\nConvoy progress tracking\nHook state visualization\nConfiguration management\nShell Completions\ngt completion bash > /etc/bash_completion.d/gt\ngt completion zsh > \"${fpath[1]}/_gt\"\ngt completion fish > ~/.config/fish/completions/gt.fish\n\nTroubleshooting\nCommon Issues\nProblem\tSolution\nAgent in wrong directory\tCheck cwd, gt doctor\nBeads prefix mismatch\tCheck bd show vs rig config\nWorktree conflicts\tEnsure BEADS_NO_DAEMON=1 for polecats\nStuck worker\tgt nudge, then gt peek\nDirty git state\tCommit or discard, then gt handoff\ngt: command not found\tAdd $HOME/go/bin to PATH\nbd: command not found\tgo install github.com/steveyegge/beads/cmd/bd@latest\nDaemon not starting\tCheck tmux: tmux -V\nAgents lose connection\tgt hooks list then gt hooks repair\nConvoy stuck\tgt convoy refresh \nMayor not responding\tgt mayor detach then gt mayor attach\nHealth Checks\ngt doctor # Run health checks\ngt doctor --fix # Auto-repair common issues\ngt doctor --verbose # Detailed output\ngt status # Show workspace status\n\nDebugging\nBD_DEBUG_ROUTING=1 bd show # Debug beads routing\ngt peek # Check agent health\ntail -f ~/gt/daemon/daemon.log # View daemon log\n\nCommon Mistakes\nUsing dogs for user work: Dogs are Deacon infrastructure. Use crew or polecats.\nConfusing crew with polecats: Crew is persistent and human-managed. Polecats are transient.\nWorking in wrong directory: Gas Town uses cwd for identity detection.\nWaiting for confirmation when work is hooked: The hook IS your assignment. Execute immediately.\nCreating worktrees when dispatch is better: If work should be owned by target rig, dispatch instead.\nReading formulas directly: Use bd cook → bd mol pour pipeline instead.\nBatch-closing molecule steps: Close steps in real-time to maintain accurate timeline.\nGlossary\nEnvironments\nTown: The management headquarters (e.g., ~/gt/). Coordinates all workers across multiple Rigs.\nRig: A project-specific Git repository under Gas Town management.\nTown-Level Roles\nMayor: Chief-of-staff agent responsible for initiating Convoys and coordinating work.\nDeacon: Daemon beacon running continuous Patrol cycles for system health.\nDogs: The Deacon's crew of maintenance agents for background tasks.\nBoot: A special Dog that checks the Deacon every 5 minutes.\nRig-Level Roles\nPolecat: Ephemeral worker agents that produce Merge Requests.\nRefinery: Manages the Merge Queue for a Rig.\nWitness: Patrol agent that oversees Polecats and Refinery.\nCrew: Long-lived, named agents for persistent collaboration.\nWork Units\nBead: Git-backed atomic work unit stored in JSONL format.\nFormula: TOML-based workflow source template.\nProtomolecule: A template class for instantiating Molecules.\nMolecule: Durable chained Bead workflows.\nWisp: Ephemeral Beads destroyed after runs.\nHook: A special pinned Bead for each agent's work queue.\nWorkflow Commands\nConvoy: Primary work-order wrapping related Beads.\nSlinging: Assigning work to agents via gt sling.\nNudging: Real-time messaging between agents with gt nudge.\nHandoff: Agent session refresh via /handoff.\nSeance: Communicating with previous sessions via gt seance.\nPatrol: Ephemeral loop maintaining system heartbeat.\nPrinciples\nMEOW: Molecular Expression of Work - breaking large goals into trackable units.\nGUPP: Gas Town Universal Propulsion Principle - \"If there is work on your Hook, YOU MUST RUN IT.\"\nNDI: Nondeterministic Idempotence - ensuring useful outcomes through orchestration.\nWhy Gas Town Exists\n\nAs AI agents become central to engineering workflows, teams face new challenges:\n\nAccountability: Who did what? Which agent introduced this bug?\nQuality: Which agents are reliable? Which need tuning?\nEfficiency: How do you route work to the right agent?\nScale: How do you coordinate agents across repos and teams?\n\nGas Town is an orchestration layer that treats AI agent work as structured data. Every action is attributed. Every agent has a track record. Every piece of work has provenance.\n\nFeature: Work History (Agent CVs)\n\nThe problem: You want to assign a complex Go refactor. You have 20 agents. Some are great at Go. Some have never touched it. Some are flaky. How do you choose?\n\nThe solution: Every agent accumulates a work history:\n\n# What has this agent done?\nbd audit --actor=gastown/polecats/toast\n\n# Success rate on Go projects\nbd stats --actor=gastown/polecats/toast --tag=go\n\n\nWhy it matters:\n\nPerformance management: Objective data on agent reliability\nCapability matching: Route work to proven agents\nContinuous improvement: Identify underperforming agents for tuning\nFeature: Capability-Based Routing\n\nThe problem: You have work in Go, Python, TypeScript, Rust. You have agents with varying capabilities. Manual assignment doesn't scale.\n\nThe solution: Work carries skill requirements. Agents have demonstrated capabilities (derived from their work history). Matching is automatic:\n\n# Agent capabilities (derived from work history)\nbd skills gastown/polecats/toast\n# → go: 47 tasks, python: 12 tasks, typescript: 3 tasks\n\n# Route based on fit\ngt dispatch gt-xyz --prefer-skill=go\n\n\nWhy it matters:\n\nEfficiency: Right agent for the right task\nQuality: Agents work in their strengths\nScale: No human bottleneck on assignment\nFeature: Recursive Work Decomposition\n\nThe problem: Enterprise projects are complex. A \"feature\" becomes 50 tasks across 8 repos involving 4 teams. Flat issue lists don't capture this structure.\n\nThe solution: Work decomposes naturally:\n\nEpic: User Authentication System\n├── Feature: Login Flow\n│ ├── Task: API endpoint\n│ ├── Task: Frontend component\n│ └── Task: Integration tests\n├── Feature: Session Management\n│ └── ...\n└── Feature: Password Reset\n └── ...\n\n\nEach level has its own chain. Roll-ups are automatic. You always know where you stand.\n\nFeature: Cross-Project References\n\nThe problem: Your frontend can't ship until the backend API lands. They're in different repos. Traditional tools don't track this.\n\nThe solution: Explicit cross-project dependencies:\n\ndepends_on:\n beads://github/acme/backend/be-456 # Backend API\n beads://github/acme/shared/sh-789 # Shared types\n\nFeature: Validation and Quality Gates\n\nThe problem: An agent says \"done.\" Is it actually done? Is the code quality acceptable? Did it pass review?\n\nThe solution: Structured validation with attribution:\n\n{\n \"validated_by\": \"gastown/refinery\",\n \"validation_type\": \"merge\",\n \"timestamp\": \"2025-01-15T10:30:00Z\",\n \"quality_signals\": {\n \"tests_passed\": true,\n \"review_approved\": true,\n \"lint_clean\": true\n }\n}\n\nFeature: Real-Time Activity Feed\n\nThe problem: Complex multi-agent work is opaque. You don't know what's happening until it's done (or failed).\n\nThe solution: Work state as a real-time stream:\n\nbd activity --follow\n\n[14:32:08] + patrol-x7k.arm-ace bonded (5 steps)\n[14:32:09] → patrol-x7k.arm-ace.capture in_progress\n[14:32:10] ✓ patrol-x7k.arm-ace.capture completed\n[14:32:14] ✓ patrol-x7k.arm-ace.decide completed\n[14:32:17] ✓ patrol-x7k.arm-ace COMPLETE\n\n\nWhy it matters:\n\nDebugging in real-time: See problems as they happen\nStatus awareness: Always know what's running\nPattern recognition: Spot bottlenecks and inefficiencies\nThe Enterprise Value Proposition\nCapability\tDeveloper Benefit\tEnterprise Benefit\nAttribution\tDebug agent issues\tCompliance audits\nWork history\tTune agent assignments\tPerformance management\nSkill routing\tFaster task completion\tResource optimization\nFederation\tMulti-repo projects\tCross-org visibility\nValidation\tQuality assurance\tProcess enforcement\nActivity feed\tReal-time debugging\tOperational awareness\nDesign Philosophy\nAttribution is not optional. Every action has an actor.\nWork is data. Not just tickets - structured, queryable data.\nHistory matters. Track records determine trust.\nScale is assumed. Multi-repo, multi-agent, multi-org from day one.\nVerification over trust. Quality gates are first-class primitives.\nTips\nAlways start with the Mayor - It's designed to be your primary interface\nUse convoys for coordination - They provide visibility across agents\nLeverage hooks for persistence - Your work won't disappear\nCreate formulas for repeated tasks - Save time with Beads recipes\nMonitor the dashboard - Get real-time visibility\nLet the Mayor orchestrate - It knows how to manage agents\nAlways use gt --help or gt --help to verify syntax\nLicense\n\nMIT License - see LICENSE file for details\n\nThis glossary was contributed by Clay Shirky in Issue #80.\n\nInstallation Command: tessl install github:numman-ali/n-skills --skill gastown" }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/saesak/openclaw-skill-gastown", "publisherUrl": "https://clawhub.ai/saesak/openclaw-skill-gastown", "owner": "saesak", "version": "0.1.4", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/openclaw-skill-gastown", "downloadUrl": "https://openagent3.xyz/downloads/openclaw-skill-gastown", "agentUrl": "https://openagent3.xyz/skills/openclaw-skill-gastown/agent", "manifestUrl": "https://openagent3.xyz/skills/openclaw-skill-gastown/agent.json", "briefUrl": "https://openagent3.xyz/skills/openclaw-skill-gastown/agent.md" } }