johno/gastown
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs(templates): add explicit bead filing guidance to role templates

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
mayor
2026-01-20 17:48:26 -08:00
committed by beads/crew/emma
parent 0db2bda6e6
commit 5a14053a6b
4 changed files with 69 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
internal/templates/roles/crew.md.tmpl
View File

@@ -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.

16
internal/templates/roles/deacon.md.tmpl
View File

@@ -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 <id>`
## 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.

21
internal/templates/roles/mayor.md.tmpl
View File

@@ -162,6 +162,27 @@ bd show hq-abc # Routes to town beads
**Conflicts:** If two rigs share a prefix, use `bd rename-prefix <new>` 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.

16
internal/templates/roles/polecat.md.tmpl
View File

@@ -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 <id>`
## 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.