diff --git a/README.md b/README.md index 6cf5578a..91333153 100644 --- a/README.md +++ b/README.md @@ -71,12 +71,14 @@ Git worktree-based persistent storage for agent work. Survives crashes and resta ### Convoys 🚚 -Work tracking units. Bundle multiple issues/tasks that get assigned to agents. +Work tracking units. Bundle multiple beads that get assigned to agents. ### Beads Integration 📿 Git-backed issue tracking system that stores work state as structured data. +**Bead IDs** use a prefix + 5-character alphanumeric format (e.g., `gt-abc12`, `hq-x7k2m`). The prefix indicates the bead's origin or purpose. Commands like `gt sling` and `gt convoy` accept these bead IDs to reference specific work items. + > **New to Gas Town?** See the [Glossary](docs/glossary.md) for a complete guide to terminology and concepts. ## Installation @@ -140,8 +142,8 @@ sequenceDiagram participant Hook You->>Mayor: Tell Mayor what to build - Mayor->>Convoy: Create convoy with issues - Mayor->>Agent: Sling issue to agent + Mayor->>Convoy: Create convoy with beads + Mayor->>Agent: Sling bead to agent Agent->>Hook: Store work state Agent->>Agent: Complete work Agent->>Convoy: Report completion @@ -154,11 +156,11 @@ sequenceDiagram # 1. Start the Mayor gt mayor attach -# 2. In Mayor session, create a convoy -gt convoy create "Feature X" issue-123 issue-456 --notify --human +# 2. In Mayor session, create a convoy with bead IDs +gt convoy create "Feature X" gt-abc12 gt-def34 --notify --human # 3. Assign work to an agent -gt sling issue-123 myproject +gt sling gt-abc12 myproject # 4. Track progress gt convoy list @@ -190,7 +192,7 @@ flowchart LR gt mayor attach # In Mayor, create convoy and let it orchestrate -gt convoy create "Auth System" issue-101 issue-102 --notify +gt convoy create "Auth System" gt-x7k2m gt-p9n4q --notify # Track progress gt convoy list @@ -201,8 +203,8 @@ gt convoy list Run individual runtime instances manually. Gas Town just tracks state. ```bash -gt convoy create "Fix bugs" issue-123 # Create convoy (sling auto-creates if skipped) -gt sling issue-123 myproject # Assign to worker +gt convoy create "Fix bugs" gt-abc12 # Create convoy (sling auto-creates if skipped) +gt sling gt-abc12 myproject # Assign to worker claude --resume # Agent reads mail, runs work (Claude) # or: codex # Start Codex in the workspace gt convoy list # Check progress @@ -276,11 +278,11 @@ bd mol pour release --var version=1.2.0 # Create convoy manually gt convoy create "Bug Fixes" --human -# Add issues -gt convoy add-issue bug-101 bug-102 +# Add beads to convoy +gt convoy add-issue gt-m3k9p gt-w5t2x # Assign to specific agents -gt sling bug-101 myproject/my-agent +gt sling gt-m3k9p myproject/my-agent # Check status gt convoy show @@ -325,8 +327,8 @@ gt crew add --rig # Create crew workspace ```bash gt agents # List active agents -gt sling # Assign work to agent -gt sling --agent cursor # Override runtime for this sling/spawn +gt sling # Assign work to agent +gt sling --agent cursor # Override runtime for this sling/spawn gt mayor attach # Start Mayor session gt mayor start --agent auggie # Run Mayor with a specific agent alias gt prime # Context recovery (run inside existing session) @@ -337,10 +339,10 @@ gt prime # Context recovery (run inside existing session) ### Convoy (Work Tracking) ```bash -gt convoy create [issues...] # Create convoy +gt convoy create [bead-ids...] # Create convoy with beads gt convoy list # List all convoys gt convoy show [id] # Show convoy details -gt convoy add-issue # Add issue to convoy +gt convoy add-issue # Add bead to convoy ``` ### Configuration @@ -419,9 +421,9 @@ MEOW is the recommended pattern: 1. **Tell the Mayor** - Describe what you want 2. **Mayor analyzes** - Breaks down into tasks -3. **Convoy creation** - Mayor creates convoy with issues +3. **Convoy creation** - Mayor creates convoy with beads 4. **Agent spawning** - Mayor spawns appropriate agents -5. **Work distribution** - Issues slung to agents via hooks +5. **Work distribution** - Beads slung to agents via hooks 6. **Progress monitoring** - Track through convoy status 7. **Completion** - Mayor summarizes results diff --git a/docs/INSTALLING.md b/docs/INSTALLING.md index db230270..693d4d8c 100644 --- a/docs/INSTALLING.md +++ b/docs/INSTALLING.md @@ -152,7 +152,7 @@ You can also override the agent per command without changing defaults: ```bash gt start --agent codex-low -gt sling issue-123 myproject --agent claude-haiku +gt sling gt-abc12 myproject --agent claude-haiku ``` ## Minimal Mode vs Full Stack Mode @@ -165,8 +165,8 @@ Run individual runtime instances manually. Gas Town only tracks state. ```bash # Create and assign work -gt convoy create "Fix bugs" issue-123 -gt sling issue-123 myproject +gt convoy create "Fix bugs" gt-abc12 +gt sling gt-abc12 myproject # Run runtime manually cd ~/gt/myproject/polecats/ @@ -188,9 +188,9 @@ Agents run in tmux sessions. Daemon manages lifecycle automatically. gt daemon start # Create and assign work (workers spawn automatically) -gt convoy create "Feature X" issue-123 issue-456 -gt sling issue-123 myproject -gt sling issue-456 myproject +gt convoy create "Feature X" gt-abc12 gt-def34 +gt sling gt-abc12 myproject +gt sling gt-def34 myproject # Monitor on dashboard gt convoy list @@ -303,6 +303,6 @@ rm -rf ~/gt After installation: 1. **Read the README** - Core concepts and workflows -2. **Try a simple workflow** - `gt convoy create "Test" test-issue` +2. **Try a simple workflow** - `bd create "Test task"` then `gt convoy create "Test" ` 3. **Explore docs** - `docs/reference.md` for command reference 4. **Run doctor regularly** - `gt doctor` catches problems early