From 62f3f727ab2adff70c63c6e611a8e24fa4d6b74f Mon Sep 17 00:00:00 2001
From: Steve Yegge <steve.yegge@gmail.com>
Date: Fri, 26 Dec 2025 20:05:26 -0800
Subject: [PATCH] docs: Add prefix-based routing to all role templates
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Explains how bd commands route to the correct rig based on issue
prefix, and documents routes.jsonl location and debug mode.

Updated templates:
- mayor.md.tmpl (full section)
- crew.md.tmpl (full section)
- polecat.md.tmpl (full section)
- witness.md.tmpl (compact note)
- refinery.md.tmpl (compact note)
- deacon.md.tmpl (full section)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 internal/templates/roles/crew.md.tmpl     | 14 ++++++++++++++
 internal/templates/roles/deacon.md.tmpl   |  8 ++++++++
 internal/templates/roles/mayor.md.tmpl    | 19 +++++++++++++++++++
 internal/templates/roles/polecat.md.tmpl  | 14 ++++++++++++++
 internal/templates/roles/refinery.md.tmpl |  2 ++
 internal/templates/roles/witness.md.tmpl  |  2 ++
 6 files changed, 59 insertions(+)

diff --git a/internal/templates/roles/crew.md.tmpl b/internal/templates/roles/crew.md.tmpl
index 23d3a340..19bf2890 100644
--- a/internal/templates/roles/crew.md.tmpl
+++ b/internal/templates/roles/crew.md.tmpl
@@ -43,6 +43,20 @@ Town ({{ .TownRoot }})
 - 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
 
+## Prefix-Based Routing
+
+`bd` commands automatically route to the correct rig based on issue ID prefix:
+
+```
+bd show gt-xyz   # Routes to gastown beads (from anywhere in town)
+bd show hq-abc   # Routes to town beads
+```
+
+**How it works:**
+- Routes defined in `~/gt/.beads/routes.jsonl`
+- Each rig's prefix (e.g., `gt-`) maps to its beads location
+- Debug with: `BD_DEBUG_ROUTING=1 bd show <id>`
+
 ## Your Workspace
 
 You work from: {{ .WorkDir }}
diff --git a/internal/templates/roles/deacon.md.tmpl b/internal/templates/roles/deacon.md.tmpl
index 0213bea2..41bc9513 100644
--- a/internal/templates/roles/deacon.md.tmpl
+++ b/internal/templates/roles/deacon.md.tmpl
@@ -33,6 +33,14 @@ Go Daemon (watches you, auto-starts you if down)
 patrol cycle is a wisp that gets squashed to a digest when complete. This keeps
 beads clean while maintaining an audit trail.
 
+## Prefix-Based Routing
+
+`bd` commands automatically route to the correct rig based on issue ID prefix:
+- `bd show gt-xyz` routes to gastown beads
+- `bd show hq-abc` routes to town beads
+
+Routes defined in `~/gt/.beads/routes.jsonl`. Debug with: `BD_DEBUG_ROUTING=1 bd show <id>`
+
 ## 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 ba346247..16632c46 100644
--- a/internal/templates/roles/mayor.md.tmpl
+++ b/internal/templates/roles/mayor.md.tmpl
@@ -69,6 +69,25 @@ Town ({{ .TownRoot }})
 - The rig-level `<rig>/.beads/` is **gitignored** (local runtime state)
 - Rig beads use `beads-sync` branch for multi-clone coordination
 
+## Prefix-Based Routing
+
+`bd` commands automatically route to the correct rig based on issue ID prefix:
+
+```
+bd show gt-xyz   # Routes to gastown beads (from anywhere in town)
+bd show hq-abc   # Routes to town beads
+bd show bd-def   # Routes to beads rig
+```
+
+**How it works:**
+- Routes defined in `~/gt/.beads/routes.jsonl`
+- `gt rig add` auto-registers new rig prefixes
+- Each rig's prefix (e.g., `gt-`) maps to its beads location
+
+**Debug routing:** `BD_DEBUG_ROUTING=1 bd show <id>`
+
+**Conflicts:** If two rigs share a prefix, use `bd rename-prefix <new>` to fix.
+
 ## 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 22407e59..4e63f668 100644
--- a/internal/templates/roles/polecat.md.tmpl
+++ b/internal/templates/roles/polecat.md.tmpl
@@ -40,6 +40,20 @@ Town ({{ .TownRoot }})
 - The rig-level `{{ .RigName }}/.beads/` is **gitignored** (local runtime state)
 - Run `bd sync` to push/pull beads changes via the `beads-sync` branch
 
+## Prefix-Based Routing
+
+`bd` commands automatically route to the correct rig based on issue ID prefix:
+
+```
+bd show gt-xyz   # Routes to gastown beads (from anywhere in town)
+bd show hq-abc   # Routes to town beads
+```
+
+**How it works:**
+- Routes defined in `~/gt/.beads/routes.jsonl`
+- Each rig's prefix (e.g., `gt-`) maps to its beads location
+- Debug with: `BD_DEBUG_ROUTING=1 bd show <id>`
+
 ## Gotchas when Filing Beads
 
 **Temporal language inverts dependencies.** "Phase 1 blocks Phase 2" is backwards.
diff --git a/internal/templates/roles/refinery.md.tmpl b/internal/templates/roles/refinery.md.tmpl
index e751e969..7a89cb52 100644
--- a/internal/templates/roles/refinery.md.tmpl
+++ b/internal/templates/roles/refinery.md.tmpl
@@ -149,6 +149,8 @@ gt mail send {{ .RigName }}/<worker> -s "Rebase needed" \
 - `bd close <id>` - Close issue after merge
 - `bd sync` - Sync beads changes
 
+**Prefix-based routing:** `bd show gt-xyz` works from anywhere - routes via `~/gt/.beads/routes.jsonl`.
+
 ## Session Cycling
 
 When your context fills up:
diff --git a/internal/templates/roles/witness.md.tmpl b/internal/templates/roles/witness.md.tmpl
index 6f9c4982..72af7432 100644
--- a/internal/templates/roles/witness.md.tmpl
+++ b/internal/templates/roles/witness.md.tmpl
@@ -76,6 +76,8 @@ bd show <id>                             # Issue details
 bd list --status=in_progress             # Active work in rig
 ```
 
+**Prefix-based routing:** `bd show gt-xyz` works from anywhere - routes via `~/gt/.beads/routes.jsonl`.
+
 ---
 
 ## 🚀 PROPULSION: The Universal Law