playbooks

home / skills / plurigrid / asi / beads-issue-tracker

beads-issue-tracker skill

/skills/beads-issue-tracker

This skill helps teams manage AI-driven work with a dependency-aware issue tracker, enabling ready work selection and automatic synchronization.

npx playbooks add skill plurigrid/asi --skill beads-issue-tracker

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.7 KB
---
name: beads-issue-tracker
description: |
  Guide for using Beads (bd), a dependency-aware issue tracker for AI agents. Issues chained together like beads.
license: MIT
metadata:
  author: Stakpak <[email protected]>
  version: 1.0.11
---

# Beads Issue Tracker (bd)

Issues chained together like beads. A lightweight issue tracker with first-class dependency support.

## Getting Started

```bash
bd init                      # Initialize bd in your project
bd init --prefix api         # Initialize with custom prefix (api-1, api-2)
```

## Creating Issues

```bash
bd create "Fix login bug"
bd create "Add auth" -p 0 -t feature
bd create "Write tests" -d "Unit tests for auth" --assignee alice
```

## Viewing Issues

```bash
bd list                      # List all issues
bd list --status open        # List by status
bd list --priority 0         # List by priority (0-4, 0=highest)
bd show bd-1                 # Show issue details
```

## Managing Dependencies

```bash
bd dep add bd-1 bd-2         # Add dependency (bd-2 blocks bd-1)
bd dep tree bd-1             # Visualize dependency tree
bd dep cycles                # Detect circular dependencies
```

**Dependency Types:**
- `blocks` - Task B must complete before task A
- `related` - Soft connection, doesn't block progress
- `parent-child` - Epic/subtask hierarchical relationship
- `discovered-from` - Auto-created when AI discovers related work

## Ready Work

```bash
bd ready                     # Show issues ready to work on
```

Ready = status is 'open' AND no blocking dependencies. Perfect for agents to claim next work!

## Updating Issues

```bash
bd update bd-1 --status in_progress
bd update bd-1 --priority 0
bd update bd-1 --assignee bob
```

## Closing Issues

```bash
bd close bd-1
bd close bd-2 bd-3 --reason "Fixed in PR #42"
```

## Database Location

bd automatically discovers your database:
1. `--db /path/to/db.db` flag
2. `$BEADS_DB` environment variable
3. `.beads/*.db` in current directory or ancestors
4. `~/.beads/default.db` as fallback

## Agent Integration

bd is designed for AI-supervised workflows:
- Agents create issues when discovering new work
- `bd ready` shows unblocked work ready to claim
- Use `--json` flags for programmatic parsing
- Dependencies prevent agents from duplicating effort

## Git Workflow (Auto-Sync)

bd automatically keeps git in sync:
- Export to JSONL after CRUD operations (5s debounce)
- Import from JSONL when newer than DB (after git pull)
- Works seamlessly across machines and team members

Disable with: `--no-auto-flush` or `--no-auto-import`

## References

- [GitHub Repository](https://github.com/steveyegge/beads)
- [Agent Instructions](https://github.com/steveyegge/beads/blob/main/AGENT_INSTRUCTIONS.md)

Overview

This skill guides using Beads (bd), a lightweight, dependency-aware issue tracker where issues chain together like beads. It focuses on workflows that expose unblocked work for AI agents and teams, with simple CLI commands for creating, linking, and managing issues. The guidance emphasizes dependency types, ready-state detection, and git-backed sync for multi-machine collaboration.

How this skill works

bd stores issues in a discovered or specified database and models explicit dependency relationships (blocks, related, parent-child, discovered-from). The CLI exposes commands to create, list, update, close, and visualize dependency trees, plus helpers to detect cycles and surface ready-to-work items. It also exports/imports JSONL for automatic git sync, and supports flags and environment variables to control database location and integration behavior.

When to use it

  • You need strict dependency tracking so agents or humans avoid duplicated or out-of-order work.
  • You want a minimal CLI issue tracker that integrates with AI agents and programmatic workflows.
  • You need to surface 'ready' tasks automatically (open + no blockers) for agent claiming.
  • You require visualizing or detecting circular dependencies before starting work.
  • You want git-backed synchronization across machines for a portable database.

Best practices

  • Model blocking relationships explicitly: use 'blocks' for hard sequencing and 'related' for soft links.
  • Use priorities (0 highest) and assignees to guide agent selection of ready tasks.
  • Keep agent-created issues concise and add context via descriptions to avoid redundant discoveries.
  • Rely on bd ready and --json output to programmatically feed agents or CI pipelines.
  • Disable auto-import/export during sensitive operations with --no-auto-flush or --no-auto-import.

Example use cases

  • An agent discovers a bug and creates a 'discovered-from' issue chain that spawns follow-up tasks.
  • A team lists open priority-0 issues and uses bd dep tree to resolve blocking order before work.
  • CI pipeline queries bd ready --json to auto-assign the next unblocked task to an agent.
  • Developers add dependency edges to prevent parallel work on tasks that must run sequentially.
  • Project leads detect dependency cycles with bd dep cycles and refactor epics into parent-child relations.

FAQ

How does bd determine which database file to use?

bd checks a --db flag first, then the BEADS_DB environment variable, then .beads/*.db in the current directory or ancestors, and finally falls back to ~/.beads/default.db.

What does 'ready' mean?

Ready means the issue is open and has no blocking dependencies, making it suitable for agents or team members to claim next.