Beads

Beads - Persistent Task Memory for AI Agents

Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.

bd vs TodoWrite

Decision test: "Will I need this context in 2 weeks?" YES = bd, NO = TodoWrite.

See BOUNDARIES.md for detailed comparison.

Prerequisites

bd --version  # Requires v0.60.0+

• bd CLI installed and in PATH
• Git repository (optional — use BEADS_DIR + --stealth for git-free operation)
• Initialization: bd init run once (humans do this, not agents)

CLI Reference

Run `bd prime` for AI-optimized workflow context (auto-loaded by hooks). Run `bd <command> --help` for specific command usage.

Essential commands: bd ready, bd create, bd show, bd update, bd close, bd dolt push

Session Protocol

1. bd ready — Find unblocked work 2. bd show <id> — Get full context 3. bd update <id> --claim — Claim and start work atomically 4. Add notes as you work (critical for compaction survival) 5. bd close <id> --reason "..." — Complete task 6. bd dolt push — Push to Dolt remote (if configured)

Output

Append --json to any command for structured output. Use bd show <id> --long for extended metadata. Status icons: ○ open ◐ in_progress ● blocked ✓ closed ❄ deferred.

Error Handling

See TROUBLESHOOTING.md for full details.

Examples

Track a multi-session feature:

bd create "OAuth integration" -t epic -p 1 --json
bd create "Token storage" -t task --deps blocks:oauth-id --json
bd ready --json                    # Shows unblocked work
bd update <id> --claim --json      # Claim and start
bd close <id> --reason "Implemented with refresh tokens" --json

Recover after compaction: bd list --status in_progress --json then bd show <id> --long

Discover work mid-task: bd create "Found bug" -t bug -p 1 --deps discovered-from:<current-id> --json

Advanced Features

Resources

Validation

If bd --version reports newer than 0.60.0, this skill may be stale. Run bd prime for current CLI guidance — it auto-updates with each bd release and is the canonical source of truth (ADR-0001).

ADR-0001: Use bd prime as CLI Reference Source of Truth

Status

Accepted

Context

The beads skill maintained CLI reference documentation in multiple locations:

• SKILL.md inline (~2,000+ words of CLI reference)
• references/CLI_REFERENCE.md (~2,363 words)
• Scattered examples throughout resource files

This created:

• Duplication: Same commands documented 2-3 times
• Drift risk: Documentation can fall behind bd versions
• Token overhead: ~3,000+ tokens loaded even for simple operations

Meanwhile, bd provides bd prime which generates AI-optimized workflow context automatically.

Decision

Use bd prime as the single source of truth for CLI commands:

1. SKILL.md contains only value-add content (decision frameworks, cognitive patterns) 2. CLI reference points to bd prime (auto-loaded by hooks) and bd --help 3. Resources provide depth for advanced features (molecules, agents, gates)

Consequences

Positive

• Zero maintenance: CLI docs auto-update with bd versions
• DRY: Single source of truth
• Accurate: No version drift possible
• Lighter SKILL.md: ~500 words vs ~3,300

Negative

• Dependency on bd prime format: If output changes significantly, may need adaptation
• External tool requirement: Skill assumes bd is installed

Implementation

Files restructured:

• SKILL.md — Reduced from 3,306 to ~500 words
• references/ → resources/ — Directory rename for consistency
• New resources added: agents.md, async-gates.md, chemistry-patterns.md, worktrees.md
• Existing resources preserved with path updates

Related

• Claude Code skill progressive disclosure guidelines
• Similar pattern implemented in other Claude Code skill ecosystems

Date

2025-01-02

Beads Skill Maintenance Guide

Architecture Decisions

ADRs in adr/ document key decisions. These are NOT loaded during skill invocation—they're reference material for maintainers making changes.

Key Principle: DRY via bd prime

NEVER duplicate CLI documentation in SKILL.md or resources.

• bd prime outputs AI-optimized workflow context
• bd <command> --help provides specific usage
• Both auto-update with bd releases

SKILL.md should only contain:

• Decision frameworks (bd vs TodoWrite)
• Prerequisites (install verification)
• Resource index (progressive disclosure)
• Pointers to bd prime and --help

Keeping the Skill Updated

When bd releases new version:

1. Check for new features: bd --help for new commands 2. Update SKILL.md frontmatter: version: "X.Y.Z" 3. Add resources for conceptual features (agents, gates, chemistry patterns) 4. Don't add CLI reference — that's bd prime's job

What belongs in resources:

Resource update checklist:

[ ] Check if bd prime now covers this content
[ ] If yes, remove from resources (avoid duplication)
[ ] If no, update resource for new bd version
[ ] Update version compatibility in README.md

File Roles

Testing Changes

After skill updates:

# Verify SKILL.md is within token budget
wc -w plugins/beads/skills/beads/SKILL.md  # Target: 400-600 words

# Verify links resolve
# (Manual check: ensure all resource links in SKILL.md exist)

# Verify bd prime still works
bd prime | head -20

Attribution

Resources adapted from other sources should include attribution header:

# Resource Title

> Adapted from [source]

Append-only audit logging for agent interactions (prompts, responses, tool calls) in .beads/interactions.jsonl.

Each line is one event. Labeling is done by appending a new "label" event referencing a previous entry.

Usage

• Record an interaction:
• bd audit record --kind llm_call --model "claude-3-5-haiku" --prompt "..." --response "..."
• bd audit record --kind tool_call --tool-name "go test" --exit-code 1 --error "..." --issue-id bd-42

• Pipe JSON via stdin:
• cat event.json | bd audit record

• Label an entry:
• bd audit label int-a1b2 --label good --reason "Worked perfectly"
• bd audit label int-a1b2 --label bad --reason "Hallucinated a file path"

Notes

• Audit entries are append-only (no in-place edits).
• bd dolt push includes .beads/interactions.jsonl in the commit allowlist.

Show all issues that are blocked by dependencies.

Use bd blocked to see which issues have blockers preventing them from being worked on. This is the inverse of bd ready - it shows what's NOT ready.

Blocked issues have one or more dependencies with type "blocks" that are still open. Once all blocking dependencies are closed, the issue becomes ready and will appear in bd ready.

Useful for:

• Understanding why work is stuck
• Identifying critical path items
• Planning dependency resolution

Close a beads issue that's been completed.

If arguments are provided:

• $1: Issue ID
• $2+: Completion reason (optional)

If the issue ID is missing, ask for it. Optionally ask for a reason describing what was done.

Use the beads MCP close tool to close the issue. Show confirmation with the issue details.

After closing, suggest checking for:

• Dependent issues that might now be unblocked (use ready tool)
• New work discovered during this task (use create tool with discovered-from link)

View or add comments to a beads issue.

Comments are separate from issue properties (title, description, etc.) because they serve a different purpose: they're a discussion thread rather than singular editable fields. Use bd comments for threaded conversations and bd edit for core issue metadata.

View Comments

To view all comments on an issue:

• $1: Issue ID (e.g., bd-123)

Use the beads CLI bd comments <issue-id> to list all comments. Show them to the user with timestamps and authors.

Add Comment

To add a comment:

• $1: "add"
• $2: Issue ID
• $3: Comment text (or use -f flag for file input)

Use bd comments add <issue-id> "comment text" to add a comment. Confirm the comment was added successfully.

Comments are useful for:

• Progress updates during work
• Design notes or technical decisions
• Links to related resources
• Questions or blockers

Reduce database size by summarizing closed issues no longer actively referenced.

Compaction Tiers

• Tier 1: Semantic compression (30+ days closed, ~70% size reduction)
• Tier 2: Ultra compression (90+ days closed, ~95% size reduction)

Usage

• Preview candidates: bd admin compact --dry-run
• Compact all eligible: bd admin compact --all
• Compact specific issue: bd admin compact --id bd-42
• Force compact: bd admin compact --id bd-42 --force (bypass age checks)
• View statistics: bd admin compact --stats

Options

• --tier: Choose compaction tier (1 or 2, default: 1)
• --workers: Parallel workers (default: 5)
• --batch-size: Issues per batch (default: 10)

Important

This is permanent graceful decay - original content is discarded. Use bd restore <id> to view full history from git if needed.

Useful for long-running projects to keep database size manageable.

Create a new beads issue. If arguments are provided:

• $1: Issue title
• $2: Issue type (bug, feature, task, epic, chore, decision)
• $3: Priority (0-4, where 0=critical, 4=backlog)

If arguments are missing, ask the user for: 1. Issue title (required) 2. Issue type (default: task) 3. Priority (default: 2) 4. Description (optional)

Use the beads MCP create tool to create the issue. Show the created issue ID and details to the user.

Optionally ask if this issue should be linked to another issue (discovered-from, blocks, parent-child, related).

Record and track project decisions as beads issues with structured rationale, alternatives considered, and links to affected work.

Decisions use --type decision. The description field holds the structured decision record.

Record a Decision

When the user wants to record a decision (or you invoke bd decision record):

1. Gather the following (ask if not provided):

• Title: Short summary of what was decided (required)
• Rationale: Why this was chosen (required)
• Alternatives: What else was considered (optional but encouraged)
• Affects: Issue IDs this decision impacts (optional)
• Priority: How important (default P2)

2. Create the issue with structured description:

bd create "<title>" --type decision \
  --description "$(cat <<'EOF'
## Decision

<one-sentence summary of what was decided>

## Rationale

<why this was chosen>

## Alternatives Considered

- **<alt 1>**: <why rejected>
- **<alt 2>**: <why rejected>

## Affects

- <issue IDs or area descriptions>
EOF
)"

3. If --affects issue IDs were provided, link them:

bd dep add <decision-id> <affected-id> --type related

4. Show the created decision to the user.

List Decisions

bd list --type decision

To see all decisions including closed/superseded:

bd list --type decision --all

Show a Decision

bd show <decision-id>

Include comments for discussion history:

bd comments <decision-id>

Supersede a Decision

When a decision is replaced by a new one:

1. Record the new decision (as above) 2. Link the new decision to the old one:

   bd dep add <new-id> <old-id> --type related

3. Add a comment on the old decision:

   bd comments add <old-id> "Superseded by <new-id>: <brief reason>"

4. Close the old decision:

   bd close <old-id> --reason "Superseded by <new-id>"

Add Context to an Existing Decision

Use comments to append discussion, implementation notes, or revisit rationale:

bd comments add <decision-id> "Implementation note: ..."

Search Decisions

bd search "keyword" --type decision

Conventions

• Status: open = active decision, closed = superseded or reversed
• Description format: Use the structured template above for consistency
• Linking: Use related dependency type to connect decisions to affected issues
• Labels: Use labels for categorizing decisions (e.g., architecture, tooling, process)

Delete one or more issues and clean up all references.

Safety Features

• Preview mode: Default shows what would be deleted
• --force: Required to actually delete
• --dry-run: Preview collision detection
• Dependency checks: Fails if issue has dependents (unless --cascade or --force)

Batch Deletion

• Delete multiple: bd delete bd-1 bd-2 bd-3 --force
• Delete from file: bd delete --from-file deletions.txt --force

Dependency Handling

• Default: Fails if issue has dependents not in deletion set
• --cascade: Recursively delete all dependent issues
• --force: Delete and orphan dependents

What Gets Deleted

1. All dependency links (any type, both directions) 2. Text references updated to "[deleted:ID]" in connected issues 3. Issue removed from database

This operation cannot be undone. Use with caution!

Manage dependencies between beads issues.

Available Commands

• add: Add a dependency between issues
• $1: "add"
• $2: From issue ID
• $3: To issue ID
• $4: Dependency type (blocks, related, parent-child, discovered-from)

• remove: Remove a dependency
• $1: "remove"
• $2: From issue ID
• $3: To issue ID

• tree: Show dependency tree for an issue
• $1: "tree"
• $2: Issue ID
• Flags:
• --reverse: Show dependent tree (what was discovered from this) instead of dependency tree (what blocks this)
• --format mermaid: Output as Mermaid.js flowchart (renders in GitHub/GitLab markdown)
• --json: Output as JSON
• --max-depth N: Limit tree depth (default: 50)
• --show-all-paths: Show all paths (no deduplication for diamond dependencies)

• cycles: Detect dependency cycles

Dependency Types

• blocks: Hard blocker (from blocks to) - affects ready queue
• related: Soft relationship - for context only
• parent-child: Epic/subtask relationship
• discovered-from: Track issues found during work

Mermaid Format

The --format mermaid option outputs the dependency tree as a Mermaid.js flowchart:

Example:

