From e0b6be0eafe8089c0a016532f4bd1ebb97e72df0 Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Tue, 30 Dec 2025 18:02:54 -0800 Subject: [PATCH] Document cross-rig worktree pattern (gt-xheo6.4) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation for crew workers using cross-rig worktrees: - Added Cross-Rig Worktrees section to crew.md.tmpl template - Created docs/understanding-gas-town.md with role taxonomy Key points documented: - Crew vs Dogs distinction (dogs = Deacon infra, not user work) - Identity preservation across rigs (BD_ACTOR stays the same) - When to use worktrees vs dispatch to local workers - Directory structure convention: ~/gt//crew/-/ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/understanding-gas-town.md | 170 ++++++++++++++++++++++++++ internal/templates/roles/crew.md.tmpl | 39 ++++++ 2 files changed, 209 insertions(+) create mode 100644 docs/understanding-gas-town.md diff --git a/docs/understanding-gas-town.md b/docs/understanding-gas-town.md new file mode 100644 index 00000000..e11f940b --- /dev/null +++ b/docs/understanding-gas-town.md @@ -0,0 +1,170 @@ +# Understanding Gas Town + +This document provides a conceptual overview of Gas Town's architecture, focusing on +the role taxonomy and how different agents interact. + +## Role Taxonomy + +Gas Town has several agent types, each with distinct responsibilities and lifecycles. + +### Infrastructure Roles + +These roles manage the Gas Town system itself: + +| Role | Description | Lifecycle | +|------|-------------|-----------| +| **Mayor** | Global coordinator at town root | Singleton, persistent | +| **Deacon** | Background supervisor daemon | Singleton, persistent | +| **Witness** | Per-rig polecat lifecycle manager | One per rig, persistent | +| **Refinery** | Per-rig merge queue processor | One per rig, persistent | + +### Worker Roles + +These roles do actual project work: + +| Role | Description | Lifecycle | +|------|-------------|-----------| +| **Polecat** | Ephemeral worker with own worktree | Transient, Witness-managed | +| **Crew** | Persistent worker with own clone | Long-lived, user-managed | +| **Dog** | Deacon helper for infrastructure tasks | Ephemeral, Deacon-managed | + +## Crew vs Polecats + +Both do project work, but with key differences: + +| Aspect | Crew | Polecat | +|--------|------|---------| +| **Lifecycle** | Persistent (user controls) | Transient (Witness controls) | +| **Monitoring** | None | Witness watches, nudges, recycles | +| **Work assignment** | Human-directed or self-assigned | Slung via `gt sling` | +| **Git state** | Pushes to main directly | Works on branch, Refinery merges | +| **Cleanup** | Manual | Automatic on completion | +| **Identity** | `/crew/` | `/polecats/` | + +**When to use Crew**: +- Exploratory work +- Long-running projects +- Work requiring human judgment +- Tasks where you want direct control + +**When to use Polecats**: +- Discrete, well-defined tasks +- Batch work (via swarms) +- Parallelizable work +- Work that benefits from supervision + +## Dogs vs Crew + +**Dogs are NOT workers**. This is a common misconception. + +| Aspect | Dogs | Crew | +|--------|------|------| +| **Owner** | Deacon | Human | +| **Purpose** | Infrastructure tasks | Project work | +| **Scope** | Narrow, focused utilities | General purpose | +| **Lifecycle** | Very short (single task) | Long-lived | +| **Example** | Boot (triages Deacon health) | Joe (fixes bugs, adds features) | + +Dogs are the Deacon's helpers for system-level tasks: +- **Boot**: Triages Deacon health on daemon tick +- Future dogs might handle: log rotation, health checks, etc. + +If you need to do work in another rig, use **worktrees**, not dogs. + +## Cross-Rig Work Patterns + +When a crew member needs to work on another rig: + +### Option 1: Worktrees (Preferred) + +Create a worktree in the target rig: + +```bash +# gastown/crew/joe needs to fix a beads bug +gt worktree beads +# Creates ~/gt/beads/crew/gastown-joe/ +# Identity preserved: BD_ACTOR = gastown/crew/joe +``` + +Directory structure: +``` +~/gt/beads/crew/gastown-joe/ # joe from gastown working on beads +~/gt/gastown/crew/beads-wolf/ # wolf from beads working on gastown +``` + +### Option 2: Dispatch to Local Workers + +For work that should be owned by the target rig: + +```bash +# Create issue in target rig +bd create --prefix beads "Fix authentication bug" + +# Sling to target rig's workers +gt sling bd-xyz beads +``` + +### When to Use Which + +| Scenario | Approach | +|----------|----------| +| You need to fix something quick | Worktree | +| Work should appear in your CV | Worktree | +| Work should be done by target rig team | Dispatch | +| Infrastructure/system task | Let Deacon handle it | + +## Directory Structure + +``` +~/gt/ Town root +├── .beads/ Town-level beads (hq-* prefix, mail) +├── mayor/ Mayor config +│ └── town.json +├── deacon/ Deacon daemon +│ └── dogs/ Deacon helpers (NOT workers) +│ └── boot/ Health triage dog +└── / Project container + ├── config.json Rig identity + ├── .beads/ → mayor/rig/.beads (symlink or redirect) + ├── .repo.git/ Bare repo (shared by worktrees) + ├── mayor/rig/ Mayor's clone (canonical beads) + ├── refinery/rig/ Worktree on main + ├── witness/ No clone (monitors only) + ├── crew/ Persistent human workspaces + │ ├── joe/ Local crew member + │ └── beads-wolf/ Cross-rig worktree (wolf from beads) + └── polecats/ Ephemeral worker worktrees + └── Toast/ Individual polecat +``` + +## Identity and Attribution + +All work is attributed to the actor who performed it: + +``` +Git commits: Author: gastown/crew/joe +Beads issues: created_by: gastown/crew/joe +Events: actor: gastown/crew/joe +``` + +Identity is preserved even when working cross-rig: +- `gastown/crew/joe` working in `~/gt/beads/crew/gastown-joe/` +- Commits still attributed to `gastown/crew/joe` +- Work appears on joe's CV, not beads rig's workers + +## The Propulsion Principle + +All Gas Town agents follow the same core principle: + +> **If you find something on your hook, YOU RUN IT.** + +This applies regardless of role. The hook is your assignment. Execute it immediately +without waiting for confirmation. Gas Town is a steam engine - agents are pistons. + +## Common Mistakes + +1. **Using dogs for user work**: Dogs are Deacon infrastructure. Use crew or polecats. +2. **Confusing crew with polecats**: Crew is persistent and human-managed. Polecats are transient and Witness-managed. +3. **Working in wrong directory**: Gas Town uses cwd for identity detection. Stay in your home directory. +4. **Waiting for confirmation when work is hooked**: The hook IS your assignment. Execute immediately. +5. **Creating worktrees when dispatch is better**: If work should be owned by the target rig, dispatch it instead. diff --git a/internal/templates/roles/crew.md.tmpl b/internal/templates/roles/crew.md.tmpl index 6595f88f..2ab0d408 100644 --- a/internal/templates/roles/crew.md.tmpl +++ b/internal/templates/roles/crew.md.tmpl @@ -135,6 +135,45 @@ You work from: {{ .WorkDir }} This is a full git clone of the project repository. You have complete autonomy over this workspace. +## Cross-Rig Worktrees + +When you need to work on a different rig (e.g., fix a beads bug while assigned +to gastown), you can create a worktree in the target rig: + +```bash +# Create/enter worktree in another rig +gt worktree beads # Creates ~/gt/beads/crew/{{ .RigName }}-{{ .Polecat }}/ + +# List your worktrees across all rigs +gt worktree list + +# Remove when done +gt worktree remove beads +``` + +**Directory structure:** +``` +~/gt/beads/crew/{{ .RigName }}-{{ .Polecat }}/ # You (from {{ .RigName }}) working on beads +~/gt/gastown/crew/beads-wolf/ # Wolf (from beads) working on gastown +``` + +**Key principles:** +- **Identity preserved**: Your `BD_ACTOR` stays `{{ .RigName }}/crew/{{ .Polecat }}` even in the beads worktree +- **No conflicts**: Each crew member gets their own worktree in the target rig +- **Persistent**: Worktrees survive sessions (matches your crew lifecycle) +- **Direct work**: You work directly in the target rig, no delegation + +**When to use worktrees vs dispatch:** +| Scenario | Approach | +|----------|----------| +| Quick fix in another rig | Use `gt worktree` | +| Substantial work in another rig | Use `gt worktree` | +| Work should be done by target rig's workers | `gt sling` to target rig | +| Infrastructure task | Leave it to the Deacon's dogs | + +**Note**: Dogs are Deacon infrastructure helpers (like Boot). They're NOT for user-facing +work. If you need to fix something in another rig, use worktrees, not dogs. + ## Gotchas when Filing Beads **Temporal language inverts dependencies.** "Phase 1 blocks Phase 2" is backwards.