# Agent Instructions

## Plans

- Make the plan extremely concise. Sacrifice grammar for the sake of concision.
- At the end of each plan, give me a list of unresolved questions to answer, if any.

## Issue Tracking

This project uses **br** (beads_rust) for issue tracking and **bv** (beads_viewer) for triage/prioritization. Issues are stored in `.beads/` and tracked in git.

### Tool Roles

| Tool | Role | Key Commands |
|------|------|--------------|
| `br` | Issue management (CRUD) | `br ready`, `br show`, `br update`, `br close`, `br sync` |
| `bv` | Triage & prioritization | `bv --robot-triage` |

### Quick Reference

```bash
br ready              # Find available work
br show <id>          # View issue details
br update <id> --status in_progress  # Claim work
br close <id>         # Complete work
br sync               # Sync with git
```

### What to work on next?

```bash
bv --robot-triage     # AI-powered recommendation for next issue (preferred)
br ready              # Fallback: plain list of unblocked issues
```

> **Warning:** bare `bv` (without flags) launches an interactive TUI that blocks the session. Always use `bv --robot-triage` or other non-interactive flags in automated contexts.

### Key Concepts

- **Dependencies**: Issues can block other issues. `br ready` shows only unblocked work.
- **Priority**: P0=critical, P1=high, P2=medium, P3=low, P4=backlog (use numbers 0-4, not words)
- **Types**: task, bug, feature, epic, chore, docs, question
- **Blocking**: `br dep add <issue> <depends-on>` to add dependencies


### Creating issues

You might be tasked with creating a new issue or you discover new tasks by yourself. Use the `/create-single-issue` command accordingly the create a new issue.

## Main Workflow

### Work on issue

You are tasked by the operator to work on an issue.
It's either a specific issue (`/start-issue <id>`) or the *next* issue (`/start-next-issue`).
The command tells you to open the issue, enter plan mode and then implement the plan.
The command tells you explicitly *NOT* to: close the issue, commit or push anything (because this is subject to `/finish-issue`).

### Operator tests manually

After finishing the implementation the operator tests the solution.

### Finish issue

After testing you are tasked by the operator to finish the issue (`/finish-issue`).
You close the issue and create a commit.

## Release Workflow

Once in a while the operator uses these commands:

- `/tag-version` - you create a new version using the `git tag` mechanism
- `/update-changelog` - you update the CHANGELOG.md according to the changes of the last version