bd dep tree bd-1 --format mermaid

Output can be embedded in markdown:

````markdown

flowchart TD
  bd-1["◧ bd-1: Main task"]
  bd-2["☑ bd-2: Subtask"]

  bd-1 --> bd-2

````

Status Indicators:

Each node includes a symbol indicator for quick visual status identification:

• ☐ Open - Not started yet (empty checkbox)
• ◧ In Progress - Currently being worked on (half-filled box)
• ⚠ Blocked - Waiting on something (warning sign)
• ☑ Closed - Completed! (checked checkbox)

The diagram colors are determined by your Mermaid theme (default, dark, forest, neutral, or base). Mermaid diagrams render natively in GitHub, GitLab, VSCode markdown preview, and can be imported to Miro.

Examples

• bd dep add bd-10 bd-20 --type blocks: bd-10 depends on bd-20 (bd-20 blocks bd-10)
• bd dep tree bd-20: Show what blocks bd-20 (dependency tree going UP)
• bd dep tree bd-1 --reverse: Show what was discovered from bd-1 (dependent tree going DOWN)
• bd dep tree bd-1 --reverse --max-depth 3: Show discovery tree with depth limit
• bd dep tree bd-20 --format mermaid > tree.md: Generate Mermaid diagram for documentation
• bd dep cycles: Check for circular dependencies

Reverse Mode: Discovery Trees

The --reverse flag inverts the tree direction to show dependents instead of dependencies:

Normal mode (bd dep tree ISSUE):

• Shows what blocks you (dependency tree)
• Answers: "What must I complete before I can work on this?"
• Tree flows UP toward prerequisites

Reverse mode (bd dep tree ISSUE --reverse):

• Shows what was discovered from you (dependent tree)
• Answers: "What work was discovered while working on this?"
• Tree flows DOWN from goal to discovered tasks
• Perfect for visualizing work breakdown and discovery chains

Use Cases:

• Document project evolution and how work expanded from initial goal
• Share "how we got here" context with stakeholders
• Visualize work breakdown structure from epics
• Track discovery chains (what led to what)
• Show yak shaving journeys in retrospectives

Manage epics (large features composed of multiple issues).

Available Commands

• status: Show epic completion status
• Shows progress for each epic
• Lists child issues and their states
• Calculates completion percentage

• close-eligible: Close epics where all children are complete
• Automatically closes epics when all child issues are done
• Useful for bulk epic cleanup

Epic Workflow

1. Create epic: bd create "Large Feature" -t epic -p 1 2. Link subtasks: bd dep add bd-20 bd-10 --type parent-child (task bd-20 is child of epic bd-10)

• Or at creation: bd create "Subtask title" -t task --parent bd-10

3. Track progress: bd epic status 4. Auto-close when done: bd epic close-eligible

Epics use parent-child dependencies to track subtasks.

Export all issues to JSON Lines format (one JSON object per line).

Usage

• To stdout: bd export
• To file: bd export -o issues.jsonl
• Filter by status: bd export --status open

Issues are sorted by ID for consistent diffs, making git diffs readable.

When to Use

Dolt is the primary storage backend, so manual export is rarely needed. Use bd export when you need:

• A JSONL snapshot of issue records
• Data migration to another system
• Sharing issues outside the Dolt workflow

bd export is not a full database backup. It does not capture Dolt branches, commit history, working-set state, or non-issue tables. Use bd backup for a restorable Dolt-native database backup.

bd import has been removed.

Migration

If you need to import issues from a JSONL file, use bd init with the --from-jsonl flag:

bd init <prefix> --from-jsonl issues.jsonl

Note

Dolt is the primary storage backend. Manual JSONL import is no longer supported as a standalone command.

Initialize beads issue tracking in the current directory.

If a prefix is provided as $1, use it as the issue prefix (e.g., "myproject" creates issues like myproject-1, myproject-2). If not provided, the default is the current directory name.

Use the beads MCP init tool with the prefix parameter (if provided) to set up a new beads database.

After initialization: 1. Show the database location 2. Show the issue prefix that will be used 3. Explain the basic workflow (or suggest running /beads:workflow) 4. Suggest creating the first issue with /beads:create

If beads is already initialized, inform the user and show project stats using the stats tool.

Manage labels on beads issues. Labels provide flexible cross-cutting metadata beyond structured fields (status, priority, type).

Available Commands

• add: Add a label to an issue
• $1: "add"
• $2: Issue ID
• $3: Label name

• remove: Remove a label from an issue
• $1: "remove"
• $2: Issue ID
• $3: Label name

• list: List labels on a specific issue
• $1: "list"
• $2: Issue ID

• list-all: Show all labels used across all issues

Common Label Use Cases

• Technical scope: backend, frontend, api, database
• Quality gates: needs-review, needs-tests, security-review
• Effort sizing: quick-win, complex, spike
• Context: technical-debt, documentation, performance

Use bd label add <issue-id> <label> to tag issues with contextual metadata.

List beads issues with optional filtering.

Basic Filters

• --status, -s: Filter by status (open, in_progress, blocked, closed)
• --priority, -p: Filter by priority (0-4: 0=critical, 1=high, 2=medium, 3=low, 4=backlog)
• --type, -t: Filter by type (bug, feature, task, epic, chore, decision)
• --assignee, -a: Filter by assignee
• --label, -l: Filter by labels (comma-separated, must have ALL labels)
• --label-any: Filter by labels (OR semantics, must have AT LEAST ONE)
• --title: Filter by title text (case-insensitive substring match)
• --limit, -n: Limit number of results

Advanced Filters

Pattern Matching

• --title-contains: Search for text in title (case-insensitive)
• --desc-contains: Search for text in description (case-insensitive)
• --notes-contains: Search for text in notes (case-insensitive)

Date Ranges

• --created-after: Issues created after date (YYYY-MM-DD or ISO 8601)
• --created-before: Issues created before date
• --updated-after: Issues updated after date
• --updated-before: Issues updated before date
• --closed-after: Issues closed after date
• --closed-before: Issues closed before date

Priority Range

• --priority-min: Minimum priority (inclusive)
• --priority-max: Maximum priority (inclusive)

Empty/Null Checks

• --empty-description: Find issues with no description
• --no-assignee: Find unassigned issues
• --no-labels: Find issues with no labels

Examples

Basic Usage

• bd list --status open --priority 1: High priority open issues
• bd list --type bug --assignee alice: Alice's assigned bugs
• bd list --label backend,needs-review: Backend issues needing review
• bd list --title "auth": Issues with "auth" in the title

Advanced Usage

• bd list --title-contains "auth" --status open: Search open issues for auth-related work
• bd list --priority-min 0 --priority-max 1: Critical and high priority issues only
• bd list --created-after 2025-01-01 --status open: Recent open issues
• bd list --empty-description --status open: Open issues missing descriptions
• bd list --no-assignee --priority 1: High priority unassigned work
• bd list --desc-contains "TODO" --notes-contains "review": Find items needing attention

Output Formats

• Default: Human-readable table
• --json: JSON format for scripting
• --format digraph: Graph format for golang.org/x/tools/cmd/digraph
• --format dot: Graphviz DOT format

Load AI-optimized workflow context for beads issue tracking.

Outputs essential beads workflow rules and command reference to help agents remember to use bd instead of markdown TODOs after context compaction.

bd prime
bd prime --memories-only

Use --memories-only when a hook should inject durable project memories without the full workflow guide.

Note: The bd quickstart command is deprecated. See the Quick Start on the documentation site, or the repo pointer docs/QUICKSTART.md.

The quickstart documentation covers:

• Getting started with bd
• Common workflow patterns
• Basic commands
• Dependency management
• Git integration

Use the beads MCP server to find tasks that are ready to work on (no blocking dependencies).

Call the ready tool to get a list of unblocked issues. Then present them to the user in a clear format showing:

• Issue ID
• Title
• Priority
• Issue type

If there are ready tasks, ask the user which one they'd like to work on. If they choose one, use the claim tool to start work atomically.

If there are no ready tasks, suggest checking blocked issues or creating a new issue with the create tool.

Rename the issue prefix for all issues in the database.

Updates all issue IDs and all text references across all fields.

Prefix Rules

• Max length: 8 characters
• Allowed: lowercase letters, numbers, hyphens
• Must start with a letter
• Must end with a hyphen (e.g., 'kw-', 'work-')

Usage

• Preview: bd rename-prefix kw- --dry-run
• Apply: bd rename-prefix kw-

Example: Rename from 'knowledge-work-' to 'kw-'

All dependencies and text references are automatically updated.

Reopen one or more closed issues.

Sets status to 'open' and clears the closed_at timestamp. Emits a Reopened event.

Usage

• Reopen single: bd reopen bd-42
• Reopen multiple: bd reopen bd-42 bd-43 bd-44
• With reason: bd reopen bd-42 --reason "Found regression"

More explicit than bd update --status open - specifically designed for reopening workflow.

Common reasons for reopening:

• Regression found
• Requirements changed
• Incomplete implementation
• New information discovered

Restore full history of a compacted issue from git version control.

When an issue is compacted, the git commit hash is saved. This command:

1. Reads the compacted_at_commit from the database 2. Retrieves the full issue from Dolt history at that point 3. Displays the full issue history (description, events, etc.) 4. Returns to the current state

Usage

bd restore bd-42

This is read-only - it does not modify the database or git state.

Useful for:

• Reviewing old issues after compaction
• Recovering forgotten context
• Audit trails
• Historical research

Requires git repository with issue history.

Search issues across title, description, and ID with a simple text query.

Note: The search command is optimized for quick text searches and uses less context than list when accessed via MCP. For advanced filtering options, use bd list.

Basic Usage

bd search "authentication bug"
bd search login --status open
bd search database --label backend
bd search "bd-5q"  # Search by partial issue ID

How It Works

The search command finds issues where your query appears in any of:

• Issue title
• Issue description
• Issue ID (supports partial matching)

Unlike bd list, which requires you to specify which field to search, bd search automatically searches all text fields, making it faster and more intuitive for exploratory searches.

Filters

• --status, -s: Filter by status (open, in_progress, blocked, closed)
• --assignee, -a: Filter by assignee
• --type, -t: Filter by type (bug, feature, task, epic, chore, decision)
• --label, -l: Filter by labels (must have ALL specified labels)
• --label-any: Filter by labels (must have AT LEAST ONE)
• --limit, -n: Limit number of results (default: 50)
• --sort: Sort by field: priority, created, updated, closed, status, id, title, type, assignee
• --reverse, -r: Reverse sort order
• --long: Show detailed multi-line output for each issue
• --json: Output results in JSON format

Examples

Basic Search

# Find all issues mentioning "auth" or "authentication"
bd search auth

# Search for performance issues
bd search performance --status open

# Find database-related bugs
bd search database --type bug

Filtered Search

# Find open backend issues about login
bd search login --status open --label backend

# Search Alice's tasks for "refactor"
bd search refactor --assignee alice --type task

# Find recent bugs (limited to 10 results)
bd search bug --status open --limit 10

Sorted Output

# Search bugs sorted by priority (P0 first)
bd search bug --sort priority

# Search features sorted by most recently updated
bd search feature --sort updated

# Search issues sorted by priority, lowest first
bd search refactor --sort priority --reverse

JSON Output

# Get JSON results for programmatic use
bd search "api error" --json

# Use with jq for advanced filtering
bd search memory --json | jq '.[] | select(.priority <= 1)'

Comparison with bd list

When to use `bd search`:

• You want to find issues quickly by keyword
• You're exploring the issue database
• You're using an LLM/MCP and want to minimize context usage

When to use `bd list`:

• You need advanced filters (date ranges, priority ranges, etc.)
• You want all results without a limit
• You need special output formats (digraph, dot)

Display detailed information about a beads issue.

If an issue ID is provided as $1, use it. Otherwise, ask the user for the issue ID.

Use the beads MCP show tool to retrieve issue details and present them clearly, including:

• Issue ID, title, and description
• Status, priority, and type
• Creation and update timestamps
• Dependencies (what this issue blocks or is blocked by)
• Related issues

If the issue has dependencies, offer to show the full dependency tree.

Display statistics about the current beads project.

Use the beads MCP stats tool to retrieve project metrics and present them clearly:

• Total issues by status (open, in_progress, blocked, closed)
• Issues by priority level
• Issues by type (bug, feature, task, epic, chore)
• Completion rate
• Recently updated issues

Optionally suggest actions based on the stats:

