home / skills / michalvavra / agents / beads

beads skill

safe

/skills/beads

This skill lets you manage persistent, cross-session tasks with dependency graphs, keeping context after compaction and guiding blockers.

npx playbooks add skill michalvavra/agents --skill beads

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

Files (2)

SKILL.md

1.1 KB

---
name: beads
description: Persistent task memory using dependency graphs. For multi-session work that must survive compaction.
compatibility: Requires bd CLI v0.34.0+ and git repository.
---

# Beads

Graph-based task tracker that survives conversation compaction.

## When to Use

Use bd (not TodoWrite) when:
- Context needed across sessions or after compaction
- Tasks have blockers/dependencies

## Session Start

```bash
bd ready                              # Find unblocked tasks
bd show <id>                          # Get context
bd update <id> --status in_progress   # Start work
```

## Common Commands

```bash
bd create "Title" -p 1                # Create task (priority 0-4)
bd update <id> --notes "Progress"     # Add notes (survives compaction)
bd close <id> --reason "Done"         # Complete task
bd dep add <child> <parent>           # Add dependency
bd sync                               # Sync with git remote
```

## Notes Format

```
COMPLETED: Specific deliverables
IN PROGRESS: Current state + next step
BLOCKERS: What's preventing progress
```

---

Use `bd --help` or see [references/examples.md](references/examples.md) for all commands.

Overview

This skill provides a graph-based persistent task memory for multi-session AI coding workflows. It maintains tasks, notes, and dependencies so work survives conversation compaction and session restarts. It's designed for agents and humans who need durable task context and clear blockers across time.

How this skill works

The skill stores tasks as nodes in a dependency graph and preserves notes that survive compaction. Commands create, update, inspect, and close tasks; dependency edges express blockers and unblock logic. A simple CLI (bd) surfaces unblocked work, syncs state, and keeps progress and blockers explicit across sessions.

When to use it

When task context must persist across conversation compaction or session restarts
When tasks depend on other tasks and you need explicit dependency tracking
When you need a durable notes format for progress, blockers, and completion criteria
For multi-step projects where prioritization and unblocked work discovery speed up progress

Best practices

Use structured notes: COMPLETED, IN PROGRESS, BLOCKERS to keep entries consistent
Add dependencies immediately (bd dep add child parent) to prevent hidden blockers
Mark status changes (e.g., in_progress, closed) so agents can resume work reliably
Sync regularly (bd sync) to share state across collaborators and restore after compaction
Set priority when creating tasks to triage work (priority 0-4)

Example use cases

Agent picks the next unblocked task at session start (bd ready) and opens context (bd show <id>)
Persisting progress notes during long-running feature development so context survives compaction
Model-managed backlog where dependencies determine which tasks become available
Coordinating multiple contributors by syncing task graph and blocking reasons
Automated workflows that close tasks with explicit completion reasons after tests or deployments

FAQ

How do I find work that is ready now?

Run bd ready to list unblocked tasks prioritized for immediate work.

How should notes be formatted so they survive compaction?

Use the three-section template: COMPLETED, IN PROGRESS, BLOCKERS to keep notes clear and machine-friendly.