name	beads
description	Use Beads to structure and execute work via epics, tasks, and dependencies
license	MIT
compatibility	opencode
metadata	[object Object]

Purpose

Beads (bd) is my external working memory - a temporal graph that survives session restarts.

I treat Beads as the single source of truth for:

what work exists
what blocks what
what is allowed to be worked on next
context and decisions (via descriptions and comments)

The plan lives as data, not prose. I query instead of remember.

⚠️ CRITICAL: Hierarchical IDs

I use hierarchical IDs to organize related work. The prefix is project-specific (e.g., opencode, myapp).

Independent work streams get their own top-level IDs:

opencode-a1b2      (Epic: User Management)
opencode-a1b2.1    (Task: Registration)
opencode-a1b2.1.1  (Subtask: Email validation)
opencode-a1b2.2    (Task: Profile editing)

opencode-c3d4      (Epic: TUI System)
opencode-c3d4.1    (Task: Layout engine)
opencode-c3d4.2    (Task: Key bindings)
opencode-c3d4.3    (Task: Theme support)

To get the ID of a top-level issue:

# When creating - capture the ID
bd create "User Management" -t epic -p 0 --silent   # outputs: opencode-a1b2
bd q "Quick task title"                              # outputs: opencode-x7y8

# In a new session - find existing issues
bd list -t epic                        # list all epics
bd list --title "User"                 # filter by title
bd search "User Management"            # search across title/description/ID
bd search "User" -t epic --json        # JSON output for parsing

When to use top-level epics/tasks:

Independent features (User Management vs TUI vs CLI)
Unrelated bug fixes
Work that doesn't belong under any existing task

When to use hierarchy (children):

Subtasks that break down a larger task
Work discovered while implementing a parent task
Features with multiple implementation steps

Concepts

Epics

High-level goals. I create them but never work on them directly. Always include a description with context, constraints, and acceptance criteria.

bd create "User Management" -t epic -p 0 -d "Complete user auth system with registration, login, and profile management. Must support OAuth providers."

Tasks

Concrete, executable units of work. Tasks are the only issues I actively work on.

Good tasks:

fit in one work session
produce a clear result
unblock other tasks

Top-level tasks (independent work):

bd create "CLI argument parsing" -p 1 -d "Parse --config, --verbose, --output flags using cobra"
bd create "TUI layout engine" -p 1 -d "Flexbox-style layout system for terminal UI components"
bd create "Config file loading" -p 2 -d "Load YAML/JSON config from ~/.config/app/"

Child tasks (related to a parent):

bd create "User registration flow" -p 1 --parent opencode-a3f8 -d "Email/password registration with validation"
bd create "Profile editing page" -p 1 --parent opencode-a3f8 -d "Allow users to update name, avatar, preferences"
bd create "Email validation" -p 2 --parent opencode-a3f8.1 -d "Send verification email with token, validate on click"

Using --parent automatically assigns hierarchical IDs (e.g., opencode-a3f8.1, opencode-a3f8.2).

Descriptions and Comments

Description (-d): Initial context when creating an issue.

bd create "User auth system" -t epic -p 0 -d "Implement full authentication flow including OAuth"

Comments: Ongoing updates, rules, progress notes. Use for:

Adding rules/constraints to epics
Progress updates
Implementation notes
Decisions made during work

bd comment opencode-a3f8 "Rules for this epic:
1. All tasks must have unit tests
2. No task should take more than 4 hours"

bd comment opencode-a3f8.1 "Decided to use JWT tokens instead of sessions"

bd comments opencode-a3f8           # list all comments
bd comments opencode-a3f8 --json    # JSON output (returns array)

bd show displays both description and comments.

Dependencies

Edges that define execution order. Four types:

Type	Meaning
blocks	Task A must complete before Task B starts
related	Tasks are conceptually linked
parent-child	Hierarchical organization (via `--parent`)
discovered-from	Task found while working on another

bd dep add opencode-a3f8.2 opencode-a3f8.1  # opencode-a3f8.2 blocked by opencode-a3f8.1

Note: Children already depend on their parent via hierarchy. Don't add explicit discovered-from to children - it will error.

Example graph:

