Add explicit guidance on the Mayor → Crew → Polecats delegation model:
- Crew are coordinators for epics/goals needing decomposition
- Polecats are executors for well-defined tasks
- Include decision framework table for work type routing
Closes: gt-9jd
Mayor now checks `gt escalate list` between hook and mail checks at startup.
This ensures pending escalations from other agents are handled promptly.
Other roles (witness, refinery, polecat, crew, deacon) are unaffected -
they create escalations but don't handle them at startup.
Agents were misfiling beads in HQ when they should go to project-specific
rigs (beads, gastown). The templates explained routing mechanics but not
decision making. Added "Where to File Beads" sections with:
- Routing table based on what code the issue affects
- Simple heuristic: "Which repo would the fix be committed to?"
- Examples for bd CLI → beads, gt CLI → gastown, coordination → HQ
Affects: mayor, deacon, crew, polecat templates.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add Coordination section with gt nudge command
- Clarify line 180: routine nudging is Witness job, Mayor can nudge stuck refinery/witness
- Add warning to NEVER use tmux send-keys (drops Enter key)
- Includes liftoff test timestamp in manager.go
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- convoy.go: Escape single quotes in SQL to prevent injection
- engineer.go: Add comment clarifying test command trust model
(config.json is trusted infra, not PR-controlled)
- agents.go, prime.go, mayor.md.tmpl: Fix 'gt polecats' -> 'gt polecat list'
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update all documentation to present convoy as the primary unit of work tracking:
- README.md: Show convoy create before sling in Quick Start and Workflows
- reference.md: Reorder to show Convoy Management before Work Assignment
- understanding-gas-town.md: Add convoy to dispatch workflow example
- mayor.md.tmpl: Add convoy commands to Work Management section
- crew.md.tmpl: Include convoy in dispatch workflow table
Convoy is now the standard workflow - all slings should be part of a convoy.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add "Hookable Mail" section to all role templates explaining how mail beads
can be hooked for ad-hoc instruction handoff. Key documentation points:
- GUPP applies to hooked mail: read and execute instructions
- Two use cases: hook existing mail, create+hook via gt handoff
- Role-specific examples for each agent type
Templates updated:
- boot.md.tmpl
- crew.md.tmpl
- deacon.md.tmpl
- mayor.md.tmpl
- polecat.md.tmpl
- refinery.md.tmpl
- witness.md.tmpl
Also updated prime.go fallback output functions to include hookable mail
reference for when templates fail to render.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- 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>
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>
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>
- 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
- 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>
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>
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>
Implements gt-u1j.20: Prompt templates using go:embed.
- Add internal/templates package with embedded .md.tmpl files
- Role templates: mayor, witness, refinery, polecat, crew
- Message templates: spawn, nudge, escalation, handoff
- Update gt prime to use templates with fallback to hardcoded output
- Add crew role detection for <rig>/crew/<name>/ paths
- Include Gas Town architecture overview in all role contexts
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
