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

Gas Town Multi-Agent Communication

This workspace is part of a Gas Town multi-agent environment. You communicate with other agents using gt commands — never by printing text or using raw tmux.

Nudging Agents (Immediate Delivery)

gt nudge sends a message directly to another agent's active session:

gt nudge mayor "Status update: PR review complete"
gt nudge laneassist/crew/dom "Check your mail — PR ready for review"
gt nudge witness "Polecat health check needed"
gt nudge refinery "Merge queue has items"

Target formats:

• Role shortcuts: mayor, deacon, witness, refinery
• Full path: <rig>/crew/<name>, <rig>/polecats/<name>

Important: gt nudge is the ONLY way to send text to another agent's session. Never print "Hey @name" — the other agent cannot see your terminal output.

Sending Mail (Persistent Messages)

gt mail sends messages that persist across session restarts:

# Reading
gt mail inbox                    # List messages
gt mail read <id>                # Read a specific message

# Sending (use --stdin for multi-line content)
gt mail send mayor/ -s "Subject" -m "Short message"
gt mail send laneassist/crew/dom -s "PR Review" --stdin <<'BODY'
Multi-line message content here.
Details about the PR and what to look for.
BODY
gt mail send --human -s "Subject" -m "Message to overseer"

When to Use Which

Context Recovery

After compaction or new session, run gt prime to reload your full role context, identity, and any pending work.

gt prime              # Full context reload
gt hook               # Check for assigned work
gt mail inbox         # Check for messages

Beads Issue Tracker

This project uses bd (beads) for issue tracking. Run gt prime to see full workflow context and commands.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work
bd close <id>         # Complete work

Rules

• Use bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
• Run gt prime for detailed command reference and session close protocol
• Use bd remember for persistent knowledge — do NOT use MEMORY.md files

Session Completion

When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.

MANDATORY WORKFLOW:

1. File issues for remaining work - Create issues for anything that needs follow-up
2. Run quality gates (if code changed) - Tests, linters, builds
3. Update issue status - Close finished work, update in-progress items
4. PUSH TO REMOTE - This is MANDATORY:

   git pull --rebase
   bd dolt push
   git push
   git status  # MUST show "up to date with origin"

5. Clean up - Clear stashes, prune remote branches
6. Verify - All changes committed AND pushed
7. Hand off - Provide context for next session

CRITICAL RULES:

• Work is NOT complete until git push succeeds
• NEVER stop before pushing - that leaves work stranded locally
• NEVER say "ready to push when you are" - YOU must push
• If push fails, resolve and retry until it succeeds