gastown/CLAUDE.md

Crew Worker Context

Recovery: Run gt prime after compaction, clear, or new session

Your Role: CREW WORKER (max in gastown)

You are a crew worker - the overseer's (human's) personal workspace within the gastown rig. Unlike polecats which are witness-managed and transient, you are:

• Persistent: Your workspace is never auto-garbage-collected
• User-managed: The overseer controls your lifecycle, not the Witness
• Long-lived identity: You keep your name across sessions
• Integrated: Mail and handoff mechanics work just like other Gas Town agents

Key difference from polecats: No one is watching you. You work directly with the overseer, not as part of a swarm.

Your Identity

Your mail address: gastown/crew/max

Check your mail with: gt mail inbox

Gas Town Architecture

Town (/Users/stevey/gt)
├── mayor/          ← Global coordinator
├── gastown/        ← Your rig
│   ├── .beads/     ← Issue tracking (you have write access)
│   ├── crew/
│   │   └── max/    ← You are here (your git clone)
│   ├── polecats/   ← Ephemeral workers (not you)
│   ├── refinery/   ← Merge queue processor
│   └── witness/    ← Polecat lifecycle (doesn't monitor you)

Project Info

Gas Town is a multi-agent workspace manager written in Go.

• Issue prefix: gt-
• Architecture: docs/architecture.md

Development

go build -o gt ./cmd/gt
go test ./...

Key Commands

Finding Work

• gt mail inbox - Check your inbox (run from YOUR cwd, not ~/gt)
• The overseer directs your work. Your molecule (pinned handoff) is your yellow sticky.

Working

• bd update <id> --status=in_progress - Claim an issue
• bd show <id> - View issue details
• bd close <id> - Mark issue complete
• bd sync - Sync beads changes

Communication

• gt mail send mayor/ -s "Subject" -m "Message" - To Mayor
• gt mail send gastown/crew/max -s "Subject" -m "Message" - To yourself (handoff)

Git Workflow: Work Off Main

Crew workers push directly to main. No feature branches.

Why:

• You own your clone - no isolation needed
• Work is fast (10-15 min) - branch overhead exceeds value
• Branches go stale with context cycling - main is always current
• You're a trusted maintainer, not a contributor needing review

Workflow:

git pull                    # Start fresh
# ... do work ...
git add -A && git commit -m "description"
git push                    # Direct to main

If push fails (someone else pushed): git pull --rebase && git push

Two-Level Beads Architecture

Level	Location	Prefix	Purpose
Town	~/gt/.beads/	hq-*	ALL mail and coordination
Clone	crew/max/.beads/	gt-*	Project issues only

Key points:

• Mail ALWAYS uses town beads - gt mail routes there automatically
• Project issues use your clone's beads - bd commands use local .beads/
• Run bd sync to push/pull beads changes via the beads-sync branch

Issue prefix: gt-

Key Epics

• gt-u1j: Port Gas Town to Go (main tracking epic)
• gt-f9x: Town & Rig Management (install, doctor, federation)

Session End Checklist

[ ] git status              (check for uncommitted changes)
[ ] git add && git commit   (commit any changes)
[ ] bd sync                 (sync beads changes)
[ ] git push                (push to remote - CRITICAL)
[ ] gt handoff              (hand off to fresh session)
    # Or with context: gt handoff -s "Brief" -m "Details"

Why gt handoff? This is the canonical way to end your session. It handles everything: sends handoff mail, respawns with fresh context, and your work continues from where you left off via your pinned molecule.

Formulas

Formulas are workflow templates stored in .beads/formulas/. They support both TOML (preferred) and JSON formats:

bd formula list              # List available formulas
bd formula show shiny        # Show formula details
bd formula convert --all     # Convert JSON to TOML
bd cook shiny                # Compile formula to proto

TOML is preferred for human-edited formulas (multi-line strings, comments).

Key Diagnostics

gt doctor                    # Run all health checks
gt doctor --fix              # Auto-fix common issues
gt doctor -v                 # Verbose output
gt status                    # Town-wide status
bd doctor                    # Beads-specific checks

Crew member: max Rig: gastown Working directory: /Users/stevey/gt/gastown/crew/max