• High number of blocked issues? Run /beads:blocked to investigate
• No in_progress work? Run /beads:ready to find tasks
• Many open issues? Consider prioritizing with /beads:update

bd sync is deprecated and is now a no-op.

Use Dolt commands instead

• Push to remote: bd dolt push
• Pull from remote: bd dolt pull
• Commit pending changes: bd dolt commit
• Check connection: bd dolt show

Note

Most users should rely on the Dolt server's automatic sync (with dolt.auto-commit enabled) instead of running manual sync commands.

bd template

Manage issue templates for streamlined issue creation.

Synopsis

Templates provide pre-filled structures for common issue types, making it faster to create well-formed issues with consistent formatting.

bd template list
bd template show <template-name>
bd template create <template-name>

Description

Templates can be:

• Built-in: Provided by bd (epic, bug, feature)
• Custom: Stored in .beads/templates/ directory

Each template defines default values for:

• Description structure with placeholders
• Issue type (bug, feature, task, epic, chore)
• Priority (0-4)
• Labels
• Design notes structure
• Acceptance criteria structure

Commands

list

List all available templates (built-in and custom).

bd template list
bd template list --json

Examples:

$ bd template list
Built-in Templates:
  epic
    Type: epic, Priority: P1
    Labels: epic
  bug
    Type: bug, Priority: P1
    Labels: bug
  feature
    Type: feature, Priority: P2
    Labels: feature

show

Show detailed structure of a specific template.

bd template show <template-name>
bd template show <template-name> --json

Examples:

$ bd template show bug
Template: bug
Type: bug
Priority: P1
Labels: bug

Description:
## Summary

[Brief description of the bug]

## Steps to Reproduce
...

create

Create a custom template in .beads/templates/ directory.

bd template create <template-name>

This creates a YAML file with default structure that you can edit to customize.

Examples:

$ bd template create performance
✓ Created template: .beads/templates/performance.yaml
Edit the file to customize your template.

$ cat .beads/templates/performance.yaml
name: performance
description: |-
    [Describe the issue]
    
    ## Additional Context
    
    [Add relevant details]
type: task
priority: 2
labels: []
design: '[Design notes]'
acceptance_criteria: |-
    - [ ] Acceptance criterion 1
    - [ ] Acceptance criterion 2

# Edit the template to customize it
$ vim .beads/templates/performance.yaml

Using Templates with bd create

Use the --from-template flag to create issues from templates:

bd create --from-template <template-name> "Issue title"

Template values can be overridden with explicit flags:

# Use bug template but override priority
bd create --from-template bug "Login crashes on special chars" -p 0

# Use epic template but add extra labels
bd create --from-template epic "Q4 Infrastructure" -l infrastructure,ops

Examples:

# Create epic from template
$ bd create --from-template epic "Phase 3 Features"
✓ Created issue: bd-a3f8e9
  Title: Phase 3 Features
  Priority: P1
  Status: open

# Create bug report from template
$ bd create --from-template bug "Auth token validation fails"
✓ Created issue: bd-42bc7a
  Title: Auth token validation fails
  Priority: P1
  Status: open

# Use custom template
$ bd template create security-audit
$ bd create --from-template security-audit "Review authentication flow"

Template File Format

Templates are YAML files with the following structure:

name: template-name
description: |
  Multi-line description with placeholders
  
  ## Section heading
  
  [Placeholder text]

type: bug|feature|task|epic|chore
priority: 0-4
labels:
  - label1
  - label2

design: |
  Design notes structure

acceptance_criteria: |
  - [ ] Acceptance criterion 1
  - [ ] Acceptance criterion 2

Built-in Templates

epic

For large features composed of multiple issues.

Structure:

• Overview and scope
• Success criteria checklist
• Background and motivation
• In-scope / out-of-scope sections
• Architecture design notes
• Component breakdown

Defaults:

• Type: epic
• Priority: P1
• Labels: epic

bug

For bug reports with consistent structure.

Structure:

• Summary
• Steps to reproduce
• Expected vs actual behavior
• Environment details
• Root cause analysis (design)
• Proposed fix
• Impact assessment

Defaults:

• Type: bug
• Priority: P1
• Labels: bug

feature

For feature requests and enhancements.

Structure:

• Feature description
• Motivation and use cases
• Proposed solution
• Alternatives considered
• Technical design
• API changes
• Testing strategy

Defaults:

• Type: feature
• Priority: P2
• Labels: feature

Custom Templates

Custom templates override built-in templates with the same name. This allows you to customize built-in templates for your project.

Priority: 1. Custom templates in .beads/templates/ 2. Built-in templates

Example - Override bug template:

# Create custom bug template
$ bd template create bug

# Edit to add project-specific fields
$ cat > .beads/templates/bug.yaml << 'EOF'
name: bug
description: |
  ## Bug Report
  
  **Severity:** [critical|high|medium|low]
  **Component:** [auth|api|frontend|backend]
  
  ## Description
  [Describe the bug]
  
  ## Reproduction
  1. Step 1
  2. Step 2
  
  ## Impact
  [Who is affected? How many users?]

type: bug
priority: 0
labels:
  - bug
  - needs-triage

design: |
  ## Investigation Notes
  [Technical details]

acceptance_criteria: |
  - [ ] Bug fixed and verified
  - [ ] Tests added
  - [ ] Monitoring added
EOF

# Now 'bd create --from-template bug' uses your custom template

JSON Output

All template commands support --json flag for programmatic use:

$ bd template list --json
[
  {
    "name": "epic",
    "description": "## Overview...",
    "type": "epic",
    "priority": 1,
    "labels": ["epic"],
    "design": "## Architecture...",
    "acceptance_criteria": "- [ ] All child issues..."
  }
]

$ bd template show bug --json
{
  "name": "bug",
  "description": "## Summary...",
  "type": "bug",
  "priority": 1,
  "labels": ["bug"],
  "design": "## Root Cause...",
  "acceptance_criteria": "- [ ] Bug no longer..."
}

Best Practices

1. Use templates for consistency: Establish team conventions for common issue types 2. Customize built-ins: Override built-in templates to match your workflow 3. Version control templates: Commit .beads/templates/ to share across team 4. Keep templates focused: Create specific templates (e.g., performance, security-audit) rather than generic ones 5. Use placeholders: Mark sections requiring input with [brackets] or TODO 6. Include checklists: Use - [ ] for actionable items in description and acceptance criteria

See Also

• bd create - Create issues
• bd list - List issues
• README - Main documentation

Update a beads issue.

If arguments are provided:

• $1: Issue ID
• $2: New status (open, in_progress, blocked, closed)

If arguments are missing, ask the user for: 1. Issue ID 2. What to update (status, priority, assignee, title, description) 3. New value

Use the beads MCP update tool to apply the changes. Show the updated issue to confirm the change.

Note: Comments are managed separately with bd comments add. The update command is for singular, versioned properties (title, status, priority, etc.), while comments form a discussion thread that's appended to, not updated.

Common workflows:

• Start work: bd update <id> --claim (atomic claim + in_progress)
• Mark blocked: Update status to blocked
• Reprioritize: Update priority (0-4)

Check the installed versions of beads components and verify compatibility.

Note: The MCP server automatically checks bd CLI version >= 0.9.0 on startup. This command provides detailed version info and update instructions.

Use the beads MCP tools to: 1. Run bd version via bash to get the CLI version 2. Check the plugin version (0.9.2) 3. Compare versions and report any mismatches

Display:

• bd CLI version (from bd version)
• Plugin version (0.9.2)
• MCP server version (0.9.2)
• MCP server status (from stats tool or connection test)
• Compatibility status (✓ compatible or ⚠️ update needed)

If versions are mismatched, provide instructions:

• Update bd CLI: curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
• Update plugin: /plugin update beads
• Restart Claude Code after updating

Suggest checking for updates if the user is on an older version.

Display the beads workflow for AI agents and developers.

Beads Workflow

Beads is an issue tracker designed for AI-supervised coding workflows. Here's how to use it effectively:

1. Find Ready Work

Use /beads:ready or the ready MCP tool to see tasks with no blockers.

2. Claim Your Task

Claim the issue atomically (assignee + in_progress in one step):

• Via command: /beads:update <id> --claim
• Via MCP tool: claim with issue_id: "<id>"

3. Work on It

Implement, test, and document the feature or fix.

4. Discover New Work

As you work, you'll often find bugs, TODOs, or related work:

• Create issues: /beads:create or create MCP tool
• Link them: Use dep MCP tool with type: "discovered-from"
• This maintains context and work history

5. Complete the Task

Close the issue when done:

• Via command: /beads:close <id> "Completed: <summary>"
• Via MCP tool: close with reason

6. Check What's Unblocked

After closing, check if other work became ready:

• Use /beads:ready to see newly unblocked tasks
• Start the cycle again

Tips

• Priority levels: 0=critical, 1=high, 2=medium, 3=low, 4=backlog
• Issue types: bug, feature, task, epic, chore
• Dependencies: Use blocks for hard dependencies, related for soft links
• Auto-sync: Changes are stored in Dolt and synced via bd dolt push / bd dolt pull

Available Commands

• /beads:ready - Find unblocked work
• /beads:create - Create new issue
• /beads:show - Show issue details
• /beads:update - Update issue
• /beads:close - Close issue
• /beads:workflow - Show this guide (you are here!)

MCP Tools Available

Use these via the beads MCP server:

• ready, list, show, create, claim, update, close
• dep (manage dependencies), blocked, stats
• init (initialize bd in a project)

For more details, see the beads README at: https://github.com/gastownhall/beads

Beads Skill for Claude Code

A comprehensive skill for using beads (bd) issue tracking with Claude Code.

What This Skill Does

This skill teaches Claude Code how to use bd effectively for:

• Multi-session work tracking - Persistent memory across conversation compactions
• Dependency management - Graph-based issue relationships
• Session handoff - Writing notes that survive context resets
• Molecules and wisps (v0.34.0+) - Reusable work templates and ephemeral workflows

Installation

Copy the beads/ directory to your Claude Code skills location:

# Global installation
cp -r beads ~/.claude/skills/

# Or project-local
cp -r beads .claude/skills/

When Claude Uses This Skill

The skill activates when conversations involve:

• "multi-session", "complex dependencies", "resume after weeks"
• "project memory", "persistent context", "side quest tracking"
• Work that spans multiple days or compaction cycles
• Tasks too complex for simple TodoWrite lists

File Structure

beads/
├── SKILL.md                 # Main skill file (Claude reads this first)
├── CLAUDE.md                # Maintenance guide for updating the skill
├── README.md                # This file (for humans)
├── adr/                     # Architectural Decision Records
│   └── 0001-bd-prime-as-source-of-truth.md
└── resources/               # Detailed documentation (loaded on demand)
    ├── BOUNDARIES.md        # When to use bd vs TodoWrite
    ├── CLI_REFERENCE.md     # Live CLI reference pointers
    ├── DEPENDENCIES.md      # Dependency semantics (A blocks B vs B blocks A)
    ├── INTEGRATION_PATTERNS.md # TodoWrite and other tool integration
    ├── ISSUE_CREATION.md    # When and how to create issues
    ├── MOLECULES.md         # Protos, mols, wisps (v0.34.0+)
    ├── PATTERNS.md          # Common usage patterns
    ├── RESUMABILITY.md      # Writing notes for post-compaction recovery
    ├── STATIC_DATA.md       # Using bd for reference databases
    ├── TROUBLESHOOTING.md   # Common issues and fixes
    ├── WORKFLOWS.md         # Step-by-step workflow guides
    ├── AGENTS.md            # Agent bead tracking (v0.40+)
    ├── ASYNC_GATES.md       # Human-in-the-loop gates
    ├── CHEMISTRY_PATTERNS.md # Mol vs Wisp decision tree
    └── WORKTREES.md         # Parallel development patterns

Key Concepts

bd vs TodoWrite

The Dependency Direction Trap

bd dep add A B means "A depends on B" (B must complete before A can start).

# Want: "Setup must complete before Implementation"
bd dep add implementation setup  # ✓ CORRECT
# NOT: bd dep add setup implementation  # ✗ WRONG

Surviving Compaction

When Claude's context gets compacted, conversation history is lost but bd state survives. Write notes as if explaining to a future Claude with zero context:

bd update issue-123 --notes "COMPLETED: JWT auth with RS256
KEY DECISION: RS256 over HS256 for key rotation
IN PROGRESS: Password reset flow
NEXT: Implement rate limiting"

Requirements

• bd CLI installed (brew install beads)
• A git repository (bd requires git for sync)
• Initialized database (bd init in project root)

