Beads Issue Tracking

---
name: beads-issue-tracking
description: Use this when working on tasks in this repo that require bd (beads) issue tracking, status updates, and the mandatory end-of-session push workflow.
---

# Beads (bd) issue tracking workflow

Use this skill whenever the user asks to start work on an issue, check work queue/status, add notes, mark blocked, close work, or “land the plane”.

## Commands (preferred)

- Find work: `bd ready`
- Current status: `bd status`
- View issue details: `bd show <id>` (or `bd show <id> --json`)
- Start work: `bd update <id> --status in_progress`
- Add a note: `bd update <id> --notes "..."`
- Blocked (with notes): `bd update <id> --status blocked --notes "..."`
- Close issue: `bd close <id> --reason "..."`
- Sync bd metadata: `bd sync`

## Hard rules (this repo)

- If code changes were made, do not end the session until **push succeeds**.
- Prefer the repository’s documented workflows in `_AGENTS.md`.

## “Landing the plane” checklist (must follow)

1. Run appropriate quality gates for the changed area (tests/build/lint if available).
2. Update bd issue status (close finished work, or set blocked with notes).
3. Follow the mandatory session close protocol (do not skip steps):
   - `git status` (confirm what changed)
   - `git add <files>` (stage code changes)
   - `bd sync` (commit beads changes)
   - `git commit -m "..."` (commit code)
   - `bd sync` (commit any new beads changes)
   - `git push` (must succeed)

## Guidance for agents

- If an issue id is not provided, ask for the bd issue id (one question max), or run `bd status` / `bd ready` to locate candidates.
- Prefer using editor tasks when available (e.g., VS Code tasks for bd commands).