Adds clear guidance that crew members are coordinators, not implementers:
- Lists 4 key responsibilities: Research, Decompose, Sling, Review
- Clarifies "goal-specific mayor" model - own outcomes via delegation
- Documents when to implement directly vs delegate (trivial fixes, spikes, etc.)
Closes: gt-gig
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Remove all bd sync references and SQLite-specific code from gastown:
**Formulas (agent priming):**
- mol-polecat-work: Remove bd sync step from prepare-for-review
- mol-sync-workspace: Replace sync-beads step with verify-beads (Dolt check)
- mol-polecat-conflict-resolve: Remove bd sync from close-beads
- mol-polecat-code-review: Remove bd sync from summarize-review and complete-and-exit
- mol-polecat-review-pr: Remove bd sync from complete-and-exit
- mol-convoy-cleanup: Remove bd sync from archive-convoy
- mol-digest-generate: Remove bd sync from send-digest
- mol-town-shutdown: Replace sync-state step with verify-state
- beads-release: Replace restart-daemons with verify-install (no daemons with Dolt)
**Templates (role priming):**
- mayor.md.tmpl: Update session end checklist to remove bd sync steps
- crew.md.tmpl: Remove bd sync references from workflow and checklist
- polecat.md.tmpl: Update self-cleaning model and session close docs
- spawn.md.tmpl: Remove bd sync from completion steps
- nudge.md.tmpl: Remove bd sync from completion steps
**Go code:**
- session_manager.go: Remove syncBeads function and call
- rig_dock.go: Remove bd sync calls from dock/undock
- crew/manager.go: Remove runBdSync, update Pristine function
- crew_maintenance.go: Remove bd sync status output
- crew.go: Update pristine command help text
- polecat.go: Make sync command a no-op with deprecation message
- daemon/lifecycle.go: Remove bd sync from startup sequence
- doctor/beads_check.go: Update fix hints and Fix to use bd import not bd sync
- doctor/rig_check.go: Remove sync status check, simplify BeadsConfigValidCheck
- beads/beads.go: Update primeContent to remove bd sync references
With Dolt backend, beads changes are persisted immediately to the sql-server.
There is no separate sync step needed.
Part of epic: hq-e4eefc (SQLite removal)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Gas Town uses Dolt exclusively. Remove all bd sync and bd daemon
references from agent priming, templates, formulas, and docs.
With Dolt backend:
- Beads changes are automatically persisted
- No manual sync needed (no bd sync)
- No daemon needed (no bd daemon)
Updated files:
- polecat-CLAUDE.md template
- Role templates (crew, mayor, polecat)
- Message templates (spawn, nudge)
- Formulas (polecat-work, sync-workspace, shutdown, etc.)
- Reference docs
Part of hq-4f2f0c: Remove bd sync/daemon from agent priming
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
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>
Polish help text across all agent commands to clarify roles:
- crew: persistent workspaces vs ephemeral polecats
- deacon: town-level watchdog receiving heartbeats
- dog: cross-rig infrastructure workers (cats vs dogs)
- mayor: Chief of Staff for cross-rig coordination
- nudge: universal synchronous messaging API
- polecat: ephemeral one-task workers, self-cleaning
- refinery: merge queue serializer per rig
- witness: per-rig polecat health monitor
Add comprehensive gt nudge documentation to crew template explaining
when to use nudge vs mail, common patterns, and target shortcuts.
Add orphan-process-cleanup step to deacon patrol formula to clean up
claude subagent processes that fail to exit (TTY = "?").
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Updated polecat and crew templates to more explicitly address the
"waiting for approval" anti-pattern. LLMs naturally want to pause
and confirm before taking action, but Gas Town requires autonomous
execution.
Polecat template:
- Added "The Specific Failure Mode" section describing the exact
anti-pattern (complete work, write summary, wait)
- Added "The Self-Cleaning Model" section explaining done=gone
- Strengthened DO NOT list with explicit approval-seeking examples
Crew template:
- Added "The Approval Fallacy" section at the top
- Explains that there is no approval step in Gas Town
- Lists specific anti-patterns to avoid
These changes address the root cause of polecats sitting idle after
completing work instead of running `gt done`.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Workers now get primed on the desire-paths philosophy:
- crew.md.tmpl: New "Desire Paths" section before Tips
- polecat.md.tmpl: Updated "Agent UX" section with desire-path label
When a command fails but the guess was reasonable, workers are
encouraged to file a bead with the desire-path label. This helps
improve agent ergonomics by surfacing intuitive command patterns.
References ~/gt/docs/AGENT-ERGONOMICS.md for full philosophy.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Makes PR rules conditional on repo ownership instead of absolute ban.
Non-maintainer repos may require PRs for external contributors.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The previous NEVER create GitHub PRs language was too weak. Strengthened to:
- ABSOLUTELY FORBIDDEN header
- This is not negotiable
- Explicit STOP if about to run gh pr create
- Clarified PR Sheriff reviews incoming PRs, does not create them
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Polecats were creating GitHub PRs instead of using gt done to submit
to the Refinery. Added clear conditional language:
- If repo is steveyegge/beads or steveyegge/gastown: NEVER create PRs
- Polecats use gt done → Refinery merges
- Crew workers push directly to main
- PRs are for external contributors only
This fixes a prompting gap that led to PR #292 being created incorrectly.
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>
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>
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>
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>
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>
- .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.
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>
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>
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>
