docs: reorganize documentation into concepts, design, and examples
Move documentation files into a clearer structure: - concepts/: core ideas (convoy, identity, molecules, polecat-lifecycle, propulsion) - design/: architecture and protocols (architecture, escalation, federation, mail, etc.) - examples/: demos and tutorials (hanoi-demo) - overview.md: renamed from understanding-gas-town.md Remove outdated/superseded docs and update reference.md. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
gastown/crew/gus
committed by
Steve Yegge
Steve Yegge
parent
8ed31e9634
commit
88f784a9aa
226
docs/concepts/convoy.md
Normal file
226
docs/concepts/convoy.md
Normal file
@@ -0,0 +1,226 @@
|
||||
# Convoys
|
||||
|
||||
Convoys are the primary unit for tracking batched work across rigs.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Create a convoy tracking some issues
|
||||
gt convoy create "Feature X" gt-abc gt-def --notify overseer
|
||||
|
||||
# Check progress
|
||||
gt convoy status hq-cv-abc
|
||||
|
||||
# List active convoys (the dashboard)
|
||||
gt convoy list
|
||||
|
||||
# See all convoys including landed ones
|
||||
gt convoy list --all
|
||||
```
|
||||
|
||||
## Concept
|
||||
|
||||
A **convoy** is a persistent tracking unit that monitors related issues across
|
||||
multiple rigs. When you kick off work - even a single issue - a convoy tracks it
|
||||
so you can see when it lands and what was included.
|
||||
|
||||
```
|
||||
🚚 Convoy (hq-cv-abc)
|
||||
│
|
||||
┌────────────┼────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────┐ ┌─────────┐ ┌─────────┐
|
||||
│ gt-xyz │ │ gt-def │ │ bd-abc │
|
||||
│ gastown │ │ gastown │ │ beads │
|
||||
└────┬────┘ └────┬────┘ └────┬────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────┐ ┌─────────┐ ┌─────────┐
|
||||
│ nux │ │ furiosa │ │ amber │
|
||||
│(polecat)│ │(polecat)│ │(polecat)│
|
||||
└─────────┘ └─────────┘ └─────────┘
|
||||
│
|
||||
"the swarm"
|
||||
(ephemeral)
|
||||
```
|
||||
|
||||
## Convoy vs Swarm
|
||||
|
||||
| Concept | Persistent? | ID | Description |
|
||||
|---------|-------------|-----|-------------|
|
||||
| **Convoy** | Yes | hq-cv-* | Tracking unit. What you create, track, get notified about. |
|
||||
| **Swarm** | No | None | Ephemeral. "The workers currently on this convoy's issues." |
|
||||
|
||||
When you "kick off a swarm", you're really:
|
||||
1. Creating a convoy (the tracking unit)
|
||||
2. Assigning polecats to the tracked issues
|
||||
3. The "swarm" is just those polecats while they're working
|
||||
|
||||
When issues close, the convoy lands and notifies you. The swarm dissolves.
|
||||
|
||||
## Convoy Lifecycle
|
||||
|
||||
```
|
||||
OPEN ──(all issues close)──► LANDED/CLOSED
|
||||
↑ │
|
||||
└──(add more issues)───────────┘
|
||||
(auto-reopens)
|
||||
```
|
||||
|
||||
| State | Description |
|
||||
|-------|-------------|
|
||||
| `open` | Active tracking, work in progress |
|
||||
| `closed` | All tracked issues closed, notification sent |
|
||||
|
||||
Adding issues to a closed convoy reopens it automatically.
|
||||
|
||||
## Commands
|
||||
|
||||
### Create a Convoy
|
||||
|
||||
```bash
|
||||
# Track multiple issues across rigs
|
||||
gt convoy create "Deploy v2.0" gt-abc bd-xyz --notify gastown/joe
|
||||
|
||||
# Track a single issue (still creates convoy for dashboard visibility)
|
||||
gt convoy create "Fix auth bug" gt-auth-fix
|
||||
|
||||
# With default notification (from config)
|
||||
gt convoy create "Feature X" gt-a gt-b gt-c
|
||||
```
|
||||
|
||||
### Add Issues
|
||||
|
||||
> **Note**: `gt convoy add` is not yet implemented. Use `bd dep add` directly:
|
||||
|
||||
```bash
|
||||
# Add issue to existing convoy
|
||||
bd dep add hq-cv-abc gt-new-issue --type=tracks
|
||||
|
||||
# Adding to closed convoy requires reopening first
|
||||
bd update hq-cv-abc --status=open
|
||||
bd dep add hq-cv-abc gt-followup-fix --type=tracks
|
||||
```
|
||||
|
||||
### Check Status
|
||||
|
||||
```bash
|
||||
# Show issues and active workers (the swarm)
|
||||
gt convoy status hq-abc
|
||||
|
||||
# All active convoys (the dashboard)
|
||||
gt convoy status
|
||||
```
|
||||
|
||||
Example output:
|
||||
```
|
||||
🚚 hq-cv-abc: Deploy v2.0
|
||||
|
||||
Status: ●
|
||||
Progress: 2/4 completed
|
||||
Created: 2025-12-30T10:15:00-08:00
|
||||
|
||||
Tracked Issues:
|
||||
✓ gt-xyz: Update API endpoint [task]
|
||||
✓ bd-abc: Fix validation [bug]
|
||||
○ bd-ghi: Update docs [task]
|
||||
○ gt-jkl: Deploy to prod [task]
|
||||
```
|
||||
|
||||
### List Convoys (Dashboard)
|
||||
|
||||
```bash
|
||||
# Active convoys (default) - the primary attention view
|
||||
gt convoy list
|
||||
|
||||
# All convoys including landed
|
||||
gt convoy list --all
|
||||
|
||||
# Only landed convoys
|
||||
gt convoy list --status=closed
|
||||
|
||||
# JSON output
|
||||
gt convoy list --json
|
||||
```
|
||||
|
||||
Example output:
|
||||
```
|
||||
Convoys
|
||||
|
||||
🚚 hq-cv-w3nm6: Feature X ●
|
||||
🚚 hq-cv-abc12: Bug fixes ●
|
||||
|
||||
Use 'gt convoy status <id>' for detailed view.
|
||||
```
|
||||
|
||||
## Notifications
|
||||
|
||||
When a convoy lands (all tracked issues closed), subscribers are notified:
|
||||
|
||||
```bash
|
||||
# Explicit subscriber
|
||||
gt convoy create "Feature X" gt-abc --notify gastown/joe
|
||||
|
||||
# Multiple subscribers
|
||||
gt convoy create "Feature X" gt-abc --notify mayor/ --notify --human
|
||||
```
|
||||
|
||||
Notification content:
|
||||
```
|
||||
🚚 Convoy Landed: Deploy v2.0 (hq-cv-abc)
|
||||
|
||||
Issues (3):
|
||||
✓ gt-xyz: Update API endpoint
|
||||
✓ gt-def: Add validation
|
||||
✓ bd-abc: Update docs
|
||||
|
||||
Duration: 2h 15m
|
||||
```
|
||||
|
||||
## Auto-Convoy on Sling
|
||||
|
||||
When you sling a single issue without an existing convoy:
|
||||
|
||||
```bash
|
||||
gt sling bd-xyz beads/amber
|
||||
```
|
||||
|
||||
This auto-creates a convoy so all work appears in the dashboard:
|
||||
1. Creates convoy: "Work: bd-xyz"
|
||||
2. Tracks the issue
|
||||
3. Assigns the polecat
|
||||
|
||||
Even "swarm of one" gets convoy visibility.
|
||||
|
||||
## Cross-Rig Tracking
|
||||
|
||||
Convoys live in town-level beads (`hq-cv-*` prefix) and can track issues from any rig:
|
||||
|
||||
```bash
|
||||
# Track issues from multiple rigs
|
||||
gt convoy create "Full-stack feature" \
|
||||
gt-frontend-abc \
|
||||
gt-backend-def \
|
||||
bd-docs-xyz
|
||||
```
|
||||
|
||||
The `tracks` relation is:
|
||||
- **Non-blocking**: doesn't affect issue workflow
|
||||
- **Additive**: can add issues anytime
|
||||
- **Cross-rig**: convoy in hq-*, issues in gt-*, bd-*, etc.
|
||||
|
||||
## Convoy vs Rig Status
|
||||
|
||||
| View | Scope | Shows |
|
||||
|------|-------|-------|
|
||||
| `gt convoy status [id]` | Cross-rig | Issues tracked by convoy + workers |
|
||||
| `gt rig status <rig>` | Single rig | All workers in rig + their convoy membership |
|
||||
|
||||
Use convoys for "what's the status of this batch of work?"
|
||||
Use rig status for "what's everyone in this rig working on?"
|
||||
|
||||
## See Also
|
||||
|
||||
- [Propulsion Principle](propulsion-principle.md) - Worker execution model
|
||||
- [Mail Protocol](../design/mail-protocol.md) - Notification delivery
|
||||
279
docs/concepts/identity.md
Normal file
279
docs/concepts/identity.md
Normal file
@@ -0,0 +1,279 @@
|
||||
# Agent Identity and Attribution
|
||||
|
||||
> Canonical format for agent identity in Gas Town
|
||||
|
||||
## Why Identity Matters
|
||||
|
||||
When you deploy AI agents at scale, anonymous work creates real problems:
|
||||
|
||||
- **Debugging:** "The AI broke it" isn't actionable. *Which* AI?
|
||||
- **Quality tracking:** You can't improve what you can't measure.
|
||||
- **Compliance:** Auditors ask "who approved this code?" - you need an answer.
|
||||
- **Performance management:** Some agents are better than others at certain tasks.
|
||||
|
||||
Gas Town solves this with **universal attribution**: every action, every commit,
|
||||
every bead update is linked to a specific agent identity. This enables work
|
||||
history tracking, capability-based routing, and objective quality measurement.
|
||||
|
||||
## BD_ACTOR Format Convention
|
||||
|
||||
The `BD_ACTOR` environment variable identifies agents in slash-separated path format.
|
||||
This is set automatically when agents are spawned and used for all attribution.
|
||||
|
||||
### Format by Role Type
|
||||
|
||||
| Role Type | Format | Example |
|
||||
|-----------|--------|---------|
|
||||
| **Mayor** | `mayor` | `mayor` |
|
||||
| **Deacon** | `deacon` | `deacon` |
|
||||
| **Witness** | `{rig}/witness` | `gastown/witness` |
|
||||
| **Refinery** | `{rig}/refinery` | `gastown/refinery` |
|
||||
| **Crew** | `{rig}/crew/{name}` | `gastown/crew/joe` |
|
||||
| **Polecat** | `{rig}/polecats/{name}` | `gastown/polecats/toast` |
|
||||
|
||||
### Why Slashes?
|
||||
|
||||
The slash format mirrors filesystem paths and enables:
|
||||
- Hierarchical parsing (extract rig, role, name)
|
||||
- Consistent mail addressing (`gt mail send gastown/witness`)
|
||||
- Path-like routing in beads operations
|
||||
- Visual clarity about agent location
|
||||
|
||||
## Attribution Model
|
||||
|
||||
Gas Town uses three fields for complete provenance:
|
||||
|
||||
### Git Commits
|
||||
|
||||
```bash
|
||||
GIT_AUTHOR_NAME="gastown/crew/joe" # Who did the work (agent)
|
||||
GIT_AUTHOR_EMAIL="steve@example.com" # Who owns the work (overseer)
|
||||
```
|
||||
|
||||
Result in git log:
|
||||
```
|
||||
abc123 Fix bug (gastown/crew/joe <steve@example.com>)
|
||||
```
|
||||
|
||||
**Interpretation**:
|
||||
- The agent `gastown/crew/joe` authored the change
|
||||
- The work belongs to the workspace owner (`steve@example.com`)
|
||||
- Both are preserved in git history forever
|
||||
|
||||
### Beads Records
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "gt-xyz",
|
||||
"created_by": "gastown/crew/joe",
|
||||
"updated_by": "gastown/witness"
|
||||
}
|
||||
```
|
||||
|
||||
The `created_by` field is populated from `BD_ACTOR` when creating beads.
|
||||
The `updated_by` field tracks who last modified the record.
|
||||
|
||||
### Event Logging
|
||||
|
||||
All events include actor attribution:
|
||||
|
||||
```json
|
||||
{
|
||||
"ts": "2025-01-15T10:30:00Z",
|
||||
"type": "sling",
|
||||
"actor": "gastown/crew/joe",
|
||||
"payload": { "bead": "gt-xyz", "target": "gastown/polecats/toast" }
|
||||
}
|
||||
```
|
||||
|
||||
## Environment Setup
|
||||
|
||||
Gas Town uses a centralized `config.AgentEnv()` function to set environment
|
||||
variables consistently across all agent spawn paths (managers, daemon, boot).
|
||||
|
||||
### Example: Polecat Environment
|
||||
|
||||
```bash
|
||||
# Set automatically for polecat 'toast' in rig 'gastown'
|
||||
export GT_ROLE="polecat"
|
||||
export GT_RIG="gastown"
|
||||
export GT_POLECAT="toast"
|
||||
export BD_ACTOR="gastown/polecats/toast"
|
||||
export GIT_AUTHOR_NAME="gastown/polecats/toast"
|
||||
export GT_ROOT="/home/user/gt"
|
||||
export BEADS_DIR="/home/user/gt/gastown/.beads"
|
||||
export BEADS_AGENT_NAME="gastown/toast"
|
||||
export BEADS_NO_DAEMON="1" # Polecats use isolated beads context
|
||||
```
|
||||
|
||||
### Example: Crew Environment
|
||||
|
||||
```bash
|
||||
# Set automatically for crew member 'joe' in rig 'gastown'
|
||||
export GT_ROLE="crew"
|
||||
export GT_RIG="gastown"
|
||||
export GT_CREW="joe"
|
||||
export BD_ACTOR="gastown/crew/joe"
|
||||
export GIT_AUTHOR_NAME="gastown/crew/joe"
|
||||
export GT_ROOT="/home/user/gt"
|
||||
export BEADS_DIR="/home/user/gt/gastown/.beads"
|
||||
export BEADS_AGENT_NAME="gastown/joe"
|
||||
export BEADS_NO_DAEMON="1" # Crew uses isolated beads context
|
||||
```
|
||||
|
||||
### Manual Override
|
||||
|
||||
For local testing or debugging:
|
||||
|
||||
```bash
|
||||
export BD_ACTOR="gastown/crew/debug"
|
||||
bd create --title="Test issue" # Will show created_by: gastown/crew/debug
|
||||
```
|
||||
|
||||
See [reference.md](reference.md#environment-variables) for the complete
|
||||
environment variable reference.
|
||||
|
||||
## Identity Parsing
|
||||
|
||||
The format supports programmatic parsing:
|
||||
|
||||
```go
|
||||
// identityToBDActor converts daemon identity to BD_ACTOR format
|
||||
// Town level: mayor, deacon
|
||||
// Rig level: {rig}/witness, {rig}/refinery
|
||||
// Workers: {rig}/crew/{name}, {rig}/polecats/{name}
|
||||
```
|
||||
|
||||
| Input | Parsed Components |
|
||||
|-------|-------------------|
|
||||
| `mayor` | role=mayor |
|
||||
| `deacon` | role=deacon |
|
||||
| `gastown/witness` | rig=gastown, role=witness |
|
||||
| `gastown/refinery` | rig=gastown, role=refinery |
|
||||
| `gastown/crew/joe` | rig=gastown, role=crew, name=joe |
|
||||
| `gastown/polecats/toast` | rig=gastown, role=polecat, name=toast |
|
||||
|
||||
## Audit Queries
|
||||
|
||||
Attribution enables powerful audit queries:
|
||||
|
||||
```bash
|
||||
# All work by an agent
|
||||
bd audit --actor=gastown/crew/joe
|
||||
|
||||
# All work in a rig
|
||||
bd audit --actor=gastown/*
|
||||
|
||||
# All polecat work
|
||||
bd audit --actor=*/polecats/*
|
||||
|
||||
# Git history by agent
|
||||
git log --author="gastown/crew/joe"
|
||||
```
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **Agents are not anonymous** - Every action is attributed
|
||||
2. **Work is owned, not authored** - Agent creates, overseer owns
|
||||
3. **Attribution is permanent** - Git commits preserve history
|
||||
4. **Format is parseable** - Enables programmatic analysis
|
||||
5. **Consistent across systems** - Same format in git, beads, events
|
||||
|
||||
## CV and Skill Accumulation
|
||||
|
||||
### Human Identity is Global
|
||||
|
||||
The global identifier is your **email** - it's already in every git commit. No separate "entity bead" needed.
|
||||
|
||||
```
|
||||
steve@example.com ← global identity (from git author)
|
||||
├── Town A (home) ← workspace
|
||||
│ ├── gastown/crew/joe ← agent executor
|
||||
│ └── gastown/polecats/toast ← agent executor
|
||||
└── Town B (work) ← workspace
|
||||
└── acme/polecats/nux ← agent executor
|
||||
```
|
||||
|
||||
### Agent vs Owner
|
||||
|
||||
| Field | Scope | Purpose |
|
||||
|-------|-------|---------|
|
||||
| `BD_ACTOR` | Local (town) | Agent attribution for debugging |
|
||||
| `GIT_AUTHOR_EMAIL` | Global | Human identity for CV |
|
||||
| `created_by` | Local | Who created the bead |
|
||||
| `owner` | Global | Who owns the work |
|
||||
|
||||
**Agents execute. Humans own.** The polecat name in `completed-by: gastown/polecats/toast` is executor attribution. The CV credits the human owner (`steve@example.com`).
|
||||
|
||||
### Polecats Are Ephemeral
|
||||
|
||||
Polecats are like K8s pods - ephemeral executors with no persistent identity:
|
||||
- Named pool for human convenience (furiosa, nux, slit)
|
||||
- Names are transient - reused after cleanup
|
||||
- No persistent polecat CV
|
||||
- Work credits the human owner
|
||||
|
||||
### Skills Are Derived
|
||||
|
||||
Your CV emerges from querying work evidence:
|
||||
|
||||
```bash
|
||||
# All work by owner (across all agents)
|
||||
git log --author="steve@example.com"
|
||||
bd list --owner=steve@example.com
|
||||
|
||||
# Skills derived from evidence
|
||||
# - .go files touched → Go skill
|
||||
# - issue tags → domain skills
|
||||
# - commit patterns → activity types
|
||||
```
|
||||
|
||||
### Multi-Town Aggregation
|
||||
|
||||
A human with multiple towns has one CV:
|
||||
|
||||
```bash
|
||||
# Future: federated CV query
|
||||
bd cv steve@example.com
|
||||
# Discovers all towns, aggregates work, derives skills
|
||||
```
|
||||
|
||||
See `~/gt/docs/hop/decisions/008-identity-model.md` for architectural rationale.
|
||||
|
||||
## Enterprise Use Cases
|
||||
|
||||
### Compliance and Audit
|
||||
|
||||
```bash
|
||||
# Who touched this file in the last 90 days?
|
||||
git log --since="90 days ago" -- path/to/sensitive/file.go
|
||||
|
||||
# All changes by a specific agent
|
||||
bd audit --actor=gastown/polecats/toast --since=2025-01-01
|
||||
```
|
||||
|
||||
### Performance Tracking
|
||||
|
||||
```bash
|
||||
# Completion rate by agent
|
||||
bd stats --group-by=actor
|
||||
|
||||
# Average time to completion
|
||||
bd stats --actor=gastown/polecats/* --metric=cycle-time
|
||||
```
|
||||
|
||||
### Model Comparison
|
||||
|
||||
When agents use different underlying models, attribution enables A/B comparison:
|
||||
|
||||
```bash
|
||||
# Tag agents by model
|
||||
# gastown/polecats/claude-1 uses Claude
|
||||
# gastown/polecats/gpt-1 uses GPT-4
|
||||
|
||||
# Compare quality signals
|
||||
bd stats --actor=gastown/polecats/claude-* --metric=revision-count
|
||||
bd stats --actor=gastown/polecats/gpt-* --metric=revision-count
|
||||
```
|
||||
|
||||
Lower revision counts suggest higher first-pass quality.
|
||||
206
docs/concepts/molecules.md
Normal file
206
docs/concepts/molecules.md
Normal file
@@ -0,0 +1,206 @@
|
||||
# Molecules
|
||||
|
||||
Molecules are workflow templates that coordinate multi-step work in Gas Town.
|
||||
|
||||
## Molecule Lifecycle
|
||||
|
||||
```
|
||||
Formula (source TOML) ─── "Ice-9"
|
||||
│
|
||||
▼ bd cook
|
||||
Protomolecule (frozen template) ─── Solid
|
||||
│
|
||||
├─▶ bd mol pour ──▶ Mol (persistent) ─── Liquid ──▶ bd squash ──▶ Digest
|
||||
│
|
||||
└─▶ bd mol wisp ──▶ Wisp (ephemeral) ─── Vapor ──┬▶ bd squash ──▶ Digest
|
||||
└▶ bd burn ──▶ (gone)
|
||||
```
|
||||
|
||||
## Core Concepts
|
||||
|
||||
| Term | Description |
|
||||
|------|-------------|
|
||||
| **Formula** | Source TOML template defining workflow steps |
|
||||
| **Protomolecule** | Frozen template ready for instantiation |
|
||||
| **Molecule** | Active workflow instance with trackable steps |
|
||||
| **Wisp** | Ephemeral molecule for patrol cycles (never synced) |
|
||||
| **Digest** | Squashed summary of completed molecule |
|
||||
|
||||
## Common Mistake: Reading Formulas Directly
|
||||
|
||||
**WRONG:**
|
||||
```bash
|
||||
# Reading a formula file and manually creating beads for each step
|
||||
cat .beads/formulas/mol-polecat-work.formula.toml
|
||||
bd create --title "Step 1: Load context" --type task
|
||||
bd create --title "Step 2: Branch setup" --type task
|
||||
# ... creating beads from formula prose
|
||||
```
|
||||
|
||||
**RIGHT:**
|
||||
```bash
|
||||
# Cook the formula into a proto, pour into a molecule
|
||||
bd cook mol-polecat-work
|
||||
bd mol pour mol-polecat-work --var issue=gt-xyz
|
||||
# Now work through the step beads that were created
|
||||
bd ready # Find next step
|
||||
bd close <step-id> # Complete it
|
||||
```
|
||||
|
||||
**Key insight:** Formulas are source templates (like source code). You never read
|
||||
them directly during work. The `cook` → `pour` pipeline creates step beads for you.
|
||||
Your molecule already has steps - use `bd ready` to find them.
|
||||
|
||||
## Navigating Molecules
|
||||
|
||||
Molecules help you track where you are in multi-step workflows.
|
||||
|
||||
### Finding Your Place
|
||||
|
||||
```bash
|
||||
bd mol current # Where am I?
|
||||
bd mol current gt-abc # Status of specific molecule
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
You're working on molecule gt-abc (Feature X)
|
||||
|
||||
✓ gt-abc.1: Design
|
||||
✓ gt-abc.2: Scaffold
|
||||
✓ gt-abc.3: Implement
|
||||
→ gt-abc.4: Write tests [in_progress] <- YOU ARE HERE
|
||||
○ gt-abc.5: Documentation
|
||||
○ gt-abc.6: Exit decision
|
||||
|
||||
Progress: 3/6 steps complete
|
||||
```
|
||||
|
||||
### Seamless Transitions
|
||||
|
||||
Close a step and advance in one command:
|
||||
|
||||
```bash
|
||||
bd close gt-abc.3 --continue # Close and advance to next step
|
||||
bd close gt-abc.3 --no-auto # Close but don't auto-claim next
|
||||
```
|
||||
|
||||
**The old way (3 commands):**
|
||||
```bash
|
||||
bd close gt-abc.3
|
||||
bd ready --parent=gt-abc
|
||||
bd update gt-abc.4 --status=in_progress
|
||||
```
|
||||
|
||||
**The new way (1 command):**
|
||||
```bash
|
||||
bd close gt-abc.3 --continue
|
||||
```
|
||||
|
||||
### Transition Output
|
||||
|
||||
```
|
||||
✓ Closed gt-abc.3: Implement feature
|
||||
|
||||
Next ready in molecule:
|
||||
gt-abc.4: Write tests
|
||||
|
||||
→ Marked in_progress (use --no-auto to skip)
|
||||
```
|
||||
|
||||
### When Molecule Completes
|
||||
|
||||
```
|
||||
✓ Closed gt-abc.6: Exit decision
|
||||
|
||||
Molecule gt-abc complete! All steps closed.
|
||||
Consider: bd mol squash gt-abc --summary '...'
|
||||
```
|
||||
|
||||
## Molecule Commands
|
||||
|
||||
### Beads Operations (bd)
|
||||
|
||||
```bash
|
||||
# Formulas
|
||||
bd formula list # Available formulas
|
||||
bd formula show <name> # Formula details
|
||||
bd cook <formula> # Formula → Proto
|
||||
|
||||
# Molecules (data operations)
|
||||
bd mol list # Available protos
|
||||
bd mol show <id> # Proto details
|
||||
bd mol pour <proto> # Create mol
|
||||
bd mol 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
|
||||
bd mol current # Where am I in the current molecule?
|
||||
```
|
||||
|
||||
### Agent Operations (gt)
|
||||
|
||||
```bash
|
||||
# Hook management
|
||||
gt hook # What's on MY hook
|
||||
gt mol current # What should I work on next
|
||||
gt mol progress <id> # Execution progress of molecule
|
||||
gt mol attach <bead> <mol> # Pin molecule to bead
|
||||
gt mol detach <bead> # Unpin molecule from bead
|
||||
|
||||
# Agent lifecycle
|
||||
gt mol burn # Burn attached molecule
|
||||
gt mol squash # Squash attached molecule
|
||||
gt mol step done <step> # Complete a molecule step
|
||||
```
|
||||
|
||||
## Polecat Workflow
|
||||
|
||||
Polecats receive work via their hook - a pinned molecule attached to an issue.
|
||||
They execute molecule steps sequentially, closing each step as they complete it.
|
||||
|
||||
### Molecule Types for Polecats
|
||||
|
||||
| Type | Storage | Use Case |
|
||||
|------|---------|----------|
|
||||
| **Regular Molecule** | `.beads/` (synced) | Discrete deliverables, audit trail |
|
||||
| **Wisp** | `.beads/` (ephemeral) | Patrol cycles, operational loops |
|
||||
|
||||
Polecats typically use **regular molecules** because each assignment has audit value.
|
||||
Patrol agents (Witness, Refinery, Deacon) use **wisps** to prevent accumulation.
|
||||
|
||||
### Hook Management
|
||||
|
||||
```bash
|
||||
gt hook # What's on MY hook?
|
||||
gt mol attach-from-mail <id> # Attach work from mail message
|
||||
gt done # Signal completion (syncs, submits to MQ, notifies Witness)
|
||||
```
|
||||
|
||||
### Polecat Workflow Summary
|
||||
|
||||
```
|
||||
1. Spawn with work on hook
|
||||
2. gt hook # What's hooked?
|
||||
3. bd mol current # Where am I?
|
||||
4. Execute current step
|
||||
5. bd close <step> --continue
|
||||
6. If more steps: GOTO 3
|
||||
7. gt done # Signal completion
|
||||
```
|
||||
|
||||
### Wisp vs Molecule Decision
|
||||
|
||||
| Question | Molecule | Wisp |
|
||||
|----------|----------|------|
|
||||
| Does it need audit trail? | Yes | No |
|
||||
| Will it repeat continuously? | No | Yes |
|
||||
| Is it discrete deliverable? | Yes | No |
|
||||
| Is it operational routine? | No | Yes |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use `--continue` for propulsion** - Keep momentum by auto-advancing
|
||||
2. **Check progress with `bd mol current`** - Know where you are before resuming
|
||||
3. **Squash completed molecules** - Create digests for audit trail
|
||||
4. **Burn routine wisps** - Don't accumulate ephemeral patrol data
|
||||
283
docs/concepts/polecat-lifecycle.md
Normal file
283
docs/concepts/polecat-lifecycle.md
Normal file
@@ -0,0 +1,283 @@
|
||||
# Polecat Lifecycle
|
||||
|
||||
> Understanding the three-layer architecture of polecat workers
|
||||
|
||||
## Overview
|
||||
|
||||
Polecats have three distinct lifecycle layers that operate independently. Confusing
|
||||
these layers leads to bugs like "idle polecats" and misunderstanding when
|
||||
recycling occurs.
|
||||
|
||||
## The Self-Cleaning Polecat Model
|
||||
|
||||
**Polecats are responsible for their own cleanup.** When a polecat completes its
|
||||
work unit, it:
|
||||
|
||||
1. Signals completion via `gt done`
|
||||
2. Exits its session immediately (no idle waiting)
|
||||
3. Requests its own nuke (self-delete)
|
||||
|
||||
This removes dependency on the Witness/Deacon for cleanup and ensures polecats
|
||||
never sit idle. The simple model: **sandbox dies with session**.
|
||||
|
||||
### Why Self-Cleaning?
|
||||
|
||||
- **No idle polecats** - There's no state where a polecat exists without work
|
||||
- **Reduced watchdog overhead** - Deacon doesn't need to patrol for zombies
|
||||
- **Faster turnover** - Resources freed immediately on completion
|
||||
- **Simpler mental model** - Done means gone
|
||||
|
||||
### What About Pending Merges?
|
||||
|
||||
The Refinery owns the merge queue. Once `gt done` submits work:
|
||||
- The branch is pushed to origin
|
||||
- Work exists in the MQ, not in the polecat
|
||||
- If rebase fails, Refinery re-implements on new baseline (fresh polecat)
|
||||
- The original polecat is already gone - no sending work "back"
|
||||
|
||||
## The Three Layers
|
||||
|
||||
| Layer | Component | Lifecycle | Persistence |
|
||||
|-------|-----------|-----------|-------------|
|
||||
| **Session** | Claude (tmux pane) | Ephemeral | Cycles per step/handoff |
|
||||
| **Sandbox** | Git worktree | Persistent | Until nuke |
|
||||
| **Slot** | Name from pool | Persistent | Until nuke |
|
||||
|
||||
### Session Layer
|
||||
|
||||
The Claude session is **ephemeral**. It cycles frequently:
|
||||
|
||||
- After each molecule step (via `gt handoff`)
|
||||
- On context compaction
|
||||
- On crash/timeout
|
||||
- After extended work periods
|
||||
|
||||
**Key insight:** Session cycling is **normal operation**, not failure. The polecat
|
||||
continues working—only the Claude context refreshes.
|
||||
|
||||
```
|
||||
Session 1: Steps 1-2 → handoff
|
||||
Session 2: Steps 3-4 → handoff
|
||||
Session 3: Step 5 → gt done
|
||||
```
|
||||
|
||||
All three sessions are the **same polecat**. The sandbox and slot persist throughout.
|
||||
|
||||
### Sandbox Layer
|
||||
|
||||
The sandbox is the **git worktree**—the polecat's working directory:
|
||||
|
||||
```
|
||||
~/gt/gastown/polecats/Toast/
|
||||
```
|
||||
|
||||
This worktree:
|
||||
- Exists from `gt sling` until `gt polecat nuke`
|
||||
- Survives all session cycles
|
||||
- Contains uncommitted work, staged changes, branch state
|
||||
- Is independent of other polecat sandboxes
|
||||
|
||||
The Witness never destroys sandboxes mid-work. Only `nuke` removes them.
|
||||
|
||||
### Slot Layer
|
||||
|
||||
The slot is the **name allocation** from the polecat pool:
|
||||
|
||||
```bash
|
||||
# Pool: [Toast, Shadow, Copper, Ash, Storm...]
|
||||
# Toast is allocated to work gt-abc
|
||||
```
|
||||
|
||||
The slot:
|
||||
- Determines the sandbox path (`polecats/Toast/`)
|
||||
- Maps to a tmux session (`gt-gastown-Toast`)
|
||||
- Appears in attribution (`gastown/polecats/Toast`)
|
||||
- Is released only on nuke
|
||||
|
||||
## Correct Lifecycle
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ gt sling │
|
||||
│ → Allocate slot from pool (Toast) │
|
||||
│ → Create sandbox (worktree on new branch) │
|
||||
│ → Start session (Claude in tmux) │
|
||||
│ → Hook molecule to polecat │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Work Happens │
|
||||
│ │
|
||||
│ Session cycles happen here: │
|
||||
│ - gt handoff between steps │
|
||||
│ - Compaction triggers respawn │
|
||||
│ - Crash → Witness respawns │
|
||||
│ │
|
||||
│ Sandbox persists through ALL session cycles │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ gt done (self-cleaning) │
|
||||
│ → Push branch to origin │
|
||||
│ → Submit work to merge queue (MR bead) │
|
||||
│ → Request self-nuke (sandbox + session cleanup) │
|
||||
│ → Exit immediately │
|
||||
│ │
|
||||
│ Work now lives in MQ, not in polecat. │
|
||||
│ Polecat is GONE. No idle state. │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Refinery: merge queue │
|
||||
│ → Rebase and merge to main │
|
||||
│ → Close the issue │
|
||||
│ → If conflict: spawn FRESH polecat to re-implement │
|
||||
│ (never send work back to original polecat - it's gone) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## What "Recycle" Means
|
||||
|
||||
**Session cycling**: Normal. Claude restarts, sandbox stays, slot stays.
|
||||
|
||||
```bash
|
||||
gt handoff # Session cycles, polecat continues
|
||||
```
|
||||
|
||||
**Sandbox recreation**: Repair only. Should be rare.
|
||||
|
||||
```bash
|
||||
gt polecat repair Toast # Emergency: recreate corrupted worktree
|
||||
```
|
||||
|
||||
Session cycling happens constantly. Sandbox recreation should almost never happen
|
||||
during normal operation.
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### Idle Polecats
|
||||
|
||||
**Myth:** Polecats wait between tasks in an idle state.
|
||||
|
||||
**Reality:** Polecats don't exist without work. The lifecycle is:
|
||||
1. Work assigned → polecat spawned
|
||||
2. Work done → polecat nuked
|
||||
3. There is no idle state
|
||||
|
||||
If you see a polecat without work, something is broken. Either:
|
||||
- The hook was lost (bug)
|
||||
- The session crashed before loading context
|
||||
- Manual intervention corrupted state
|
||||
|
||||
### Manual State Transitions
|
||||
|
||||
**Anti-pattern:**
|
||||
```bash
|
||||
gt polecat done Toast # DON'T: external state manipulation
|
||||
gt polecat reset Toast # DON'T: manual lifecycle control
|
||||
```
|
||||
|
||||
**Correct:**
|
||||
```bash
|
||||
# Polecat signals its own completion:
|
||||
gt done # (from inside the polecat session)
|
||||
|
||||
# Only Witness nukes polecats:
|
||||
gt polecat nuke Toast # (from Witness, after verification)
|
||||
```
|
||||
|
||||
Polecats manage their own session lifecycle. The Witness manages sandbox lifecycle.
|
||||
External manipulation bypasses verification.
|
||||
|
||||
### Sandboxes Without Work
|
||||
|
||||
**Anti-pattern:** A sandbox exists but no molecule is hooked.
|
||||
|
||||
This means:
|
||||
- The polecat was spawned incorrectly
|
||||
- The hook was lost during crash
|
||||
- State corruption occurred
|
||||
|
||||
**Recovery:**
|
||||
```bash
|
||||
# From Witness:
|
||||
gt polecat nuke Toast # Clean slate
|
||||
gt sling gt-abc gastown # Respawn with work
|
||||
```
|
||||
|
||||
### Confusing Session with Sandbox
|
||||
|
||||
**Anti-pattern:** Thinking session restart = losing work.
|
||||
|
||||
```bash
|
||||
# Session ends (handoff, crash, compaction)
|
||||
# Work is NOT lost because:
|
||||
# - Git commits persist in sandbox
|
||||
# - Staged changes persist in sandbox
|
||||
# - Molecule state persists in beads
|
||||
# - Hook persists across sessions
|
||||
```
|
||||
|
||||
The new session picks up where the old one left off via `gt prime`.
|
||||
|
||||
## Session Lifecycle Details
|
||||
|
||||
Sessions cycle for these reasons:
|
||||
|
||||
| Trigger | Action | Result |
|
||||
|---------|--------|--------|
|
||||
| `gt handoff` | Voluntary | Clean cycle to fresh context |
|
||||
| Context compaction | Automatic | Forced by Claude Code |
|
||||
| Crash/timeout | Failure | Witness respawns |
|
||||
| `gt done` | Completion | Session exits, Witness takes over |
|
||||
|
||||
All except `gt done` result in continued work. Only `gt done` signals completion.
|
||||
|
||||
## Witness Responsibilities
|
||||
|
||||
The Witness monitors polecats but does NOT:
|
||||
- Force session cycles (polecats self-manage via handoff)
|
||||
- Interrupt mid-step (unless truly stuck)
|
||||
- Nuke polecats (polecats self-nuke via `gt done`)
|
||||
|
||||
The Witness DOES:
|
||||
- Respawn crashed sessions
|
||||
- Nudge stuck polecats
|
||||
- Handle escalations
|
||||
- Clean up orphaned polecats (crash before `gt done`)
|
||||
|
||||
## Polecat Identity
|
||||
|
||||
**Key insight:** Polecat *identity* is long-lived; only sessions and sandboxes are ephemeral.
|
||||
|
||||
In the HOP model, every entity has a chain (CV) that tracks:
|
||||
- What work they've done
|
||||
- Success/failure rates
|
||||
- Skills demonstrated
|
||||
- Quality metrics
|
||||
|
||||
The polecat *name* (Toast, Shadow, etc.) is a slot from a pool - truly ephemeral.
|
||||
But the *agent identity* that executes as that polecat accumulates a work history.
|
||||
|
||||
```
|
||||
POLECAT IDENTITY (persistent) SESSION (ephemeral) SANDBOX (ephemeral)
|
||||
├── CV chain ├── Claude instance ├── Git worktree
|
||||
├── Work history ├── Context window ├── Branch
|
||||
├── Skills demonstrated └── Dies on handoff └── Dies on gt done
|
||||
└── Credit for work or gt done
|
||||
```
|
||||
|
||||
This distinction matters for:
|
||||
- **Attribution** - Who gets credit for the work?
|
||||
- **Skill routing** - Which agent is best for this task?
|
||||
- **Cost accounting** - Who pays for inference?
|
||||
- **Federation** - Agents having their own chains in a distributed world
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Overview](../overview.md) - Role taxonomy and architecture
|
||||
- [Molecules](molecules.md) - Molecule execution and polecat workflow
|
||||
- [Propulsion Principle](propulsion-principle.md) - Why work triggers immediate execution
|
||||
105
docs/concepts/propulsion-principle.md
Normal file
105
docs/concepts/propulsion-principle.md
Normal file
@@ -0,0 +1,105 @@
|
||||
# The Propulsion Principle
|
||||
|
||||
> **If you find something on your hook, YOU RUN IT.**
|
||||
|
||||
Gas Town is a steam engine. Agents are pistons. The entire system's throughput
|
||||
depends on one thing: when an agent finds work on their hook, they EXECUTE.
|
||||
|
||||
## Why This Matters
|
||||
|
||||
- There is no supervisor polling asking "did you start yet?"
|
||||
- The hook IS your assignment - it was placed there deliberately
|
||||
- Every moment you wait is a moment the engine stalls
|
||||
- Other agents may be blocked waiting on YOUR output
|
||||
|
||||
## The Handoff Contract
|
||||
|
||||
When you were spawned, work was hooked for you. The system trusts that:
|
||||
|
||||
1. You will find it on your hook
|
||||
2. You will understand what it is (`bd show` / `gt hook`)
|
||||
3. You will BEGIN IMMEDIATELY
|
||||
|
||||
This isn't about being a good worker. This is physics. Steam engines don't
|
||||
run on politeness - they run on pistons firing. You are the piston.
|
||||
|
||||
## Molecule Navigation: Key Enabler
|
||||
|
||||
Molecules enable propulsion by providing clear waypoints. You don't need to
|
||||
memorize steps or wait for instructions - discover them:
|
||||
|
||||
### Orientation Commands
|
||||
|
||||
```bash
|
||||
gt hook # What's on my hook?
|
||||
bd mol current # Where am I in the molecule?
|
||||
bd ready # What step is next?
|
||||
bd show <step-id> # What does this step require?
|
||||
```
|
||||
|
||||
### Before/After: Step Transitions
|
||||
|
||||
**The old workflow (friction):**
|
||||
```bash
|
||||
# Finish step 3
|
||||
bd close gt-abc.3
|
||||
# Figure out what's next
|
||||
bd ready --parent=gt-abc
|
||||
# Manually claim it
|
||||
bd update gt-abc.4 --status=in_progress
|
||||
# Now finally work on it
|
||||
```
|
||||
|
||||
Three commands. Context switches. Momentum lost.
|
||||
|
||||
**The new workflow (propulsion):**
|
||||
```bash
|
||||
bd close gt-abc.3 --continue
|
||||
```
|
||||
|
||||
One command. Auto-advance. Momentum preserved.
|
||||
|
||||
### The Propulsion Loop
|
||||
|
||||
```
|
||||
1. gt hook # What's hooked?
|
||||
2. bd mol current # Where am I?
|
||||
3. Execute step
|
||||
4. bd close <step> --continue # Close and advance
|
||||
5. GOTO 2
|
||||
```
|
||||
|
||||
## The Failure Mode We're Preventing
|
||||
|
||||
```
|
||||
Polecat restarts with work on hook
|
||||
→ Polecat announces itself
|
||||
→ Polecat waits for confirmation
|
||||
→ Witness assumes work is progressing
|
||||
→ Nothing happens
|
||||
→ Gas Town stops
|
||||
```
|
||||
|
||||
## Startup Behavior
|
||||
|
||||
1. Check hook (`gt hook`)
|
||||
2. Work hooked → EXECUTE immediately
|
||||
3. Hook empty → Check mail for attached work
|
||||
4. Nothing anywhere → ERROR: escalate to Witness
|
||||
|
||||
**Note:** "Hooked" means work assigned to you. This triggers autonomous mode
|
||||
even if no molecule is attached. Don't confuse with "pinned" which is for
|
||||
permanent reference beads.
|
||||
|
||||
## The Capability Ledger
|
||||
|
||||
Every completion is recorded. Every handoff is logged. Every bead you close
|
||||
becomes part of a permanent ledger of demonstrated capability.
|
||||
|
||||
- Your work is visible
|
||||
- Redemption is real (consistent good work builds over time)
|
||||
- Every completion is evidence that autonomous execution works
|
||||
- Your CV grows with every completion
|
||||
|
||||
This isn't just about the current task. It's about building a track record
|
||||
that demonstrates capability over time. Execute with care.
|
||||
Reference in New Issue
Block a user