Add bootstrap documentation for new Gas Town installations
Documents the full process for bootstrapping a Gas Town from a harness repository, including Go installation, gt binary build, rig population, and beads initialization. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
224
docs/bootstrap.md
Normal file
224
docs/bootstrap.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# Bootstrapping Gas Town from a Harness
|
||||
|
||||
This guide documents how to bootstrap a full Gas Town installation from a harness repository (e.g., `steveyegge/stevey-gt`).
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- macOS or Linux
|
||||
- Git configured with SSH access to GitHub
|
||||
- Homebrew (for macOS)
|
||||
|
||||
## Overview
|
||||
|
||||
A Gas Town harness is a template repository containing:
|
||||
- Town-level configuration (`mayor/`, `.beads/`)
|
||||
- Rig configs (`gastown/config.json`, `beads/config.json`)
|
||||
- CLAUDE.md for Mayor context
|
||||
|
||||
The harness does NOT contain:
|
||||
- The actual gt binary (must be built)
|
||||
- Full rig structures (must be populated)
|
||||
- Agent state files (must be created)
|
||||
|
||||
## Step 1: Clone the Harness
|
||||
|
||||
```bash
|
||||
git clone git@github.com:steveyegge/stevey-gt.git ~/gt
|
||||
cd ~/gt
|
||||
```
|
||||
|
||||
## Step 2: Install Go
|
||||
|
||||
Gas Town is written in Go. Install it via Homebrew:
|
||||
|
||||
```bash
|
||||
brew install go
|
||||
go version # Verify: should show go1.25+
|
||||
```
|
||||
|
||||
## Step 3: Clone Gastown into Mayor's Rig
|
||||
|
||||
The gt binary lives in the gastown repository. Clone it into the mayor's rig directory:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/gt/gastown/mayor
|
||||
git clone git@github.com:steveyegge/gastown.git ~/gt/gastown/mayor/rig
|
||||
```
|
||||
|
||||
## Step 4: Build the gt Binary
|
||||
|
||||
```bash
|
||||
cd ~/gt/gastown/mayor/rig
|
||||
go build -o gt ./cmd/gt
|
||||
```
|
||||
|
||||
Optionally install to PATH:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/bin
|
||||
cp gt ~/bin/gt
|
||||
# Ensure ~/bin is in your PATH
|
||||
```
|
||||
|
||||
## Step 5: Populate Rig Structures
|
||||
|
||||
For each rig in your harness (gastown, beads, etc.), create the full agent structure:
|
||||
|
||||
### Gastown Rig
|
||||
|
||||
```bash
|
||||
cd ~/gt/gastown
|
||||
|
||||
# Create directories
|
||||
mkdir -p refinery witness polecats crew/main
|
||||
|
||||
# Clone for refinery (canonical main)
|
||||
git clone git@github.com:steveyegge/gastown.git refinery/rig
|
||||
|
||||
# Clone for crew workspace
|
||||
git clone git@github.com:steveyegge/gastown.git crew/main
|
||||
```
|
||||
|
||||
### Beads Rig
|
||||
|
||||
```bash
|
||||
cd ~/gt/beads
|
||||
|
||||
# Create directories
|
||||
mkdir -p refinery mayor witness polecats crew/main
|
||||
|
||||
# Clone for each agent
|
||||
git clone git@github.com:steveyegge/beads.git refinery/rig
|
||||
git clone git@github.com:steveyegge/beads.git mayor/rig
|
||||
git clone git@github.com:steveyegge/beads.git crew/main
|
||||
```
|
||||
|
||||
## Step 6: Create Agent State Files
|
||||
|
||||
Each agent needs a state.json file:
|
||||
|
||||
```bash
|
||||
# Gastown agents
|
||||
echo '{"role": "refinery", "last_active": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' > ~/gt/gastown/refinery/state.json
|
||||
echo '{"role": "witness", "last_active": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' > ~/gt/gastown/witness/state.json
|
||||
echo '{"role": "mayor", "last_active": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' > ~/gt/gastown/mayor/state.json
|
||||
|
||||
# Beads agents
|
||||
echo '{"role": "refinery", "last_active": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' > ~/gt/beads/refinery/state.json
|
||||
echo '{"role": "witness", "last_active": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' > ~/gt/beads/witness/state.json
|
||||
echo '{"role": "mayor", "last_active": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' > ~/gt/beads/mayor/state.json
|
||||
```
|
||||
|
||||
## Step 7: Initialize Town-Level Beads
|
||||
|
||||
```bash
|
||||
cd ~/gt
|
||||
bd init --prefix gm
|
||||
```
|
||||
|
||||
If there are existing issues in JSONL that fail to import (e.g., due to invalid issue types), you can:
|
||||
- Fix the JSONL manually and re-run `bd sync --import-only`
|
||||
- Or start fresh with the empty database
|
||||
|
||||
Run doctor to check for issues:
|
||||
|
||||
```bash
|
||||
bd doctor --fix
|
||||
```
|
||||
|
||||
## Step 8: Verify Installation
|
||||
|
||||
```bash
|
||||
cd ~/gt
|
||||
|
||||
# Check gt works
|
||||
gt status
|
||||
|
||||
# Check rig structure
|
||||
gt rig list
|
||||
|
||||
# Expected output:
|
||||
# gastown - Polecats: 0, Crew: 1, Agents: [refinery mayor]
|
||||
# beads - Polecats: 0, Crew: 1, Agents: [refinery mayor]
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Go not in PATH
|
||||
If `go` command fails, ensure Homebrew's bin is in your PATH:
|
||||
```bash
|
||||
export PATH="/opt/homebrew/bin:$PATH"
|
||||
```
|
||||
|
||||
### Witnesses Not Detected
|
||||
Known issue (gm-2ej): The witness detection code checks for `witness/rig` but witnesses don't have a git clone. This is a bug in the detection logic - witnesses should still work.
|
||||
|
||||
### Beads Import Fails
|
||||
Known issue (gm-r6e): If your JSONL contains invalid issue types (e.g., "merge-request"), the import will fail. Either fix the JSONL or start with an empty database.
|
||||
|
||||
## Full Bootstrap Script
|
||||
|
||||
Here's a condensed script for bootstrapping:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
# Configuration
|
||||
HARNESS_REPO="git@github.com:steveyegge/stevey-gt.git"
|
||||
GASTOWN_REPO="git@github.com:steveyegge/gastown.git"
|
||||
BEADS_REPO="git@github.com:steveyegge/beads.git"
|
||||
TOWN_ROOT="$HOME/gt"
|
||||
|
||||
# Clone harness
|
||||
git clone "$HARNESS_REPO" "$TOWN_ROOT"
|
||||
cd "$TOWN_ROOT"
|
||||
|
||||
# Install Go if needed
|
||||
if ! command -v go &> /dev/null; then
|
||||
brew install go
|
||||
fi
|
||||
|
||||
# Clone and build gastown
|
||||
mkdir -p gastown/mayor
|
||||
git clone "$GASTOWN_REPO" gastown/mayor/rig
|
||||
cd gastown/mayor/rig
|
||||
go build -o gt ./cmd/gt
|
||||
cp gt ~/bin/gt
|
||||
cd "$TOWN_ROOT"
|
||||
|
||||
# Populate gastown rig
|
||||
cd gastown
|
||||
mkdir -p refinery witness polecats crew/main
|
||||
git clone "$GASTOWN_REPO" refinery/rig
|
||||
git clone "$GASTOWN_REPO" crew/main
|
||||
echo '{"role": "refinery"}' > refinery/state.json
|
||||
echo '{"role": "witness"}' > witness/state.json
|
||||
echo '{"role": "mayor"}' > mayor/state.json
|
||||
cd "$TOWN_ROOT"
|
||||
|
||||
# Populate beads rig
|
||||
cd beads
|
||||
mkdir -p refinery mayor witness polecats crew/main
|
||||
git clone "$BEADS_REPO" refinery/rig
|
||||
git clone "$BEADS_REPO" mayor/rig
|
||||
git clone "$BEADS_REPO" crew/main
|
||||
echo '{"role": "refinery"}' > refinery/state.json
|
||||
echo '{"role": "witness"}' > witness/state.json
|
||||
echo '{"role": "mayor"}' > mayor/state.json
|
||||
cd "$TOWN_ROOT"
|
||||
|
||||
# Initialize beads
|
||||
bd init --prefix gm
|
||||
|
||||
# Verify
|
||||
gt status
|
||||
echo "Bootstrap complete!"
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
After bootstrapping:
|
||||
1. Start a Mayor session: `gt mayor attach`
|
||||
2. Check for work: `bd ready`
|
||||
3. Spawn workers as needed: `gt spawn --issue <id>`
|
||||
Reference in New Issue
Block a user