beads-issue-tracking
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.
When & Why to Use This Skill
This Claude skill provides an automated interface for the Beads (bd) issue tracking system, streamlining task management, status updates, and repository synchronization. It enhances developer productivity and repository health by enforcing a standardized 'landing the plane' protocol, ensuring every session concludes with verified code changes and synchronized metadata.
Use Cases
- Locating and initiating work on prioritized issues by querying the 'bd' work queue and updating task statuses to 'in_progress'.
- Maintaining project transparency through real-time updates of issue notes and handling blocked tasks with detailed justifications directly within the agent workflow.
- Executing a mandatory end-of-session checklist that automates quality gates, metadata syncing, and verified git pushes to prevent broken builds or uncommitted changes.
| 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>(orbd 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)
- Run appropriate quality gates for the changed area (tests/build/lint if available).
- Update bd issue status (close finished work, or set blocked with notes).
- 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 readyto locate candidates. - Prefer using editor tasks when available (e.g., VS Code tasks for bd commands).