gastown/docs/bootstrap.md

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

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:

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:

mkdir -p ~/gt/gastown/mayor
git clone git@github.com:steveyegge/gastown.git ~/gt/gastown/mayor/rig

Step 4: Build the gt Binary

cd ~/gt/gastown/mayor/rig
go build -o gt ./cmd/gt

Optionally install to PATH:

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

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

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:

# 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

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:

bd doctor --fix

Step 8: Verify Installation

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:

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:

#!/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>