commit aeb4baa75f193c37f257b6abb54bb6ba80156112 · bretton.dev/coves

+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).