docs: Radically condense documentation (10k → 548 lines)
Replace 28 sprawling docs with 2 focused ones: - README.md: User-focused, top-down intro (268 lines) - docs/reference.md: Technical reference (280 lines) Key changes: - Top-down structure (formulas first, not beads) - Bullets/tables over prose - Human commands (start/shutdown/attach) vs agent commands - All 6 roles documented (Overseer through Polecat) - Ice-9/protomolecule easter eggs for the Expanse/Vonnegut fans - Prefix-based beads routing explanation 🤖 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
280
docs/reference.md
Normal file
280
docs/reference.md
Normal file
@@ -0,0 +1,280 @@
|
||||
# Gas Town Reference
|
||||
|
||||
Technical reference for Gas Town internals. Read the README first.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
~/gt/ Town root
|
||||
├── .beads/ Town-level beads (hq-* prefix)
|
||||
├── mayor/ Mayor config
|
||||
│ └── town.json
|
||||
└── <rig>/ Project container (NOT a git clone)
|
||||
├── config.json Rig identity
|
||||
├── .beads/ → mayor/rig/.beads
|
||||
├── .repo.git/ Bare repo (shared by worktrees)
|
||||
├── mayor/rig/ Mayor's clone (canonical beads)
|
||||
├── refinery/rig/ Worktree on main
|
||||
├── witness/ No clone (monitors only)
|
||||
├── crew/<name>/ Human workspaces
|
||||
└── polecats/<name>/ Worker worktrees
|
||||
```
|
||||
|
||||
**Key points:**
|
||||
- Rig root is a container, not a clone
|
||||
- `.repo.git/` is bare - refinery and polecats are worktrees
|
||||
- Mayor clone holds canonical `.beads/`, others inherit via redirect
|
||||
|
||||
## Beads Routing
|
||||
|
||||
Gas Town routes beads commands based on issue ID prefix. You don't need to think
|
||||
about which database to use - just use the issue ID.
|
||||
|
||||
```bash
|
||||
bd show gt-xyz # Routes to gastown rig's beads
|
||||
bd show hq-abc # Routes to town-level beads
|
||||
bd show wyv-123 # Routes to wyvern rig's beads
|
||||
```
|
||||
|
||||
**How it works**: Routes are defined in `~/gt/.beads/routes.jsonl`. Each rig's
|
||||
prefix maps to its beads location (the mayor's clone in that rig).
|
||||
|
||||
| Prefix | Routes To | Purpose |
|
||||
|--------|-----------|---------|
|
||||
| `hq-*` | `~/gt/.beads/` | Mayor mail, cross-rig coordination |
|
||||
| `gt-*` | `~/gt/gastown/mayor/rig/.beads/` | Gastown project issues |
|
||||
| `wyv-*` | `~/gt/wyvern/mayor/rig/.beads/` | Wyvern project issues |
|
||||
|
||||
Debug routing: `BD_DEBUG_ROUTING=1 bd show <id>`
|
||||
|
||||
## Configuration
|
||||
|
||||
### Rig Config (`config.json`)
|
||||
```json
|
||||
{
|
||||
"type": "rig",
|
||||
"name": "myproject",
|
||||
"git_url": "https://github.com/...",
|
||||
"beads": { "prefix": "mp" }
|
||||
}
|
||||
```
|
||||
|
||||
### Settings (`settings/config.json`)
|
||||
```json
|
||||
{
|
||||
"theme": "desert",
|
||||
"max_workers": 5,
|
||||
"merge_queue": { "enabled": true }
|
||||
}
|
||||
```
|
||||
|
||||
### Runtime (`.runtime/` - gitignored)
|
||||
Process state, PIDs, ephemeral data.
|
||||
|
||||
## Formula Format
|
||||
|
||||
```toml
|
||||
formula = "name"
|
||||
type = "workflow" # workflow | expansion | aspect
|
||||
version = 1
|
||||
description = "..."
|
||||
|
||||
[vars.feature]
|
||||
description = "..."
|
||||
required = true
|
||||
|
||||
[[steps]]
|
||||
id = "step-id"
|
||||
title = "{{feature}}"
|
||||
description = "..."
|
||||
needs = ["other-step"] # Dependencies
|
||||
```
|
||||
|
||||
**Composition:**
|
||||
```toml
|
||||
extends = ["base-formula"]
|
||||
|
||||
[compose]
|
||||
aspects = ["cross-cutting"]
|
||||
|
||||
[[compose.expand]]
|
||||
target = "step-id"
|
||||
with = "macro-formula"
|
||||
```
|
||||
|
||||
## Molecule Lifecycle
|
||||
|
||||
```
|
||||
Formula (source TOML) ─── "Ice-9"
|
||||
│
|
||||
▼ bd cook
|
||||
Protomolecule (frozen template) ─── Solid
|
||||
│
|
||||
├─▶ bd pour ──▶ Mol (persistent) ─── Liquid ──▶ bd squash ──▶ Digest
|
||||
│
|
||||
└─▶ bd wisp ──▶ Wisp (ephemeral) ─── Vapor ──┬▶ bd squash ──▶ Digest
|
||||
└▶ bd burn ──▶ (gone)
|
||||
```
|
||||
|
||||
**Note**: Wisps are stored in `.beads/` with an ephemeral flag - they're not
|
||||
persisted to JSONL. They exist only in memory during execution.
|
||||
|
||||
## Molecule Commands
|
||||
|
||||
```bash
|
||||
# Formulas
|
||||
bd formula list # Available formulas
|
||||
bd formula show <name> # Formula details
|
||||
bd cook <formula> # Formula → Proto
|
||||
|
||||
# Molecules
|
||||
bd mol list # Available protos
|
||||
bd mol show <id> # Proto details
|
||||
bd pour <proto> # Create mol
|
||||
bd wisp <proto> # Create wisp
|
||||
bd mol bond <proto> <parent> # Attach to existing mol
|
||||
bd mol squash <id> # Condense to digest
|
||||
bd mol burn <id> # Discard wisp
|
||||
```
|
||||
|
||||
## Agent Lifecycle
|
||||
|
||||
### Polecat Shutdown
|
||||
```
|
||||
1. Complete work steps
|
||||
2. bd mol squash (create digest)
|
||||
3. Submit to merge queue
|
||||
4. gt handoff (request shutdown)
|
||||
5. Wait for Witness to kill session
|
||||
6. Witness removes worktree + branch
|
||||
```
|
||||
|
||||
### Session Cycling
|
||||
```
|
||||
1. Agent notices context filling
|
||||
2. gt handoff (sends mail to self)
|
||||
3. Manager kills session
|
||||
4. Manager starts new session
|
||||
5. New session reads handoff mail
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Purpose |
|
||||
|----------|---------|
|
||||
| `BEADS_DIR` | Point to shared beads database |
|
||||
| `BEADS_NO_DAEMON` | Required for worktree polecats |
|
||||
| `GT_TOWN_ROOT` | Override town root detection |
|
||||
|
||||
## CLI Reference
|
||||
|
||||
### Town Management
|
||||
```bash
|
||||
gt install [path] # Create town
|
||||
gt install --git # With git init
|
||||
gt doctor # Health check
|
||||
gt doctor --fix # Auto-repair
|
||||
```
|
||||
|
||||
### Rig Management
|
||||
```bash
|
||||
gt rig add <name> --remote=<url>
|
||||
gt rig list
|
||||
gt rig remove <name>
|
||||
```
|
||||
|
||||
### Work Assignment
|
||||
```bash
|
||||
gt sling <bead> <rig> # Assign to polecat
|
||||
gt sling <bead> <rig> --molecule=<proto>
|
||||
```
|
||||
|
||||
### Communication
|
||||
```bash
|
||||
gt mail inbox
|
||||
gt mail read <id>
|
||||
gt mail send <addr> -s "Subject" -m "Body"
|
||||
gt mail send --human -s "..." # To overseer
|
||||
```
|
||||
|
||||
### Sessions
|
||||
```bash
|
||||
gt handoff # Request cycle (context-aware)
|
||||
gt handoff --shutdown # Terminate (polecats)
|
||||
gt session stop <rig>/<agent>
|
||||
gt peek <agent> # Check health
|
||||
gt nudge <agent> # Wake stuck worker
|
||||
```
|
||||
|
||||
### Emergency
|
||||
```bash
|
||||
gt stop --all # Kill all sessions
|
||||
gt stop --rig <name> # Kill rig sessions
|
||||
```
|
||||
|
||||
## Beads Commands (bd)
|
||||
|
||||
```bash
|
||||
bd ready # Work with no blockers
|
||||
bd list --status=open
|
||||
bd list --status=in_progress
|
||||
bd show <id>
|
||||
bd create --title="..." --type=task
|
||||
bd update <id> --status=in_progress
|
||||
bd close <id>
|
||||
bd dep add <child> <parent> # child depends on parent
|
||||
bd sync # Push/pull changes
|
||||
```
|
||||
|
||||
## Patrol Agents
|
||||
|
||||
Deacon, Witness, and Refinery run continuous patrol loops using wisps:
|
||||
|
||||
| Agent | Patrol Molecule | Responsibility |
|
||||
|-------|-----------------|----------------|
|
||||
| **Deacon** | `mol-deacon-patrol` | Agent lifecycle, plugin execution, health checks |
|
||||
| **Witness** | `mol-witness-patrol` | Monitor polecats, nudge stuck workers |
|
||||
| **Refinery** | `mol-refinery-patrol` | Process merge queue, review PRs |
|
||||
|
||||
```
|
||||
1. bd wisp mol-<role>-patrol
|
||||
2. Execute steps (check workers, process queue, run plugins)
|
||||
3. bd mol squash (or burn if routine)
|
||||
4. Loop
|
||||
```
|
||||
|
||||
## Plugin Molecules
|
||||
|
||||
Plugins are molecules with specific labels:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "mol-security-scan",
|
||||
"labels": ["template", "plugin", "witness", "tier:haiku"]
|
||||
}
|
||||
```
|
||||
|
||||
Patrol molecules bond plugins dynamically:
|
||||
```bash
|
||||
bd mol bond mol-security-scan $PATROL_ID --var scope="$SCOPE"
|
||||
```
|
||||
|
||||
## Common Issues
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| Agent in wrong directory | Check cwd, `gt doctor` |
|
||||
| Beads prefix mismatch | Check `bd show` vs rig config |
|
||||
| Worktree conflicts | Ensure `BEADS_NO_DAEMON=1` for polecats |
|
||||
| Stuck worker | `gt nudge`, then `gt peek` |
|
||||
| Dirty git state | Commit or discard, then `gt handoff` |
|
||||
|
||||
## Architecture Notes
|
||||
|
||||
**Bare repo pattern**: `.repo.git/` is bare (no working dir). Refinery and polecats are worktrees sharing refs. Polecat branches visible to refinery immediately.
|
||||
|
||||
**Beads as control plane**: No separate orchestrator. Molecule steps ARE beads issues. State transitions are git commits.
|
||||
|
||||
**Nondeterministic idempotence**: Any worker can continue any molecule. Steps are atomic checkpoints in beads.
|
||||
|
||||
<!-- TODO: Add architecture diagram -->
|
||||
Reference in New Issue
Block a user