A community based topic aggregation platform built on atproto
bretton.dev
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
18bd ready --json
19```
20
21**Create new issues:**
22```bash
23bd create "Issue title" -t bug|feature|task -p 0-4 --json
24bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json
25```
26
27**Claim and update:**
28```bash
29bd update bd-42 --status in_progress --json
30bd update bd-42 --priority 1 --json
31```
32
33**Complete work:**
34```bash
35bd 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
561. **Check ready work**: `bd ready` shows unblocked issues
572. **Claim your task**: `bd update <id> --status in_progress`
583. **Work on it**: Implement, test, document
594. **Discover new work?** Create linked issue:
60 - `bd create "Found bug" -p 1 --deps discovered-from:<parent-id>`
615. **Complete**: `bd close <id> --reason "Done"`
626. **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
66bd 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
73If using Claude or MCP-compatible clients, install the beads MCP server:
74
75```bash
76pip install beads-mcp
77```
78
79Add to MCP config (e.g., `~/.config/claude/config.json`):
80```json
81{
82 "beads": {
83 "command": "beads-mcp",
84 "args": []
85 }
86}
87```
88
89Then use `mcp__beads__*` functions instead of CLI commands.
90
91### Managing AI-Generated Planning Documents
92
93AI 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)
109history/
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
131For more details, see the [beads repository](https://github.com/steveyegge/beads).