bretton.dev
A community based topic aggregation platform built on atproto
docs: add AI agent guidelines for beads issue tracker
Add comprehensive documentation for AI agents on using bd (beads)
for issue tracking, including workflow, priorities, and best practices
for managing planning documents in history/ directory.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
+131
AGENTS.md
+131
AGENTS.md
···
1
+
# AI Agent Guidelines for Coves
2
+
3
+
## Issue Tracking with bd (beads)
4
+
5
+
**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
6
+
7
+
### Why bd?
8
+
9
+
- Dependency-aware: Track blockers and relationships between issues
10
+
- Git-friendly: Auto-syncs to JSONL for version control
11
+
- Agent-optimized: JSON output, ready work detection, discovered-from links
12
+
- Prevents duplicate tracking systems and confusion
13
+
14
+
### Quick Start
15
+
16
+
**Check for ready work:**
17
+
```bash
18
+
bd ready --json
19
+
```
20
+
21
+
**Create new issues:**
22
+
```bash
23
+
bd create "Issue title" -t bug|feature|task -p 0-4 --json
24
+
bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json
25
+
```
26
+
27
+
**Claim and update:**
28
+
```bash
29
+
bd update bd-42 --status in_progress --json
30
+
bd update bd-42 --priority 1 --json
31
+
```
32
+
33
+
**Complete work:**
34
+
```bash
35
+
bd close bd-42 --reason "Completed" --json
36
+
```
37
+
38
+
### Issue Types
39
+
40
+
- `bug` - Something broken
41
+
- `feature` - New functionality
42
+
- `task` - Work item (tests, docs, refactoring)
43
+
- `epic` - Large feature with subtasks
44
+
- `chore` - Maintenance (dependencies, tooling)
45
+
46
+
### Priorities
47
+
48
+
- `0` - Critical (security, data loss, broken builds)
49
+
- `1` - High (major features, important bugs)
50
+
- `2` - Medium (default, nice-to-have)
51
+
- `3` - Low (polish, optimization)
52
+
- `4` - Backlog (future ideas)
53
+
54
+
### Workflow for AI Agents
55
+
56
+
1. **Check ready work**: `bd ready` shows unblocked issues
57
+
2. **Claim your task**: `bd update <id> --status in_progress`
58
+
3. **Work on it**: Implement, test, document
59
+
4. **Discover new work?** Create linked issue:
60
+
- `bd create "Found bug" -p 1 --deps discovered-from:<parent-id>`
61
+
5. **Complete**: `bd close <id> --reason "Done"`
62
+
6. **Commit together**: Always commit the `.beads/issues.jsonl` file together with the code changes so issue state stays in sync with code state
63
+
64
+
### Auto-Sync
65
+
66
+
bd automatically syncs with git:
67
+
- Exports to `.beads/issues.jsonl` after changes (5s debounce)
68
+
- Imports from JSONL when newer (e.g., after `git pull`)
69
+
- No manual export/import needed!
70
+
71
+
### MCP Server (Recommended)
72
+
73
+
If using Claude or MCP-compatible clients, install the beads MCP server:
74
+
75
+
```bash
76
+
pip install beads-mcp
77
+
```
78
+
79
+
Add to MCP config (e.g., `~/.config/claude/config.json`):
80
+
```json
81
+
{
82
+
"beads": {
83
+
"command": "beads-mcp",
84
+
"args": []
85
+
}
86
+
}
87
+
```
88
+
89
+
Then use `mcp__beads__*` functions instead of CLI commands.
90
+
91
+
### Managing AI-Generated Planning Documents
92
+
93
+
AI assistants often create planning and design documents during development:
94
+
- PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md
95
+
- DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md
96
+
- TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files
97
+
98
+
**Best Practice: Use a dedicated directory for these ephemeral files**
99
+
100
+
**Recommended approach:**
101
+
- Create a `history/` directory in the project root
102
+
- Store ALL AI-generated planning/design docs in `history/`
103
+
- Keep the repository root clean and focused on permanent project files
104
+
- Only access `history/` when explicitly asked to review past planning
105
+
106
+
**Example .gitignore entry (optional):**
107
+
```
108
+
# AI planning documents (ephemeral)
109
+
history/
110
+
```
111
+
112
+
**Benefits:**
113
+
- ✅ Clean repository root
114
+
- ✅ Clear separation between ephemeral and permanent documentation
115
+
- ✅ Easy to exclude from version control if desired
116
+
- ✅ Preserves planning history for archeological research
117
+
- ✅ Reduces noise when browsing the project
118
+
119
+
### Important Rules
120
+
121
+
- ✅ Use bd for ALL task tracking
122
+
- ✅ Always use `--json` flag for programmatic use
123
+
- ✅ Link discovered work with `discovered-from` dependencies
124
+
- ✅ Check `bd ready` before asking "what should I work on?"
125
+
- ✅ Store AI planning docs in `history/` directory
126
+
- ❌ Do NOT create markdown TODO lists
127
+
- ❌ Do NOT use external issue trackers
128
+
- ❌ Do NOT duplicate tracking systems
129
+
- ❌ Do NOT clutter repo root with planning documents
130
+
131
+
For more details, see the [beads repository](https://github.com/steveyegge/beads).