7112c42ee9
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 <noreply@anthropic.com>
132 lines
4.1 KiB
Markdown
132 lines
4.1 KiB
Markdown
# 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/<rig>/`)
|
|
|
|
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
|