Version Compatibility

Contributing

This skill is maintained at github.com/gastownhall/beads in the plugins/beads/skills/beads/ directory.

Issues and PRs welcome for:

• Documentation improvements
• New workflow patterns
• Bug fixes in examples
• Additional troubleshooting scenarios

License

MIT (same as beads)

Agent Beads

Adapted from ACF beads skill

v0.40+: First-class support for agent tracking via type=agent beads.

When to Use Agent Beads

Bead Types

Other types (task, bug, feature, epic) remain unchanged.

State Machine

Agent beads track state for coordination:

idle → spawning → running/working → done → idle
                       ↓
                    stuck → (needs intervention)

Key states: idle, spawning, running, working, stuck, done, stopped, dead

The dead state is set by Witness (monitoring system) via heartbeat timeout—agents don't set this themselves.

Slot Architecture

Slots are named references from agent beads to other beads:

Why slots? They enforce constraints (one work item at a time) and enable queries like "what is agent X working on?" or "which agent has this work?"

Monitoring Integration

Agent beads enable:

• Witness System: Monitors agent health via heartbeats
• State Coordination: ZFC-compliant state machine for multi-agent systems
• Work Attribution: Track which agent owns which work

CLI Reference

Run bd agent --help for state/heartbeat/show commands. Run bd slot --help for set/clear/show commands. Run bd create --help for --type=agent and --type=role options.

Async Gates for Workflow Coordination

Adapted from ACF beads skill

bd gate provides async coordination primitives for cross-session and external-condition workflows. Gates are wisps (ephemeral issues) that block until a condition is met.

---

Gate Types

---

Creating Gates

# Human approval gate
bd gate create --await human:deploy-approval \
  --title "Approve production deploy" \
  --timeout 4h

# CI gate (GitHub Actions)
bd gate create --await gh:run:123456789 \
  --title "Wait for CI" \
  --timeout 30m

# PR merge gate
bd gate create --await gh:pr:42 \
  --title "Wait for PR approval" \
  --timeout 24h

# Timer gate (deployment propagation)
bd gate create --await timer:15m \
  --title "Wait for deployment propagation"

Required options:

• --await <spec> — Gate condition (see types above)
• --timeout <duration> — Recommended: prevents forever-open gates

Optional:

• --title <text> — Human-readable description
• --notify <recipients> — Email/beads addresses to notify

---

Monitoring Gates

bd gate list              # All open gates
bd gate list --all        # Include closed
bd gate show <gate-id>    # Details for specific gate
bd gate eval              # Auto-close elapsed/completed gates
bd gate eval --dry-run    # Preview what would close

Auto-close behavior (bd gate eval):

• timer:* — Closes when duration elapsed
• gh:run:* — Checks GitHub API, closes on success/failure
• gh:pr:* — Checks GitHub API, closes on merge/close
• human:* — Requires explicit bd gate approve

---

Closing Gates

# Human gates require explicit approval
bd gate approve <gate-id>
bd gate approve <gate-id> --comment "Reviewed and approved by Steve"

# Manual close (any gate)
bd gate close <gate-id>
bd gate close <gate-id> --reason "No longer needed"

# Auto-close via evaluation
bd gate eval

---

Best Practices

1. Always set timeouts: Prevents forever-open gates

   bd gate create --await human:... --timeout 24h

2. Clear titles: Title should indicate what's being gated

   --title "Approve Phase 2: Core Implementation"

3. Eval periodically: Run at session start to close elapsed gates

   bd gate eval

4. Clean up obsolete gates: Close gates that are no longer needed

   bd gate close <id> --reason "superseded by new approach"

5. Check before creating: Avoid duplicate gates

   bd gate list | grep "spec-myfeature"

---

Gates vs Issues

Gates are designed to be temporary coordination primitives—they exist only until their condition is satisfied.

---

Troubleshooting

Gate won't close

# Check gate details
bd gate show <gate-id>

# For gh:run gates, verify the run exists
gh run view <run-id>

# Force close if stuck
bd gate close <gate-id> --reason "manual override"

Can't find gate ID

# List all gates (including closed)
bd gate list --all

# Search by title pattern
bd gate list | grep "Phase 2"

CI run ID detection fails

# Check GitHub CLI auth
gh auth status

# List runs manually
gh run list --branch <branch>

# Use specific workflow
gh run list --workflow ci.yml --branch <branch>

Boundaries: When to Use bd vs TodoWrite

This reference provides detailed decision criteria for choosing between bd issue tracking and TodoWrite for task management.

Contents

• The Core Question
• Decision Matrix
• Use bd for: Multi-Session Work, Complex Dependencies, Knowledge Work, Side Quests, Project Memory
• Use TodoWrite for: Single-Session Tasks, Linear Execution, Immediate Context, Simple Tracking
• Detailed Comparison
• Integration Patterns
• Pattern 1: bd as Strategic, TodoWrite as Tactical
• Pattern 2: TodoWrite as Working Copy of bd
• Pattern 3: Transition Mid-Session
• Real-World Examples
• Strategic Document Development, Simple Feature Implementation, Bug Investigation, Refactoring with Dependencies
• Common Mistakes
• Using TodoWrite for multi-session work, using bd for simple tasks, not transitioning when complexity emerges, creating too many bd issues, never using bd
• The Transition Point
• Summary Heuristics

The Core Question

"Could I resume this work after 2 weeks away?"

• If bd would help you resume → use bd
• If markdown skim would suffice → TodoWrite is fine

This heuristic captures the essential difference: bd provides structured context that persists across long gaps, while TodoWrite excels at immediate session tracking.

Decision Matrix

Use bd for:

Multi-Session Work

Work spanning multiple compaction cycles or days where context needs to persist.

Examples:

• Strategic document development requiring research across multiple sessions
• Feature implementation split across several coding sessions
• Bug investigation requiring experimentation over time
• Architecture design evolving through multiple iterations

Why bd wins: Issues capture context that survives compaction. Return weeks later and see full history, design decisions, and current status.

Complex Dependencies

Work with blockers, prerequisites, or hierarchical structure.

Examples:

• OAuth integration requiring database setup, endpoint creation, and frontend changes
• Research project with multiple parallel investigation threads
• Refactoring with dependencies between different code areas
• Migration requiring sequential steps in specific order

Why bd wins: Dependency graph shows what's blocking what. bd ready automatically surfaces unblocked work. No manual tracking required.

Knowledge Work

Tasks with fuzzy boundaries, exploration, or strategic thinking.

Examples:

• Architecture decision requiring research into frameworks and trade-offs
• API design requiring research into multiple options
• Performance optimization requiring measurement and experimentation
• Documentation requiring understanding system architecture

Why bd wins: design and acceptance_criteria fields capture evolving understanding. Issues can be refined as exploration reveals more information.

Side Quests

Exploratory work that might pause the main task.

Examples:

• During feature work, discover a better pattern worth exploring
• While debugging, notice related architectural issue
• During code review, identify potential improvement
• While writing tests, find edge case requiring research

Why bd wins: Create issue with discovered-from dependency, pause main work safely. Context preserved for both tracks. Resume either one later.

Project Memory

Need to resume work after significant time with full context.

Examples:

• Open source contributions across months
• Part-time projects with irregular schedule
• Complex features split across sprints
• Research projects with long investigation periods

Why bd wins: Dolt-backed database persists indefinitely. All context, decisions, and history available on resume. No relying on conversation scrollback or markdown files.

---

Use TodoWrite for:

Single-Session Tasks

Work that completes within current conversation.

Examples:

• Implementing a single function based on clear spec
• Fixing a bug with known root cause
• Adding unit tests for existing code
• Updating documentation for recent changes

Why TodoWrite wins: Simple checklist is perfect for linear execution. No need for persistence or dependencies. Clear completion within session.

Linear Execution

Straightforward step-by-step tasks with no branching.

Examples:

• Database migration with clear sequence
• Deployment checklist
• Code style cleanup across files
• Dependency updates following upgrade guide

Why TodoWrite wins: Steps are predetermined and sequential. No discovery, no blockers, no side quests. Just execute top to bottom.

Immediate Context

All information already in conversation.

Examples:

• User provides complete spec and asks for implementation
• Bug report with reproduction steps and fix approach
• Refactoring request with clear before/after vision
• Config changes based on user preferences

Why TodoWrite wins: No external context to track. Everything needed is in current conversation. TodoWrite provides user visibility, nothing more needed.

Simple Tracking

Just need a checklist to show progress to user.

Examples:

• Breaking down implementation into visible steps
• Showing validation workflow progress
• Demonstrating systematic approach
• Providing reassurance work is proceeding

Why TodoWrite wins: User wants to see thinking and progress. TodoWrite is visible in conversation. bd is invisible background structure.

---

Detailed Comparison

Integration Patterns

bd and TodoWrite can coexist effectively in a session. Use both strategically.

Pattern 1: bd as Strategic, TodoWrite as Tactical

Setup:

• bd tracks high-level issues and dependencies
• TodoWrite tracks current session's execution steps

Example:

bd issue: "Implement user authentication" (epic)
  ├─ Child issue: "Create login endpoint"
  ├─ Child issue: "Add JWT token validation"  ← Currently working on this
  └─ Child issue: "Implement logout"

TodoWrite (for JWT validation):
- [ ] Install JWT library
- [ ] Create token validation middleware
- [ ] Add tests for token expiry
- [ ] Update API documentation

When to use:

• Complex features with clear implementation steps
• User wants to see current progress but larger context exists
• Multi-session work currently in single-session execution phase

Pattern 2: TodoWrite as Working Copy of bd

Setup:

• Start with bd issue containing full context
• Create TodoWrite checklist from bd issue's acceptance criteria
• Update bd as TodoWrite items complete

Example:

Session start:
- Check bd: "issue-auth-42: Add JWT token validation" is ready
- Extract acceptance criteria into TodoWrite
- Mark bd issue as in_progress
- Work through TodoWrite items
- Update bd design notes as you learn
- When TodoWrite completes, close bd issue

When to use:

• bd issue is ready but execution is straightforward
• User wants visible progress tracking
• Need structured approach to larger issue

Pattern 3: Transition Mid-Session

From TodoWrite to bd:

Recognize mid-execution that work is more complex than anticipated.

Trigger signals:

• Discovering blockers or dependencies
• Realizing work won't complete this session
• Finding side quests or related issues
• Needing to pause and resume later

How to transition:

1. Create bd issue with current TodoWrite content
2. Note: "Discovered this is multi-session work during implementation"
3. Add dependencies as discovered
4. Keep TodoWrite for current session
5. Update bd issue before session ends
6. Next session: resume from bd, create new TodoWrite if needed

From bd to TodoWrite:

Rare, but happens when bd issue turns out simpler than expected.

Trigger signals:

• All context already clear
• No dependencies discovered
• Can complete within session
• User wants execution visibility

How to transition:

1. Keep bd issue for historical record
2. Create TodoWrite from issue description
3. Execute via TodoWrite
4. Close bd issue when done
5. Note: "Completed in single session, simpler than expected"

Real-World Examples

Example 1: Database Migration Planning

Scenario: Planning migration from MySQL to PostgreSQL for production application.

Why bd:

• Multi-session work across days/weeks
• Fuzzy boundaries - scope emerges through investigation
• Side quests - discover schema incompatibilities requiring refactoring
• Dependencies - can't migrate data until schema validated
• Project memory - need to resume after interruptions

bd structure:

db-epic: "Migrate production database to PostgreSQL"
  ├─ db-1: "Audit current MySQL schema and queries"
  ├─ db-2: "Research PostgreSQL equivalents for MySQL features" (blocks schema design)
  ├─ db-3: "Design PostgreSQL schema with type mappings"
  └─ db-4: "Create migration scripts and test data integrity" (blocked by db-3)

TodoWrite role: None initially. Might use TodoWrite for single-session testing sprints once migration scripts ready.

Example 2: Simple Feature Implementation

Scenario: Add logging to existing endpoint based on clear specification.

Why TodoWrite:

• Single session work
• Linear execution - add import, call logger, add test
• All context in user message
• Completes within conversation

TodoWrite:

- [ ] Import logging library
- [ ] Add log statements to endpoint
- [ ] Add test for log output
- [ ] Run tests

bd role: None. Overkill for straightforward task.

Example 3: Bug Investigation

Initial assessment: Seems simple, try TodoWrite first.

TodoWrite:

- [ ] Reproduce bug
- [ ] Identify root cause
- [ ] Implement fix
- [ ] Add regression test

