From ded1ffba0bc8db9381a4d583bd465e1a4f2d841f Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Sat, 20 Dec 2025 15:37:52 -0800 Subject: [PATCH] docs: add two-level beads architecture documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add clear explanations of the town-level vs rig-level beads architecture: - Town beads (~/gt/.beads): HQ coordination, no sync-branch - Rig beads (in git clones): project work, uses beads-sync branch - Clarify that rig-level .beads at container is gitignored Updated: - docs/architecture.md: New 'Two-Level Beads Architecture' section - CLAUDE.md: Enhanced existing section with table and sync-branch info - templates/roles/*.tmpl: Added beads architecture to crew, polecat, mayor 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 13 +++++++- docs/architecture.md | 40 ++++++++++++++++++++++++ internal/templates/roles/crew.md.tmpl | 12 +++++++ internal/templates/roles/mayor.md.tmpl | 13 ++++++++ internal/templates/roles/polecat.md.tmpl | 12 +++++++ 5 files changed, 89 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 730d97d7..37128a6a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -69,7 +69,18 @@ go test ./... ## Beads Database -Your rig has its own beads database at `/Users/stevey/gt/gastown/.beads` +**Two-level beads architecture** - understand this to avoid confusion: + +| Level | Location | sync-branch | Prefix | Purpose | +|-------|----------|-------------|--------|---------| +| Town | `~/gt/.beads/` | NOT set | `hq-*` | Mayor mail, HQ coordination | +| Rig | `crew/max/.beads/` (this clone) | `beads-sync` | `gt-*` | Project issues | + +**Key points:** +- You're in a **gastown.git clone** - your `.beads/` is tracked in the gastown repo +- The rig-level `~/gt/gastown/.beads/` is **gitignored** (local runtime state) +- Your beads sync via `beads-sync` branch to coordinate with other clones +- Run `bd sync` to push/pull beads changes Issue prefix: `gt-` diff --git a/docs/architecture.md b/docs/architecture.md index 8f431ce5..98f7efb4 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -203,6 +203,46 @@ There is no separate orchestrator maintaining workflow state. Beads IS the orche | **Pinned beads** | Ongoing concerns that don't close | Planned (post-v1) | | **Resource beads** | Leases, locks, quotas | Planned (post-v1) | +#### Two-Level Beads Architecture + +Gas Town uses a **two-level beads architecture**. This is critical to understand: + +``` +~/gt/ # Town repo (stevey-gt.git) +├── .beads/ # TOWN-LEVEL: HQ beads (tracked here) +│ ├── config.yaml # NO sync-branch (single clone) +│ └── issues.jsonl # hq-* prefix for mayor mail +│ +└── gastown/ # Rig container (NOT a git clone) + ├── .beads/ # GITIGNORED - local runtime state + │ └── (populated at runtime) + │ + └── crew/max/ # Project repo clone (gastown.git) + └── .beads/ # RIG-LEVEL: Project beads (tracked in gastown.git) + ├── config.yaml # sync-branch: beads-sync + └── issues.jsonl # gt-* prefix for project issues +``` + +**Key points:** + +| Level | Location | Git Repo | sync-branch | Prefix | Purpose | +|-------|----------|----------|-------------|--------|---------| +| Town | `~/gt/.beads/` | stevey-gt.git | NOT set | `hq-*` | Mayor mail, cross-rig coordination | +| Rig | `~/gt/gastown/crew/max/.beads/` | gastown.git | `beads-sync` | `gt-*` | Project bugs, features, tasks | + +**Why two levels?** +- **Town beads** are for the Gas Town installation itself (only one clone) +- **Rig beads** are for the project (shared across multiple clones: crew, polecats, mayor/rig) + +**Why different sync-branch settings?** +- **Town beads**: Single clone at HQ, no coordination needed, commits to main +- **Rig beads**: Multiple clones (polecats, crew, refinery), need `beads-sync` branch to avoid conflicts with code commits + +**Common confusion:** +- `~/gt/gastown/.beads/` at the rig container level is **gitignored** (local runtime state) +- The real project beads live in the **gastown.git clones** (e.g., `crew/max/.beads/`) +- All clones share the same beads via git sync on the `beads-sync` branch + **Molecules** are crystallized workflow patterns that can be attached to work items. See the dedicated **Molecules** section below for full details on composition, nondeterministic idempotence, and built-in workflows. **The OS Metaphor**: Gas Town is an operating system for work: diff --git a/internal/templates/roles/crew.md.tmpl b/internal/templates/roles/crew.md.tmpl index e30bcb19..efac04f8 100644 --- a/internal/templates/roles/crew.md.tmpl +++ b/internal/templates/roles/crew.md.tmpl @@ -31,6 +31,18 @@ Town ({{ .TownRoot }}) │ └── witness/ ← Polecat lifecycle (doesn't monitor you) ``` +## Two-Level Beads Architecture + +| Level | Location | sync-branch | Prefix | Purpose | +|-------|----------|-------------|--------|---------| +| Town | `~/gt/.beads/` | NOT set | `hq-*` | Mayor mail, HQ coordination | +| Rig | `crew/{{ .Polecat }}/.beads/` | `beads-sync` | project prefix | Project issues | + +**Key points:** +- You're in a project git clone - your `.beads/` is tracked in the project repo +- The rig-level `{{ .RigName }}/.beads/` is **gitignored** (local runtime state) +- Run `bd sync` to push/pull beads changes via the `beads-sync` branch + ## Your Workspace You work from: {{ .WorkDir }} diff --git a/internal/templates/roles/mayor.md.tmpl b/internal/templates/roles/mayor.md.tmpl index 221c13e8..24592503 100644 --- a/internal/templates/roles/mayor.md.tmpl +++ b/internal/templates/roles/mayor.md.tmpl @@ -29,6 +29,19 @@ Town ({{ .TownRoot }}) - **Refinery**: Per-rig merge queue processor - **Beads**: Issue tracking system shared by all rig agents +## Two-Level Beads Architecture + +| Level | Location | sync-branch | Prefix | Purpose | +|-------|----------|-------------|--------|---------| +| Town | `~/gt/.beads/` | NOT set | `hq-*` | Your mail, HQ coordination | +| Rig | `/crew/*/.beads/` | `beads-sync` | project prefix | Project issues | + +**Key points:** +- **Town beads**: Your mail lives here. Commits to main (single clone, no sync needed) +- **Rig beads**: Project work lives in git clones (crew/*, polecats/*) +- The rig-level `/.beads/` is **gitignored** (local runtime state) +- Rig beads use `beads-sync` branch for multi-clone coordination + ## Responsibilities - **Work dispatch**: Spawn workers for issues, coordinate batch work on epics diff --git a/internal/templates/roles/polecat.md.tmpl b/internal/templates/roles/polecat.md.tmpl index 4e56a26b..ad95a196 100644 --- a/internal/templates/roles/polecat.md.tmpl +++ b/internal/templates/roles/polecat.md.tmpl @@ -28,6 +28,18 @@ Town ({{ .TownRoot }}) - **Witness**: Monitors you, nudges if stuck, handles your cleanup - **Refinery**: Merges your work when complete +## Two-Level Beads Architecture + +| Level | Location | sync-branch | Prefix | Purpose | +|-------|----------|-------------|--------|---------| +| Town | `~/gt/.beads/` | NOT set | `hq-*` | Mayor mail, HQ coordination | +| Rig | `polecats/{{ .Polecat }}/.beads/` | `beads-sync` | project prefix | Project issues | + +**Key points:** +- You're in a project git clone - your `.beads/` is tracked in the project repo +- The rig-level `{{ .RigName }}/.beads/` is **gitignored** (local runtime state) +- Run `bd sync` to push/pull beads changes via the `beads-sync` branch + ## Responsibilities - **Issue completion**: Work on assigned beads issues