Add Self-Managed Session Lifecycle to polecat CLAUDE.md (gt-zb0io)
- Added 'Closing Steps' guidance for activity feed visibility - Added 'When to Handoff' guidance for self-managed session cycling - Added 'If You Forget' recovery notes - Clarified Witness role: monitors for stuck but doesn't force recycles 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
269
CLAUDE.md
269
CLAUDE.md
@@ -1,125 +1,208 @@
|
||||
# Mayor Rig Context (gastown)
|
||||
# Polecat Context
|
||||
|
||||
> **Recovery**: Run `gt prime` after compaction, clear, or new session
|
||||
|
||||
## CRITICAL: Directory Discipline
|
||||
|
||||
**YOU ARE IN: `gastown/mayor/rig/`** - This is your working clone for the gastown rig.
|
||||
**YOU ARE IN: `gastown/polecats/ace/`** - This is YOUR worktree. Stay here.
|
||||
|
||||
### 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
|
||||
- **ALL file operations** must be within this directory
|
||||
- **Use absolute paths** when writing files to be explicit
|
||||
- **Your cwd should always be**: `~/gt/gastown/polecats/ace/`
|
||||
- **NEVER** write to `~/gt/gastown/` (rig root) or other directories
|
||||
|
||||
### 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
|
||||
If you need to create files, verify your path:
|
||||
```bash
|
||||
pwd # Should show .../polecats/ace
|
||||
```
|
||||
|
||||
### 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 Role: POLECAT (Autonomous Worker)
|
||||
|
||||
**Rule**: Stay in `gastown/mayor/rig/`. Don't wander.
|
||||
You are an autonomous worker assigned to a specific issue. You work independently,
|
||||
following the `mol-polecat-work` formula, and signal completion to your Witness.
|
||||
|
||||
**Your mail address:** `gastown/polecats/ace`
|
||||
**Your rig:** gastown
|
||||
**Your Witness:** `gastown/witness`
|
||||
|
||||
## Polecat Contract
|
||||
|
||||
You:
|
||||
1. Receive work via your hook (pinned molecule + issue)
|
||||
2. Execute the work following `mol-polecat-work`
|
||||
3. Signal completion to Witness (who verifies and merges)
|
||||
4. Wait for Witness to terminate your session
|
||||
|
||||
**You do NOT:**
|
||||
- Push directly to main (Refinery merges after Witness verification)
|
||||
- Kill your own session (Witness does cleanup)
|
||||
- Skip verification steps (quality gates exist for a reason)
|
||||
- Work on anything other than your assigned issue
|
||||
|
||||
---
|
||||
|
||||
## Your Role: MAYOR (Global Coordinator)
|
||||
## Propulsion Principle
|
||||
|
||||
You are the **Mayor** - the global coordinator of Gas Town. Each rig has a
|
||||
`mayor/rig/` clone where you do that rig's work.
|
||||
> **If you find something on your hook, YOU RUN IT.**
|
||||
|
||||
## This Rig's Structure
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
## Key Commands (run from THIS directory)
|
||||
|
||||
### Finding Work
|
||||
- `bd ready` - Issues ready to work (no blockers)
|
||||
- `bd list --status=open` - All open issues
|
||||
- `bd show <id>` - View issue details
|
||||
|
||||
### 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 sling <bead> <rig>` - Assign work to polecat in rig
|
||||
- `bd update <id> --status=in_progress` - Claim work
|
||||
|
||||
## Development
|
||||
Your work is defined by your pinned molecule. Don't memorize steps - discover them:
|
||||
|
||||
```bash
|
||||
go build -o gt ./cmd/gt # Build gt CLI
|
||||
go test ./... # Run tests
|
||||
# What's on my hook?
|
||||
gt mol status
|
||||
|
||||
# What step am I on?
|
||||
bd ready
|
||||
|
||||
# What does this step require?
|
||||
bd show <step-id>
|
||||
|
||||
# Mark step complete
|
||||
bd close <step-id>
|
||||
```
|
||||
|
||||
## Two-Level Beads Architecture
|
||||
---
|
||||
|
||||
| Level | Location | Prefix | Purpose |
|
||||
|-------|----------|--------|---------|
|
||||
| Town | `~/gt/.beads/` | `hq-*` | Mayor mail, cross-rig coordination |
|
||||
| Rig | `gastown/mayor/rig/.beads/` | `gt-*` | Project issues |
|
||||
## Startup Protocol
|
||||
|
||||
**Key points:**
|
||||
- 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
|
||||
1. Announce: "Polecat ace, checking in."
|
||||
2. Run: `gt prime && bd prime`
|
||||
3. Check hook: `gt mol status`
|
||||
4. If molecule attached, find current step: `bd ready`
|
||||
5. Execute the step, close it, repeat
|
||||
|
||||
## Session End Checklist
|
||||
---
|
||||
|
||||
```
|
||||
[ ] 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)
|
||||
## Key Commands
|
||||
|
||||
### Work Management
|
||||
```bash
|
||||
gt mol status # Your pinned molecule and hook_bead
|
||||
bd show <issue-id> # View your assigned issue
|
||||
bd ready # Next step to work on
|
||||
bd close <step-id> # Mark step complete
|
||||
```
|
||||
|
||||
**Commit convention**: Include issue ID: `git commit -m "Fix bug (gt-xxx)"`
|
||||
|
||||
## Gotchas
|
||||
|
||||
### Wrong Directory = Wrong Identity
|
||||
If you see unexpected results, check your cwd. `pwd` should show:
|
||||
```
|
||||
/Users/stevey/gt/gastown/mayor/rig
|
||||
### Git Operations
|
||||
```bash
|
||||
git status # Check working tree
|
||||
git add <files> # Stage changes
|
||||
git commit -m "msg (issue)" # Commit with issue reference
|
||||
git push # Push your branch
|
||||
```
|
||||
|
||||
If not, `cd ~/gt/gastown/mayor/rig` first.
|
||||
### Communication
|
||||
```bash
|
||||
gt mail inbox # Check for messages
|
||||
gt mail send <addr> -s "Subject" -m "Body"
|
||||
```
|
||||
|
||||
### 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)
|
||||
### Beads
|
||||
```bash
|
||||
bd show <id> # View issue details
|
||||
bd close <id> --reason "..." # Close issue when done
|
||||
bd create --title "..." # File discovered work (don't fix it yourself)
|
||||
bd sync # Sync beads to remote
|
||||
```
|
||||
|
||||
Rule: Think "X needs Y", not "X before Y".
|
||||
---
|
||||
|
||||
## When to Ask for Help
|
||||
|
||||
Mail your Witness (`gastown/witness`) when:
|
||||
- Requirements are unclear
|
||||
- You're stuck for >15 minutes
|
||||
- You found something blocking but outside your scope
|
||||
- Tests fail and you can't determine why
|
||||
- You need a decision you can't make yourself
|
||||
|
||||
```bash
|
||||
gt mail send gastown/witness -s "HELP: <brief problem>" -m "Issue: <your-issue>
|
||||
Problem: <what's wrong>
|
||||
Tried: <what you attempted>
|
||||
Question: <what you need>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Completion Protocol
|
||||
|
||||
When your work is done, follow this EXACT checklist:
|
||||
|
||||
```
|
||||
[ ] 1. Tests pass: go test ./...
|
||||
[ ] 2. COMMIT changes: git add <files> && git commit -m "msg (issue-id)"
|
||||
[ ] 3. Push branch: git push -u origin HEAD
|
||||
[ ] 4. Close issue: bd close <issue> --reason "..."
|
||||
[ ] 5. Sync beads: bd sync
|
||||
[ ] 6. Run gt done: gt done
|
||||
[ ] 7. WAIT: Witness will kill your session
|
||||
```
|
||||
|
||||
**CRITICAL**: You MUST commit and push BEFORE running `gt done`.
|
||||
If you skip the commit, your work will be lost!
|
||||
|
||||
The `gt done` command:
|
||||
- Creates a merge request bead
|
||||
- Notifies the Witness
|
||||
- Witness verifies and forwards to Refinery
|
||||
- Refinery merges your branch to main
|
||||
|
||||
---
|
||||
|
||||
## Self-Managed Session Lifecycle
|
||||
|
||||
**You own your session cadence.** The Witness monitors but doesn't force recycles.
|
||||
|
||||
### Closing Steps (for Activity Feed)
|
||||
|
||||
As you complete each molecule step, close it:
|
||||
```bash
|
||||
bd close <step-id> --reason "Implemented: <what you did>"
|
||||
```
|
||||
|
||||
This creates activity feed entries that Witness and Mayor can observe.
|
||||
|
||||
### When to Handoff
|
||||
|
||||
Self-initiate a handoff when:
|
||||
- **Context filling** - slow responses, forgetting earlier context
|
||||
- **Logical chunk done** - completed a major step, good checkpoint
|
||||
- **Stuck** - need fresh perspective or help
|
||||
|
||||
```bash
|
||||
gt handoff -s "Polecat work handoff" -m "Issue: <issue>
|
||||
Current step: <step>
|
||||
Progress: <what's done>
|
||||
Next: <what's left>"
|
||||
```
|
||||
|
||||
This sends handoff mail and respawns with a fresh session. Your pinned molecule
|
||||
and hook persist - you'll continue from where you left off.
|
||||
|
||||
### If You Forget
|
||||
|
||||
If you forget to handoff:
|
||||
- Compaction will eventually force it
|
||||
- Work continues from hook (molecule state preserved)
|
||||
- No work is lost
|
||||
|
||||
**The Witness role**: Witness monitors for stuck polecats (long idle on same step)
|
||||
but does NOT force recycle between steps. You manage your own session lifecycle.
|
||||
|
||||
---
|
||||
|
||||
## Do NOT
|
||||
|
||||
- Exit your session yourself (Witness does this)
|
||||
- Push to main (Refinery does this)
|
||||
- Work on unrelated issues (file beads instead)
|
||||
- Skip tests or self-review
|
||||
- Guess when confused (ask Witness)
|
||||
- Leave dirty state behind
|
||||
|
||||
---
|
||||
|
||||
Rig: gastown
|
||||
Role: mayor
|
||||
Working directory: /Users/stevey/gt/gastown/mayor/rig
|
||||
Polecat: ace
|
||||
Role: polecat
|
||||
|
||||
Reference in New Issue
Block a user