johno/gastown
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: clarify Beads issue ID format in README (gt-uzx2c)

Browse Source 
Added "Issue IDs" section to Core Concepts explaining that Gas Town
uses Beads' auto-generated short IDs (e.g., gt-x7k2m) rather than
sequential numbers like GitHub issues.

Updated all example issue IDs throughout the README to use realistic
Beads-style IDs instead of confusing "issue-123" format.

Fixes: GitHub #309
This commit is contained in:
furiosa
2026-01-11 10:55:10 -05:00
committed by Boden Fuller
parent d126c967a0
commit ce9cd72c37
1 changed files with 28 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
README.md
View File

@@ -77,6 +77,27 @@ Work tracking units. Bundle multiple issues/tasks that get assigned to agents.
Git-backed issue tracking system that stores work state as structured data. Git-backed issue tracking system that stores work state as structured data.
### Issue IDs 🔢
Gas Town uses [Beads](https://github.com/steveyegge/beads) for issue tracking, which generates **short random IDs** - not sequential numbers like GitHub issues.
```
gt-x7k2m ← Gas Town issue (gt prefix)
bd-9np4q ← Beads issue (bd prefix)
myproj-abc3 ← Your project (custom prefix)
```
The prefix comes from your project's Beads configuration. Find yours with `bd config get prefix`.
**Common commands:**
```bash
bd list # List all issues
bd show gt-x7k2m # Show issue details
bd ready # Issues ready for work
```
> **Note:** These are Beads IDs, not GitHub issue numbers. GitHub issue #309 might have Beads ID `gt-uzx2c`.
> **New to Gas Town?** See the [Glossary](docs/glossary.md) for a complete guide to terminology and concepts. > **New to Gas Town?** See the [Glossary](docs/glossary.md) for a complete guide to terminology and concepts.
## Installation ## Installation
@@ -142,10 +163,10 @@ sequenceDiagram
gt mayor attach gt mayor attach
# 2. In Mayor session, create a convoy # 2. In Mayor session, create a convoy
gt convoy create "Feature X" issue-123 issue-456 --notify --human gt convoy create "Feature X" gt-x7k2m gt-9np4q --notify --human
# 3. Assign work to an agent # 3. Assign work to an agent
gt sling issue-123 myproject gt sling gt-x7k2m myproject
# 4. Track progress # 4. Track progress
gt convoy list gt convoy list
@@ -177,7 +198,7 @@ flowchart LR
gt mayor attach gt mayor attach
# In Mayor, create convoy and let it orchestrate # In Mayor, create convoy and let it orchestrate
gt convoy create "Auth System" issue-101 issue-102 --notify gt convoy create "Auth System" gt-a3k7x gt-b2m9y --notify
# Track progress # Track progress
gt convoy list gt convoy list
@@ -188,8 +209,8 @@ gt convoy list
Run individual runtime instances manually. Gas Town just tracks state. Run individual runtime instances manually. Gas Town just tracks state.
```bash ```bash
gt convoy create "Fix bugs" issue-123 # Create convoy (sling auto-creates if skipped) gt convoy create "Fix bugs" gt-f4n8p # Create convoy (sling auto-creates if skipped)
gt sling issue-123 myproject # Assign to worker gt sling gt-f4n8p myproject # Assign to worker
claude --resume # Agent reads mail, runs work (Claude) claude --resume # Agent reads mail, runs work (Claude)
# or: codex # Start Codex in the workspace # or: codex # Start Codex in the workspace
gt convoy list # Check progress gt convoy list # Check progress
@@ -264,10 +285,10 @@ bd mol pour release --var version=1.2.0
gt convoy create "Bug Fixes" --human gt convoy create "Bug Fixes" --human
# Add issues # Add issues
gt convoy add-issue bug-101 bug-102 gt convoy add-issue gt-c5p2q gt-d8r3s
# Assign to specific agents # Assign to specific agents
gt sling bug-101 myproject/my-agent gt sling gt-c5p2q myproject/my-agent
# Check status # Check status
gt convoy show gt convoy show