diff --git a/examples/README.md b/examples/README.md
index c5dc9deb..01c90592 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -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
 
diff --git a/examples/claude-code-skill/README.md b/examples/claude-code-skill/README.md
new file mode 100644
index 00000000..db19d1e9
--- /dev/null
+++ b/examples/claude-code-skill/README.md
@@ -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).
diff --git a/examples/claude-code-skill/SKILL.md b/examples/claude-code-skill/SKILL.md
new file mode 100644
index 00000000..3e01e06f
--- /dev/null
+++ b/examples/claude-code-skill/SKILL.md
@@ -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 |
diff --git a/examples/claude-code-skill/references/BOUNDARIES.md b/examples/claude-code-skill/references/BOUNDARIES.md
new file mode 100644
index 00000000..b88eb2f1
--- /dev/null
+++ b/examples/claude-code-skill/references/BOUNDARIES.md
@@ -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.
diff --git a/examples/claude-code-skill/references/CLI_REFERENCE.md b/examples/claude-code-skill/references/CLI_REFERENCE.md
new file mode 100644
index 00000000..91113e7b
--- /dev/null
+++ b/examples/claude-code-skill/references/CLI_REFERENCE.md
@@ -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
+```
diff --git a/examples/claude-code-skill/references/DEPENDENCIES.md b/examples/claude-code-skill/references/DEPENDENCIES.md
new file mode 100644
index 00000000..77b1733c
--- /dev/null
+++ b/examples/claude-code-skill/references/DEPENDENCIES.md
@@ -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.
diff --git a/examples/claude-code-skill/references/WORKFLOWS.md b/examples/claude-code-skill/references/WORKFLOWS.md
new file mode 100644
index 00000000..e4e6add8
--- /dev/null
+++ b/examples/claude-code-skill/references/WORKFLOWS.md
@@ -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
+