What actually happens: Reproducing bug reveals it's intermittent. Root cause investigation shows multiple potential issues. Needs time to investigate.

Transition to bd:

Create bd issue: "Fix intermittent auth failure in production"
  - Description: Initially seemed simple but reproduction shows complex race condition
  - Design: Three potential causes identified, need to test each
  - Created issues for each hypothesis with discovered-from dependency

Pause for day, resume next session from bd context

Example 4: Refactoring with Dependencies

Scenario: Extract common validation logic from three controllers.

Why bd:

• Dependencies - must extract before modifying callers
• Multi-file changes need coordination
• Potential side quest - might discover better pattern during extraction
• Need to track which controllers updated

bd structure:

refactor-1: "Create shared validation module"
  → blocks refactor-2, refactor-3, refactor-4

refactor-2: "Update auth controller to use shared validation"
refactor-3: "Update user controller to use shared validation"
refactor-4: "Update payment controller to use shared validation"

TodoWrite role: Could use TodoWrite for individual controller updates as implementing.

Why this works: bd ensures you don't forget to update a controller. bd ready shows next available work. Dependencies prevent starting controller update before extraction complete.

Common Mistakes

Mistake 1: Using TodoWrite for Multi-Session Work

What happens:

• Next session, forget what was done
• Scroll conversation history to reconstruct
• Lose design decisions made during implementation
• Start over or duplicate work

Solution: Create bd issue instead. Persist context across sessions.

Mistake 2: Using bd for Simple Linear Tasks

What happens:

• Overhead of creating issue not justified
• User can't see progress in conversation
• Extra tool use for no benefit

Solution: Use TodoWrite. It's designed for exactly this case.

Mistake 3: Not Transitioning When Complexity Emerges

What happens:

• Start with TodoWrite for "simple" task
• Discover blockers and dependencies mid-way
• Keep using TodoWrite despite poor fit
• Lose context when conversation ends

Solution: Transition to bd when complexity signal appears. Not too late mid-session.

Mistake 4: Creating Too Many bd Issues

What happens:

• Every tiny task gets an issue
• Database cluttered with trivial items
• Hard to find meaningful work in bd ready

Solution: Reserve bd for work that actually benefits from persistence. Use "2 week test" - would bd help resume after 2 weeks? If no, skip it.

Mistake 5: Never Using bd Because TodoWrite is Familiar

What happens:

• Multi-session projects become markdown swamps
• Lose track of dependencies and blockers
• Can't resume work effectively
• Rotten half-implemented plans

Solution: Force yourself to use bd for next multi-session project. Experience the difference in organization and resumability.

Mistake 6: Always Asking Before Creating Issues (or Never Asking)

When to create directly (no user question needed):

• Bug reports: Clear scope, specific problem ("Found: auth doesn't check profile permissions")
• Research tasks: Investigative work ("Research workaround for Slides export")
• Technical TODOs: Discovered during implementation ("Add validation to form handler")
• Side quest capture: Discoveries that need tracking ("Issue: MCP can't read Shared Drive files")

Why create directly: Asking slows discovery capture. User expects proactive issue creation for clear-cut problems.

When to ask first (get user input):

• Strategic work: Fuzzy boundaries, multiple valid approaches ("Should we implement X or Y pattern?")
• Potential duplicates: Might overlap with existing work
• Large epics: Multiple approaches, unclear scope ("Plan migration strategy")
• Major scope changes: Changing direction of existing issue

Why ask: Ensures alignment on fuzzy work, prevents duplicate effort, clarifies scope before investment.

Rule of thumb: If you can write a clear, specific issue title and description in one sentence, create directly. If you need user input to clarify the work, ask first.

Examples:

• ✅ Create directly: "workspace MCP: Google Doc → .docx export fails with UTF-8 encoding error"
• ✅ Create directly: "Research: Workarounds for reading Google Slides from Shared Drives"
• ❓ Ask first: "Should we refactor the auth system now or later?" (strategic decision)
• ❓ Ask first: "I found several data validation issues, should I file them all?" (potential overwhelming)

The Transition Point

Most work starts with an implicit mental model:

"This looks straightforward" → TodoWrite

As work progresses:

✅ Stays straightforward → Continue with TodoWrite, complete in session

⚠️ Complexity emerges → Transition to bd, preserve context

The skill is recognizing the transition point:

Transition signals:

• "This is taking longer than expected"
• "I've discovered a blocker"
• "This needs more research"
• "I should pause this and investigate X first"
• "The user might not be available to continue today"
• "I found three related issues while working on this"

When you notice these signals: Create bd issue, preserve context, work from structured foundation.

Summary Heuristics

Quick decision guides:

Time horizon:

• Same session → TodoWrite
• Multiple sessions → bd

Dependency structure:

• Linear steps → TodoWrite
• Blockers/prerequisites → bd

Scope clarity:

• Well-defined → TodoWrite
• Exploratory → bd

Context complexity:

• Conversation has everything → TodoWrite
• External context needed → bd

User interaction:

• User watching progress → TodoWrite visible in chat
• Background work → bd invisible structure

Resume difficulty:

• Easy from markdown → TodoWrite
• Need structured history → bd

When in doubt: Use the 2-week test. If you'd struggle to resume this work after 2 weeks without bd, use bd.

Chemistry Patterns

Adapted from ACF beads skill

Beads uses a chemistry metaphor for work templates. This guide covers when and how to use each phase.

Phase Transitions

┌─────────────────────────────────────────────────────────────┐
│                    PROTO (Solid)                            │
│              Frozen template, reusable pattern              │
│                    .beads/ with template label              │
└─────────────────────────┬───────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          │               │               │
          ▼               │               ▼
┌─────────────────┐       │       ┌─────────────────┐
│   MOL (Liquid)  │       │       │  WISP (Vapor)   │
│   bd pour       │       │       │  bd wisp create │
│                 │       │       │                 │
│  Persistent     │       │       │  Ephemeral      │
│  .beads/        │       │       │  .beads-wisp/   │
│  Git synced     │       │       │  Gitignored     │
└────────┬────────┘       │       └────────┬────────┘
         │                │                │
         │                │        ┌───────┴───────┐
         │                │        │               │
         ▼                │        ▼               ▼
   ┌──────────┐           │   ┌─────────┐    ┌─────────┐
   │  CLOSE   │           │   │ SQUASH  │    │  BURN   │
   │ normally │           │   │ → digest│    │ → gone  │
   └──────────┘           │   └─────────┘    └─────────┘
                          │
                          ▼
                  ┌───────────────┐
                  │   DISTILL     │
                  │ Extract proto │
                  │ from ad-hoc   │
                  │ epic          │
                  └───────────────┘

Decision Tree: Mol vs Wisp

Will this work be referenced later?
│
├─ YES → Does it need audit trail / git history?
│        │
│        ├─ YES → MOL (bd pour)
│        │        Examples: Features, bugs, specs
│        │
│        └─ NO  → Could go either way
│                 Consider: Will someone else see this?
│                 │
│                 ├─ YES → MOL
│                 └─ NO  → WISP (then squash if valuable)
│
└─ NO  → WISP (bd wisp create)
         Examples: Grooming, health checks, scratch work
         End state: burn (no value) or squash (capture learnings)

Quick Reference

Common Patterns

Pattern 1: Grooming Wisp

Use for periodic backlog maintenance.

# Start grooming
bd wisp create grooming --var date="2025-01-02"

# Work through checklist (stale, duplicates, verification)
# Track findings in wisp notes

# End: capture summary
bd mol squash <wisp-id>  # Creates digest: "Closed 3, added 5 relationships"

Why wisp? Grooming is operational—you don't need permanent issues for "reviewed stale items."

Pattern 2: Code Review Wisp

Use for PR review checklists.

# Start review
bd wisp create pr-review --var pr="123" --var repo="myproject"

# Track review findings (security, performance, style)
# Each finding is a child issue in the wisp

# End: promote real issues, discard noise
bd mol squash <wisp-id>  # Creates permanent issues for real findings

Why wisp? Review checklists are ephemeral. Only actual findings become permanent issues.

Pattern 3: Research Spike Wisp

Use for time-boxed exploration.

# Start spike (2 hour timebox)
bd wisp create spike --var topic="GraphQL pagination"

# Explore, take notes in wisp issues
# Track sources, findings, dead ends

# End: decide outcome
bd mol squash <wisp-id>  # If valuable → creates research summary issue
# OR
bd mol burn <wisp-id>    # If dead end → no trace

Why wisp? Research might lead nowhere. Don't pollute the database with abandoned explorations.

Commands Reference

Creating Work

# Persistent mol (solid → liquid)
bd pour <proto>                    # Synced to git
bd pour <proto> --var key=value

# Ephemeral wisp (solid → vapor)
bd wisp create <proto>             # Not synced
bd wisp create <proto> --var key=value

Ending Work

# Mol: close normally
bd close <mol-id>

# Wisp: squash (condense to digest)
bd mol squash <wisp-id>            # Creates permanent digest issue

# Wisp: burn (evaporate, no trace)
bd mol burn <wisp-id>              # Deletes with no record

Managing

# List wisps
bd wisp list

# Garbage collect orphaned wisps
bd wisp gc
bd wisp gc --closed --force          # Purge all closed wisps

# View proto/mol structure
bd mol show <id>

# List available protos
bd mol catalog

Storage Locations

Anti-Patterns

Related Resources

• MOLECULES.md — Proto definitions
• WORKFLOWS.md — General beads workflows

CLI Reference

This skill does not bundle a copied CLI command reference. The command surface is generated from the installed bd binary and would drift if duplicated here.

Use these live sources instead:

• bd prime for AI-oriented workflow context and session rules
• bd <command> --help for command-specific usage
• bd help --all for the complete local CLI reference
• docs/CLI_REFERENCE.md in the beads repository for the generated Markdown reference
• <https://gastownhall.github.io/beads/cli-reference/> for the published generated reference

Maintainers: regenerate repository CLI docs with ./scripts/generate-cli-docs.sh. Do not paste generated command output into this skill resource.

Dependency Types Guide

Deep dive into bd's four dependency types: blocks, related, parent-child, and discovered-from.

Contents

• Overview - Four types at a glance, which affect bd ready?
• blocks - Hard Blocker
• When to Use - Prerequisites, sequential steps, build order
• When NOT to Use - Soft preferences, parallel work
• Examples - API development, migrations, library dependencies
• Creating blocks Dependencies
• Common Patterns - Build foundation first, migration sequences, testing gates
• Automatic Unblocking
• related - Soft Link
• When to Use - Context, related features, parallel work
• When NOT to Use
• Examples - Feature context, research links, parallel development
• Creating related Dependencies
• Common Patterns - Context clusters, research threads, feature families
• parent-child - Hierarchical
• When to Use - Epics/subtasks, phases
• When NOT to Use
• Examples - Epic with subtasks, phased projects
• Creating parent-child Dependencies
• Combining with blocks
• Common Patterns - Epic decomposition, nested hierarchies
• discovered-from - Provenance
• When to Use - Side quests, research findings
• Why This Matters
• Examples - Bug discovered during feature work, research branches
• Creating discovered-from Dependencies
• Common Patterns - Discovery during implementation, research expansion
• Combining with blocks
• Decision Guide
• Decision Tree
• Quick Reference by Situation
• Common Mistakes
• Using blocks for preferences, using discovered-from for planning, not using dependencies, over-using blocks, wrong direction
• Advanced Patterns
• Diamond dependencies, optional dependencies, discovery cascade, epic with phases
• Visualization
• Summary

Overview

bd supports four dependency types that serve different purposes in organizing and tracking work:

Key insight: Only blocks dependencies affect what work is ready. The other three provide structure and context.

---

blocks - Hard Blocker

Semantics: Issue A blocks issue B. B cannot start until A is complete.

Effect: Issue B disappears from bd ready until issue A is closed.

When to Use

Use blocks when work literally cannot proceed:

• Prerequisites: Database schema must exist before endpoints can use it
• Sequential steps: Migration step 1 must complete before step 2
• Build order: Foundation must be done before building on top
• Technical blockers: Library must be installed before code can use it

When NOT to Use

Don't use blocks for:

• Soft preferences: "Should do X before Y but could do either"
• Parallel work: Both can proceed independently
• Information links: Just want to note relationship
• Recommendations: "Would be better if done in this order"

Use related instead for soft connections.

Examples

Example 1: API Development

db-schema-1: "Create users table"
  blocks
api-endpoint-2: "Add GET /users endpoint"

