# Issue tracker: Beads

Tickets and specs for this repo live in `.beads/`. Use the `bd` CLI for all operations. Commit `.beads/` when worktree-based automation needs to see the tracker state.

This is a seed template. When triage labels are configured, replace every `<mapped-...-label>` placeholder with the exact string from `docs/agents/triage-labels.md`. Without triage, remove the `needs-triage` label flag from general ticket creation and replace the two ready-role placeholders with the canonical `ready-for-agent` and `ready-for-human` strings.

## Conventions

- **Ticket IDs**: Beads IDs are strings such as `bd-a1b2`, never GitHub-style numeric issue references.
- **Create a ticket**: `bd create "Title" --body-file - -t task -p 2 --json`. When triage is configured, add `-l <mapped-needs-triage-label>`.
- **Create an AFK child ticket**: `bd create "Title" --body-file - --parent <parent-id> -t task -p 2 -l <mapped-ready-for-agent-label> --json`.
- **Create a HITL child ticket**: `bd create "Title" --body-file - --parent <parent-id> -t task -p 2 -l <mapped-ready-for-human-label> --json`.
- **Ticket type**: `-t, --type` accepts `bug|feature|task|epic|chore|decision`; default is `task`.
- **Priority**: `-p 2` is Beads' default medium priority. `0` / `P0` is highest; `4` / `P4` is lowest.
- **Labels**: `-l, --labels` accepts comma-separated labels.
- **Read a ticket**: `bd show <ID> --json` and `bd comments <ID> --json`.
- **List autonomous work**: `bd ready --label <mapped-ready-for-agent-label> --exclude-type epic --exclude-label wayfinder:map --json` returns unblocked AFK work. Never dispatch from raw `bd ready --json`: it can include HITL tickets and coordination epics.
- **Query children for QA**: `bd list --parent <parent-id> --all --json --limit 0` returns the full parent-scoped child set.
- **List open work**: `bd list --status open --json` returns open tickets, including blocked tickets; do not use it as an autonomous queue.
- **Add a blocker**: `bd dep add <blocked-id> <blocker-id> --type blocks`.
- **Comment**: `bd comments add <ID> "..." --json`; use `-f <file>` for multiline notes.
- **Apply or remove labels**: `bd label add <ID> <label>` / `bd label remove <ID> <label>`.
- **Claim**: `bd update <ID> --claim --json`.
- **Close**: `bd close <ID> --reason "..." --json`.

## When a skill says "publish to the issue tracker"

Create a Beads ticket, passing the Markdown body through stdin or a body file. Add the mapped `needs-triage` label only when triage is configured.

## When a skill says "fetch the relevant ticket"

Run `bd show <ID> --json` and `bd comments <ID> --json`.

## When the triage skill asks for incoming work

Include this section only when `triage` is installed. List open tickets, then inspect the relevant tickets and comments. Process unlabeled tickets, the mapped `needs-triage` queue, and answered `needs-info` tickets oldest first. Replace the prior triage-state label rather than accumulating conflicting state labels.

## When `/to-qa` needs completed child work

Fetch the full child set with `bd list --parent <parent-id> --all --json --limit 0`.

Include only child tickets whose stored status is `closed`. Exclude open, in-progress, blocked, deferred, or otherwise incomplete children and report them as warnings. Read each included child with `bd show <child-id> --json` and `bd comments <child-id> --json`. Do not mutate Beads tickets during `/to-qa`.

## Wayfinding operations

The **map** is a Beads epic and each investigation is a child ticket.

- **Map**: create an epic labelled `wayfinder:map`, with no ready-role label; its body holds Destination, Notes, Decisions so far, Not yet specified, and Out of scope.
- **Child ticket**: create it with `--parent <map-id>`, a `wayfinder:<type>` label, and the mapped mode label. AFK tickets get `<mapped-ready-for-agent-label>`; HITL tickets get `<mapped-ready-for-human-label>`.
- **Blocking**: `bd dep add <blocked-id> <blocker-id> --type blocks`.
- **AFK frontier**: `bd ready --parent <map-id> --label <mapped-ready-for-agent-label> --exclude-type epic --exclude-label wayfinder:map --unassigned --json`. Only this queue may be dispatched autonomously.
- **HITL frontier**: `bd list --parent <map-id> --status open --ready --label <mapped-ready-for-human-label> --no-assignee --json --limit 0`. Surface these tickets to the human; do not dispatch them autonomously.
- **Claim**: `bd update <id> --claim --json` as the session's first write.
- **Resolve**: post the answer, close the child, then add a one-line gist and child reference to the map's Decisions so far.