johno/gastown
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat: rename harness to HQ throughout docs and code (gt-a41)

Browse Source 
The "hq-" prefix for town-level beads revealed that "HQ" (headquarters)
is a better name than "harness" for the top-level Gas Town structure.

- Renamed docs/harness.md to docs/hq.md with updated content
- Updated all documentation references in architecture.md and bootstrap.md
- Updated CLI help text and user-facing messages in install.go
- Updated gitinit.go with HQGitignore constant and HQ terminology
- Updated molecule templates in builtin_molecules.go
- Kept InitGitForHarness function name for backwards compatibility

HQ is more intuitive (where the mayor sits), fits the Mad Max aesthetic,
matches the beads prefix (hq-*), and is self-documenting.

🤖 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
2025-12-20 14:24:49 -08:00
parent afee8bba17
commit 91a0f3b80f
7 changed files with 542 additions and 539 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
docs/architecture.md
View File

@@ -47,28 +47,28 @@ graph TB
## Core Concepts
### Harness (Town)
### HQ (Town)
A **Harness** is the installation directory where Gas Town lives - the physical root of your workspace. The terms "harness" and "town" are often used interchangeably:
- **Harness** = physical (the directory at `~/gt/`)
The **HQ** (headquarters) is the installation directory where Gas Town lives - the physical root of your workspace. The terms "HQ" and "town" are often used interchangeably:
- **HQ** = physical (the directory at `~/gt/`)
- **Town** = logical (the Gas Town workspace concept)
A harness contains:
- `CLAUDE.md` - Mayor role context (Mayor runs from harness root)
An HQ contains:
- `CLAUDE.md` - Mayor role context (Mayor runs from HQ root)
- `mayor/` - Mayor configuration, state, and registry
- `.beads/` - Town-level beads (gm-* prefix for mayor mail)
- `.beads/` - Town-level beads (hq-* prefix for mayor mail)
- `rigs/` or rig directories - Managed project containers
Create a harness with `gt install`:
Create an HQ with `gt install`:
```bash
gt install ~/gt --git # Create harness with git
gt install ~/gt --git # Create HQ with git
```
**See**: [docs/harness.md](harness.md) for comprehensive harness documentation, including:
**See**: [docs/hq.md](hq.md) for comprehensive HQ documentation, including:
- Beads redirect patterns for complex setups
- Multi-system sharing (PGT/GGT coexistence)
- Harness templates for organizations
- Migration between harnesses
- HQ templates for organizations
- Migration between HQs
### Rig
@@ -765,14 +765,14 @@ Both patterns are valid. Use static molecules for well-defined workflows (engine
## Directory Structure
### Harness Level
### HQ Level
The harness (town root) is created by `gt install`:
The HQ (town root) is created by `gt install`:
```
~/gt/ # HARNESS ROOT (Gas Town installation)
~/gt/ # HQ ROOT (Gas Town installation)
├── CLAUDE.md # Mayor role context (runs from here)
├── .beads/ # Town-level beads (prefix: gm-)
├── .beads/ # Town-level beads (prefix: hq-)
│ ├── beads.db # Mayor mail, coordination, handoffs
│ └── config.yaml
│
@@ -785,13 +785,13 @@ The harness (town root) is created by `gt install`:
│ ├── gastown/ # A rig (project container)
│ └── wyvern/ # Another rig
│
└── <rig>/ # OR rigs at harness root (legacy)
└── <rig>/ # OR rigs at HQ root (legacy)
```
**Notes**:
- Mayor's mail is in town beads (`gm-*` issues), not JSONL files
- Rigs can be in `rigs/` or at harness root (both work)
- See [docs/harness.md](harness.md) for advanced harness configurations
- Mayor's mail is in town beads (`hq-*` issues), not JSONL files
- Rigs can be in `rigs/` or at HQ root (both work)
- See [docs/hq.md](hq.md) for advanced HQ configurations
### Rig Level
@@ -873,10 +873,10 @@ graph TB
### ASCII Directory Layout
For reference without mermaid rendering (see [harness.md](harness.md) for creation/setup):
For reference without mermaid rendering (see [hq.md](hq.md) for creation/setup):
```
~/gt/ # HARNESS ROOT (Gas Town installation)
~/gt/ # HQ ROOT (Gas Town installation)
├── CLAUDE.md # Mayor role context
├── .beads/ # Town-level beads (gm-* prefix)
│ ├── beads.db # Mayor mail, coordination
@@ -1599,13 +1599,13 @@ This ensures all agents in the rig share a single beads database, separate from
## CLI Commands
### Harness Management
### HQ Management
```bash
gt install [path] # Create Gas Town harness (see harness.md)
gt install [path] # Create Gas Town HQ (see hq.md)
gt install --git # Also initialize git with .gitignore
gt install --github=u/r # Also create GitHub repo
gt git-init # Initialize git for existing harness
gt git-init # Initialize git for existing HQ
gt doctor # Check workspace health
gt doctor --fix # Auto-fix issues
```
@@ -1758,7 +1758,7 @@ The **plan-oracle** plugin helps decompose work:
The **beads-hygiene** plugin detects and fixes cross-pollution between nested beads databases.
**Background**: Gas Town has a two-level beads architecture:
- **Town-level** (`~/gt/.beads/`): Mayor mail, cross-rig coordination, harness-level issues
- **Town-level** (`~/gt/.beads/`): Mayor mail, cross-rig coordination, HQ-level issues
- **Rig-level** (`~/gt/<rig>/.beads/`): Project-specific work (bugs, features, tasks)
Workers sometimes get confused about which database they're in, especially when:
@@ -1778,7 +1778,7 @@ Workers sometimes get confused about which database they're in, especially when:
2. Check for cross-level dependency references
- Flag `gt-*` issues that depend on `hq-*` (usually wrong)
3. Analyze recent activity for context confusion
- Agent in `gastown/` creating harness-level issues
- Agent in `gastown/` creating HQ-level issues
- Agent at town level creating rig-specific issues
4. Identify misfiled issues that should be moved
@@ -1800,9 +1800,9 @@ Workers sometimes get confused about which database they're in, especially when:
You are reviewing beads databases for cross-pollution between Gas Town's
two-level architecture:
TOWN LEVEL (~/gt/.beads/): Coordination, mayor mail, harness issues
TOWN LEVEL (~/gt/.beads/): Coordination, mayor mail, HQ issues
- Prefix: hq-* (headquarters)
- Contains: cross-rig coordination, strategic planning, harness bugs
- Contains: cross-rig coordination, strategic planning, HQ bugs
RIG LEVEL (~/gt/<rig>/.beads/): Project-specific work
- Prefix: <rig>-* (e.g., gt-* for gastown rig)

18
docs/bootstrap.md
View File

@@ -1,6 +1,6 @@
# Bootstrapping Gas Town from a Harness
# Bootstrapping Gas Town from an HQ
This guide documents how to bootstrap a full Gas Town installation from a harness repository (e.g., `steveyegge/stevey-gt`).
This guide documents how to bootstrap a full Gas Town installation from an HQ repository (e.g., `steveyegge/stevey-gt`).
## Prerequisites
@@ -10,17 +10,17 @@ This guide documents how to bootstrap a full Gas Town installation from a harnes
## Overview
A Gas Town harness is a template repository containing:
A Gas Town HQ 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 HQ 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
## Step 1: Clone the HQ
```bash
git clone git@github.com:steveyegge/stevey-gt.git ~/gt
@@ -62,7 +62,7 @@ cp gt ~/bin/gt
## Step 5: Populate Rig Structures
For each rig in your harness (gastown, beads, etc.), create the full agent structure:
For each rig in your HQ (gastown, beads, etc.), create the full agent structure:
### Gastown Rig
@@ -165,13 +165,13 @@ Here's a condensed script for bootstrapping:
set -e
# Configuration
HARNESS_REPO="git@github.com:steveyegge/stevey-gt.git"
HQ_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"
# Clone HQ
git clone "$HQ_REPO" "$TOWN_ROOT"
cd "$TOWN_ROOT"
# Install Go if needed

94
docs/harness.md → docs/hq.md
View File

@@ -1,29 +1,29 @@
# Gas Town Harness Design
# Gas Town HQ Design
A **harness** is the top-level directory where Gas Town is installed - the workspace that contains all your rigs, agents, and coordination infrastructure.
The **HQ** (headquarters) 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?
## What Is an HQ?
Think of a harness as the "mount point" for Gas Town. It's the root directory where:
Think of HQ 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:
An HQ 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
## HQ Structure
```
~/gt/ # HARNESS ROOT
├── .git/ # Harness is a git repo
~/gt/ # HQ ROOT
├── .git/ # HQ is a git repo
├── .gitignore # Generated by gt git-init
├── .beads/ # Town-level beads (gm-* prefix)
├── .beads/ # Town-level beads (hq-* prefix)
│ ├── beads.db # Mayor mail, coordination, handoffs
│ └── config.yaml # Beads config with prefix: gm
│ └── config.yaml # Beads config with prefix: hq
│
├── CLAUDE.md # Mayor role context (runs from here)
│
@@ -36,15 +36,15 @@ A harness is NOT:
│ ├── gastown/ # A rig (project container)
│ └── wyvern/ # Another rig
│
└── <rig-name>/ # OR rigs at harness root (legacy)
└── <rig-name>/ # OR rigs at HQ root (legacy)
```
## Creating a Harness
## Creating an HQ
Use `gt install` to create a new harness:
Use `gt install` to create a new HQ:
```bash
# Create a new harness
# Create a new HQ
gt install ~/gt
# Create with git initialization
@@ -53,7 +53,7 @@ gt install ~/gt --git
# Create and push to GitHub
gt install ~/gt --github=username/my-gastown --private
# Initialize current directory as harness
# Initialize current directory as HQ
gt install . --name my-workspace
```
@@ -61,26 +61,26 @@ 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
4. Initializes town-level beads with `hq-` prefix
5. Optionally initializes git with `.gitignore`
## Harness vs Town vs Rig
## HQ 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/` |
| **HQ** | Installation directory | `~/gt/` |
| **Town** | Logical workspace (same as HQ) | The Gas Town instance |
| **Rig** | Project container within HQ | `~/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).
The terms "HQ" and "town" are often used interchangeably. An HQ IS a town. The distinction is physical (HQ = directory) vs logical (town = workspace concept).
## Beads in a Harness
## Beads in an HQ
A harness has **two levels** of beads:
An HQ has **two levels** of beads:
### Town-Level Beads
Located at `<harness>/.beads/` with `gm-` prefix:
Located at `<hq>/.beads/` with `hq-` prefix:
- Mayor mail and inbox
- Cross-rig coordination messages
- Session handoff notes
@@ -96,8 +96,8 @@ 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
In complex setups, you may want the HQ root's `.beads/` to redirect to a rig's beads. This is useful when:
- Multiple systems share an HQ
- You want a single source of truth for beads
- Migration scenarios
@@ -118,13 +118,13 @@ mayor/rigs/gastown/.beads
```
**When to use redirects:**
- Shared harness between different Gas Town versions (PGT/GGT)
- Shared HQ 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.
Sometimes you need to run multiple Gas Town systems from the same parent directory. This creates a "shared HQ" scenario.
### The Problem
@@ -139,19 +139,19 @@ If Python Gas Town (PGT) and Go Gas Town (GGT) both use `~/ai/`:
### Solutions
**Option 1: Separate harnesses (recommended)**
**Option 1: Separate HQs (recommended)**
```
~/ai/ # PGT harness
~/gt/ # GGT harness (separate)
~/ai/ # PGT HQ
~/gt/ # GGT HQ (separate)
```
**Option 2: Namespaced directories**
```
~/ai/
├── pgt/ # PGT harness
├── pgt/ # PGT HQ
│ ├── mayor/
│ └── gastown/
└── ggt/ # GGT harness
└── ggt/ # GGT HQ
├── mayor/
└── gastown/
```
@@ -165,7 +165,7 @@ If Python Gas Town (PGT) and Go Gas Town (GGT) both use `~/ai/`:
└── gastown/ # Shared rig
```
## Harness Configuration Files
## HQ Configuration Files
### mayor/town.json
@@ -211,9 +211,9 @@ Mayor agent state:
}
```
## Git for Harnesses
## Git for HQs
A harness should be a git repository. This enables:
An HQ should be a git repository. This enables:
- Versioning of configuration
- Beads sync across machines
- Session handoff via beads commits
@@ -232,7 +232,7 @@ gt git-init --github=user/repo --private # Private repo
The `gt git-init` command creates:
```gitignore
# Gas Town harness gitignore
# Gas Town HQ gitignore
# Agent sessions and logs
*.log
@@ -262,9 +262,9 @@ credentials.json
.beads/*.pid
```
## Harness Health Checks
## HQ Health Checks
Run `gt doctor` to check harness health:
Run `gt doctor` to check HQ health:
```bash
gt doctor # Check all
@@ -278,12 +278,12 @@ Checks include:
- Beads database health
- Git state cleanliness
## Harness Templates
## HQ Templates
For organizations wanting consistent Gas Town setups, create a template repository:
```bash
# Create template harness
# Create template HQ
gt install ~/gt-template --git --no-beads
# Customize CLAUDE.md, add standard rigs
# Push to GitHub as template repo
@@ -294,7 +294,7 @@ cd my-gastown
gt install . --force # Reinitialize with fresh beads
```
## Migration Between Harnesses
## Migration Between HQs
To move Gas Town to a new location:
@@ -303,20 +303,20 @@ To move Gas Town to a new location:
bd export > beads-backup.jsonl
```
2. **Create new harness:**
2. **Create new HQ:**
```bash
gt install ~/new-harness --git
gt install ~/new-hq --git
```
3. **Add rigs:**
```bash
cd ~/new-harness
cd ~/new-hq
gt rig add gastown https://github.com/user/gastown
```
4. **Import beads:**
```bash
cd ~/new-harness
cd ~/new-hq
bd import < beads-backup.jsonl
```
@@ -324,7 +324,7 @@ To move Gas Town to a new location:
| Action | Command |
|--------|---------|
| Create harness | `gt install <path>` |
| Create HQ | `gt install <path>` |
| Initialize git | `gt git-init` |
| Add rig | `gt rig add <name> <git-url>` |
| Check health | `gt doctor` |