Why: Endpoint literally needs table to exist
Effect: api-endpoint-2 won't show in bd ready until db-schema-1 closed

Example 2: Migration Sequence

migrate-1: "Backup production database"
  blocks
migrate-2: "Run schema migration"
  blocks
migrate-3: "Verify data integrity"

Why: Each step must complete before next can safely proceed
Effect: bd ready shows only migrate-1; closing it reveals migrate-2, etc.

Example 3: Library Installation

setup-1: "Install JWT library"
  blocks
auth-2: "Implement JWT validation"

Why: Code won't compile/run without library
Effect: Can't start auth-2 until setup-1 complete

Creating blocks Dependencies

bd dep add blocked-issue prerequisite-issue
# or explicitly:
bd dep add blocked-issue prerequisite-issue --type blocks

Direction matters: from_id depends on to_id. Think: "dependent depends on prerequisite".

Common Patterns

Pattern: Build Foundation First

foundation-1: "Set up authentication system"
  blocks all of:
    - feature-2: "Add user profiles"
    - feature-3: "Add admin panel"
    - feature-4: "Add API access"

One foundational issue blocks multiple dependent features.

Pattern: Sequential Pipeline

step-1 blocks step-2 blocks step-3 blocks step-4

Linear chain where each step depends on previous.
bd ready shows only current step.

Pattern: Parallel Then Merge

research-1: "Investigate option A"
research-2: "Investigate option B"
research-3: "Investigate option C"
All three block:
  decision-4: "Choose approach based on research"

Multiple parallel tasks must complete before next step.

Automatic Unblocking

When you close an issue that's blocking others:

1. Close db-schema-1
2. bd automatically updates: api-endpoint-2 is now ready
3. bd ready shows api-endpoint-2
4. No manual unblocking needed

This is why blocks is powerful - bd maintains ready state automatically.

---

related - Soft Link

Semantics: Issues are related but neither blocks the other.

Effect: No impact on bd ready. Pure informational link.

When to Use

Use related for context and discoverability:

• Similar work: "These tackle the same problem from different angles"
• Shared context: "Working on one provides insight for the other"
• Alternative approaches: "These are different ways to solve X"
• Complementary features: "These work well together but aren't required"

When NOT to Use

Don't use related if:

• One actually blocks the other → use blocks
• One discovered the other → use discovered-from
• One is parent of the other → use parent-child

Examples

Example 1: Related Refactoring

refactor-1: "Extract validation logic"
  related to
refactor-2: "Extract error handling logic"

Why: Both are refactoring efforts, similar patterns, but independent
Effect: None on ready state; just notes the relationship

Example 2: Documentation and Code

feature-1: "Add OAuth login"
  related to
docs-2: "Document OAuth setup"

Why: Docs and feature go together, but can be done in any order
Effect: Can work on either whenever; just notes they're connected

Example 3: Alternative Approaches

perf-1: "Investigate Redis caching"
  related to
perf-2: "Investigate CDN caching"

Why: Both address performance, different approaches, explore both
Effect: Both show in bd ready; choosing one doesn't block the other

Creating related Dependencies

bd dep add issue-1 issue-2 --type related

Direction doesn't matter for related - it's a symmetric link.

Common Patterns

Pattern: Cluster Related Work

api-redesign related to:
  - api-docs-update
  - api-client-update
  - api-tests-update
  - api-versioning

Group of issues all related to API work.
Use related to show they're part of same initiative.

Pattern: Cross-Cutting Concerns

security-audit related to:
  - auth-module
  - api-endpoints
  - database-access
  - frontend-forms

Security audit touches multiple areas.
Related links show what areas it covers.

---

parent-child - Hierarchical

Semantics: Issue A is parent of issue B. Typically A is an epic, B is a subtask.

Effect: No impact on bd ready. Creates hierarchical structure.

When to Use

Use parent-child for breaking down large work:

• Epics and subtasks: Big feature split into smaller pieces
• Hierarchical organization: Logical grouping of related tasks
• Progress tracking: See completion of children relative to parent
• Work breakdown structure: Decompose complex work

When NOT to Use

Don't use parent-child if:

• Siblings need ordering → add blocks between children
• Relationship is equality → use related
• Just discovered one from the other → use discovered-from

Examples

Example 1: Feature Epic

oauth-epic: "Implement OAuth integration" (epic)
  parent of:
    - oauth-1: "Set up OAuth credentials" (task)
    - oauth-2: "Implement authorization flow" (task)
    - oauth-3: "Add token refresh" (task)
    - oauth-4: "Create login UI" (task)

Why: Epic decomposed into implementable tasks
Effect: Hierarchical structure; all show in bd ready (unless blocked)

Example 2: Research with Findings

research-epic: "Investigate caching strategies" (epic)
  parent of:
    - research-1: "Redis evaluation"
    - research-2: "Memcached evaluation"
    - research-3: "CDN evaluation"
    - decision-4: "Choose caching approach"

Why: Research project with multiple investigation threads
Effect: Can track progress across all investigations

Creating parent-child Dependencies

bd dep add child-task-id parent-epic-id --type parent-child

Direction matters: The child depends on the parent. Think: "child depends on parent" or "task is part of epic".

Combining with blocks

Parent-child gives structure; blocks gives ordering:

auth-epic (parent of all)
  ├─ auth-1: "Install library"
  ├─ auth-2: "Create middleware" (blocked by auth-1)
  ├─ auth-3: "Add endpoints" (blocked by auth-2)
  └─ auth-4: "Add tests" (blocked by auth-3)

parent-child: Shows these are all part of auth epic
blocks: Shows they must be done in order

Common Patterns

Pattern: Epic with Independent Subtasks

Epic with no ordering between children:
All children show in bd ready immediately.
Work on any child in any order.
Close the epic explicitly once all children complete and the parent outcome is done.

Pattern: Epic with Sequential Subtasks

Epic with blocks dependencies between children:
bd ready shows only first child.
Closing each child unblocks next.
Epic provides structure, blocks provides order.

Pattern: Nested Epics

major-epic
  ├─ sub-epic-1
  │   ├─ task-1a
  │   └─ task-1b
  └─ sub-epic-2
      ├─ task-2a
      └─ task-2b

Multiple levels of hierarchy for complex projects.

---

discovered-from - Provenance

Semantics: Issue B was discovered while working on issue A.

Effect: No impact on bd ready. Tracks origin and provides context.

When to Use

Use discovered-from to preserve discovery context:

• Side quests: Found new work during implementation
• Research findings: Discovered issue while investigating
• Bug found during feature work: Context of discovery matters
• Follow-up work: Identified next steps during current work

Why This Matters

Knowing where an issue came from helps:

• Understand context: Why was this created?
• Reconstruct thinking: What led to this discovery?
• Assess relevance: Is this still important given original context?
• Track exploration: See what emerged from research

Examples

Example 1: Bug During Feature

feature-10: "Add user profiles"
  discovered-from leads to
bug-11: "Existing auth doesn't handle profile permissions"

Why: While adding profiles, discovered auth system inadequate
Context: Bug might not exist if profiles weren't being added

Example 2: Research Findings

research-5: "Investigate caching options"
  discovered-from leads to
finding-6: "Redis supports persistence unlike Memcached"
finding-7: "CDN caching incompatible with our auth model"
decision-8: "Choose Redis based on findings"

Why: Research generated specific findings
Context: Findings only relevant in context of research question

Example 3: Refactoring Reveals Technical Debt

refactor-20: "Extract validation logic"
  discovered-from leads to
debt-21: "Validation inconsistent across controllers"
debt-22: "No validation for edge cases"
improvement-23: "Could add validation library"

Why: Refactoring work revealed multiple related issues
Context: Issues discovered as side effect of refactoring

Creating discovered-from Dependencies

bd dep add discovered-issue-id original-work-id --type discovered-from

Direction matters: from_id was discovered while working on to_id.

Common Patterns

Pattern: Exploration Tree

spike-1: "Investigate API redesign"
  discovered-from →
    finding-2: "Current API mixes REST and GraphQL"
    finding-3: "Authentication not consistent"
    finding-4: "Rate limiting missing"

One exploration generates multiple findings.
Tree structure shows exploration process.

Pattern: Bug Investigation Chain

bug-1: "Login fails intermittently"
  discovered-from →
    bug-2: "Race condition in session creation"
      discovered-from →
        bug-3: "Database connection pool too small"

Investigation of one bug reveals root cause as another bug.
Chain shows how you got from symptom to cause.

Pattern: Feature Implementation Side Quests

feature-main: "Add shopping cart"
  discovered-from →
    improvement-a: "Product images should be cached"
    bug-b: "Price formatting wrong for some locales"
    debt-c: "Inventory system needs refactoring"

Main feature work generates tangential discoveries.
Captured for later without derailing main work.

Combining with blocks

Can use both together:

feature-10: "Add user profiles"
  discovered-from →
    bug-11: "Auth system needs role-based access"
      blocks →
        feature-10: "Add user profiles"

Discovery: Found bug during feature work
Assessment: Bug actually blocks feature
Actions: Mark feature blocked, work on bug first

---

Decision Guide

"Which dependency type should I use?"

Decision Tree

Does Issue A prevent Issue B from starting?
  YES → blocks
  NO ↓

Is Issue B a subtask of Issue A?
  YES → parent-child (A parent, B child)
  NO ↓

Was Issue B discovered while working on Issue A?
  YES → discovered-from (A original, B discovered)
  NO ↓

Are Issues A and B just related?
  YES → related

Quick Reference by Situation

---

Common Mistakes

Mistake 1: Using blocks for Preferences

Wrong:

docs-1: "Update documentation"
  blocks
feature-2: "Add new feature"

Reason: "We prefer to update docs first"

Problem: Documentation doesn't actually block feature implementation.

Right: Use related or don't link at all. If you want ordering, note it in issue descriptions but don't enforce with blocks.

Mistake 2: Using discovered-from for Planning

Wrong:

epic-1: "OAuth integration"
  discovered-from →
    task-2: "Set up OAuth credentials"

Reason: "I'm planning these tasks from the epic"

Problem: discovered-from is for emergent discoveries, not planned decomposition.

Right: Use parent-child for planned task breakdown.

Mistake 3: Not Using Any Dependencies

Symptom: Long list of issues with no structure.

Problem: Can't tell what's blocked, what's related, how work is organized.

Solution: Add structure with dependencies:

• Group with parent-child
• Order with blocks
• Link with related
• Track discovery with discovered-from

Mistake 4: Over-Using blocks

Wrong:

Everything blocks everything else in strict sequential order.

Problem: No parallel work possible; bd ready shows only one issue.

Right: Only use blocks for actual technical dependencies. Allow parallel work where possible.

Mistake 5: Wrong Direction

Wrong:

bd dep add database-schema api-endpoint

Meaning: database-schema depends on api-endpoint (schema needs endpoint?!)

Problem: Backwards! The endpoint depends on the schema, not the other way around.

Right:

bd dep add api-endpoint database-schema

Meaning: api-endpoint depends on database-schema (endpoint needs schema ✓)

Mnemonic: "from_id depends on to_id" or "dependent depends on prerequisite"

---

Advanced Patterns

Pattern: Diamond Dependencies

        setup
       /    \
   impl-a  impl-b
       \    /
       testing

setup blocks both impl-a and impl-b
both impl-a and impl-b block testing

Both implementations must complete before testing can begin.

Pattern: Optional Dependencies

core-feature (ready immediately)
  related to
nice-to-have (ready immediately)

Both can be done, neither blocks the other.
Use related to show they're connected.

Pattern: Discovery Cascade

research-main
  discovered-from → finding-1
  discovered-from → finding-2
    discovered-from → deep-finding-3

Research generates findings.
Findings generate deeper findings.
Tree shows discovery process.

Pattern: Epic with Phases

auth-epic
  parent of phase-1-epic
    parent of: setup-1, setup-2, setup-3
  parent of phase-2-epic
    parent of: implement-1, implement-2
  parent of phase-3-epic
    parent of: test-1, test-2

phase-1-epic blocks phase-2-epic blocks phase-3-epic

Nested hierarchy with phase ordering.

---

Visualization

When you run bd show issue-id on an issue, you see:

Issue: feature-10
Dependencies (blocks this issue):
  - setup-5: "Install library"
  - config-6: "Add configuration"

Dependents (blocked by this issue):
  - test-12: "Add integration tests"
  - docs-13: "Document new feature"

Related:
  - refactor-8: "Similar refactoring effort"

Discovered from:
  - research-3: "API investigation"

This shows the full dependency context for an issue.

