feat: rename harness to HQ throughout docs and code (gt-a41)
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
331
docs/hq.md
Normal file
331
docs/hq.md
Normal file
@@ -0,0 +1,331 @@
|
||||
# Gas Town HQ Design
|
||||
|
||||
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 an HQ?
|
||||
|
||||
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
|
||||
|
||||
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)
|
||||
|
||||
## HQ Structure
|
||||
|
||||
```
|
||||
~/gt/ # HQ ROOT
|
||||
├── .git/ # HQ is a git repo
|
||||
├── .gitignore # Generated by gt git-init
|
||||
├── .beads/ # Town-level beads (hq-* prefix)
|
||||
│ ├── beads.db # Mayor mail, coordination, handoffs
|
||||
│ └── config.yaml # Beads config with prefix: hq
|
||||
│
|
||||
├── 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 HQ root (legacy)
|
||||
```
|
||||
|
||||
## Creating an HQ
|
||||
|
||||
Use `gt install` to create a new HQ:
|
||||
|
||||
```bash
|
||||
# Create a new HQ
|
||||
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 HQ
|
||||
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 `hq-` prefix
|
||||
5. Optionally initializes git with `.gitignore`
|
||||
|
||||
## HQ vs Town vs Rig
|
||||
|
||||
| Concept | Description | Example |
|
||||
|---------|-------------|---------|
|
||||
| **HQ** | Installation directory | `~/gt/` |
|
||||
| **Town** | Logical workspace (same as HQ) | The Gas Town instance |
|
||||
| **Rig** | Project container within HQ | `~/gt/gastown/` |
|
||||
|
||||
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 an HQ
|
||||
|
||||
An HQ has **two levels** of beads:
|
||||
|
||||
### Town-Level Beads
|
||||
|
||||
Located at `<hq>/.beads/` with `hq-` 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 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
|
||||
|
||||
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 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 HQ" 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 HQs (recommended)**
|
||||
```
|
||||
~/ai/ # PGT HQ
|
||||
~/gt/ # GGT HQ (separate)
|
||||
```
|
||||
|
||||
**Option 2: Namespaced directories**
|
||||
```
|
||||
~/ai/
|
||||
├── pgt/ # PGT HQ
|
||||
│ ├── mayor/
|
||||
│ └── gastown/
|
||||
└── ggt/ # GGT HQ
|
||||
├── 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
|
||||
```
|
||||
|
||||
## HQ 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 HQs
|
||||
|
||||
An HQ 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 HQ 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
|
||||
```
|
||||
|
||||
## HQ Health Checks
|
||||
|
||||
Run `gt doctor` to check HQ 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
|
||||
|
||||
## HQ Templates
|
||||
|
||||
For organizations wanting consistent Gas Town setups, create a template repository:
|
||||
|
||||
```bash
|
||||
# Create template HQ
|
||||
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 HQs
|
||||
|
||||
To move Gas Town to a new location:
|
||||
|
||||
1. **Export beads state:**
|
||||
```bash
|
||||
bd export > beads-backup.jsonl
|
||||
```
|
||||
|
||||
2. **Create new HQ:**
|
||||
```bash
|
||||
gt install ~/new-hq --git
|
||||
```
|
||||
|
||||
3. **Add rigs:**
|
||||
```bash
|
||||
cd ~/new-hq
|
||||
gt rig add gastown https://github.com/user/gastown
|
||||
```
|
||||
|
||||
4. **Import beads:**
|
||||
```bash
|
||||
cd ~/new-hq
|
||||
bd import < beads-backup.jsonl
|
||||
```
|
||||
|
||||
## Summary
|
||||
|
||||
| Action | Command |
|
||||
|--------|---------|
|
||||
| Create HQ | `gt install <path>` |
|
||||
| Initialize git | `gt git-init` |
|
||||
| Add rig | `gt rig add <name> <git-url>` |
|
||||
| Check health | `gt doctor` |
|
||||
| View status | `gt status` |
|
||||
Reference in New Issue
Block a user