Key insight: Rig and Bond operate at different abstraction levels:
- Rig = source-level composition (formula YAML with extends/compose)
- Bond = artifact-level composition (protos, mols, wisps)
This preserves the symmetric bond table while cleanly separating
authoring (rig) from runtime composition (bond).
New docs:
- rig-cook-run.md: Canonical spec for the three phases
Updated docs:
- molecule-algebra.md: Three Phases section, rig/bond distinction
- molecular-chemistry.md: Rig/bond clarification in bond section
- vision.md: Core Innovation 3 now covers Rig/Cook/Run
"This is a discovery, not an invention."
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
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>
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>
- Updated molecules.md to reflect actual JSONL storage format
- Updated architecture.md molecule sections with ASCII diagrams
- Replaced markdown "## Step:" format with tree diagrams
- Changed plugin system from directory-based to molecule-based
- Plugins now use labels for metadata (tier, phase, role)
- Mol Mall distributes molecules.jsonl fragments
Related: gt-u818, gt-9za0
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Formalizes the pinned bead system for all Gas Town roles:
- One hook per agent (enforced, not multiple)
- Title-based discovery mechanism ({role} Handoff)
- Mail as delivery vs hook as authority
- Proposed gt doctor checks for hook validation
- Dashboard visibility recommendations
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds support for managing multiple Claude Code accounts in Gas Town:
- accounts.json config parsing in mayor/ directory
- gt account list/add/default commands
- GT_ACCOUNT env var support with priority resolution
- --account flag on gt spawn and gt crew at commands
- CLAUDE_CONFIG_DIR injection into tmux sessions
Priority order: GT_ACCOUNT env var > --account flag > default from config
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Design doc for Gas Town account management feature enabling users to
switch between multiple Claude Code accounts (e.g., personal vs work).
Key decisions:
- Uses CLAUDE_CONFIG_DIR env var as core mechanism
- Config stored in ~/gt/mayor/accounts.yaml (follows town config pattern)
- NOT in Beads (config, not work items)
- NOT molecules (mechanical, not cognitive)
- Extensible for API keys, per-role defaults, federation
🤖 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>
Introduces Proto → Wisp → Mol architecture for agent sessions:
- mol-crew-session: Light harness enabling autonomous overnight work
Key insight: if attached mol exists, continue without awaiting input
- mol-polecat-session: One-shot wisp wrapping polecat work assignments
Handles onboard → execute → cleanup lifecycle
This separates "how to work" (proto) from "what to work on" (mol),
enabling session continuity and autonomous long-mol processing.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Documents the Universal Gas Town Propulsion Principle - the single rule
that drives all agent behavior: "If you find something on your hook,
YOU RUN IT."
Covers:
- The One Rule (hook has work → work happens)
- Why it works (stateless agents, molecule-driven)
- The sling lifecycle diagram
- Agent startup protocol
- Examples and anti-patterns
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Adds gt peek as ergonomic alias for gt session capture:
gt peek gastown/furiosa # Last 100 lines
gt peek gastown/furiosa 50 # Last 50 lines
Creates nudge/peek pair as canonical session interface:
gt nudge - send TO session (reliable delivery)
gt peek - read FROM session (capture-pane wrapper)
Adds docs/session-communication.md explaining:
- Why raw tmux send-keys is unreliable for Claude
- The reliable NudgeSession pattern (literal + delay + Enter)
- Command reference and common patterns
- Guidance for template authors
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
When polecat branches have .beads/ tracked from previous bd sync operations,
those files would contaminate the new worktree. Now setupSharedBeads():
1. Removes any existing .beads/ contents before creating redirect
2. Points redirect directly to mayor/rig/.beads (matches crew workers)
Also adds sling-design.md documenting the gt sling command design.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Wisps are at <rig>/.beads-wisp/, outside any git clone.
This matches the actual code implementation.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- All rig patrols (Deacon, Witness, Refinery) now share mayor/rig/.beads-wisp/
- Removed separate wisp directories for witness/ and refinery/
- Polecats do not use wisps (each assignment has audit value)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
New documents:
- docs/molecular-chemistry.md: Comprehensive guide to the chemistry metaphor
for work composition. Covers all phases (proto/mol/wisp), transitions
(pour/wisp/squash/burn/distill), polymorphic bond operator, and the
thermodynamic properties of the work execution engine.
- docs/chemistry-design-changes.md: Implementation roadmap for realizing
the chemistry UX in Beads and Gas Town. Includes specifications for
new commands (bd pour, bd wisp, bd pin, bd hook) and migration notes.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add doctor checks for new config architecture:
- SettingsCheck: Verify rigs have settings/ directory
- RuntimeGitignoreCheck: Verify .runtime/ is gitignored
- LegacyGastownCheck: Detect/remove old .gastown/ dirs
- Update .gitignore to include .runtime/
- Update architecture.md with new directory structure
- Update hq.md to clarify PGT vs GGT config locations
🤖 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.
- Create wisp-architecture.md with canonical storage spec
- Document role assignments (Deacon/Witness/Refinery use wisps)
- Specify .beads-ephemeral/ as gitignored storage
- Define patrol execution pattern with required squash
- Update architecture.md to reference new doc
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
New design for tracking dependencies across project boundaries:
- Capability-based: reference provides:X labels, not issue IDs
- bd ship command for publishing capabilities
- external: prefix in blocked_by for cross-project refs
- Molecule parking for blocked work
🤖 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>
- New docs/deacon-plugins.md with full plugin architecture
- Directory-based discovery at ~/gt/plugins/
- Gate types: cooldown, cron, condition, event
- Parallel execution support via Task tool subagents
- Updated mol-deacon-patrol plugin-run step to reference new docs
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Added comprehensive CLI reference documentation for the three molecule
lifecycle commands:
- bd mol bond: Instantiate proto into Mol (durable) or Wisp (ephemeral)
- bd mol squash: Complete molecule and generate digest
- bd mol burn: Abandon molecule without digest
Includes argument tables, behavior descriptions, examples, and a
lifecycle diagram showing the steam engine metaphor mapping.
Closes: gt-odvf
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add visual diagram showing Proto → Mol/Wisp → Digest state transitions
with the "states of matter" metaphor (crystal → liquid/gas → distillate).
Document when to use Mol (durable) vs Wisp (ephemeral) based on audit
requirements and work importance.
Closes: gt-c6zs
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- docs/architecture.md: update mail routing explanation
- internal/witness/manager.go: fix actual bd mail calls to gt mail
- internal/cmd/mail.go: remove stale compatibility note
- internal/daemon/lifecycle.go: update comment
Add documentation for two key features:
1. Mail Routing (internal/mail/router.go):
- Routes messages to correct beads database by recipient
- Town-level (mayor/, deacon/) -> ~/gt/.beads
- Rig-level (rig/polecat) -> ~/gt/rig/.beads
- Uses BEADS_DIR env var for all bd commands
2. Shared Beads for Polecats:
- Polecats use redirect files instead of own beads DBs
- .beads/redirect contains relative path to shared beads
- Eliminates git sync overhead between polecat worktrees
- setupSharedBeads() creates redirect on polecat spawn
Generated with 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>
The "hq-" prefix for town-level beads revealed that "HQ" (headquarters)
is a better name than "harness" for the top-level Gas Town structure.
- Renamed docs/harness.md to docs/hq.md with updated content
- Updated all documentation references in architecture.md and bootstrap.md
- Updated CLI help text and user-facing messages in install.go
- Updated gitinit.go with HQGitignore constant and HQ terminology
- Updated molecule templates in builtin_molecules.go
- Kept InitGitForHarness function name for backwards compatibility
HQ is more intuitive (where the mayor sits), fits the Mad Max aesthetic,
matches the beads prefix (hq-*), and is self-documenting.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Updated beads-hygiene plugin spec to use 'hq-' (headquarters) instead
of 'stevetown-'. Short, visually distinct from rig prefixes, and
semantically clear.
🤖 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>
Detects and fixes cross-pollution between Gas Town's two-level beads
architecture (town-level vs rig-level). Workers sometimes get confused
about which database they're in, creating issues at the wrong level.
The plugin scans for:
- Prefix mismatches (wrong prefix for location)
- Cross-level dependency references
- Agent identity/context confusion
- Misfiled issues that should be moved
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add Pluggable Molecules section to architecture.md explaining
directory-based plugins for extensible workflows
- Create molecules.md with full design for code-review molecule
- Document plugin CLAUDE.md format with frontmatter
- Describe phased execution (discovery/structural/tactical/synthesis)
- Include implementation plan and usage examples
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Rewrite vision.md with enterprise cognitive processing framing
- Expand README with comprehensive project overview
- Remove internal strategic references from merge-queue-design.md
- Position Gas Town as "IDE of 2026" for AI agent orchestration
Key messaging:
- Enterprise-grade cognitive processing machine
- Molecules as structured workflow guardrails
- Nondeterministic idempotence for crash recovery
- Beads as unified control/data plane
- Hierarchical auditability and observability
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Key additions:
- Explain that beads is BOTH data and control plane (intentional blur)
- Add 'Operational Molecules' section with mol-polecat-work, mol-rig-activate, mol-graceful-shutdown examples
- Emphasize 'nondeterministic idempotence' as THE key property enabling autonomous operation
- Show that molecules aren't just for work - they're for any multi-step cognitive process
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Documents the full process for bootstrapping a Gas Town from a harness
repository, including Go installation, gt binary build, rig population,
and beads initialization.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update all code and documentation to use deacon/ instead of daemon/
for lifecycle mail targets:
- internal/cmd/handoff.go: getManager() returns deacon/ for Mayor/Witness
- internal/daemon/lifecycle.go: ProcessLifecycleRequests uses deacon/ inbox
- docs/architecture.md: update all references in lifecycle docs
- scripts/mayor-respawn-daemon.sh: use BD_IDENTITY=deacon for mail commands
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