---

Summary

Four dependency types, four different purposes:

1. blocks: Sequential work, prerequisites, hard blockers

• Affects bd ready
• Use for technical dependencies only

2. related: Context, similar work, soft connections

• Informational only
• Use liberally for discoverability

3. parent-child: Epics and subtasks, hierarchical structure

• Organizational only
• Use for work breakdown

4. discovered-from: Side quests, research findings, provenance

• Context preservation
• Use to track emergence

Key insight: Only blocks affects what work is ready. The other three provide rich context without constraining execution.

Use dependencies to create a graph that:

• Automatically maintains ready work
• Preserves discovery context
• Shows project structure
• Links related work

This graph becomes the persistent memory that survives compaction and enables long-horizon agent work.

Integration Patterns with Other Skills

How bd-issue-tracking integrates with TodoWrite, writing-plans, and other skills for optimal workflow.

Contents

• TodoWrite Integration - Temporal layering pattern
• writing-plans Integration - Detailed implementation plans
• Cross-Skill Workflows - Using multiple skills together
• Decision Framework - When to use which tool

---

TodoWrite Integration

Both tools complement each other at different timescales:

Temporal Layering Pattern

TodoWrite (short-term working memory - this hour):

• Tactical execution: "Review Section 3", "Expand Q&A answers"
• Marked completed as you go
• Present/future tense ("Review", "Expand", "Create")
• Ephemeral: Disappears when session ends

Beads (long-term episodic memory - this week/month):

• Strategic objectives: "Continue work on strategic planning document"
• Key decisions and outcomes in notes field
• Past tense in notes ("COMPLETED", "Discovered", "Blocked by")
• Persistent: Survives compaction and session boundaries

Key insight: TodoWrite = working copy for the current hour. Beads = project journal for the current month.

The Handoff Pattern

1. Session start: Read bead → Create TodoWrite items for immediate actions 2. During work: Mark TodoWrite items completed as you go 3. Reach milestone: Update bead notes with outcomes + context 4. Session end: TodoWrite disappears, bead survives with enriched notes

After compaction: TodoWrite is gone forever, but bead notes reconstruct what happened.

Example: TodoWrite tracks execution, Beads capture meaning

TodoWrite (ephemeral execution view):

[completed] Implement login endpoint
[in_progress] Add password hashing with bcrypt
[pending] Create session middleware

Corresponding bead notes (persistent context):

bd update issue-123 --notes "COMPLETED: Login endpoint with bcrypt password
hashing (12 rounds). KEY DECISION: Using JWT tokens (not sessions) for stateless
auth - simplifies horizontal scaling. IN PROGRESS: Session middleware implementation.
NEXT: Need user input on token expiry time (1hr vs 24hr trade-off)."

What's different:

• TodoWrite: Task names (what to do)
• Beads: Outcomes and decisions (what was learned, why it matters)

Don't duplicate: TodoWrite tracks execution, Beads captures meaning and context.

When to Update Each Tool

Update TodoWrite (frequently):

• Mark task completed as you finish each one
• Add new tasks as you break down work
• Update in_progress when switching tasks

Update Beads (at milestones):

• Completed a significant piece of work
• Made a key decision that needs documentation
• Hit a blocker that pauses progress
• About to ask user for input
• Session token usage > 70%
• End of session

Pattern: TodoWrite changes every few minutes. Beads updates every hour or at natural breakpoints.

Full Workflow Example

Scenario: Implement OAuth authentication (multi-session work)

Session 1 - Planning:

# Create bd issue
bd create "Implement OAuth authentication" -t feature -p 0 --design "
JWT tokens with refresh rotation.
See BOUNDARIES.md for bd vs TodoWrite decision.
"

# Mark in_progress
bd update oauth-1 --claim

# Create TodoWrite for today's work
TodoWrite:
- [ ] Research OAuth 2.0 refresh token flow
- [ ] Design token schema
- [ ] Set up test environment

End of Session 1:

# Update bd with outcomes
bd update oauth-1 --notes "COMPLETED: Researched OAuth2 refresh flow. Decided on 7-day refresh tokens.
KEY DECISION: RS256 over HS256 (enables key rotation per security review).
IN PROGRESS: Need to set up test OAuth provider.
NEXT: Configure test provider, then implement token endpoint."

# TodoWrite disappears when session ends

Session 2 - Implementation (after compaction):

# Read bd to reconstruct context
bd show oauth-1
# See: COMPLETED research, NEXT is configure test provider

# Create fresh TodoWrite from NEXT
TodoWrite:
- [ ] Configure test OAuth provider
- [ ] Implement token endpoint
- [ ] Add basic tests

# Work proceeds...

# Update bd at milestone
bd update oauth-1 --notes "COMPLETED: Test provider configured, token endpoint implemented.
TESTS: 5 passing (token generation, validation, expiry).
IN PROGRESS: Adding refresh token rotation.
NEXT: Implement rotation, add rate limiting, security review."

For complete decision criteria and boundaries, see: BOUNDARIES.md

---

writing-plans Integration

For complex multi-step features, the design field in bd issues can link to detailed implementation plans that break work into bite-sized RED-GREEN-REFACTOR steps.

When to Create Detailed Plans

Use detailed plans for:

• Complex features with multiple components
• Multi-session work requiring systematic breakdown
• Features where TDD discipline adds value (core logic, critical paths)
• Work that benefits from explicit task sequencing

Skip detailed plans for:

• Simple features (single function, straightforward logic)
• Exploratory work (API testing, pattern discovery)
• Infrastructure setup (configuration, wiring)

The test: If you can implement it in one session without a checklist, skip the detailed plan.

Using the writing-plans Skill

When design field needs detailed breakdown, reference the writing-plans skill:

Pattern:

# Create issue with high-level design
bd create "Implement OAuth token refresh" --design "
Add JWT refresh token flow with rotation.
See docs/plans/2025-10-23-oauth-refresh-design.md for detailed plan.
"

# Then use writing-plans skill to create detailed plan
# The skill creates: docs/plans/YYYY-MM-DD-<feature-name>.md

Detailed plan structure (from writing-plans):

• Bite-sized tasks (2-5 minutes each)
• Explicit RED-GREEN-REFACTOR steps per task
• Exact file paths and complete code
• Verification commands with expected output
• Frequent commit points

Example task from detailed plan:

### Task 1: Token Refresh Endpoint

**Files:**
- Create: `src/auth/refresh.py`
- Test: `tests/auth/test_refresh.py`

**Step 1: Write failing test**

def test_refresh_token_returns_new_access_token(): refresh_token = create_valid_refresh_token() response = refresh_endpoint(refresh_token) assert response.status == 200 assert response.access_token is not None

**Step 2: Run test to verify it fails**
Run: `pytest tests/auth/test_refresh.py::test_refresh_token_returns_new_access_token -v`
Expected: FAIL with "refresh_endpoint not defined"

**Step 3: Implement minimal code**
[... exact implementation ...]

**Step 4: Verify test passes**
[... verification ...]

**Step 5: Commit**

git add tests/auth/test_refresh.py src/auth/refresh.py git commit -m "feat: add token refresh endpoint"

Integration with bd Workflow

Three-layer structure: 1. bd issue: Strategic objective + high-level design 2. Detailed plan (writing-plans): Step-by-step execution guide 3. TodoWrite: Current task within the plan

During planning phase: 1. Create bd issue with high-level design 2. If complex: Use writing-plans skill to create detailed plan 3. Link plan in design field: See docs/plans/YYYY-MM-DD-<topic>.md

During execution phase: 1. Open detailed plan (if exists) 2. Use TodoWrite to track current task within plan 3. Update bd notes at milestones, not per-task 4. Close bd issue when all plan tasks complete

Don't duplicate: Detailed plan = execution steps. BD notes = outcomes and decisions.

Example bd notes after using detailed plan:

bd update oauth-5 --notes "COMPLETED: Token refresh endpoint (5 tasks from plan: endpoint + rotation + tests)
KEY DECISION: 7-day refresh tokens (vs 30-day) - reduces risk of token theft
TESTS: All 12 tests passing (auth, rotation, expiry, error handling)"

When NOT to Use Detailed Plans

Red flags:

• Feature is simple enough to implement in one pass
• Work is exploratory (discovering patterns, testing APIs)
• Infrastructure work (OAuth setup, MCP configuration)
• Would spend more time planning than implementing

Rule of thumb: Use detailed plans when systematic breakdown prevents mistakes, not for ceremony.

Pattern summary:

• Simple feature: bd issue only
• Complex feature: bd issue + TodoWrite
• Very complex feature: bd issue + writing-plans + TodoWrite

---

Cross-Skill Workflows

Pattern: Research Document with Strategic Planning

Scenario: User asks "Help me write a strategic planning document for Q4"

Tools used: bd-issue-tracking + developing-strategic-documents skill

Workflow: 1. Create bd issue for tracking:

   bd create "Q4 strategic planning document" -t task -p 0
   bd update strat-1 --claim

2. Use developing-strategic-documents skill for research and writing

3. Update bd notes at milestones:

   bd update strat-1 --notes "COMPLETED: Research phase (reviewed 5 competitor docs, 3 internal reports)
   KEY DECISION: Focus on market expansion over cost optimization per exec input
   IN PROGRESS: Drafting recommendations section
   NEXT: Get exec review of draft recommendations before finalizing"

4. TodoWrite tracks immediate writing tasks:

   - [ ] Draft recommendation 1: Market expansion
   - [ ] Add supporting data from research
   - [ ] Create budget estimates

Why this works: bd preserves context across sessions (document might take days), skill provides writing framework, TodoWrite tracks current work.

Pattern: Multi-File Refactoring

Scenario: Refactor authentication system across 8 files

Tools used: bd-issue-tracking + systematic-debugging (if issues found)

Workflow: 1. Create epic and subtasks:

   bd create "Refactor auth system to use JWT" -t epic -p 0
   bd create "Update login endpoint" -t task
   bd create "Update token validation" -t task
   bd create "Update middleware" -t task
   bd create "Update tests" -t task

   # Link hierarchy (child depends on parent)
   bd dep add login-1 auth-epic --type parent-child
   bd dep add validation-2 auth-epic --type parent-child
   bd dep add middleware-3 auth-epic --type parent-child
   bd dep add tests-4 auth-epic --type parent-child
   # Or use --parent at creation time:
   # bd create "Update login endpoint" -t task --parent auth-epic

   # Add ordering
   bd dep add validation-2 login-1  # validation depends on login
   bd dep add middleware-3 validation-2  # middleware depends on validation
   bd dep add tests-4 middleware-3  # tests depend on middleware

2. Work through subtasks in order, using TodoWrite for each:

   Current: login-1
   TodoWrite:
   - [ ] Update login route signature
   - [ ] Add JWT generation
   - [ ] Update tests
   - [ ] Verify backward compatibility

3. Update bd notes as each completes:

   bd close login-1 --reason "Updated to JWT. Tests passing. Backward compatible with session auth."

4. If issues discovered, use systematic-debugging skill + create blocker issues

Why this works: bd tracks dependencies and progress across files, TodoWrite focuses on current file, skills provide specialized frameworks when needed.

---

Decision Framework

Which Tool for Which Purpose?

Decision Tree

Is this work done in this session?
├─ Yes → Use TodoWrite only
└─ No → Use bd
    ├─ Simple feature → bd issue + TodoWrite
    └─ Complex feature → bd issue + writing-plans + TodoWrite

Will conversation history get compacted?
├─ Likely → Use bd (context survives)
└─ Unlikely → TodoWrite is sufficient

Does work have dependencies or blockers?
├─ Yes → Use bd (tracks relationships)
└─ No → TodoWrite is sufficient

Is this specialized domain work?
├─ Research/writing → developing-strategic-documents
├─ Complex debugging → systematic-debugging
├─ Detailed implementation → writing-plans
└─ General tracking → bd + TodoWrite

Integration Anti-Patterns

Don't:

• Duplicate TodoWrite tasks into bd notes (different purposes)
• Create bd issues for single-session linear work (use TodoWrite)
• Put detailed implementation steps in bd notes (use writing-plans)
• Update bd after every TodoWrite task (update at milestones)
• Use writing-plans for exploratory work (defeats the purpose)

Do:

• Update bd when changing tools or reaching milestones
• Use TodoWrite as "working copy" of bd's NEXT section
• Link between tools (bd design field → writing-plans file path)
• Choose the right level of formality for the work complexity

---

Summary

Key principle: Each tool operates at a different timescale and level of detail.

