From 7112c42ee9074d42a033a8a97356b45cc0a5b088 Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Fri, 19 Dec 2025 12:08:33 -0800 Subject: [PATCH] docs: document GGT harness separation from PGT (gt-dq3) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Created docs/harness.md documenting the GGT harness at ~/gt/ and its separation from the legacy PGT harness at ~/ai/. Updated architecture.md and federation-design.md to use ~/gt/ consistently. Key changes: - Created harness.md with full harness structure documentation - Added Harness section to Core Concepts in architecture.md - Updated mermaid diagrams from ~/ai/ to ~/gt/ - Documented cleanup steps for legacy ~/ai/ artifacts 🤝 Handoff: The ~/ai/ directory has GGT leftovers that can be cleaned: - rm -rf ~/ai/gastown/mayor/ (old GGT clone) - rm ~/ai/.beads/redirect (old beads redirect) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/architecture.md | 8 ++- docs/federation-design.md | 6 +- docs/harness.md | 131 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 140 insertions(+), 5 deletions(-) create mode 100644 docs/harness.md diff --git a/docs/architecture.md b/docs/architecture.md index de916809..fb006147 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -11,7 +11,7 @@ graph TB subgraph "Gas Town" Overseer["👤 Overseer
(Human Operator)"] - subgraph Town["Town (~/ai/)"] + subgraph Town["Town (~/gt/)"] Mayor["🎩 Mayor
(Global Coordinator)"] subgraph Rig1["Rig: wyvern"] @@ -45,6 +45,10 @@ graph TB ## Core Concepts +### Harness + +A **Harness** is the installation directory for Gas Town - the top-level workspace containing all components. The canonical GGT harness is at `~/gt/`. See [harness.md](harness.md) for setup details and migration from legacy configurations. + ### Town A **Town** is a complete Gas Town installation - the workspace where everything lives. A town contains: @@ -1281,7 +1285,7 @@ type Worker interface { ### Configuration ```yaml -# ~/ai/config/outposts.yaml +# ~/gt/config/outposts.yaml outposts: - name: local type: local diff --git a/docs/federation-design.md b/docs/federation-design.md index e6d388a6..129b38a1 100644 --- a/docs/federation-design.md +++ b/docs/federation-design.md @@ -12,13 +12,13 @@ Gas Town needs to scale beyond a single machine: ### Model A: "Town Clone" (VMs) -Clone the entire `~/ai` workspace to a remote VM. It runs like a regular Gas Town: +Clone the entire `~/gt` workspace to a remote VM. It runs like a regular Gas Town: ``` ┌─────────────────────────────────────────┐ │ GCE VM (or any Linux box) │ │ │ -│ ~/ai/ # Full town clone │ +│ ~/gt/ # Full town clone │ │ ├── config/ # Town config │ │ ├── mayor/ # Mayor (or none) │ │ ├── gastown/ # Rig with agents │ @@ -356,7 +356,7 @@ Workers need Claude API access: ## Configuration ```yaml -# ~/ai/config/outposts.yaml +# ~/gt/config/outposts.yaml outposts: # Always present - the local machine - name: local diff --git a/docs/harness.md b/docs/harness.md new file mode 100644 index 00000000..0ddb80ba --- /dev/null +++ b/docs/harness.md @@ -0,0 +1,131 @@ +# Gas Town Harness + +A **harness** is a Gas Town installation directory - the top-level workspace where all Gas Town components live. + +## GGT Harness Location + +The Go implementation of Gas Town (GGT) uses a separate harness from the Python implementation (PGT): + +| Implementation | Harness Location | Status | +|----------------|------------------|--------| +| GGT (Go) | `~/gt/` | Active, canonical | +| PGT (Python) | `~/ai/` | Legacy, reference only | + +## Harness Structure + +A properly configured GGT harness looks like: + +``` +~/gt/ # HARNESS ROOT +├── CLAUDE.md # Mayor role prompting +├── .beads/ # Town-level beads (gm-* prefix) +│ ├── beads.db # Mayor mail, coordination +│ └── config.yaml +│ +├── mayor/ # Mayor's HOME at town level +│ ├── town.json # {"type": "town", "name": "..."} +│ ├── rigs.json # Registry of managed rigs +│ └── state.json +│ +├── gastown/ # A rig (project container) +│ ├── config.json +│ ├── .beads/ → mayor/rig/.beads # Symlink to canonical beads +│ ├── mayor/rig/ # Mayor's clone (beads authority) +│ ├── refinery/rig/ # Refinery's clone +│ ├── witness/ # Witness agent +│ ├── crew/ # Overseer workspaces +│ └── polecats/ # Worker directories +│ +└── wyvern/ # Another rig (same structure) +``` + +## Key Directories + +### Town Level (`~/gt/`) + +- **CLAUDE.md**: Mayor role prompting, loaded when Mayor starts +- **.beads/**: Town-level beads database (prefix: `gm-`) + - Contains Mayor mail and cross-rig coordination beads +- **mayor/**: Mayor's home directory with town configuration + +### Rig Level (`~/gt//`) + +Each rig is a **container directory** (NOT a git clone) that holds: + +- **config.json**: Rig configuration (git_url, beads prefix) +- **.beads/**: Symlink to `mayor/rig/.beads` (canonical beads) +- **mayor/rig/**: Mayor's git clone, canonical for beads and worktrees +- **refinery/rig/**: Refinery's clone for merge operations +- **witness/**: Witness agent state +- **crew/**: Overseer's personal workspaces +- **polecats/**: Worker directories (git worktrees) + +## Historical Context: PGT/GGT Separation + +During initial GGT development, both implementations briefly shared `~/ai/`: + +``` +~/ai/ (legacy mixed harness - DO NOT USE for GGT) +├── gastown/ +│ ├── .gastown/ # PGT marker +│ └── mayor/ # OLD GGT clone (deprecated) +├── mayor/ # PGT Mayor home +└── .beads/redirect # OLD redirect (deprecated) +``` + +This caused confusion because: +- `~/ai/gastown/` contained both PGT markers AND GGT code +- `~/ai/mayor/` was PGT's Mayor home, conflicting with GGT concepts +- The beads redirect pointed at GGT beads from a PGT harness + +The separation was completed by creating `~/gt/` as the dedicated GGT harness. + +## Cleanup Steps for ~/ai/ + +If you have the legacy mixed harness, clean it up: + +```bash +# Remove old GGT clone (beads are no longer here) +rm -rf ~/ai/gastown/mayor/ + +# Remove old beads redirect +rm ~/ai/.beads/redirect + +# Keep PGT-specific files: +# - ~/ai/mayor/ (PGT Mayor home) +# - ~/ai/gastown/.gastown/ (PGT marker) +``` + +## Creating a New Harness + +To create a fresh GGT harness: + +```bash +gt install ~/my-harness +``` + +This creates: +- Town-level directories and configuration +- Town-level beads database +- CLAUDE.md for Mayor role + +Then add rigs: + +```bash +cd ~/my-harness +gt rig add myproject https://github.com/user/myproject +``` + +## Environment Variables + +When spawning agents, Gas Town sets: + +| Variable | Purpose | Example | +|----------|---------|---------| +| `BEADS_DIR` | Point to rig's beads | `/path/to/rig/.beads` | +| `BEADS_NO_DAEMON` | Disable daemon for worktrees | `1` | + +## See Also + +- [Architecture](architecture.md) - Full system design +- [Federation Design](federation-design.md) - Remote outposts