docs: add architecture.md and update manager.go comments (gt-5st7b)

Phase 5 of epic gt-4r1ph (align agent/role beads with two-level architecture): - Create docs/architecture.md with agent bead storage table documenting the correct two-level architecture: - Town beads (~/gt/.beads/): hq-mayor, hq-deacon, hq-*-role - Rig beads (<rig>/.beads/): <prefix>-<rig>-witness, <prefix>-<rig>-refinery - Update internal/rig/manager.go initAgentBeads() comments with MIGRATION NOTEs explaining current state vs target architecture (gt-4r1ph) - Close PR #50 with explanation that the fix direction was wrong CLAUDE.md templates already correctly document hq-* for town beads and project prefix for rig beads. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-03 20:59:08 -08:00
parent 36301adf20
commit 3e39f25064
2 changed files with 119 additions and 3 deletions
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -0,0 +1,116 @@
+# Gas Town Architecture
+
+Technical architecture for Gas Town multi-agent workspace management.
+
+## Two-Level Beads Architecture
+
+Gas Town uses a two-level beads architecture to separate organizational coordination
+from project implementation work.
+
+| Level | Location | Prefix | Purpose |
+|-------|----------|--------|---------|
+| **Town** | `~/gt/.beads/` | `hq-*` | Cross-rig coordination, Mayor mail, agent identity |
+| **Rig** | `<rig>/mayor/rig/.beads/` | project prefix | Implementation work, MRs, project issues |
+
+### Town-Level Beads (`~/gt/.beads/`)
+
+Organizational chain for cross-rig coordination:
+- Mayor mail and messages
+- Convoy coordination (batch work across rigs)
+- Strategic issues and decisions
+- **Town-level agent beads** (Mayor, Deacon)
+- **Role definition beads** (global templates)
+
+### Rig-Level Beads (`<rig>/mayor/rig/.beads/`)
+
+Project chain for implementation work:
+- Bugs, features, tasks for the project
+- Merge requests and code reviews
+- Project-specific molecules
+- **Rig-level agent beads** (Witness, Refinery, Polecats)
+
+## Agent Bead Storage
+
+Agent beads track lifecycle state for each agent. Storage location depends on
+the agent's scope.
+
+| Agent Type | Scope | Bead Location | Bead ID Format |
+|------------|-------|---------------|----------------|
+| Mayor | Town | `~/gt/.beads/` | `hq-mayor` |
+| Deacon | Town | `~/gt/.beads/` | `hq-deacon` |
+| Dogs | Town | `~/gt/.beads/` | `hq-dog-<name>` |
+| Witness | Rig | `<rig>/.beads/` | `<prefix>-<rig>-witness` |
+| Refinery | Rig | `<rig>/.beads/` | `<prefix>-<rig>-refinery` |
+| Polecats | Rig | `<rig>/.beads/` | `<prefix>-<rig>-polecat-<name>` |
+
+### Role Beads
+
+Role beads are global templates stored in town beads with `hq-` prefix:
+- `hq-mayor-role` - Mayor role definition
+- `hq-deacon-role` - Deacon role definition
+- `hq-witness-role` - Witness role definition
+- `hq-refinery-role` - Refinery role definition
+- `hq-polecat-role` - Polecat role definition
+
+Each agent bead references its role bead via the `role_bead` field.
+
+## Agent Taxonomy
+
+### Town-Level Agents (Cross-Rig)
+
+| Agent | Role | Persistence |
+|-------|------|-------------|
+| **Mayor** | Global coordinator, handles cross-rig communication and escalations | Persistent |
+| **Deacon** | Daemon beacon - receives heartbeats, runs plugins and monitoring | Persistent |
+| **Dogs** | Long-running workers for cross-rig batch work | Variable |
+
+### Rig-Level Agents (Per-Project)
+
+| Agent | Role | Persistence |
+|-------|------|-------------|
+| **Witness** | Monitors polecat health, handles nudging and cleanup | Persistent |
+| **Refinery** | Processes merge queue, runs verification | Persistent |
+| **Polecats** | Ephemeral workers assigned to specific issues | Ephemeral |
+
+## Directory Structure
+
+```
+~/gt/                           Town root
+├── .beads/                     Town-level beads (hq-* prefix)
+│   ├── config.yaml             Beads configuration
+│   ├── issues.jsonl            Town issues (mail, agents, convoys)
+│   └── routes.jsonl            Prefix → rig routing table
+├── mayor/                      Mayor config
+│   └── town.json               Town configuration
+└── <rig>/                      Project container (NOT a git clone)
+    ├── config.json             Rig identity and beads prefix
+    ├── .beads/ → mayor/rig/.beads  Symlink to canonical beads
+    ├── .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/<name>/            Human workspaces
+    └── polecats/<name>/        Worker worktrees
+```
+
+## Beads Routing
+
+The `routes.jsonl` file maps issue ID prefixes to their storage locations:
+
+```jsonl
+{"prefix":"hq","path":"/Users/stevey/gt/.beads"}
+{"prefix":"gt","path":"/Users/stevey/gt/gastown/mayor/rig/.beads"}
+```
+
+This enables transparent cross-rig beads operations:
+
+```bash
+bd show hq-mayor    # Routes to town beads
+bd show gt-xyz      # Routes to gastown rig beads
+```
+
+## See Also
+
+- [reference.md](reference.md) - Command reference
+- [molecules.md](molecules.md) - Workflow molecules
+- [identity.md](identity.md) - Agent identity and BD_ACTOR