This Claude skill implements the 'bd' (beads) workflow, a powerful system for issue tracking and task management designed specifically for AI agents and developers. It provides a Git-friendly, dependency-aware framework that synchronizes task history directly within repositories, ensuring a single source of truth for project status, blockers, and planning without relying on external spreadsheets or fragmented markdown files.

When should I use bd-workflow?

bd-workflow is useful in the following scenarios: • Autonomous Agent Task Execution: Enabling AI agents to independently identify unblocked tasks using 'bd ready', claim work, and update statuses in real-time. • Git-Synced Issue Tracking: Maintaining a persistent and version-controlled history of bugs, features, and chores within the repository via .beads/issues.jsonl. • Complex Dependency Management: Visualizing and tracking blockers and 'discovered-from' links to manage project flow and prevent development bottlenecks. • Standardized Workflow Automation: Replacing ad-hoc TODO lists with machine-readable JSON outputs that can be easily parsed by CI/CD pipelines or other automation tools.

name	bd-workflow
description	How to use bd (beads) for issue tracking, ready work, status updates, and comments in this repo.

bd (beads) Workflow Guide

This document expands the abbreviated rules in AGENTS.md. Read this whenever you interact with task tracking, planning docs, or MCP helpers.

Why bd?

Dependency-aware: track blockers, dependents, and discovered-from links.
Git-friendly: bd auto-syncs to .beads/issues.jsonl, so repos capture task history.
Agent-optimized: machine-readable JSON output (--json) plus "ready" filtering.
Single source of truth: prevents duplicate trackers, markdown TODOs, or ad-hoc spreadsheets.

Quick Start Commands

bd ready --json -n 0                    # find unblocked work
bd create "Issue title" -t task -p 2 --json
bd update bd-42 --status in_progress --json
bd close bd-42 --reason "Completed" --json

Always run bd with --json. Pipe/parse as needed.

Issue Types & Priorities

Types: bug, feature, task, epic, chore.
Priorities: 0 (critical) through 4 (backlog). Respect existing priority unless the PM/user changes it.

Workflow for AI Agents

Check ready work with bd ready --json -n 0. Do this before asking what to work on.
Claim the task: bd update <id> --status in_progress --json (add notes if relevant).
Implement / test / document the change.
Discover new work? Create a linked issue (e.g., bd create "Fix follow-up" -p 1 --deps discovered-from:<parent> --json).
Complete the task via bd close <id> --reason "Completed" --json when the PR merges.
Commit .beads/issues.jsonl alongside code. Never leave tracker changes uncommitted.

Auto-Sync Behavior

bd exports to .beads/issues.jsonl automatically (5s debounce) after changes.
After git pull, bd imports newer JSONL back into the local state. No manual sync needed.

MCP Integration (Optional)

Install: pip install beads-mcp.
Add to ~/.config/claude/config.json:

{
  "beads": {
    "command": "beads-mcp",
    "args": []
  }
}

Use mcp__beads__* calls instead of the CLI if your client supports MCP.

Planning Document Hygiene

AI-generated planning/design docs should live under history/ (add it to .gitignore if desired). Keeping the repo root clean avoids confusing ephemeral plans with durable docs.

Important Rules (Do & Don't)

✅ Use bd for all task tracking.
✅ Include discovered-from dependencies to show provenance.
✅ Keep .beads/issues.jsonl in every relevant commit.
✅ Store planning docs in history/.
❌ No markdown TODO lists or alternative trackers.
❌ No forgetting --json.
❌ No cluttering the repo root with temporary planning files.

Need More Context?

See README.md / QUICKSTART.md for broader project background, but treat bd as the authoritative view of work.

bd-workflow

When & Why to Use This Skill

Use Cases