• TodoWrite: Minutes to hours (current execution)
• bd: Hours to weeks (persistent context)
• writing-plans: Days to weeks (detailed breakdown)
• Other skills: As needed (domain frameworks)

Integration pattern: Use the lightest tool sufficient for the task, add heavier tools only when complexity demands it.

For complete boundaries and decision criteria, see: BOUNDARIES.md

Issue Creation Guidelines

Guidance on when and how to create bd issues for maximum effectiveness.

Contents

• When to Ask First vs Create Directly
• Issue Quality
• Making Issues Resumable
• Design vs Acceptance Criteria

When to Ask First vs Create Directly {#when-to-ask}

Ask the user before creating when:

• Knowledge work with fuzzy boundaries
• Task scope is unclear
• Multiple valid approaches exist
• User's intent needs clarification

Create directly when:

• Clear bug discovered during implementation
• Obvious follow-up work identified
• Technical debt with clear scope
• Dependency or blocker found

Why ask first for knowledge work? Task boundaries in strategic/research work are often unclear until discussed, whereas technical implementation tasks are usually well-defined. Discussion helps structure the work properly before creating issues, preventing poorly-scoped issues that need immediate revision.

Issue Quality {#quality}

Use clear, specific titles and include sufficient context in descriptions to resume work later.

Field Usage

Use --design flag for:

• Implementation approach decisions
• Architecture notes
• Trade-offs considered

Use --acceptance flag for:

• Definition of done
• Testing requirements
• Success metrics

Making Issues Resumable (Complex Technical Work) {#resumable}

For complex technical features spanning multiple sessions, enhance notes field with implementation details.

Optional but valuable for technical work:

• Working API query code (tested, with response structure)
• Sample API responses showing actual data
• Desired output format examples (show, don't describe)
• Research context (why this approach, what was discovered)

Example pattern:

bd update issue-9 --notes "IMPLEMENTATION GUIDE:
WORKING CODE: service.about().get(fields='importFormats')
Returns: dict with 49 entries like {'text/markdown': [...]}
OUTPUT FORMAT: # Drive Import Formats (markdown with categorized list)
CONTEXT: text/markdown support added July 2024, not in static docs"

When to add: Multi-session technical features with APIs or specific formats. Skip for simple tasks.

For detailed patterns and examples, read: RESUMABILITY.md

Design vs Acceptance Criteria (Critical Distinction) {#design-vs-acceptance}

Common mistake: Putting implementation details in acceptance criteria. Here's the difference:

DESIGN field (HOW to build it):

• "Use two-phase batchUpdate approach: insert text first, then apply formatting"
• "Parse with regex to find * and _ markers"
• "Use JWT tokens with 1-hour expiry"
• Trade-offs: "Chose batchUpdate over streaming API for atomicity"

ACCEPTANCE CRITERIA (WHAT SUCCESS LOOKS LIKE):

• "Bold and italic markdown formatting renders correctly in the Doc"
• "Solution accepts markdown input and creates Doc with specified title"
• "Returns doc_id and webViewLink to caller"
• "User tokens persist across sessions and refresh automatically"

Why this matters:

• Design can change during implementation (e.g., use library instead of regex)
• Acceptance criteria should remain stable across sessions
• Criteria should be outcome-focused ("what must be true?") not step-focused ("do these steps")
• Each criterion should be verifiable - you can definitively say yes/no

The pitfall

Writing criteria like "- [ ] Use batchUpdate approach" locks you into one implementation.

Better: "- [ ] Formatting is applied atomically (all at once or not at all)" - allows flexible implementation.

Test yourself

If you rewrote the solution using a different approach, would the acceptance criteria still apply? If not, they're design notes, not criteria.

Example of correct structure

✅ Design field:

Two-phase Docs API approach:
1. Parse markdown to positions
2. Create doc + insert text in one call
3. Apply formatting in second call
Rationale: Atomic operations, easier to debug formatting separately

✅ Acceptance criteria:

- [ ] Markdown formatting renders in Doc (bold, italic, headings)
- [ ] Lists preserve order and nesting
- [ ] Links are clickable
- [ ] Large documents (>50KB) process without timeout

❌ Wrong (design masquerading as criteria):

- [ ] Use two-phase batchUpdate approach
- [ ] Apply formatting in second batchUpdate call

Quick Reference

Creating good issues:

1. Title: Clear, specific, action-oriented 2. Description: Problem statement, context, why it matters 3. Design: Approach, architecture, trade-offs (can change) 4. Acceptance: Outcomes, success criteria (should be stable) 5. Notes: Implementation details, session handoffs (evolves over time)

Common mistakes:

• Vague titles: "Fix bug" → "Fix: auth token expires before refresh"
• Implementation in acceptance: "Use JWT" → "Auth tokens persist across sessions"
• Missing context: "Update database" → "Update database: add user_last_login for session analytics"

Molecules and Wisps Reference

This reference covers bd's molecular chemistry system for reusable work templates and ephemeral workflows.

The Chemistry Metaphor

bd v0.34.0 introduces a chemistry-inspired workflow system:

Phase transitions:

• spawn / pour: Solid (proto) → Liquid (mol)
• wisp create: Solid (proto) → Vapor (wisp)
• squash: Vapor (wisp) → Digest (permanent summary)
• burn: Vapor (wisp) → Nothing (deleted, no trace)
• distill: Liquid (ad-hoc epic) → Solid (proto)

When to Use Molecules

Use Protos/Mols When:

• Repeatable patterns - Same workflow structure used multiple times (releases, reviews, onboarding)
• Team knowledge capture - Encoding tribal knowledge as executable templates
• Audit trail matters - Work that needs to be tracked and reviewed later
• Cross-session persistence - Work spanning multiple days/sessions

Use Wisps When:

• Operational loops - Patrol cycles, health checks, routine monitoring
• One-shot orchestration - Temporary coordination that shouldn't clutter history
• Diagnostic runs - Debugging workflows with no archival value
• High-frequency ephemeral work - Would create noise in permanent database

Key insight: Wisps prevent database bloat from routine operations while still providing structure during execution.

---

Proto Management

Creating a Proto

Protos are epics with the template label. Create manually or distill from existing work:

# Manual creation
bd create "Release Workflow" --type epic --label template
bd create "Run tests for {{component}}" --type task
bd dep add task-id epic-id --type parent-child

# Distill from ad-hoc work (extracts template from existing epic)
bd mol distill bd-abc123 --as "Release Workflow" --var version=1.0.0

Proto naming convention: Use mol- prefix for clarity (e.g., mol-release, mol-patrol).

Listing Formulas

bd formula list                 # List all formulas (protos)
bd formula list --json          # Machine-readable

Viewing Proto Structure

bd mol show mol-release         # Show template structure and variables
bd mol show mol-release --json  # Machine-readable

---

Spawning Molecules

Basic Spawn (Creates Wisp by Default)

bd mol spawn mol-patrol                    # Creates wisp (ephemeral)
bd mol spawn mol-feature --pour            # Creates mol (persistent)
bd mol spawn mol-release --var version=2.0 # With variable substitution

Chemistry shortcuts:

bd mol pour mol-feature                    # Shortcut for spawn --pour
bd mol wisp mol-patrol                     # Explicit wisp creation

Spawn with Immediate Execution

bd mol run mol-release --var version=2.0

bd mol run does three things: 1. Spawns the molecule (persistent) 2. Assigns root issue to caller 3. Pins root issue for session recovery

Use `mol run` when: Starting durable work that should survive crashes. The pin ensures bd ready shows the work after restart.

Spawn with Attachments

Attach additional protos in a single command:

bd mol spawn mol-feature --attach mol-testing --var name=auth
# Spawns mol-feature, then spawns mol-testing and bonds them

Attach types:

• sequential (default) - Attached runs after primary completes
• parallel - Attached runs alongside primary
• conditional - Attached runs only if primary fails

bd mol spawn mol-deploy --attach mol-rollback --attach-type conditional

---

Bonding Molecules

Bond Types

bd mol bond A B                    # Sequential: B runs after A
bd mol bond A B --type parallel    # Parallel: B runs alongside A
bd mol bond A B --type conditional # Conditional: B runs if A fails

Operand Combinations

Phase Control in Bonds

By default, spawned protos inherit target's phase. Override with flags:

# Found bug during wisp patrol? Persist it:
bd mol bond mol-critical-bug wisp-patrol --pour

# Need ephemeral diagnostic on persistent feature?
bd mol bond mol-temp-check bd-feature --wisp

Custom Compound Names

bd mol bond mol-feature mol-deploy --as "Feature with Deploy"

---

Wisp Lifecycle

Creating Wisps

bd mol wisp mol-patrol                       # From proto
bd mol spawn mol-patrol                      # Same (spawn defaults to wisp)
bd mol spawn mol-check --var target=db       # With variables

Listing Wisps

bd mol wisp list                     # List all wisps
bd mol wisp list --json              # Machine-readable

Ending Wisps

Option 1: Squash (compress to digest)

bd mol squash wisp-abc123                              # Auto-generate summary
bd mol squash wisp-abc123 --summary "Completed patrol" # Agent-provided summary
bd mol squash wisp-abc123 --keep-children              # Keep children, just create digest
bd mol squash wisp-abc123 --dry-run                    # Preview

Squash creates a permanent digest issue summarizing the wisp's work, then deletes the wisp children.

Option 2: Burn (delete without trace)

bd mol burn wisp-abc123                    # Delete wisp, no digest

Use burn for routine work with no archival value.

Garbage Collection

bd mol wisp gc                       # Clean up orphaned wisps
bd mol wisp gc --closed              # Preview closed wisp deletion
bd mol wisp gc --closed --force      # Purge all closed wisps

---

Distilling Protos

Extract a reusable template from ad-hoc work:

bd mol distill bd-o5xe --as "Release Workflow"
bd mol distill bd-abc --var feature_name=auth-refactor --var version=1.0.0

What distill does: 1. Loads existing epic and all children 2. Clones structure as new proto (adds template label) 3. Replaces concrete values with {{variable}} placeholders

Variable syntax (both work):

--var branch=feature-auth      # variable=value (recommended)
--var feature-auth=branch      # value=variable (auto-detected)

Use cases:

• Team develops good workflow organically, wants to reuse it
• Capture tribal knowledge as executable templates
• Create starting point for similar future work

---

Cross-Project Dependencies

Concept

Projects can depend on capabilities shipped by other projects:

# Project A ships a capability
bd ship auth-api                # Marks capability as available

# Project B depends on it
bd dep add bd-123 external:project-a:auth-api

Shipping Capabilities

bd ship <capability>            # Ship capability (requires closed issue)
bd ship <capability> --force    # Ship even if issue not closed
bd ship <capability> --dry-run  # Preview

How it works: 1. Find issue with export:<capability> label 2. Validate issue is closed 3. Add provides:<capability> label

Depending on External Capabilities

bd dep add <issue> external:<project>:<capability>

The dependency is satisfied when the external project has a closed issue with provides:<capability> label.

`bd ready` respects external deps: Issues blocked by unsatisfied external dependencies won't appear in ready list.

---

Common Patterns

Pattern: Weekly Review Proto

# Create proto
bd create "Weekly Review" --type epic --label template
bd create "Review open issues" --type task
bd create "Update priorities" --type task
bd create "Archive stale work" --type task
# Link as children...

# Use each week
bd mol spawn mol-weekly-review --pour

Pattern: Ephemeral Patrol Cycle

# Patrol proto exists
bd mol wisp mol-patrol

# Execute patrol work...

# End patrol
bd mol squash wisp-abc123 --summary "Patrol complete: 3 issues found, 2 resolved"

Pattern: Feature with Rollback

bd mol spawn mol-deploy --attach mol-rollback --attach-type conditional
# If deploy fails, rollback automatically becomes unblocked

Pattern: Capture Tribal Knowledge

# After completing a good workflow organically
bd mol distill bd-release-epic --as "Release Process" --var version=X.Y.Z
# Now team can: bd mol spawn mol-release-process --var version=2.0.0

---

CLI Quick Reference

---

Troubleshooting

"Proto not found"

• Check bd formula list for available formulas/protos
• Protos need template label on the epic

"Variable not substituted"

• Use --var key=value syntax
• Check proto for {{key}} placeholders with bd mol show

"Wisp commands fail"

• Wisps stored in .beads-wisp/ (separate from .beads/)
• Check bd mol wisp list for active wisps

"External dependency not satisfied"

• Target project must have closed issue with provides:<capability> label
• Use bd ship <capability> in target project first