gastown: Instructions file for Codex

Agent Instructions

See CLAUDE.md for complete agent context and instructions.

This file exists for compatibility with tools that look for AGENTS.md.

Recovery: Run gt prime after compaction, clear, or new session

Full context is injected by gt prime at session start.

---

Beads Workflow Integration

This project uses beads for issue tracking. Issues live in .beads/ and are tracked in git.

Two CLIs: bd (issue CRUD) and bv (graph-aware triage, read-only).

bd: Issue Management

bd ready              # Unblocked issues ready to work
bd list --status=open # All open issues
bd show <id>          # Full details with dependencies
bd create --title="..." --type=task --priority=2
bd update <id> --status=in_progress
bd close <id>         # Mark complete
bd close <id1> <id2>  # Close multiple
bd dep add <a> <b>    # a depends on b
bd sync               # Sync with git

bv: Graph Analysis (read-only)

NEVER run bare bv — it launches interactive TUI. Always use --robot-* flags:

bv --robot-triage     # Ranked picks, quick wins, blockers, health
bv --robot-next       # Single top pick + claim command
bv --robot-plan       # Parallel execution tracks
bv --robot-alerts     # Stale issues, cascades, mismatches
bv --robot-insights   # Full graph metrics: PageRank, betweenness, cycles

Workflow

1. Start: bd ready (or bv --robot-triage for graph analysis)
2. Claim: bd update <id> --status=in_progress
3. Work: Implement the task
4. Complete: bd close <id>
5. Sync: bd sync at session end

Session Close Protocol

git status            # Check what changed
git add <files>       # Stage code changes
bd sync               # Commit beads changes
git commit -m "..."   # Commit code
bd sync               # Commit any new beads changes
git push              # Push to remote

Key Concepts

• Priority: P0=critical, P1=high, P2=medium, P3=low, P4=backlog (numbers only)
• Types: task, bug, feature, epic, question, docs
• Dependencies: bd ready shows only unblocked work