Merge PR #81: Add Claude Code skill for beads usage patterns
Adds comprehensive skill documentation teaching Claude agents when and how to use beads effectively, including decision criteria for bd vs TodoWrite, workflow patterns, and integration guidance.
This commit is contained in:
Steve Yegge
@@ -11,6 +11,7 @@ This directory contains examples of how to integrate bd with AI agents and workf
|
||||
- **[git-hooks/](git-hooks/)** - Pre-configured git hooks for automatic export/import
|
||||
- **[branch-merge/](branch-merge/)** - Branch merge workflow with collision resolution
|
||||
- **[claude-desktop-mcp/](claude-desktop-mcp/)** - MCP server for Claude Desktop integration
|
||||
- **[claude-code-skill/](claude-code-skill/)** - Claude Code skill for effective beads usage patterns
|
||||
|
||||
## Quick Start
|
||||
|
||||
|
||||
142
examples/claude-code-skill/README.md
Normal file
142
examples/claude-code-skill/README.md
Normal file
@@ -0,0 +1,142 @@
|
||||
# Claude Code Skill for Beads
|
||||
|
||||
A comprehensive Claude Code skill that teaches Claude how to use beads effectively for issue tracking in multi-session coding workflows.
|
||||
|
||||
## What is This?
|
||||
|
||||
This is a [Claude Code](https://claude.com/claude-code) skill - a markdown-based instruction set that teaches Claude AI how to use beads. While the [beads plugin](../../.claude-plugin/) provides slash commands and MCP tools for basic operations, this skill complements it by teaching the **philosophy and patterns** of effective beads usage.
|
||||
|
||||
## What Does It Provide?
|
||||
|
||||
**Main skill file:**
|
||||
- Core workflow patterns (discovery, execution, planning phases)
|
||||
- Decision criteria for when to use bd vs TodoWrite/markdown
|
||||
- Session start protocols and ready work checks
|
||||
- Issue lifecycle management
|
||||
- Integration patterns with other tools
|
||||
|
||||
**Reference documentation:**
|
||||
- `references/BOUNDARIES.md` - Detailed decision criteria for bd vs TodoWrite with examples
|
||||
- `references/CLI_REFERENCE.md` - Complete command reference with all flags
|
||||
- `references/DEPENDENCIES.md` - Deep dive into dependency types and relationship patterns
|
||||
- `references/WORKFLOWS.md` - Step-by-step workflows with checklists
|
||||
|
||||
## Why is This Useful?
|
||||
|
||||
The skill helps Claude understand:
|
||||
|
||||
1. **When to use beads** - Not every task needs bd. The skill teaches when bd helps vs when markdown/TodoWrite is better (per Steve Yegge's insight about markdown "losing its way in the middle")
|
||||
|
||||
2. **How to structure issues** - Proper use of dependency types, issue metadata, and relationship patterns
|
||||
|
||||
3. **Workflow patterns** - Proactive issue creation during discovery, status maintenance during execution, dependency graphs during planning
|
||||
|
||||
4. **Integration with other tools** - How bd and TodoWrite can coexist, each serving its purpose
|
||||
|
||||
## Installation
|
||||
|
||||
### Prerequisites
|
||||
|
||||
1. Install beads CLI:
|
||||
```bash
|
||||
curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/install.sh | bash
|
||||
```
|
||||
|
||||
2. Have [Claude Code](https://claude.com/claude-code) installed
|
||||
|
||||
### Install the Skill
|
||||
|
||||
You can install this skill in two ways:
|
||||
|
||||
#### Option 1: Copy to Claude Code Skills Directory
|
||||
|
||||
```bash
|
||||
# Clone this repo (if you haven't already)
|
||||
git clone https://github.com/steveyegge/beads.git
|
||||
cd beads/examples/claude-code-skill
|
||||
|
||||
# Create a symlink in your Claude Code skills directory
|
||||
ln -s "$(pwd)" ~/.claude/skills/bd
|
||||
```
|
||||
|
||||
#### Option 2: Copy Files Directly
|
||||
|
||||
```bash
|
||||
# Create the skill directory
|
||||
mkdir -p ~/.claude/skills/bd
|
||||
|
||||
# Copy the skill files
|
||||
cp -r beads/examples/claude-code-skill/* ~/.claude/skills/bd/
|
||||
```
|
||||
|
||||
### Verify Installation
|
||||
|
||||
Restart Claude Code, then in a new session, ask:
|
||||
|
||||
```
|
||||
Do you have the bd skill installed?
|
||||
```
|
||||
|
||||
Claude should confirm it has access to the bd skill and can help with beads issue tracking.
|
||||
|
||||
## How It Works
|
||||
|
||||
Claude Code automatically loads skills from `~/.claude/skills/`. When this skill is installed:
|
||||
|
||||
1. Claude gets the core workflow from `SKILL.md` immediately
|
||||
2. Claude can read reference docs when it needs detailed information
|
||||
3. The skill uses progressive disclosure - quick reference in SKILL.md, details in references/
|
||||
|
||||
## Usage Examples
|
||||
|
||||
Once installed, Claude will automatically:
|
||||
|
||||
- Check for ready work at session start (if `.beads/` exists)
|
||||
- Suggest creating bd issues for multi-session work
|
||||
- Use appropriate dependency types when linking issues
|
||||
- Maintain proper issue lifecycle (create → in_progress → close)
|
||||
- Know when to use bd vs TodoWrite
|
||||
|
||||
You can also explicitly ask Claude to use beads:
|
||||
|
||||
```
|
||||
Let's track this work in bd since it spans multiple sessions
|
||||
```
|
||||
|
||||
```
|
||||
Create a bd issue for this bug we discovered
|
||||
```
|
||||
|
||||
```
|
||||
Show me what's ready to work on in bd
|
||||
```
|
||||
|
||||
## Relationship to Beads Plugin
|
||||
|
||||
This skill complements the [beads plugin](../../.claude-plugin/):
|
||||
|
||||
- **Plugin** (`.claude-plugin/`): Provides slash commands (`/bd-create`, `/bd-ready`) and MCP tools for basic operations
|
||||
- **Skill** (this directory): Teaches Claude the patterns, philosophy, and decision-making for effective beads usage
|
||||
|
||||
You can use both together for the best experience:
|
||||
- Plugin for quick operations
|
||||
- Skill for intelligent workflow decisions
|
||||
|
||||
### Why CLI Instead of MCP?
|
||||
|
||||
This skill teaches Claude to use the bd CLI directly (via Bash commands like `bd ready`, `bd create`, etc.) rather than relying on MCP tools. This approach has several benefits:
|
||||
|
||||
- **Lower context usage** - No MCP server prompt loaded into every session, saving tokens
|
||||
- **Works everywhere** - Only requires bd binary installed, no MCP server setup needed
|
||||
- **Explicit operations** - All bd commands visible in conversation history for transparency
|
||||
- **Full functionality** - CLI supports `--json` flag for programmatic parsing just like MCP
|
||||
|
||||
The MCP server is excellent for interactive use, but for autonomous agent workflows where context efficiency matters, direct CLI usage is more practical. The skill provides the guidance Claude needs to use the CLI effectively.
|
||||
|
||||
## Contributing
|
||||
|
||||
Found ways to improve the skill? Contributions welcome! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
|
||||
|
||||
## License
|
||||
|
||||
Same as beads - MIT License. See [LICENSE](../../LICENSE).
|
||||
420
examples/claude-code-skill/SKILL.md
Normal file
420
examples/claude-code-skill/SKILL.md
Normal file
@@ -0,0 +1,420 @@
|
||||
---
|
||||
name: bd-issue-tracking
|
||||
description: Track complex, multi-session work with dependency graphs using bd (beads) issue tracker. Use when work spans multiple sessions, has complex dependencies, or requires persistent context across compaction cycles. For simple single-session linear tasks, TodoWrite remains appropriate.
|
||||
---
|
||||
|
||||
# bd Issue Tracking
|
||||
|
||||
## Overview
|
||||
|
||||
bd is a graph-based issue tracker for persistent memory across sessions. Use for multi-session work with complex dependencies; use TodoWrite for simple single-session tasks.
|
||||
|
||||
## When to Use bd vs TodoWrite
|
||||
|
||||
### Use bd when:
|
||||
- **Multi-session work** - Tasks spanning multiple compaction cycles or days
|
||||
- **Complex dependencies** - Work with blockers, prerequisites, or hierarchical structure
|
||||
- **Knowledge work** - Strategic documents, research, or tasks with fuzzy boundaries
|
||||
- **Side quests** - Exploratory work that might pause the main task
|
||||
- **Project memory** - Need to resume work after weeks away with full context
|
||||
|
||||
### Use TodoWrite when:
|
||||
- **Single-session tasks** - Work that completes within current session
|
||||
- **Linear execution** - Straightforward step-by-step tasks with no branching
|
||||
- **Immediate context** - All information already in conversation
|
||||
- **Simple tracking** - Just need a checklist to show progress
|
||||
|
||||
**Key insight**: If resuming work after 2 weeks would be difficult without bd, use bd. If the work can be picked up from a markdown skim, TodoWrite is sufficient.
|
||||
|
||||
**For detailed decision criteria and examples, read:** [references/BOUNDARIES.md](references/BOUNDARIES.md)
|
||||
|
||||
## Session Start Protocol
|
||||
|
||||
**bd is available when:**
|
||||
- Project has a `.beads/` directory (project-local database), OR
|
||||
- `~/.beads/` exists (global fallback database for any directory)
|
||||
|
||||
**At session start, always check for bd availability and run ready check:**
|
||||
|
||||
1. **Always check ready work automatically** at session start
|
||||
2. **Report status** to establish shared context
|
||||
|
||||
### Quick Start Pattern
|
||||
|
||||
```bash
|
||||
# At session start, run:
|
||||
bd ready --json
|
||||
|
||||
# Report to user:
|
||||
"I can see X items ready to work on: [brief summary]"
|
||||
|
||||
# If using global ~/.beads, note this in report
|
||||
```
|
||||
|
||||
This gives immediate shared context about available work without requiring user prompting.
|
||||
|
||||
**Note**: bd auto-discovers the database:
|
||||
- Uses `.beads/*.db` in current project if exists
|
||||
- Falls back to `~/.beads/default.db` otherwise
|
||||
- No configuration needed
|
||||
|
||||
### When No Work is Ready
|
||||
|
||||
If `bd ready` returns empty but issues exist:
|
||||
|
||||
```bash
|
||||
bd blocked --json
|
||||
```
|
||||
|
||||
Report blockers and suggest next steps.
|
||||
|
||||
### Database Selection
|
||||
|
||||
bd automatically selects the appropriate database:
|
||||
- **Project-local** (`.beads/` in project): Used for project-specific work
|
||||
- **Global fallback** (`~/.beads/`): Used when no project-local database exists
|
||||
|
||||
**Use case for global database**: Cross-project tracking, personal task management, knowledge work that doesn't belong to a specific project.
|
||||
|
||||
**For complete session start workflows, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md#session-start)
|
||||
|
||||
## Core Operations
|
||||
|
||||
All bd commands support `--json` flag for structured output when needed for programmatic parsing.
|
||||
|
||||
### Essential Operations
|
||||
|
||||
**Check ready work:**
|
||||
```bash
|
||||
bd ready
|
||||
bd ready --json # For structured output
|
||||
bd ready --priority 0 # Filter by priority
|
||||
bd ready --assignee alice # Filter by assignee
|
||||
```
|
||||
|
||||
**Create new issue:**
|
||||
```bash
|
||||
bd create "Fix login bug"
|
||||
bd create "Add OAuth" -p 0 -t feature
|
||||
bd create "Write tests" -d "Unit tests for auth module" --assignee alice
|
||||
bd create "Research caching" --design "Evaluate Redis vs Memcached"
|
||||
```
|
||||
|
||||
**Update issue status:**
|
||||
```bash
|
||||
bd update issue-123 --status in_progress
|
||||
bd update issue-123 --priority 0
|
||||
bd update issue-123 --assignee bob
|
||||
bd update issue-123 --design "Decided to use Redis for persistence support"
|
||||
```
|
||||
|
||||
**Close completed work:**
|
||||
```bash
|
||||
bd close issue-123
|
||||
bd close issue-123 --reason "Implemented in PR #42"
|
||||
bd close issue-1 issue-2 issue-3 --reason "Bulk close related work"
|
||||
```
|
||||
|
||||
**Show issue details:**
|
||||
```bash
|
||||
bd show issue-123
|
||||
bd show issue-123 --json
|
||||
```
|
||||
|
||||
**List issues:**
|
||||
```bash
|
||||
bd list
|
||||
bd list --status open
|
||||
bd list --priority 0
|
||||
bd list --type bug
|
||||
bd list --assignee alice
|
||||
```
|
||||
|
||||
**For complete CLI reference with all flags and examples, read:** [references/CLI_REFERENCE.md](references/CLI_REFERENCE.md)
|
||||
|
||||
## Issue Lifecycle Workflow
|
||||
|
||||
### 1. Discovery Phase (Proactive Issue Creation)
|
||||
|
||||
**During exploration or implementation, proactively file issues for:**
|
||||
- Bugs or problems discovered
|
||||
- Potential improvements noticed
|
||||
- Follow-up work identified
|
||||
- Technical debt encountered
|
||||
- Questions requiring research
|
||||
|
||||
**Pattern:**
|
||||
```bash
|
||||
# When encountering new work during a task:
|
||||
bd create "Found: auth doesn't handle profile permissions"
|
||||
bd dep add current-task-id new-issue-id --type discovered-from
|
||||
|
||||
# Continue with original task - issue persists for later
|
||||
```
|
||||
|
||||
**Key benefit**: Capture context immediately instead of losing it when conversation ends.
|
||||
|
||||
### 2. Execution Phase (Status Maintenance)
|
||||
|
||||
**Mark issues in_progress when starting work:**
|
||||
```bash
|
||||
bd update issue-123 --status in_progress
|
||||
```
|
||||
|
||||
**Update throughout work:**
|
||||
```bash
|
||||
# Add design notes as implementation progresses
|
||||
bd update issue-123 --design "Using JWT with RS256 algorithm"
|
||||
|
||||
# Update acceptance criteria if requirements clarify
|
||||
bd update issue-123 --acceptance "- JWT validation works\n- Tests pass\n- Error handling returns 401"
|
||||
```
|
||||
|
||||
**Close when complete:**
|
||||
```bash
|
||||
bd close issue-123 --reason "Implemented JWT validation with tests passing"
|
||||
```
|
||||
|
||||
**Important**: Closed issues remain in database - they're not deleted, just marked complete for project history.
|
||||
|
||||
### 3. Planning Phase (Dependency Graphs)
|
||||
|
||||
For complex multi-step work, structure issues with dependencies before starting:
|
||||
|
||||
**Create parent epic:**
|
||||
```bash
|
||||
bd create "Implement user authentication" -t epic -d "OAuth integration with JWT tokens"
|
||||
```
|
||||
|
||||
**Create subtasks:**
|
||||
```bash
|
||||
bd create "Set up OAuth credentials" -t task
|
||||
bd create "Implement authorization flow" -t task
|
||||
bd create "Add token refresh" -t task
|
||||
```
|
||||
|
||||
**Link with dependencies:**
|
||||
```bash
|
||||
# parent-child for epic structure
|
||||
bd dep add auth-epic auth-setup --type parent-child
|
||||
bd dep add auth-epic auth-flow --type parent-child
|
||||
|
||||
# blocks for ordering
|
||||
bd dep add auth-setup auth-flow
|
||||
```
|
||||
|
||||
**For detailed dependency patterns and types, read:** [references/DEPENDENCIES.md](references/DEPENDENCIES.md)
|
||||
|
||||
## Dependency Types Reference
|
||||
|
||||
bd supports four dependency types:
|
||||
|
||||
1. **blocks** - Hard blocker (issue A blocks issue B from starting)
|
||||
2. **related** - Soft link (issues are related but not blocking)
|
||||
3. **parent-child** - Hierarchical (epic/subtask relationship)
|
||||
4. **discovered-from** - Provenance (issue B discovered while working on A)
|
||||
|
||||
**For complete guide on when to use each type with examples and patterns, read:** [references/DEPENDENCIES.md](references/DEPENDENCIES.md)
|
||||
|
||||
## Integration with TodoWrite
|
||||
|
||||
**Both tools can coexist in a session:**
|
||||
|
||||
### Recommended Pattern
|
||||
|
||||
1. **Use bd** for project-level issue tracking and dependencies
|
||||
2. **Use TodoWrite** as "working copy" for current session's active tasks
|
||||
3. **Sync status**: When completing TodoWrite items, update corresponding bd issues
|
||||
|
||||
### Example Flow
|
||||
|
||||
```
|
||||
Session start:
|
||||
- bd ready shows: "3 issues ready to work on"
|
||||
- User chooses one: "Let's work on issue-123"
|
||||
- Create TodoWrite checklist for implementation steps
|
||||
- bd update issue-123 --status in_progress
|
||||
- Work through TodoWrite items
|
||||
- When done: bd close issue-123
|
||||
- bd ready to see what unblocked
|
||||
```
|
||||
|
||||
**For patterns on transitioning between tools mid-session, read:** [references/BOUNDARIES.md](references/BOUNDARIES.md#integration-patterns)
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Pattern 1: Knowledge Work Session
|
||||
|
||||
User asks for strategic document development:
|
||||
1. Check if bd available: `bd ready`
|
||||
2. If related epic exists, show current status
|
||||
3. Create new issues for discovered research needs
|
||||
4. Use discovered-from to track where ideas came from
|
||||
5. Update design notes as research progresses
|
||||
|
||||
### Pattern 2: Side Quest Handling
|
||||
|
||||
During main task, discover a problem:
|
||||
1. Create issue: `bd create "Found: inventory system needs refactoring"`
|
||||
2. Link using discovered-from: `bd dep add main-task new-issue --type discovered-from`
|
||||
3. Assess: blocker or can defer?
|
||||
4. If blocker: `bd update main-task --status blocked`, work on new issue
|
||||
5. If deferrable: note in issue, continue main task
|
||||
|
||||
### Pattern 3: Multi-Session Project Resume
|
||||
|
||||
Starting work after time away:
|
||||
1. Run `bd ready` to see available work
|
||||
2. Run `bd blocked` to understand what's stuck
|
||||
3. Run `bd list --status closed --limit 10` to see recent completions
|
||||
4. Run `bd show issue-id` on issue to work on
|
||||
5. Update status and begin work
|
||||
|
||||
**For complete workflow walkthroughs with checklists, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md)
|
||||
|
||||
## Issue Creation Guidelines
|
||||
|
||||
### When to Ask First vs Create Directly
|
||||
|
||||
**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
|
||||
|
||||
**Reason**: Creating issues helps clarify thinking, but for ambiguous knowledge work, discussion refines the task structure first.
|
||||
|
||||
### Issue Quality
|
||||
|
||||
Use clear, specific titles and include sufficient context in descriptions to resume work later.
|
||||
|
||||
**Use --design flag for:**
|
||||
- Implementation approach decisions, architecture notes, trade-offs considered
|
||||
|
||||
**Use --acceptance flag for:**
|
||||
- Definition of done, testing requirements, success metrics
|
||||
|
||||
## Statistics and Monitoring
|
||||
|
||||
**Check project health:**
|
||||
```bash
|
||||
bd stats
|
||||
bd stats --json
|
||||
```
|
||||
|
||||
Returns: total issues, open, in_progress, closed, blocked, ready, avg lead time
|
||||
|
||||
**Find blocked work:**
|
||||
```bash
|
||||
bd blocked
|
||||
bd blocked --json
|
||||
```
|
||||
|
||||
Use stats to:
|
||||
- Report progress to user
|
||||
- Identify bottlenecks
|
||||
- Understand project velocity
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Issue Types
|
||||
|
||||
```bash
|
||||
bd create "Title" -t task # Standard work item (default)
|
||||
bd create "Title" -t bug # Defect or problem
|
||||
bd create "Title" -t feature # New functionality
|
||||
bd create "Title" -t epic # Large work with subtasks
|
||||
bd create "Title" -t chore # Maintenance or cleanup
|
||||
```
|
||||
|
||||
### Priority Levels
|
||||
|
||||
```bash
|
||||
bd create "Title" -p 0 # Highest priority (critical)
|
||||
bd create "Title" -p 1 # High priority
|
||||
bd create "Title" -p 2 # Normal priority (default)
|
||||
bd create "Title" -p 3 # Low priority
|
||||
```
|
||||
|
||||
### Bulk Operations
|
||||
|
||||
```bash
|
||||
# Close multiple issues at once
|
||||
bd close issue-1 issue-2 issue-3 --reason "Completed in sprint 5"
|
||||
|
||||
# Create multiple issues from markdown file
|
||||
bd create --file issues.md
|
||||
```
|
||||
|
||||
### Dependency Visualization
|
||||
|
||||
```bash
|
||||
# Show full dependency tree for an issue
|
||||
bd dep tree issue-123
|
||||
|
||||
# Check for circular dependencies
|
||||
bd dep cycles
|
||||
```
|
||||
|
||||
### Built-in Help
|
||||
|
||||
```bash
|
||||
# Quick start guide (comprehensive built-in reference)
|
||||
bd quickstart
|
||||
|
||||
# Command-specific help
|
||||
bd create --help
|
||||
bd dep --help
|
||||
```
|
||||
|
||||
## JSON Output
|
||||
|
||||
All bd commands support `--json` flag for structured output:
|
||||
|
||||
```bash
|
||||
bd ready --json
|
||||
bd show issue-123 --json
|
||||
bd list --status open --json
|
||||
bd stats --json
|
||||
```
|
||||
|
||||
Use JSON output when you need to parse results programmatically or extract specific fields.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**If bd command not found:**
|
||||
- Check installation: `bd version`
|
||||
- Verify PATH includes bd binary location
|
||||
|
||||
**If issues seem lost:**
|
||||
- Use `bd list` to see all issues
|
||||
- Filter by status: `bd list --status closed`
|
||||
- Closed issues remain in database permanently
|
||||
|
||||
**If dependencies seem wrong:**
|
||||
- Use `bd show issue-id` to see full dependency tree
|
||||
- Use `bd dep tree issue-id` for visualization
|
||||
- Dependencies are directional: `bd dep add from-id to-id` means from-id blocks to-id
|
||||
- See [references/DEPENDENCIES.md](references/DEPENDENCIES.md#common-mistakes)
|
||||
|
||||
**If database seems out of sync:**
|
||||
- bd auto-syncs JSONL after each operation (5s debounce)
|
||||
- bd auto-imports JSONL when newer than DB (after git pull)
|
||||
- Manual operations: `bd export`, `bd import`
|
||||
|
||||
## Reference Files
|
||||
|
||||
Detailed information organized by topic:
|
||||
|
||||
| Reference | Read When |
|
||||
|-----------|-----------|
|
||||
| [references/BOUNDARIES.md](references/BOUNDARIES.md) | Need detailed decision criteria for bd vs TodoWrite, or integration patterns |
|
||||
| [references/CLI_REFERENCE.md](references/CLI_REFERENCE.md) | Need complete command reference, flag details, or examples |
|
||||
| [references/WORKFLOWS.md](references/WORKFLOWS.md) | Need step-by-step workflows with checklists for common scenarios |
|
||||
| [references/DEPENDENCIES.md](references/DEPENDENCIES.md) | Need deep understanding of dependency types or relationship patterns |
|
||||
443
examples/claude-code-skill/references/BOUNDARIES.md
Normal file
443
examples/claude-code-skill/references/BOUNDARIES.md
Normal file
@@ -0,0 +1,443 @@
|
||||
# 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](#the-core-question)
|
||||
- [Decision Matrix](#decision-matrix)
|
||||
- [Use bd for](#use-bd-for): Multi-Session Work, Complex Dependencies, Knowledge Work, Side Quests, Project Memory
|
||||
- [Use TodoWrite for](#use-todowrite-for): Single-Session Tasks, Linear Execution, Immediate Context, Simple Tracking
|
||||
- [Detailed Comparison](#detailed-comparison)
|
||||
- [Integration Patterns](#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](#real-world-examples)
|
||||
- Strategic Document Development, Simple Feature Implementation, Bug Investigation, Refactoring with Dependencies
|
||||
- [Common Mistakes](#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](#the-transition-point)
|
||||
- [Summary Heuristics](#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:**
|
||||
- Policy proposal requiring stakeholder analysis and evidence gathering
|
||||
- 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**: Git-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
|
||||
|
||||
| Aspect | bd | TodoWrite |
|
||||
|--------|-----|-----------|
|
||||
| **Persistence** | Git-backed, survives compaction | Session-only, lost after conversation |
|
||||
| **Dependencies** | Graph-based, automatic ready detection | Manual, no automatic tracking |
|
||||
| **Discoverability** | `bd ready` surfaces work | Scroll conversation for todos |
|
||||
| **Complexity** | Handles nested epics, blockers | Flat list only |
|
||||
| **Visibility** | Background structure, not in conversation | Visible to user in chat |
|
||||
| **Setup** | Requires `.beads/` directory in project | Always available |
|
||||
| **Best for** | Complex, multi-session, explorative | Simple, single-session, linear |
|
||||
| **Context capture** | Design notes, acceptance criteria, links | Just task description |
|
||||
| **Evolution** | Issues can be updated, refined over time | Static once written |
|
||||
| **Audit trail** | Full history of changes | Only visible in conversation |
|
||||
|
||||
## 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: Strategic Document Development
|
||||
|
||||
**Scenario**: Developing policy proposal requiring research, stakeholder analysis, evidence gathering.
|
||||
|
||||
**Why bd**:
|
||||
- Multi-session research across days
|
||||
- Fuzzy boundaries - scope emerges through investigation
|
||||
- Side quests - discover related policies to analyze
|
||||
- Dependencies - can't write recommendations until research complete
|
||||
- Project memory - need to resume after interruptions
|
||||
|
||||
**bd structure**:
|
||||
```
|
||||
barb-epic: "Develop BARB metrics policy proposal"
|
||||
├─ barb-1: "Research existing BARB documentation"
|
||||
├─ barb-2: "Analyze stakeholder positions" (blocks recommendations)
|
||||
├─ barb-3: "Gather evidence for alternative approaches"
|
||||
└─ barb-4: "Draft policy recommendations" (blocked by barb-2)
|
||||
```
|
||||
|
||||
**TodoWrite role**: None initially. Might use TodoWrite for single-session writing sprints once research complete.
|
||||
|
||||
### 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.
|
||||
|
||||
## 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.
|
||||
365
examples/claude-code-skill/references/CLI_REFERENCE.md
Normal file
365
examples/claude-code-skill/references/CLI_REFERENCE.md
Normal file
@@ -0,0 +1,365 @@
|
||||
# CLI Reference
|
||||
|
||||
Complete command reference for bd (beads) CLI tool. All commands support `--json` flag for structured output.
|
||||
|
||||
## Contents
|
||||
|
||||
- [Quick Reference](#quick-reference)
|
||||
- [Global Flags](#global-flags)
|
||||
- [Core Commands](#core-commands)
|
||||
- [bd ready](#bd-ready) - Find unblocked work
|
||||
- [bd create](#bd-create) - Create new issues
|
||||
- [bd update](#bd-update) - Update issue status, priority, assignee
|
||||
- [bd close](#bd-close) - Close completed work
|
||||
- [bd show](#bd-show) - Show issue details
|
||||
- [bd list](#bd-list) - List issues with filters
|
||||
- [Dependency Commands](#dependency-commands)
|
||||
- [bd dep add](#bd-dep-add) - Create dependencies
|
||||
- [bd dep tree](#bd-dep-tree) - Visualize dependency trees
|
||||
- [bd dep cycles](#bd-dep-cycles) - Detect circular dependencies
|
||||
- [Monitoring Commands](#monitoring-commands)
|
||||
- [bd stats](#bd-stats) - Project statistics
|
||||
- [bd blocked](#bd-blocked) - Find blocked work
|
||||
- [Setup Commands](#setup-commands)
|
||||
- [bd init](#bd-init) - Initialize database
|
||||
- [bd quickstart](#bd-quickstart) - Show quick start guide
|
||||
- [Common Workflows](#common-workflows)
|
||||
- [JSON Output](#json-output)
|
||||
- [Database Auto-Discovery](#database-auto-discovery)
|
||||
- [Git Integration](#git-integration)
|
||||
- [Tips](#tips)
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Command | Purpose | Key Flags |
|
||||
|---------|---------|-----------|
|
||||
| `bd ready` | Find unblocked work | `--priority`, `--assignee`, `--limit`, `--json` |
|
||||
| `bd list` | List all issues with filters | `--status`, `--priority`, `--type`, `--assignee` |
|
||||
| `bd show` | Show issue details | `--json` |
|
||||
| `bd create` | Create new issue | `-t`, `-p`, `-d`, `--design`, `--acceptance` |
|
||||
| `bd update` | Update existing issue | `--status`, `--priority`, `--design` |
|
||||
| `bd close` | Close completed issue | `--reason` |
|
||||
| `bd dep add` | Add dependency | `--type` (blocks, related, parent-child, discovered-from) |
|
||||
| `bd dep tree` | Visualize dependency tree | (no flags) |
|
||||
| `bd dep cycles` | Detect circular dependencies | (no flags) |
|
||||
| `bd stats` | Get project statistics | `--json` |
|
||||
| `bd blocked` | Find blocked issues | `--json` |
|
||||
| `bd init` | Initialize bd in directory | `--prefix` |
|
||||
| `bd quickstart` | Show quick start guide | (no flags) |
|
||||
|
||||
## Global Flags
|
||||
|
||||
Available for all commands:
|
||||
|
||||
```bash
|
||||
--json # Output in JSON format
|
||||
--db /path/to/db # Specify database path (default: auto-discover)
|
||||
--actor "name" # Actor name for audit trail
|
||||
--no-auto-flush # Disable automatic JSONL sync
|
||||
--no-auto-import # Disable automatic JSONL import
|
||||
```
|
||||
|
||||
## Core Commands
|
||||
|
||||
### bd ready
|
||||
|
||||
Find tasks with no blockers - ready to be worked on.
|
||||
|
||||
```bash
|
||||
bd ready # All ready work
|
||||
bd ready --json # JSON format
|
||||
bd ready --priority 0 # Only priority 0 (critical)
|
||||
bd ready --assignee alice # Only assigned to alice
|
||||
bd ready --limit 5 # Limit to 5 results
|
||||
```
|
||||
|
||||
**Use at session start** to see available work.
|
||||
|
||||
---
|
||||
|
||||
### bd create
|
||||
|
||||
Create a new issue with optional metadata.
|
||||
|
||||
```bash
|
||||
bd create "Title"
|
||||
bd create "Title" -t bug -p 0
|
||||
bd create "Title" -d "Description"
|
||||
bd create "Title" --design "Design notes"
|
||||
bd create "Title" --acceptance "Definition of done"
|
||||
bd create "Title" --assignee alice
|
||||
```
|
||||
|
||||
**Flags**:
|
||||
- `-t, --type`: task (default), bug, feature, epic, chore
|
||||
- `-p, --priority`: 0-3 (default: 2)
|
||||
- `-d, --description`: Issue description
|
||||
- `--design`: Design notes
|
||||
- `--acceptance`: Acceptance criteria
|
||||
- `--assignee`: Who should work on this
|
||||
|
||||
---
|
||||
|
||||
### bd update
|
||||
|
||||
Update an existing issue's metadata.
|
||||
|
||||
```bash
|
||||
bd update issue-123 --status in_progress
|
||||
bd update issue-123 --priority 0
|
||||
bd update issue-123 --design "Decided to use Redis"
|
||||
bd update issue-123 --acceptance "Tests passing"
|
||||
```
|
||||
|
||||
**Status values**: open, in_progress, blocked, closed
|
||||
|
||||
---
|
||||
|
||||
### bd close
|
||||
|
||||
Close (complete) an issue.
|
||||
|
||||
```bash
|
||||
bd close issue-123
|
||||
bd close issue-123 --reason "Implemented in PR #42"
|
||||
bd close issue-1 issue-2 issue-3 --reason "Bulk close"
|
||||
```
|
||||
|
||||
**Note**: Closed issues remain in database for history.
|
||||
|
||||
---
|
||||
|
||||
### bd show
|
||||
|
||||
Show detailed information about a specific issue.
|
||||
|
||||
```bash
|
||||
bd show issue-123
|
||||
bd show issue-123 --json
|
||||
```
|
||||
|
||||
Shows: all fields, dependencies, dependents, audit history.
|
||||
|
||||
---
|
||||
|
||||
### bd list
|
||||
|
||||
List all issues with optional filters.
|
||||
|
||||
```bash
|
||||
bd list # All issues
|
||||
bd list --status open # Only open
|
||||
bd list --priority 0 # Critical
|
||||
bd list --type bug # Only bugs
|
||||
bd list --assignee alice # By assignee
|
||||
bd list --status closed --limit 10 # Recent completions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dependency Commands
|
||||
|
||||
### bd dep add
|
||||
|
||||
Add a dependency between issues.
|
||||
|
||||
```bash
|
||||
bd dep add from-issue to-issue # blocks (default)
|
||||
bd dep add from-issue to-issue --type blocks
|
||||
bd dep add from-issue to-issue --type related
|
||||
bd dep add epic-id task-id --type parent-child
|
||||
bd dep add original-id found-id --type discovered-from
|
||||
```
|
||||
|
||||
**Dependency types**:
|
||||
1. **blocks**: from-issue blocks to-issue (hard blocker)
|
||||
2. **related**: Soft link (no blocking)
|
||||
3. **parent-child**: Epic/subtask hierarchy
|
||||
4. **discovered-from**: Tracks origin of discovery
|
||||
|
||||
---
|
||||
|
||||
### bd dep tree
|
||||
|
||||
Visualize full dependency tree for an issue.
|
||||
|
||||
```bash
|
||||
bd dep tree issue-123
|
||||
```
|
||||
|
||||
Shows all dependencies and dependents in tree format.
|
||||
|
||||
---
|
||||
|
||||
### bd dep cycles
|
||||
|
||||
Detect circular dependencies.
|
||||
|
||||
```bash
|
||||
bd dep cycles
|
||||
```
|
||||
|
||||
Finds dependency cycles that would prevent work from being ready.
|
||||
|
||||
---
|
||||
|
||||
## Monitoring Commands
|
||||
|
||||
### bd stats
|
||||
|
||||
Get project statistics.
|
||||
|
||||
```bash
|
||||
bd stats
|
||||
bd stats --json
|
||||
```
|
||||
|
||||
Returns: total, open, in_progress, closed, blocked, ready, avg lead time.
|
||||
|
||||
---
|
||||
|
||||
### bd blocked
|
||||
|
||||
Get blocked issues with blocker information.
|
||||
|
||||
```bash
|
||||
bd blocked
|
||||
bd blocked --json
|
||||
```
|
||||
|
||||
Use to identify bottlenecks when ready list is empty.
|
||||
|
||||
---
|
||||
|
||||
## Setup Commands
|
||||
|
||||
### bd init
|
||||
|
||||
Initialize bd in current directory.
|
||||
|
||||
```bash
|
||||
bd init # Auto-detect prefix
|
||||
bd init --prefix api # Custom prefix
|
||||
```
|
||||
|
||||
Creates `.beads/` directory and database.
|
||||
|
||||
---
|
||||
|
||||
### bd quickstart
|
||||
|
||||
Show comprehensive quick start guide.
|
||||
|
||||
```bash
|
||||
bd quickstart
|
||||
```
|
||||
|
||||
Displays built-in reference for command syntax and workflows.
|
||||
|
||||
---
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Session Start
|
||||
|
||||
```bash
|
||||
bd ready --json
|
||||
bd show issue-123
|
||||
bd update issue-123 --status in_progress
|
||||
```
|
||||
|
||||
### Discovery During Work
|
||||
|
||||
```bash
|
||||
bd create "Found: bug in auth" -t bug
|
||||
bd dep add current-issue new-issue --type discovered-from
|
||||
```
|
||||
|
||||
### Completing Work
|
||||
|
||||
```bash
|
||||
bd close issue-123 --reason "Implemented with tests passing"
|
||||
bd ready # See what unblocked
|
||||
```
|
||||
|
||||
### Planning Epic
|
||||
|
||||
```bash
|
||||
bd create "OAuth Integration" -t epic
|
||||
bd create "Set up credentials" -t task
|
||||
bd create "Implement flow" -t task
|
||||
|
||||
bd dep add oauth-epic oauth-creds --type parent-child
|
||||
bd dep add oauth-epic oauth-flow --type parent-child
|
||||
bd dep add oauth-creds oauth-flow # creds blocks flow
|
||||
|
||||
bd dep tree oauth-epic
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## JSON Output
|
||||
|
||||
All commands support `--json` for structured output:
|
||||
|
||||
```bash
|
||||
bd ready --json
|
||||
bd show issue-123 --json
|
||||
bd list --status open --json
|
||||
bd stats --json
|
||||
```
|
||||
|
||||
Use when parsing programmatically or extracting specific fields.
|
||||
|
||||
---
|
||||
|
||||
## Database Auto-Discovery
|
||||
|
||||
bd finds database in this order:
|
||||
|
||||
1. `--db` flag: `bd ready --db /path/to/db.db`
|
||||
2. `$BEADS_DB` environment variable
|
||||
3. `.beads/*.db` in current directory or ancestors
|
||||
4. `~/.beads/default.db` as fallback
|
||||
|
||||
**Project-local** (`.beads/`): Project-specific work, git-tracked
|
||||
|
||||
**Global fallback** (`~/.beads/`): Cross-project tracking, personal tasks
|
||||
|
||||
---
|
||||
|
||||
## Git Integration
|
||||
|
||||
bd automatically syncs with git:
|
||||
|
||||
- **After each operation**: Exports to JSONL (5s debounce)
|
||||
- **After git pull**: Imports from JSONL if newer than DB
|
||||
|
||||
**Files**:
|
||||
- `.beads/*.jsonl` - Source of truth (git-tracked)
|
||||
- `.beads/*.db` - Local cache (gitignored)
|
||||
|
||||
---
|
||||
|
||||
## Tips
|
||||
|
||||
**Use JSON for parsing**:
|
||||
```bash
|
||||
bd ready --json | jq '.[0].id'
|
||||
```
|
||||
|
||||
**Bulk operations**:
|
||||
```bash
|
||||
bd close issue-1 issue-2 issue-3 --reason "Sprint complete"
|
||||
```
|
||||
|
||||
**Quick filtering**:
|
||||
```bash
|
||||
bd list --status open --priority 0 --type bug
|
||||
```
|
||||
|
||||
**Built-in help**:
|
||||
```bash
|
||||
bd quickstart # Comprehensive guide
|
||||
bd create --help # Command-specific help
|
||||
```
|
||||
747
examples/claude-code-skill/references/DEPENDENCIES.md
Normal file
747
examples/claude-code-skill/references/DEPENDENCIES.md
Normal file
@@ -0,0 +1,747 @@
|
||||
# Dependency Types Guide
|
||||
|
||||
Deep dive into bd's four dependency types: blocks, related, parent-child, and discovered-from.
|
||||
|
||||
## Contents
|
||||
|
||||
- [Overview](#overview) - Four types at a glance, which affect bd ready?
|
||||
- [blocks - Hard Blocker](#blocks---hard-blocker)
|
||||
- [When to Use](#when-to-use) - Prerequisites, sequential steps, build order
|
||||
- [When NOT to Use](#when-not-to-use) - Soft preferences, parallel work
|
||||
- [Examples](#examples) - API development, migrations, library dependencies
|
||||
- [Creating blocks Dependencies](#creating-blocks-dependencies)
|
||||
- [Common Patterns](#common-patterns) - Build foundation first, migration sequences, testing gates
|
||||
- [Automatic Unblocking](#automatic-unblocking)
|
||||
- [related - Soft Link](#related---soft-link)
|
||||
- [When to Use](#when-to-use-1) - Context, related features, parallel work
|
||||
- [When NOT to Use](#when-not-to-use-1)
|
||||
- [Examples](#examples-1) - Feature context, research links, parallel development
|
||||
- [Creating related Dependencies](#creating-related-dependencies)
|
||||
- [Common Patterns](#common-patterns-1) - Context clusters, research threads, feature families
|
||||
- [parent-child - Hierarchical](#parent-child---hierarchical)
|
||||
- [When to Use](#when-to-use-2) - Epics/subtasks, phases
|
||||
- [When NOT to Use](#when-not-to-use-2)
|
||||
- [Examples](#examples-2) - Epic with subtasks, phased projects
|
||||
- [Creating parent-child Dependencies](#creating-parent-child-dependencies)
|
||||
- [Combining with blocks](#combining-with-blocks)
|
||||
- [Common Patterns](#common-patterns-2) - Epic decomposition, nested hierarchies
|
||||
- [discovered-from - Provenance](#discovered-from---provenance)
|
||||
- [When to Use](#when-to-use-3) - Side quests, research findings
|
||||
- [Why This Matters](#why-this-matters)
|
||||
- [Examples](#examples-3) - Bug discovered during feature work, research branches
|
||||
- [Creating discovered-from Dependencies](#creating-discovered-from-dependencies)
|
||||
- [Common Patterns](#common-patterns-3) - Discovery during implementation, research expansion
|
||||
- [Combining with blocks](#combining-with-blocks-1)
|
||||
- [Decision Guide](#decision-guide)
|
||||
- [Decision Tree](#decision-tree)
|
||||
- [Quick Reference by Situation](#quick-reference-by-situation)
|
||||
- [Common Mistakes](#common-mistakes)
|
||||
- Using blocks for preferences, using discovered-from for planning, not using dependencies, over-using blocks, wrong direction
|
||||
- [Advanced Patterns](#advanced-patterns)
|
||||
- Diamond dependencies, optional dependencies, discovery cascade, epic with phases
|
||||
- [Visualization](#visualization)
|
||||
- [Summary](#summary)
|
||||
|
||||
## Overview
|
||||
|
||||
bd supports four dependency types that serve different purposes in organizing and tracking work:
|
||||
|
||||
| Type | Purpose | Affects `bd ready`? | Common Use |
|
||||
|------|---------|---------------------|------------|
|
||||
| **blocks** | Hard blocker | Yes - blocked issues excluded | Sequential work, prerequisites |
|
||||
| **related** | Soft link | No - just informational | Context, related work |
|
||||
| **parent-child** | Hierarchy | No - structural only | Epics and subtasks |
|
||||
| **discovered-from** | Provenance | No - tracks origin | Side quests, research findings |
|
||||
|
||||
**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
|
||||
|
||||
```bash
|
||||
bd dep add prerequisite-issue blocked-issue
|
||||
# or explicitly:
|
||||
bd dep add prerequisite-issue blocked-issue --type blocks
|
||||
```
|
||||
|
||||
**Direction matters**: `from_id` blocks `to_id`. Think: "prerequisite blocks dependent".
|
||||
|
||||
### 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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
bd dep add parent-epic-id child-task-id --type parent-child
|
||||
```
|
||||
|
||||
**Direction matters**: `from_id` is parent, `to_id` is child.
|
||||
|
||||
### 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 epic when all children complete.
|
||||
```
|
||||
|
||||
**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
|
||||
|
||||
```bash
|
||||
bd dep add original-work-id discovered-issue-id --type discovered-from
|
||||
```
|
||||
|
||||
**Direction matters**: `to_id` was discovered while working on `from_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
|
||||
|
||||
| Situation | Use |
|
||||
|-----------|-----|
|
||||
| B needs A complete to start | blocks |
|
||||
| B is part of A (epic/task) | parent-child |
|
||||
| Found B while working on A | discovered-from |
|
||||
| A and B are similar/connected | related |
|
||||
| B should come after A but could start | related + note |
|
||||
| A and B are alternatives | related |
|
||||
| B is follow-up to A | discovered-from |
|
||||
|
||||
---
|
||||
|
||||
## 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**:
|
||||
```bash
|
||||
bd dep add api-endpoint database-schema
|
||||
|
||||
Meaning: api-endpoint blocks database-schema
|
||||
```
|
||||
|
||||
**Problem**: Backwards! Schema should block endpoint, not other way around.
|
||||
|
||||
**Right**:
|
||||
```bash
|
||||
bd dep add database-schema api-endpoint
|
||||
|
||||
Meaning: database-schema blocks api-endpoint
|
||||
```
|
||||
|
||||
**Mnemonic**: "from_id blocks to_id" or "prerequisite blocks dependent"
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
387
examples/claude-code-skill/references/WORKFLOWS.md
Normal file
387
examples/claude-code-skill/references/WORKFLOWS.md
Normal file
@@ -0,0 +1,387 @@
|
||||
# Workflows and Checklists
|
||||
|
||||
Detailed step-by-step workflows for common bd usage patterns with checklists.
|
||||
|
||||
## Contents
|
||||
|
||||
- [Session Start Workflow](#session-start) - Check bd ready, establish context
|
||||
- [Discovery and Issue Creation](#discovery) - Proactive issue creation during work
|
||||
- [Status Maintenance](#status-maintenance) - Keeping bd status current
|
||||
- [Epic Planning](#epic-planning) - Structuring complex work with dependencies
|
||||
- [Side Quest Handling](#side-quests) - Discovery during main task, assessing blocker vs deferrable, resuming
|
||||
- [Multi-Session Resume](#resume) - Returning after days/weeks away
|
||||
- [Unblocking Work](#unblocking) - Handling blocked issues
|
||||
- [Integration with TodoWrite](#integration-with-todowrite) - Using both tools together
|
||||
- [Common Workflow Patterns](#common-workflow-patterns)
|
||||
- Systematic Exploration, Bug Investigation, Refactoring with Dependencies, Spike Investigation
|
||||
- [Checklist Templates](#checklist-templates)
|
||||
- Starting Any Work Session, Creating Issues During Work, Completing Work, Planning Complex Features
|
||||
- [Decision Points](#decision-points)
|
||||
- [Troubleshooting Workflows](#troubleshooting-workflows)
|
||||
|
||||
## Session Start Workflow {#session-start}
|
||||
|
||||
**bd is available when**:
|
||||
- Project has `.beads/` directory (project-local), OR
|
||||
- `~/.beads/` exists (global fallback for any directory)
|
||||
|
||||
**Automatic checklist at session start:**
|
||||
|
||||
```
|
||||
Session Start (when bd is available):
|
||||
- [ ] Run bd ready --json
|
||||
- [ ] Report: "X items ready to work on: [summary]"
|
||||
- [ ] If using global ~/.beads, note this in report
|
||||
- [ ] If none ready, check bd blocked --json
|
||||
- [ ] Suggest next action based on findings
|
||||
```
|
||||
|
||||
**Pattern**: Always run `bd ready` when starting work where bd is available. Report status immediately to establish shared context.
|
||||
|
||||
**Database selection**: bd auto-discovers which database to use (project-local `.beads/` takes precedence over global `~/.beads/`).
|
||||
|
||||
---
|
||||
|
||||
## Discovery and Issue Creation {#discovery}
|
||||
|
||||
**When encountering new work during implementation:**
|
||||
|
||||
```
|
||||
Discovery Workflow:
|
||||
- [ ] Notice bug, improvement, or follow-up work
|
||||
- [ ] Assess: Can defer or is blocker?
|
||||
- [ ] Create issue with bd create "Issue title"
|
||||
- [ ] Add discovered-from dependency: bd dep add current-id new-id --type discovered-from
|
||||
- [ ] If blocker: pause and switch; if not: continue current work
|
||||
- [ ] Issue persists for future sessions
|
||||
```
|
||||
|
||||
**Pattern**: Proactively file issues as you discover work. Context captured immediately instead of lost when session ends.
|
||||
|
||||
**When to ask first**:
|
||||
- Knowledge work with fuzzy scope
|
||||
- User intent unclear
|
||||
- Multiple valid approaches
|
||||
|
||||
**When to create directly**:
|
||||
- Clear bug found
|
||||
- Obvious follow-up work
|
||||
- Technical debt with clear scope
|
||||
|
||||
---
|
||||
|
||||
## Status Maintenance {#status-maintenance}
|
||||
|
||||
**Throughout work on an issue:**
|
||||
|
||||
```
|
||||
Issue Lifecycle:
|
||||
- [ ] Start: Update status to in_progress
|
||||
- [ ] During: Add design notes as decisions made
|
||||
- [ ] During: Update acceptance criteria if requirements clarify
|
||||
- [ ] During: Add dependencies if blockers discovered
|
||||
- [ ] Complete: Close with summary of what was done
|
||||
- [ ] After: Check bd ready to see what unblocked
|
||||
```
|
||||
|
||||
**Pattern**: Keep bd status current so project state is always accurate.
|
||||
|
||||
**Status transitions**:
|
||||
- `open` → `in_progress` when starting work
|
||||
- `in_progress` → `blocked` if blocker discovered
|
||||
- `blocked` → `in_progress` when unblocked
|
||||
- `in_progress` → `closed` when complete
|
||||
|
||||
---
|
||||
|
||||
## Epic Planning {#epic-planning}
|
||||
|
||||
**For complex multi-step features:**
|
||||
|
||||
```
|
||||
Epic Planning Workflow:
|
||||
- [ ] Create epic issue for high-level goal
|
||||
- [ ] Break down into child task issues
|
||||
- [ ] Create each child task
|
||||
- [ ] Add parent-child dependencies from epic to each child
|
||||
- [ ] Add blocks dependencies between children if needed
|
||||
- [ ] Use bd ready to work through tasks in dependency order
|
||||
```
|
||||
|
||||
**Example**: OAuth Integration Epic
|
||||
|
||||
```bash
|
||||
1. Create epic:
|
||||
bd create "Implement OAuth integration" -t epic -d "OAuth with Google and GitHub"
|
||||
design: "Support Google and GitHub providers"
|
||||
|
||||
2. Create child tasks:
|
||||
bd create "Set up OAuth client credentials" -t task
|
||||
bd create "Implement authorization code flow" -t task
|
||||
bd create "Add token storage and refresh" -t task
|
||||
bd create "Create login/logout endpoints" -t task
|
||||
|
||||
3. Link children to parent:
|
||||
bd dep add oauth-epic oauth-setup --type parent-child
|
||||
bd dep add oauth-epic oauth-flow --type parent-child
|
||||
bd dep add oauth-epic oauth-storage --type parent-child
|
||||
bd dep add oauth-epic oauth-endpoints --type parent-child
|
||||
|
||||
4. Add blocks between children:
|
||||
bd dep add oauth-setup oauth-flow
|
||||
# Setup blocks flow implementation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Side Quest Handling {#side-quests}
|
||||
|
||||
**When discovering work that pauses main task:**
|
||||
|
||||
```
|
||||
Side Quest Workflow:
|
||||
- [ ] During main work, discover problem or opportunity
|
||||
- [ ] Create issue for side quest
|
||||
- [ ] Add discovered-from dependency linking to main work
|
||||
- [ ] Assess: blocker or can defer?
|
||||
- [ ] If blocker: mark main work blocked, switch to side quest
|
||||
- [ ] If deferrable: note in issue, continue main work
|
||||
- [ ] Update statuses to reflect current focus
|
||||
```
|
||||
|
||||
**Example**: During feature implementation, discover architectural issue
|
||||
|
||||
```
|
||||
Main task: Adding user profiles
|
||||
|
||||
Discovery: Notice auth system should use role-based access
|
||||
|
||||
Actions:
|
||||
1. Create issue: "Implement role-based access control"
|
||||
2. Link: discovered-from "user-profiles-feature"
|
||||
3. Assess: Blocker for profiles feature
|
||||
4. Mark profiles as blocked
|
||||
5. Switch to RBAC implementation
|
||||
6. Complete RBAC, unblocks profiles
|
||||
7. Resume profiles work
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Multi-Session Resume {#resume}
|
||||
|
||||
**Starting work after days/weeks away:**
|
||||
|
||||
```
|
||||
Resume Workflow:
|
||||
- [ ] Run bd ready to see available work
|
||||
- [ ] Run bd stats for project overview
|
||||
- [ ] List recent closed issues for context
|
||||
- [ ] Show details on issue to work on
|
||||
- [ ] Review design notes and acceptance criteria
|
||||
- [ ] Update status to in_progress
|
||||
- [ ] Begin work with full context
|
||||
```
|
||||
|
||||
**Why this works**: bd preserves design decisions, acceptance criteria, and dependency context. No scrolling conversation history or reconstructing from markdown.
|
||||
|
||||
---
|
||||
|
||||
## Unblocking Work {#unblocking}
|
||||
|
||||
**When ready list is empty:**
|
||||
|
||||
```
|
||||
Unblocking Workflow:
|
||||
- [ ] Run bd blocked --json to see what's stuck
|
||||
- [ ] Show details on blocked issues: bd show issue-id
|
||||
- [ ] Identify blocker issues
|
||||
- [ ] Choose: work on blocker, or reassess dependency
|
||||
- [ ] If reassess: remove incorrect dependency
|
||||
- [ ] If work on blocker: close blocker, check ready again
|
||||
- [ ] Blocked issues automatically become ready when blockers close
|
||||
```
|
||||
|
||||
**Pattern**: bd automatically maintains ready state based on dependencies. Closing a blocker makes blocked work ready.
|
||||
|
||||
**Example**:
|
||||
|
||||
```
|
||||
Situation: bd ready shows nothing
|
||||
|
||||
Actions:
|
||||
1. bd blocked shows: "api-endpoint blocked by db-schema"
|
||||
2. Show db-schema: "Create user table schema"
|
||||
3. Work on db-schema issue
|
||||
4. Close db-schema when done
|
||||
5. bd ready now shows: "api-endpoint" (automatically unblocked)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with TodoWrite
|
||||
|
||||
**Using both tools in one session:**
|
||||
|
||||
```
|
||||
Hybrid Workflow:
|
||||
- [ ] Check bd for high-level context
|
||||
- [ ] Choose bd issue to work on
|
||||
- [ ] Mark bd issue in_progress
|
||||
- [ ] Create TodoWrite from acceptance criteria for execution
|
||||
- [ ] Work through TodoWrite items
|
||||
- [ ] Update bd design notes as you learn
|
||||
- [ ] When TodoWrite complete, close bd issue
|
||||
```
|
||||
|
||||
**Why hybrid**: bd provides persistent structure, TodoWrite provides visible progress.
|
||||
|
||||
---
|
||||
|
||||
## Common Workflow Patterns
|
||||
|
||||
### Pattern: Systematic Exploration
|
||||
|
||||
Research or investigation work:
|
||||
|
||||
```
|
||||
1. Create research issue with question to answer
|
||||
2. Update design field with findings as you go
|
||||
3. Create new issues for discoveries
|
||||
4. Link discoveries with discovered-from
|
||||
5. Close research issue with conclusion
|
||||
```
|
||||
|
||||
### Pattern: Bug Investigation
|
||||
|
||||
```
|
||||
1. Create bug issue
|
||||
2. Reproduce: note steps in description
|
||||
3. Investigate: track hypotheses in design field
|
||||
4. Fix: implement solution
|
||||
5. Test: verify in acceptance criteria
|
||||
6. Close with explanation of root cause and fix
|
||||
```
|
||||
|
||||
### Pattern: Refactoring with Dependencies
|
||||
|
||||
```
|
||||
1. Create issues for each refactoring step
|
||||
2. Add blocks dependencies for correct order
|
||||
3. Work through in dependency order
|
||||
4. bd ready automatically shows next step
|
||||
5. Each completion unblocks next work
|
||||
```
|
||||
|
||||
### Pattern: Spike Investigation
|
||||
|
||||
```
|
||||
1. Create spike issue: "Investigate caching options"
|
||||
2. Time-box exploration
|
||||
3. Document findings in design field
|
||||
4. Create follow-up issues for chosen approach
|
||||
5. Link follow-ups with discovered-from
|
||||
6. Close spike with recommendation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checklist Templates
|
||||
|
||||
### Starting Any Work Session
|
||||
|
||||
```
|
||||
- [ ] Check for .beads/ directory
|
||||
- [ ] If exists: bd ready
|
||||
- [ ] Report status to user
|
||||
- [ ] Get user input on what to work on
|
||||
- [ ] Show issue details
|
||||
- [ ] Update to in_progress
|
||||
- [ ] Begin work
|
||||
```
|
||||
|
||||
### Creating Issues During Work
|
||||
|
||||
```
|
||||
- [ ] Notice new work needed
|
||||
- [ ] Create issue with clear title
|
||||
- [ ] Add context in description
|
||||
- [ ] Link with discovered-from to current work
|
||||
- [ ] Assess blocker vs deferrable
|
||||
- [ ] Update statuses appropriately
|
||||
```
|
||||
|
||||
### Completing Work
|
||||
|
||||
```
|
||||
- [ ] Implementation done
|
||||
- [ ] Tests passing
|
||||
- [ ] Close issue with summary
|
||||
- [ ] Check bd ready for unblocked work
|
||||
- [ ] Report completion and next available work
|
||||
```
|
||||
|
||||
### Planning Complex Features
|
||||
|
||||
```
|
||||
- [ ] Create epic for overall goal
|
||||
- [ ] Break into child tasks
|
||||
- [ ] Create all child issues
|
||||
- [ ] Link with parent-child dependencies
|
||||
- [ ] Add blocks between children if order matters
|
||||
- [ ] Work through in dependency order
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Decision Points
|
||||
|
||||
**Should I create a bd issue or use TodoWrite?**
|
||||
→ See [BOUNDARIES.md](BOUNDARIES.md) for decision matrix
|
||||
|
||||
**Should I ask user before creating issue?**
|
||||
→ Ask if scope unclear; create if obvious follow-up work
|
||||
|
||||
**Should I mark work as blocked or just note dependency?**
|
||||
→ Blocked = can't proceed; dependency = need to track relationship
|
||||
|
||||
**Should I create epic or just tasks?**
|
||||
→ Epic if 5+ related tasks; tasks if simpler structure
|
||||
|
||||
**Should I update status frequently or just at start/end?**
|
||||
→ Start and end minimum; during work if significant changes
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Workflows
|
||||
|
||||
**"I can't find any ready work"**
|
||||
1. Run bd blocked
|
||||
2. Identify what's blocking progress
|
||||
3. Either work on blockers or create new work
|
||||
|
||||
**"I created an issue but it's not showing in ready"**
|
||||
1. Run bd show on the issue
|
||||
2. Check dependencies field
|
||||
3. If blocked, resolve blocker first
|
||||
4. If incorrectly blocked, remove dependency
|
||||
|
||||
**"Work is more complex than expected"**
|
||||
1. Transition from TodoWrite to bd mid-session
|
||||
2. Create bd issue with current context
|
||||
3. Note: "Discovered complexity during implementation"
|
||||
4. Add dependencies as discovered
|
||||
5. Continue with bd tracking
|
||||
|
||||
**"I closed an issue but work isn't done"**
|
||||
1. Reopen with bd update status=open
|
||||
2. Or create new issue linking to closed one
|
||||
3. Note what's still needed
|
||||
4. Closed issues can't be reopened in some systems, so create new if needed
|
||||
|
||||
**"Too many issues, can't find what matters"**
|
||||
1. Use bd list with filters (priority, issue_type)
|
||||
2. Use bd ready to focus on unblocked work
|
||||
3. Consider closing old issues that no longer matter
|
||||
4. Use labels for organization
|
||||
|
||||
Reference in New Issue
Block a user