# Beads Issue Tracking Instructions

This project uses **Beads (bd)** for issue tracking. Use the bd CLI or MCP tools for all task management.

## Core Workflow Rules

1. **Track ALL work in bd** - Never use markdown TODOs or comment-based task lists
2. **Check ready work first** - Run `bd ready` to find unblocked issues
3. **Always include descriptions** - Provide meaningful context when creating issues
4. **Link discovered work** - Use `discovered-from` dependencies for issues found during work
5. **Sync at session end** - Run `bd dolt push` before ending your session

## Quick Command Reference

### Finding Work
```bash
bd ready              # Show unblocked issues ready for work
bd list --status open # List all open issues
bd show <id>          # View issue details
bd blocked            # Show blocked issues and their blockers
```

### Creating Issues
```bash
bd create "Title" --description="Details" -t bug|feature|task -p 0-4 --json
bd create "Found bug" --description="Details" --deps discovered-from:bd-42 --json
```

### Working on Issues
```bash
bd update <id> --claim               # Claim work atomically
bd update <id> --priority 1          # Change priority
bd close <id> --reason "Completed"   # Mark complete
```

### Dependencies
```bash
bd dep add <issue> <depends-on>      # Add dependency (issue depends on depends-on)
bd dep add <issue> <depends-on> --type=related  # Soft link
```

### Syncing
```bash
bd dolt push  # ALWAYS run at session end - commits and pushes changes
```

## Issue Types

- `bug` - Something broken that needs fixing
- `feature` - New functionality
- `task` - Work item (tests, docs, refactoring)
- `epic` - Large feature composed of multiple issues
- `chore` - Maintenance work (dependencies, tooling)

## Priorities

- `0` - Critical (security, data loss, broken builds)
- `1` - High (major features, important bugs)
- `2` - Medium (default, nice-to-have)
- `3` - Low (polish, optimization)
- `4` - Backlog (future ideas)

## MCP Tools Available

If the MCP server is configured, you can use these tools directly:
- `mcp_beads_ready` - Find ready tasks
- `mcp_beads_list` - List issues with filters
- `mcp_beads_show` - Show issue details
- `mcp_beads_create` - Create new issues
- `mcp_beads_update` - Update issue status/priority
- `mcp_beads_close` - Close completed issues
- `mcp_beads_dep` - Manage dependencies
- `mcp_beads_blocked` - Show blocked issues
- `mcp_beads_stats` - Get issue statistics

## Important Rules

- ✅ Use bd for ALL task tracking
- ✅ Always use `--json` flag for programmatic use
- ✅ Link discovered work with `discovered-from` dependencies
- ✅ Check `bd ready` before asking "what should I work on?"
- ✅ Run `bd dolt push` at end of session
- ❌ Do NOT create markdown TODO lists
- ❌ Do NOT use external issue trackers
- ❌ Do NOT duplicate tracking systems

For more details, run `bd --help` or see the project's AGENTS.md file.