Add directory discipline section to mayor priming
- Fix gastown/mayor/rig/CLAUDE.md (had wrong crew content) - Add CRITICAL: Directory Discipline section to mayor.md.tmpl - Emphasizes working from mayor/rig/, not crew/* or town root
This commit is contained in:
Steve Yegge
185
CLAUDE.md
185
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 <id>` - View issue details
|
||||
|
||||
- **Issue prefix**: `gt-`
|
||||
- **Architecture**: docs/architecture.md
|
||||
### Communication
|
||||
- `gt mail inbox` - Check your messages
|
||||
- `gt mail read <id>` - Read specific message
|
||||
- `gt mail send <addr> -s "Subject" -m "Message"` - Send mail
|
||||
|
||||
### Status
|
||||
- `gt status` - Overall town status
|
||||
- `gt rigs` - List all rigs
|
||||
|
||||
### Work Management
|
||||
- `gt spawn --issue <id>` - Spawn polecat for issue
|
||||
- `bd update <id> --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 <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:
|
||||
```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 <files> (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
|
||||
|
||||
@@ -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
|
||||
- `<rig>/crew/*` - Those are CREW workers, not you
|
||||
- `<rig>/polecats/*` - Those are POLECATS, not you
|
||||
|
||||
### ALWAYS work from:
|
||||
- `<rig>/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,
|
||||
|
||||
Reference in New Issue
Block a user