gastown/docs/harness.md

# Gas Town Harness Design

A **harness** is the top-level directory where Gas Town is installed - the workspace that contains all your rigs, agents, and coordination infrastructure.

## What Is a Harness?

Think of a harness as the "mount point" for Gas Town. It's the root directory where:
- The Mayor operates from
- Rigs are registered and managed
- Town-level beads coordinate mail and handoffs
- The entire workspace is versioned as a git repository

A harness is NOT:
- A git clone of any project (rigs contain the clones)
- A hidden directory (it's visible and user-controlled)
- Tied to any specific project (it can manage multiple rigs)

## Harness Structure

```
~/gt/                              # HARNESS ROOT
├── .git/                          # Harness is a git repo
├── .gitignore                     # Generated by gt git-init
├── .beads/                        # Town-level beads (gm-* prefix)
│   ├── beads.db                   # Mayor mail, coordination, handoffs
│   └── config.yaml                # Beads config with prefix: gm
│
├── CLAUDE.md                      # Mayor role context (runs from here)
│
├── mayor/                         # Mayor config and state
│   ├── town.json                  # {"type": "town", "name": "..."}
│   ├── rigs.json                  # Registry of managed rigs
│   └── state.json                 # Mayor state
│
├── rigs/                          # Managed rig containers
│   ├── gastown/                   # A rig (project container)
│   └── wyvern/                    # Another rig
│
└── <rig-name>/                    # OR rigs at harness root (legacy)
```

## Creating a Harness

Use `gt install` to create a new harness:

```bash
# Create a new harness
gt install ~/gt

# Create with git initialization
gt install ~/gt --git

# Create and push to GitHub
gt install ~/gt --github=username/my-gastown --private

# Initialize current directory as harness
gt install . --name my-workspace
```

The install command:
1. Creates the directory structure (`mayor/`, `rigs/`)
2. Writes configuration files (`town.json`, `rigs.json`, `state.json`)
3. Generates `CLAUDE.md` with Mayor role context
4. Initializes town-level beads with `gm-` prefix
5. Optionally initializes git with `.gitignore`

## Harness vs Town vs Rig

| Concept | Description | Example |
|---------|-------------|---------|
| **Harness** | Installation directory | `~/gt/` |
| **Town** | Logical workspace (same as harness) | The Gas Town instance |
| **Rig** | Project container within harness | `~/gt/gastown/` |

The terms "harness" and "town" are often used interchangeably. A harness IS a town. The distinction is physical (harness = directory) vs logical (town = workspace concept).

## Beads in a Harness

A harness has **two levels** of beads:

### Town-Level Beads

Located at `<harness>/.beads/` with `gm-` prefix:
- Mayor mail and inbox
- Cross-rig coordination messages
- Session handoff notes

### Rig-Level Beads

Each rig has its own `.beads/` with a project-specific prefix:
- Work issues (bugs, features, tasks)
- Merge requests
- Agent-local mail within the rig

The Mayor sees both: town beads for mail, rig beads for work coordination.

## Beads Redirect Pattern

In complex setups, you may want the harness root's `.beads/` to redirect to a rig's beads. This is useful when:
- Multiple systems share a harness
- You want a single source of truth for beads
- Migration scenarios

Create a redirect file:

```bash
# Instead of .beads/ directory, create .beads/redirect file
mkdir .beads
echo "path/to/actual/.beads" > .beads/redirect
```

Example from a real setup:
```
# ~/ai/.beads/redirect
# Redirect to gastown beads (Mayor workspace)
# The Mayor runs in ~/ai but manages gastown issues in mayor/rigs/gastown
mayor/rigs/gastown/.beads
```

**When to use redirects:**
- Shared harness between different Gas Town versions (PGT/GGT)
- When rig beads should be the canonical town beads
- Hybrid setups where agents work in different locations

## Multiple Gas Towns in One Location

Sometimes you need to run multiple Gas Town systems from the same parent directory. This creates a "shared harness" scenario.

### The Problem

If Python Gas Town (PGT) and Go Gas Town (GGT) both use `~/ai/`:
```
~/ai/
├── .gastown/           # PGT config
├── .beads/             # Which system owns this?
├── mayor/              # PGT mayor? GGT mayor?
└── gastown/            # PGT rig? GGT rig?
```

### Solutions

**Option 1: Separate harnesses (recommended)**
```
~/ai/                   # PGT harness
~/gt/                   # GGT harness (separate)
```

**Option 2: Namespaced directories**
```
~/ai/
├── pgt/                # PGT harness
│   ├── mayor/
│   └── gastown/
└── ggt/                # GGT harness
    ├── mayor/
    └── gastown/
```

**Option 3: Beads redirect (advanced)**
```
~/ai/
├── .beads/redirect     # Points to canonical location
├── pgt-mayor/          # PGT-specific
├── ggt-mayor/          # GGT-specific
└── gastown/            # Shared rig
```

## Harness Configuration Files

### mayor/town.json

Identifies this as a Gas Town installation:

```json
{
  "type": "town",
  "version": 1,
  "name": "stevey-gastown",
  "created_at": "2024-01-15T10:30:00Z"
}
```

### mayor/rigs.json

Registry of managed rigs:

```json
{
  "version": 1,
  "rigs": {
    "gastown": {
      "git_url": "https://github.com/steveyegge/gastown",
      "added_at": "2024-01-15T10:30:00Z"
    },
    "wyvern": {
      "git_url": "https://github.com/steveyegge/wyvern",
      "added_at": "2024-01-16T09:00:00Z"
    }
  }
}
```

### mayor/state.json

Mayor agent state:

```json
{
  "role": "mayor",
  "last_active": "2024-01-17T14:30:00Z"
}
```

## Git for Harnesses

A harness should be a git repository. This enables:
- Versioning of configuration
- Beads sync across machines
- Session handoff via beads commits
- Recovery after failures

### Initialize git

```bash
gt git-init                      # Basic git setup
gt git-init --github=user/repo   # Create GitHub repo
gt git-init --github=user/repo --private  # Private repo
```

### Standard .gitignore

The `gt git-init` command creates:

```gitignore
# Gas Town harness gitignore

# Agent sessions and logs
*.log
*.pid
/sessions/

# Rig working directories (managed separately)
/rigs/*/polecats/*/
/rigs/*/refinery/rig/
/rigs/*/crew/*/

# Sensitive files
.env
*.key
*.pem
credentials.json

# Editor and OS
.DS_Store
*.swp
*~
.idea/
.vscode/

# Beads daemon
.beads/beads.sock
.beads/*.pid
```

## Harness Health Checks

Run `gt doctor` to check harness health:

```bash
gt doctor              # Check all
gt doctor --fix        # Auto-fix issues
```

Checks include:
- Configuration file validity
- Mayor state consistency
- Rig registry accuracy
- Beads database health
- Git state cleanliness

## Harness Templates

For organizations wanting consistent Gas Town setups, create a template repository:

```bash
# Create template harness
gt install ~/gt-template --git --no-beads
# Customize CLAUDE.md, add standard rigs
# Push to GitHub as template repo

# Users clone template
gh repo create my-gastown --template org/gt-template
cd my-gastown
gt install . --force  # Reinitialize with fresh beads
```

## Migration Between Harnesses

To move Gas Town to a new location:

1. **Export beads state:**
   ```bash
   bd export > beads-backup.jsonl
   ```

2. **Create new harness:**
   ```bash
   gt install ~/new-harness --git
   ```

3. **Add rigs:**
   ```bash
   cd ~/new-harness
   gt rig add gastown https://github.com/user/gastown
   ```

4. **Import beads:**
   ```bash
   cd ~/new-harness
   bd import < beads-backup.jsonl
   ```

## Summary

| Action | Command |
|--------|---------|
| Create harness | `gt install <path>` |
| Initialize git | `gt git-init` |
| Add rig | `gt rig add <name> <git-url>` |
| Check health | `gt doctor` |
| View status | `gt status` |