gastown/docs/hq.md

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:

# 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:

# 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:

• When rig beads should be the canonical town beads
• Hybrid setups where agents work in different locations

HQ Configuration Files

mayor/town.json

Identifies this as a Gas Town installation:

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

mayor/rigs.json

Registry of managed rigs:

{
  "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:

{
  "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

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:

# 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:

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:

# 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:

   bd export > beads-backup.jsonl
   

2. Create new HQ:

   gt install ~/new-hq --git
   

3. Add rigs:

   cd ~/new-hq
   gt rig add gastown https://github.com/user/gastown
   

4. Import beads:

   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