- Role templates (crew, polecat, mayor, deacon, witness, refinery)
- prime.go startup protocol messages
- Documentation (propulsion, reference, molecules, wisp architecture)
- Session hints and sling prompts
- Formula template instructions
- CLAUDE.md
The hook is the user-facing concept, molecules are implementation details.
Agents should use `gt hook` to check what work is assigned to them.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The Mayor should dispatch work to crew/polecats, not edit code directly.
mayor/rig exists as the source for worktrees, not as a working directory.
Key changes:
- Remove "Edit code here" instruction
- Add warning about staged changes accumulating
- Point to gt worktree for cross-rig work
- Clarify coordinator vs implementer distinction
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Work is NOT landed until it's either on main or in the Refinery MQ.
Feature branches are dangerous in multi-agent environments - the repo
baseline can diverge wildly in hours.
Add documentation for crew workers using cross-rig worktrees:
- Added Cross-Rig Worktrees section to crew.md.tmpl template
- Created docs/understanding-gas-town.md with role taxonomy
Key points documented:
- Crew vs Dogs distinction (dogs = Deacon infra, not user work)
- Identity preservation across rigs (BD_ACTOR stays the same)
- When to use worktrees vs dispatch to local workers
- Directory structure convention: ~/gt/<rig>/crew/<source-rig>-<name>/
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Using "greenplace" (The Green Place from Mad Max: Fury Road) as the
canonical example project/rig name in documentation and help text.
This provides a clearer distinction from the actual gastown repo name.
Changes:
- docs/*.md: Updated all example paths and commands
- internal/cmd/*.go: Updated help text examples
- internal/templates/: Updated example references
- Tests: Updated to use greenplace in example session names
Note: Import paths (github.com/steveyegge/gastown) and actual code
paths referencing the gastown repo structure are unchanged.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Boot is a watchdog that the daemon pokes instead of Deacon directly,
centralizing the 'when to wake Deacon' decision in an agent that can
reason about context.
Key changes:
- Add internal/boot package with marker file and status tracking
- Add gt boot commands: status, spawn, triage
- Add mol-boot-triage formula for Boot's triage cycle
- Modify daemon to call ensureBootRunning instead of ensureDeaconRunning
- Add tmux.IsAvailable() for degraded mode detection
- Add boot.md.tmpl role template
Boot lifecycle:
1. Daemon tick spawns Boot (fresh each time)
2. Boot runs triage: observe, decide, act
3. Boot cleans stale handoffs from Deacon inbox
4. Boot exits (or handoffs in non-degraded mode)
In degraded mode (no tmux), Boot runs mechanical triage directly.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Remove decision-making logic from Go code and document agent responsibility:
- ProcessMR() now returns error indicating agent handles processing
- Foreground mode deprecated with message directing to background mode
- Retry() no longer calls ProcessMR (agent picks up retried MRs)
- Added ZFC compliance section to refinery role template
- Marked unused helper functions as deprecated (runTests, getMergeConfig, pushWithRetry)
The Refinery agent (Claude) now:
- Runs git commands directly (fetch, checkout, merge, push)
- Detects conflicts and decides: retry, notify polecat, escalate
- Runs tests and decides: proceed, rollback, retry
- Makes all engineering decisions based on command output
Go code provides only primitives: queue listing, status, mail notifications.
(gt-sxa64)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add "The Capability Ledger" section to all 6 role templates explaining:
- Work visibility and reputation
- Redemption through consistent quality
- Every completion as evidence of autonomous execution at scale
- Work history as growing portfolio/CV
Also fix hooked vs pinned terminology confusion:
- "Hooked" = work assigned to you (triggers autonomous mode)
- "Pinned" = permanent reference beads
- Add clarifying note to all startup behavior sections
- Update code examples to use --status=hooked
Update prime.go AUTONOMOUS MODE output with ledger framing.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- checkSlungWork now queries for status=hooked instead of status=pinned
- This makes AUTONOMOUS WORK MODE fire correctly when work is slung via gt hook
- Added "physics not politeness" language to AUTONOMOUS MODE output
- Added full Theory of Operation section to refinery.md.tmpl for consistency
The bug was: gt hook sets status=hooked but gt prime was querying for
status=pinned, so AUTONOMOUS MODE never triggered for hooked work.
(gt-kc7yj.3)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The template incorrectly used --assignee flag on bd mol wisp which doesn't
exist. Changed to two-step pattern matching deacon template.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds comprehensive "Theory of Operation" section explaining WHY agents
must execute work immediately when found on their hook. Uses steam engine
metaphor to convey that this is physics, not politeness.
Each role gets a tailored metaphor:
- Mayor: main drive shaft
- Crew/Polecat: piston
- Deacon: flywheel
- Witness: pressure gauge
- Refinery: exhaust valve
The section explains the failure mode (agent waits, human is AFK,
Gas Town stops) and reinforces the propulsion principle.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Beads CLI restructured: pour and wisp are now subcommands of mol.
- bd pour → bd mol pour
- bd wisp → bd mol wisp
Updated all documentation, templates, and code to use new command structure.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Delete all .formula.json files (TOML versions exist)
- Update sling.go comment to say TOML only
Note: Doc updates were prepared but those docs were deleted
upstream in the recent refactoring.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The Deacon propulsion was broken because:
1. outputDeaconPatrolContext() created patrols in gastown/mayor/rig/.beads
2. checkSlungWork() looked in ~/gt/deacon/.beads/ (empty)
3. These were different locations - pinned work never found
Fix:
- Created redirect: ~/gt/deacon/.beads/redirect -> ../.beads (town beads)
- Changed outputDeaconPatrolContext() to use ctx.WorkDir instead of
hardcoded gastown path
- Updated deacon template to remove hardcoded gastown references
- Updated wisp creation docs to use two-step pattern (create then pin)
Also cleaned up 14 stale patrol wisps that accumulated in rig beads
from repeated startup attempts.
Filed gt-0pdhj to track remaining hardcoded gastown dependencies.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Test expected "Patrol Execution Protocol" but template uses
"Startup Protocol: Propulsion" heading instead.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Fix gastown/mayor/rig/CLAUDE.md (had wrong crew content)
- Add CRITICAL: Directory Discipline section to mayor.md.tmpl
- Emphasizes working from mayor/rig/, not crew/* or town root
Templates now instruct agents to discover steps at runtime via
bd ready / bd show instead of listing steps inline. This prevents
duplication between templates and formula YAML.
gt wisp command does not exist; bd wisp is the correct command for
creating wisps from protos. Closes gt-6n13.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Witness: Added Handoff Bead section with nudge state schema
- Refinery: Added Handoff Bead section with merge queue state schema
- Both reference their respective pinned handoff beads
Closes gt-poxd
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Gas Town is a stream engine, not a swarm engine. Polecats can start
and land independently at any time. "Swarm" is used lightly for
batch coordination, but there are no swarm IDs or batch boundaries.
Changes:
- architecture.md: Add stream engine intro paragraph, update
references from "swarming" to "parallel polecats" or "batch"
- prompts.md: Rename SWARM_* messages to BATCH_*, update terminology
- crew.md.tmpl: Replace "swarm" references with "transient worker pool"
and "batch work"
The gt swarm command and internal/swarm/ package remain as-is since
they provide the tooling for batch operations.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Rename "Dependency Trap" to "Gotchas when Filing Beads" in all 6 role templates
- Fix "git clone" to "git worktree" in polecat template
- Simplify completion section to just "gt done"
- Condense Work Protocol section (let molecule define steps)
- Simplify "Before Signaling Done" to trust gt done internals
- Clarify work status: use "gt mol status" as primary command
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Temporal language like "Phase 1 blocks Phase 2" triggers incorrect
dependency direction. Added a concise warning to all 6 role templates
(crew, polecat, mayor, witness, refinery, deacon) reminding agents:
- Think "X needs Y", not "X comes before Y"
- Verify with `bd blocked`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Crew: Updated to use 'gt handoff' instead of manual mail
- Crew: Added note about relaxed cycling (no fixed heuristic)
- Polecat: Added note that 'gt handoff' redirects to 'gt done'
Patrol workers (Deacon, Witness, Refinery) already had their
N-rounds heuristics documented in previous commits.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Most MRs are button-pushes (clean rebase + push). Only complex rebases
(conflicts, test failures) consume significant context.
- 20 simple MRs before handoff
- Immediate handoff after any complex rebase
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Each patrol role now has role-specific context management:
- Deacon: 20 loops or immediate on extraordinary action
- Witness: 15 polecats processed (spawns + nudges + decommissions)
- Refinery: 7 merge requests processed
Templates include state.json format and handoff instructions.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Updated all role prompt templates to document the startup hook protocol:
- polecat.md.tmpl: Added gt mol status check, self-pin from mail protocol
- witness.md.tmpl: Added gt mol status check, self-pin from mail protocol
- refinery.md.tmpl: Added gt mol status check, self-pin from mail protocol
- crew.md.tmpl: Added new Startup Protocol section with hook-first flow
- deacon.md.tmpl: Added gt mol status check, self-pin from mail protocol
- mayor.md.tmpl: Expanded startup protocol with hook-first flow
Each template now includes:
1. Check hook first (gt mol status)
2. If empty, check mail for attached work
3. Self-pin protocol (gt mol attach-from-mail) if needed
4. Role-specific fallback behavior
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Apply the Universal Gas Town Propulsion Principle to all agent templates:
"If you find something on your hook, YOU RUN IT."
Changes:
- deacon.md.tmpl: Hook-first startup, no decision logic
- polecat.md.tmpl: Simplified propulsion startup, molecule-following
- witness.md.tmpl: Wisp slinging when spawning, propulsion loop
- refinery.md.tmpl: Accept slung branches, hook-based execution
Key principle: Agents don't decide whether to do work. They check their hook
and execute what's there. The hook IS the decision.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Remove redundant phrases like 'ephemeral wisp' and 'ephemeral molecule'
since wisp already implies ephemeral. Keep 'ephemeral' only where it is
definitional (explaining what wisps are) or contrasting (vs durable mol).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Replaces raw tmux send-keys with gt nudge in spawn processing.
Adds Session Communication section to key commands reference.
Adds warning against raw tmux send-keys.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- .beads-ephemeral/ -> .beads-wisp/
- Rename doctor checks: EphemeralCheck -> WispCheck
- Update all docs to use 'transient' for polecats, 'wisp' for molecules
- Preserve 'ephemeral' only as descriptive adjective for wisps
- Steam engine metaphor: wisps are steam vapors that dissipate
Part of Christmas launch wisp terminology unification.
Polecats should not push their branches to origin directly.
They submit work via `gt done` which goes through the merge queue.
The Refinery handles merging to main.
This was causing stale polecat branches to accumulate on origin.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Two mechanisms, different purposes:
- Pinned molecule (bd mol run) = What you are working on, tracked by beads
- Handoff mail = Optional context notes for session restarts
Updated templates, architecture.md, and builtin_molecules.go
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Updates Deacon CLAUDE.md template with patrol execution instructions:
- Patrol molecule workflow (mol-deacon-patrol)
- Startup protocol: check for attached molecule, resume or bond
- Patrol execution loop: execute steps, close, loop or exit
- Nondeterministic idempotence for handoff
Enhances gt prime for Deacon:
- Adds patrol status section showing attached/naked state
- Shows molecule progress when patrol is in progress
- Includes Deacon-specific startup directive
Also adds standalone prompts/roles/deacon.md for reference.
Closes: gt-rana.4
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Crew workers are trusted maintainers who push directly to main:
- Own their clones (no isolation needed)
- Fast work cycles (10-15 min) make branch overhead wasteful
- Branches go stale with context cycling
- Polecats use branches/MRs; crew does not need review
Also updated two-level beads docs (removed stale rig-level references).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add clear explanations of the town-level vs rig-level beads architecture:
- Town beads (~/gt/.beads): HQ coordination, no sync-branch
- Rig beads (in git clones): project work, uses beads-sync branch
- Clarify that rig-level .beads at container is gitignored
Updated:
- docs/architecture.md: New 'Two-Level Beads Architecture' section
- CLAUDE.md: Enhanced existing section with table and sync-branch info
- templates/roles/*.tmpl: Added beads architecture to crew, polecat, mayor
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add molecule-first paradigm note at top of architecture.md
- Update all spawn examples to include --molecule flag
- Add "Config vs Molecule" section with cognition principle
- Add policy-to-molecule escalation note in federation-design.md
- Update role templates (mayor, witness) with molecule usage
Key message: Gas Town spawns workers on molecules, not just issues.
The issue is seed data; the molecule defines the workflow.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Key changes:
- Add gt nudge command for reliable Claude session messaging
- spawn.go now uses NudgeSession instead of SendKeysDebounced
- Fix templates test to match actual deacon template text
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove hacky 5-second delay from spawn
- Send SPAWN notification to Witness after starting polecat session
- Witness uses AI to monitor polecat startup and nudge when ready
- Added SPAWN REQUEST PROCESSING section to Witness template
This implements event-driven polecat readiness detection (gt-hb0).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Remove hacky 5-second delay from spawn
- Send SPAWN notification to Witness after starting polecat session
- Witness uses AI to monitor polecat startup and nudge when ready
- Added SPAWN REQUEST PROCESSING section to Witness template
This implements event-driven polecat readiness detection (gt-hb0).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
