···
1
+
# AI Agent Guidelines for Coves
3
+
## Issue Tracking with bd (beads)
5
+
**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
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
16
+
**Check for ready work:**
21
+
**Create new issues:**
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
27
+
**Claim and update:**
29
+
bd update bd-42 --status in_progress --json
30
+
bd update bd-42 --priority 1 --json
35
+
bd close bd-42 --reason "Completed" --json
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)
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)
54
+
### Workflow for AI Agents
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
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!
71
+
### MCP Server (Recommended)
73
+
If using Claude or MCP-compatible clients, install the beads MCP server:
76
+
pip install beads-mcp
79
+
Add to MCP config (e.g., `~/.config/claude/config.json`):
83
+
"command": "beads-mcp",
89
+
Then use `mcp__beads__*` functions instead of CLI commands.
91
+
### Managing AI-Generated Planning Documents
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
98
+
**Best Practice: Use a dedicated directory for these ephemeral files**
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
106
+
**Example .gitignore entry (optional):**
108
+
# AI planning documents (ephemeral)
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
119
+
### Important Rules
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
131
+
For more details, see the [beads repository](https://github.com/steveyegge/beads).
bretton.dev