AGENTS.md

1# Agent Instructions
2 
3This project uses **bd** (beads) for issue tracking. Run `bd onboard` to get started.
4 
5## Quick Reference
6 
7```bash
8bd ready              # Find available work
9bd show <id>          # View issue details
10bd update <id> --claim  # Claim work atomically
11bd close <id>         # Complete work
12bd sync               # Sync with git
13```
14 
15## Non-Interactive Shell Commands
16 
17**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts.
18 
19Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.
20 
21**Use these forms instead:**
22```bash
23# Force overwrite without prompting
24cp -f source dest           # NOT: cp source dest
25mv -f source dest           # NOT: mv source dest
26rm -f file                  # NOT: rm file
27 
28# For recursive operations
29rm -rf directory            # NOT: rm -r directory
30cp -rf source dest          # NOT: cp -r source dest
31```
32 
33**Other commands that may prompt:**
34- `scp` - use `-o BatchMode=yes` for non-interactive
35- `ssh` - use `-o BatchMode=yes` to fail instead of prompting
36- `apt-get` - use `-y` flag
37- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var
38 
39<!-- BEGIN BEADS INTEGRATION -->
40## Issue Tracking with bd (beads)
41 
42**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
43 
44### Why bd?
45 
46- Dependency-aware: Track blockers and relationships between issues
47- Version-controlled: Built on Dolt with cell-level merge
48- Agent-optimized: JSON output, ready work detection, discovered-from links
49- Prevents duplicate tracking systems and confusion
50 
51### Quick Start
52 
53**Check for ready work:**
54 
55```bash
56bd ready --json
57```
58 
59**Create new issues:**
60 
61```bash
62bd create &quot;Issue title&quot; --description=&quot;Detailed context&quot; -t bug|feature|task -p 0-4 --json
63bd create &quot;Issue title&quot; --description=&quot;What this issue is about&quot; -p 1 --deps discovered-from:bd-123 --json
64```
65 
66**Claim and update:**
67 
68```bash
69bd update &lt;id&gt; --claim --json
70bd update bd-42 --priority 1 --json
71```
72 
73**Complete work:**
74 
75```bash
76bd close bd-42 --reason &quot;Completed&quot; --json
77```
78 
79### Issue Types
80 
81- `bug` - Something broken
82- `feature` - New functionality
83- `task` - Work item (tests, docs, refactoring)
84- `epic` - Large feature with subtasks
85- `chore` - Maintenance (dependencies, tooling)
86 
87### Priorities
88 
89- `0` - Critical (security, data loss, broken builds)
90- `1` - High (major features, important bugs)
91- `2` - Medium (default, nice-to-have)
92- `3` - Low (polish, optimization)
93- `4` - Backlog (future ideas)
94 
95### Workflow for AI Agents
96 
971. **Check ready work**: `bd ready` shows unblocked issues
982. **Claim your task atomically**: `bd update <id> --claim`
993. **Work on it**: Implement, test, document
1004. **Discover new work?** Create linked issue:
101   - `bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>`
1025. **Complete**: `bd close <id> --reason "Done"`
103 
104### Auto-Sync
105 
106bd automatically syncs with git:
107 
108- Exports to `.beads/issues.jsonl` after changes (5s debounce)
109- Imports from JSONL when newer (e.g., after `git pull`)
110- No manual export/import needed!
111 
112### Important Rules
113 
114- ✅ Use bd for ALL task tracking
115- ✅ Always use `--json` flag for programmatic use
116- ✅ Link discovered work with `discovered-from` dependencies
117- ✅ Check `bd ready` before asking "what should I work on?"
118- ❌ Do NOT create markdown TODO lists
119- ❌ Do NOT use external issue trackers
120- ❌ Do NOT duplicate tracking systems
121 
122For more details, see README.md and docs/QUICKSTART.md.
123 
124## Landing the Plane (Session Completion)
125 
126**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
127 
128**MANDATORY WORKFLOW:**
129 
1301. **File issues for remaining work** - Create issues for anything that needs follow-up
1312. **Run quality gates** (if code changed) - Tests, linters, builds
1323. **Update issue status** - Close finished work, update in-progress items
1334. **PUSH TO REMOTE** - This is MANDATORY:
134```bash
135   git pull --rebase
136   bd sync
137   git push
138   git status  # MUST show "up to date with origin"
139```
1405. **Clean up** - Clear stashes, prune remote branches
1416. **Verify** - All changes committed AND pushed
1427. **Hand off** - Provide context for next session
143 
144**CRITICAL RULES:**
145- Work is NOT complete until `git push` succeeds
146- NEVER stop before pushing - that leaves work stranded locally
147- NEVER say "ready to push when you are" - YOU must push
148- If push fails, resolve and retry until it succeeds
149 
150<!-- END BEADS INTEGRATION -->
151