Add Claude Code skill for beads usage

- Provides comprehensive workflow patterns and decision criteria - Includes quick reference (SKILL.md) and detailed references - Teaches when to use bd vs markdown/TodoWrite - Covers dependency types and issue lifecycle management - Complements existing plugin with usage philosophy
2025-10-18 17:54:46 +01:00
parent 9d78a66dc3
commit 7f93a602d2
7 changed files with 2494 additions and 0 deletions
@@ -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
@@ -0,0 +1,131 @@
 # 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
 ## 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).
@@ -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 |
@@ -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.
@@ -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
 ```
@@ -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.
@@ -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