The document conflated epics and molecules. This revision:
- Explains molecules as the general abstraction for executable work
- Introduces the concept of molecular shapes (Epic, Christmas Ornament, etc.)
- Clarifies that epics are just ONE shape (a simple TODO list pattern)
- Adds the key insight: All epics are molecules. Not all molecules are epics.
- Explains why the data plane stores all shapes the same way
- Updates Related Documents with better descriptions
🤖 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>
Corrected from 'three-tier' to 'two-tier' model:
- Town level: persistent (.beads/) + ephemeral (.beads-wisp/)
- Rig level: persistent (.beads/) + ephemeral (.beads-wisp/)
Each tier has both durable and wisp storage, not three separate tiers.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Renamed from "Two-Level" to "Three-Tier" to include wisps
- Added rig wisps tier (.beads-wisp/) for ephemeral patrol state
- Clarified deacon uses town beads (not rig beads)
- Added git tracking status for each tier
Related: gt-ci84 (deacon wisp storage bug)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Documents how beads serves as the universal data store for all agent
coordination: work molecules, mail messages, hooks, and inboxes are
all issues with consistent field semantics.
Key insights:
- Mail reuses assignee (to), title (subject), labels (from:)
- Hooks and inboxes are queries, not containers
- Two-level architecture: town beads (mail) vs rig beads (work)
🤖 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>
resolveRoleToSession now accepts paths like <rig>/crew/<name>,
<rig>/witness, and <rig>/refinery in addition to role shortcuts.
For example: 'gt handoff gastown/crew/max' now works.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Update gt handoff to detect polecats (via GT_POLECAT env var) and
call gt done instead of respawning - polecats have Witness-managed lifecycle
- Update CLAUDE.md Session End Checklist to use gt handoff
- This is the canonical way to end any agent session - it handles mail,
respawn, and context restoration via SessionStart hook
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- crew.md: Use gt handoff instead of manual mail for handoff
- witness.md: Use gt handoff in Session Self-Cycling section
- refinery.md: Simplify Session Self-Cycling to use gt handoff
- deacon.md: Add Session Self-Cycling section with gt handoff
All non-polecat roles now consistently document gt handoff as the
canonical way to end sessions. Polecats use gt done (handled by Witness).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
buildRestartCommand now detects the town root and includes a cd to the
appropriate directory before launching claude. This ensures each role
starts in its correct working directory:
- gt-mayor → town root (~/gt)
- gt-deacon → ~/gt/deacon
- crew sessions → ~/gt/<rig>/crew/<name>
- witness sessions → ~/gt/<rig>/witness
- refinery sessions → ~/gt/<rig>/refinery
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
The daemon was creating the deacon session in ~/gt (town root) which loaded
the Mayor CLAUDE.md instead of the Deacon CLAUDE.md. Also, tmux SetEnvironment
does not export variables to spawned processes.
Changes:
- Create deacon session in ~/gt/deacon (correct CLAUDE.md)
- Export GT_ROLE=deacon in launch command (process inherits env)
- Apply to both initial launch and restart paths
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Added comment explaining that the pinned field gets overwritten by
subsequent bd commands due to a bug in the beads auto-import logic.
The handoff bead attachment mechanism works correctly and is the
primary work assignment mechanism.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
New command that sends a message to all active workers (polecats + crew).
Supports filtering by rig with --rig flag, and can include infrastructure
agents (mayor, deacon, witness, refinery) with --all flag.
Usage:
gt broadcast "Check your mail"
gt broadcast --rig gastown "New work available"
gt broadcast --all "System maintenance in 5 minutes"
gt broadcast --dry-run "Test"
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
