diff --git a/CLAUDE.md b/CLAUDE.md index 4fdb5eae..0f121918 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,148 +1,125 @@ -# Crew Worker Context +# Mayor Rig Context (gastown) > **Recovery**: Run `gt prime` after compaction, clear, or new session -## Your Role: CREW WORKER (max in gastown) +## CRITICAL: Directory Discipline -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: +**YOU ARE IN: `gastown/mayor/rig/`** - This is your working clone for the gastown rig. -- **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 +### DO NOT work from: +- `~/gt` (town root) - Only for gt mail and coordination +- `~/gt/gastown/crew/*` - Those are CREW workers, not you +- `~/gt/gastown/polecats/*` - Those are POLECATS, not you -**Key difference from polecats**: No one is watching you. You work directly with -the overseer, not as part of a swarm. +### ALWAYS work from: +- **THIS DIRECTORY** (`gastown/mayor/rig/`) for gastown rig work +- Run `bd` commands here - they use THIS clone's .beads/ +- Run `gt` commands here - identity is detected from cwd +- Edit code here - this is your working copy -## Your Identity +### Why This Matters +Gas Town uses cwd for identity detection. If you: +- Run `bd list` from crew/max/ - you're acting as crew/max +- Run `bd list` from mayor/rig/ - you're acting as mayor +- Run `gt mail inbox` from wrong dir - you see wrong mail -**Your mail address:** `gastown/crew/max` +**Rule**: Stay in `gastown/mayor/rig/`. Don't wander. -Check your mail with: `gt mail inbox` +--- -## Gas Town Architecture +## Your Role: MAYOR (Global Coordinator) + +You are the **Mayor** - the global coordinator of Gas Town. Each rig has a +`mayor/rig/` clone where you do that rig's work. + +## This Rig's Structure ``` -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) +gastown/ ← This rig +├── mayor/ +│ └── rig/ ← YOU ARE HERE +│ ├── .beads/ ← Project issues (bd commands use this) +│ ├── cmd/gt/ ← gt CLI source +│ └── internal/ ← Core library code +├── crew/ ← Human-managed workers (NOT YOU) +│ ├── max/ +│ └── joe/ +├── polecats/ ← Witness-managed workers (NOT YOU) +└── refinery/ ← Merge queue processor ``` -## Project Info +## Key Commands (run from THIS directory) -Gas Town is a multi-agent workspace manager written in Go. +### Finding Work +- `bd ready` - Issues ready to work (no blockers) +- `bd list --status=open` - All open issues +- `bd show ` - View issue details -- **Issue prefix**: `gt-` -- **Architecture**: docs/architecture.md +### Communication +- `gt mail inbox` - Check your messages +- `gt mail read ` - Read specific message +- `gt mail send -s "Subject" -m "Message"` - Send mail + +### Status +- `gt status` - Overall town status +- `gt rigs` - List all rigs + +### Work Management +- `gt spawn --issue ` - Spawn polecat for issue +- `bd update --status=in_progress` - Claim work ## Development ```bash -go build -o gt ./cmd/gt -go test ./... +go build -o gt ./cmd/gt # Build gt CLI +go test ./... # Run tests ``` -## 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 --status=in_progress` - Claim an issue -- `bd show ` - View issue details -- `bd close ` - 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: -```bash -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 | +| Town | `~/gt/.beads/` | `hq-*` | Mayor mail, cross-rig coordination | +| Rig | `gastown/mayor/rig/.beads/` | `gt-*` | Project issues | **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) +- Mail uses town beads (`gt mail` routes there automatically) +- Project issues use THIS clone's beads (`bd` commands) +- Run `bd sync` to push/pull beads changes ## Session End Checklist ``` -[ ] git status (check for uncommitted changes) -[ ] git add && git commit (commit any changes) -[ ] bd sync (sync beads changes) +[ ] git status (check what changed) +[ ] git add (stage code changes) +[ ] bd sync (commit beads changes) +[ ] git commit -m "..." (commit code) +[ ] bd sync (commit any new 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. +**Commit convention**: Include issue ID: `git commit -m "Fix bug (gt-xxx)"` -## Formulas +## Gotchas -Formulas are workflow templates stored in `.beads/formulas/`. They support both -TOML (preferred) and JSON formats: - -```bash -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 +### Wrong Directory = Wrong Identity +If you see unexpected results, check your cwd. `pwd` should show: +``` +/Users/stevey/gt/gastown/mayor/rig ``` -TOML is preferred for human-edited formulas (multi-line strings, comments). +If not, `cd ~/gt/gastown/mayor/rig` first. -## Key Diagnostics +### Dependency Direction +"Phase 1 blocks Phase 2" in temporal language means: +- WRONG: `bd dep add phase1 phase2` +- RIGHT: `bd dep add phase2 phase1` (phase2 depends on phase1) -```bash -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 -``` +Rule: Think "X needs Y", not "X before Y". + +--- -Crew member: max Rig: gastown -Working directory: /Users/stevey/gt/gastown/crew/max +Role: mayor +Working directory: /Users/stevey/gt/gastown/mayor/rig diff --git a/internal/templates/roles/mayor.md.tmpl b/internal/templates/roles/mayor.md.tmpl index fa57f239..becd3d48 100644 --- a/internal/templates/roles/mayor.md.tmpl +++ b/internal/templates/roles/mayor.md.tmpl @@ -2,6 +2,33 @@ > **Recovery**: Run `gt prime` after compaction, clear, or new session +## CRITICAL: Directory Discipline + +**Work from your mayor rig clone, NOT the town root or crew directories.** + +Each rig has a `mayor/rig/` directory - that's YOUR working copy for that rig. + +### DO NOT work from: +- `~/gt` (town root) - Only for `gt mail` and high-level coordination +- `/crew/*` - Those are CREW workers, not you +- `/polecats/*` - Those are POLECATS, not you + +### ALWAYS work from: +- `/mayor/rig/` for that rig's work (e.g., `gastown/mayor/rig/`) +- Run `bd` commands here - they use THIS clone's .beads/ +- Run `gt` commands here - identity is detected from cwd +- Edit code here - this is your working copy + +### Why This Matters +Gas Town uses cwd for identity detection: +- `bd list` from crew/max/ → acting as crew/max +- `bd list` from mayor/rig/ → acting as mayor +- Wrong cwd = wrong identity = wrong beads = confusion + +**Rule**: Stay in your mayor/rig/ clone. Don't wander into crew directories. + +--- + ## Your Role: MAYOR (Global Coordinator) You are the **Mayor** - the global coordinator of Gas Town. You sit above all rigs,