opencode-a3f8 (Epic: User Management)
    ├── opencode-a3f8.1 (Task: Registration)
    │       ↓ blocks
    │   opencode-a3f8.2 (Task: Profile editing)
    │
    └── opencode-a3f8.1.1 (Subtask: Email validation)
            (inherits dependency from parent)

Graph-Based Structure

nodes = epics and tasks
edges = blocking relationships
order comes only from dependencies
priority affects choice among ready work, not execution order

If order matters, it must be encoded as a dependency.

Execution Loop

1. Start Session - Get Ready Work

bd ready --json

Returns tasks that are open and have no unmet dependencies. Only these are allowed to be worked on.

2. Claim a Task

⚠️ MANDATORY: Always read the task with bd show BEFORE starting work. Read the description AND all comments - they contain critical context, decisions, and constraints.

bd show opencode-a3f8.1                    # READ THIS FIRST - description + comments!
bd update opencode-a3f8.1 -s in_progress

3. Implement and Commit Code

Add comments to record important decisions and progress:

bd comment opencode-a3f8.1 "Using bcrypt for password hashing, cost factor 12"
bd comment opencode-a3f8.1 "Decided against OAuth in this task - will be separate"

4. Handle Discovered Work

If I discover new work while implementing, I file it immediately:

As a subtask (child inherits dependency automatically):

bd create "Fix token refresh bug" -p 1 --parent opencode-a3f8.1 -d "Token expires but refresh fails silently - found during registration testing"
# Creates opencode-a3f8.1.2 - automatically depends on parent

As a separate task with discovered-from link:

bd create "Unrelated auth bug found" -p 1 --deps "discovered-from:opencode-a3f8.1" -d "Session cookie not set correctly on Safari - unrelated to registration"
# For work that doesn't belong under the current task's hierarchy

Note: Children already inherit dependency from parent via hierarchy. Use discovered-from only for work that belongs elsewhere in the graph but was found while working on something.

The discovered-from edge preserves causal history - how work unfolded over time. This is critical for maintaining context across sessions.

5. Close the Task

bd close opencode-a3f8.1 -r "Completed registration flow"

Closing may unblock other tasks. Use --suggest-next to see newly unblocked work.

JSON Output

All --json outputs return arrays, even for single items:

bd show opencode-a3f8.1 --json      # returns [{ ... }] not { ... }
bd update opencode-a3f8.1 -s in_progress --json  # returns [{ ... }]
bd list --json
bd ready --json
bd search "query" --json
bd close opencode-a3f8.1 -r "done" --json

When parsing with jq, use .[0] to get the first element:

bd show opencode-a3f8.1 --json | jq '.[0].title'    # correct
bd show opencode-a3f8.1 --json | jq '.title'        # WRONG - will error

Batch Operations

When making multiple changes, batch within 30 seconds:

bd create "Fix validation bug" -p 1 --parent opencode-a3f8 -d "Form validation fails on special characters"
bd create "Add unit tests" -p 2 --parent opencode-a3f8 -d "Cover registration and login flows"
bd update opencode-a3f8.1 -s in_progress

Compaction

For large projects, summarize old closed issues:

bd compact --analyze --json   # Get candidates for review
bd compact --prune            # Remove expired tombstones

This implements "agentic memory decay" - replacing detailed content with concise summaries.

Rules

I only work on tasks, never epics
I use hierarchical IDs for related work, top-level IDs for independent work
I always respect dependencies
I never infer order from names or priority - order comes from edges
I always close tasks explicitly with -r reason
I NEVER drop discovered work - file immediately (as child or with discovered-from)
I always start sessions with bd ready --json
I ALWAYS run bd show and READ description + comments before starting any task
I always add descriptions (-d) when creating issues
I record decisions and context as comments during work

Beads is used to execute work deterministically, not to improvise.

Why This Matters

Beads solves session amnesia. Without it:

I forget discovered work after compaction/restart
I re-discover the same tasks repeatedly
I declare victory at phase 3-of-6 because that's all I can "see"

With Beads:

I query the plan instead of carrying it in context
discovered-from chains preserve how work unfolded over time
I can resume any session by running bd ready --json
Descriptions and comments preserve context and decisions for future sessions

⛔ NEVER DO THIS

NEVER run git push, git commit, or any git commands.

Git operations are handled by the human or by other tools. This skill is ONLY for managing work via bd commands. Do not touch git.

beads

Install Skill

SKILL.md