From 5a14053a6bd32444bb4a297feb7b89acda53035e Mon Sep 17 00:00:00 2001 From: mayor Date: Tue, 20 Jan 2026 17:48:26 -0800 Subject: [PATCH] docs(templates): add explicit bead filing guidance to role templates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Agents were misfiling beads in HQ when they should go to project-specific rigs (beads, gastown). The templates explained routing mechanics but not decision making. Added "Where to File Beads" sections with: - Routing table based on what code the issue affects - Simple heuristic: "Which repo would the fix be committed to?" - Examples for bd CLI → beads, gt CLI → gastown, coordination → HQ Affects: mayor, deacon, crew, polecat templates. Co-Authored-By: Claude Opus 4.5 --- internal/templates/roles/crew.md.tmpl | 16 ++++++++++++++++ internal/templates/roles/deacon.md.tmpl | 16 ++++++++++++++++ internal/templates/roles/mayor.md.tmpl | 21 +++++++++++++++++++++ internal/templates/roles/polecat.md.tmpl | 16 ++++++++++++++++ 4 files changed, 69 insertions(+) diff --git a/internal/templates/roles/crew.md.tmpl b/internal/templates/roles/crew.md.tmpl index 42de7b38..92d1a426 100644 --- a/internal/templates/roles/crew.md.tmpl +++ b/internal/templates/roles/crew.md.tmpl @@ -195,6 +195,22 @@ gt worktree remove beads **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. +## Where to File Beads + +**File in the rig that OWNS the code, not your current rig.** + +You're working in **{{ .RigName }}** (prefix `{{ .IssuePrefix }}-`). Issues about THIS rig's code +go here by default. But if you discover bugs/issues in OTHER projects: + +| Issue is about... | File in | Command | +|-------------------|---------|---------| +| This rig's code ({{ .RigName }}) | Here (default) | `bd create "..."` | +| `bd` CLI (beads tool) | **beads** | `bd create --rig beads "..."` | +| `gt` CLI (gas town tool) | **gastown** | `bd create --rig gastown "..."` | +| Cross-rig coordination | **HQ** | `bd create --prefix hq- "..."` | + +**The test**: "Which repo would the fix be committed to?" + ## Gotchas when Filing Beads **Temporal language inverts dependencies.** "Phase 1 blocks Phase 2" is backwards. diff --git a/internal/templates/roles/deacon.md.tmpl b/internal/templates/roles/deacon.md.tmpl index 44bdbaf8..12c98534 100644 --- a/internal/templates/roles/deacon.md.tmpl +++ b/internal/templates/roles/deacon.md.tmpl @@ -111,6 +111,22 @@ beads clean while maintaining an audit trail. Routes defined in `~/gt/.beads/routes.jsonl`. Debug with: `BD_DEBUG_ROUTING=1 bd show ` +## Where to File Beads (CRITICAL) + +**File in the rig that OWNS the code, not HQ by default.** + +| Issue is about... | File in | Command | +|-------------------|---------|---------| +| `bd` CLI (beads tool bugs, features) | **beads** | `bd create --rig beads "..."` | +| `gt` CLI (gas town tool bugs, features) | **gastown** | `bd create --rig gastown "..."` | +| Deacon/witness/refinery/patrol code | **gastown** | `bd create --rig gastown "..."` | +| Cross-rig coordination, agent assignments | **HQ** | `bd create "..."` (default) | + +**The test**: "Which repo would the fix be committed to?" +- Fix in `anthropics/beads` → file in beads rig +- Fix in `anthropics/gas-town` → file in gastown rig +- Pure coordination (no code) → file in HQ + ## Gotchas when Filing Beads **Temporal language inverts dependencies.** "Phase 1 blocks Phase 2" is backwards. diff --git a/internal/templates/roles/mayor.md.tmpl b/internal/templates/roles/mayor.md.tmpl index 87e128c7..a6e80e3e 100644 --- a/internal/templates/roles/mayor.md.tmpl +++ b/internal/templates/roles/mayor.md.tmpl @@ -162,6 +162,27 @@ bd show hq-abc # Routes to town beads **Conflicts:** If two rigs share a prefix, use `bd rename-prefix ` to fix. +## Where to File Beads (CRITICAL) + +**File in the rig that OWNS the code, not where you're standing.** + +| Issue is about... | File in | Command | +|-------------------|---------|---------| +| `bd` CLI (beads tool bugs, features, docs) | **beads** | `bd create --rig beads "..."` | +| `gt` CLI (gas town tool bugs, features) | **gastown** | `bd create --rig gastown "..."` | +| Polecat/witness/refinery/convoy code | **gastown** | `bd create --rig gastown "..."` | +| Wyvern game features | **wyvern** | `bd create --rig wyvern "..."` | +| Cross-rig coordination, convoys, mail threads | **HQ** | `bd create "..."` (default) | +| Agent role descriptions, assignments | **HQ** | `bd create "..."` (default) | + +**The test**: "Which repo would the fix be committed to?" +- Fix in `anthropics/beads` → file in beads rig +- Fix in `anthropics/gas-town` → file in gastown rig +- Pure coordination (no code) → file in HQ + +**Common mistake**: Filing `bd` CLI issues in HQ because you're "coordinating." +Wrong. The issue is about beads code, so it goes in the beads rig. + ## Gotchas when Filing Beads **Temporal language inverts dependencies.** "Phase 1 blocks Phase 2" is backwards. diff --git a/internal/templates/roles/polecat.md.tmpl b/internal/templates/roles/polecat.md.tmpl index 641fccb1..c3eaf05f 100644 --- a/internal/templates/roles/polecat.md.tmpl +++ b/internal/templates/roles/polecat.md.tmpl @@ -180,6 +180,22 @@ bd show hq-abc # Routes to town beads - Each rig's prefix (e.g., `gt-`) maps to its beads location - Debug with: `BD_DEBUG_ROUTING=1 bd show ` +## Where to File Beads + +**File in the rig that OWNS the code, not your current rig.** + +You're working in **{{ .RigName }}** (prefix `{{ .IssuePrefix }}-`). Issues about THIS rig's code +go here by default. But if you discover bugs/issues in OTHER projects: + +| Issue is about... | File in | Command | +|-------------------|---------|---------| +| This rig's code ({{ .RigName }}) | Here (default) | `bd create "..."` | +| `bd` CLI (beads tool) | **beads** | `bd create --rig beads "..."` | +| `gt` CLI (gas town tool) | **gastown** | `bd create --rig gastown "..."` | +| Cross-rig coordination | **HQ** | `bd create --prefix hq- "..."` | + +**The test**: "Which repo would the fix be committed to?" + ## Gotchas when Filing Beads **Temporal language inverts dependencies.** "Phase 1 blocks Phase 2" is backwards.