johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: move Claude Code plugin to dedicated subdirectory (GH#985)

Browse Source 
Move all plugin content to claude-plugin/ subdirectory for cleaner
separation from core beads functionality:

- claude-plugin/.claude-plugin/plugin.json - plugin manifest
- claude-plugin/commands/ - all slash commands
- claude-plugin/agents/ - task-agent (now in correct location)
- claude-plugin/skills/beads/ - beads skill with resources

Root .claude-plugin/ now only contains marketplace.json pointing
to ./claude-plugin.

Note: After updating, users may need to clear plugin cache:
  rm -rf ~/.claude/plugins/cache/beads-marketplace/

Fixes #985

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Executed-By: beads/crew/dave
Rig: beads
Role: crew
This commit is contained in:
beads/crew/dave
2026-01-09 22:59:02 -08:00
committed by Steve Yegge
parent 0777bb907c
commit f03c754df1
52 changed files with 1 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
claude-plugin/skills/beads/CLAUDE.md Normal file
View File

@@ -0,0 +1,86 @@
# Beads Skill Maintenance Guide
## Architecture Decisions
ADRs in `adr/` document key decisions. These are NOT loaded during skill invocation—they're reference material for maintainers making changes.
| ADR | Decision |
|-----|----------|
| [ADR-0001](adr/0001-bd-prime-as-source-of-truth.md) | Use `bd prime` as CLI reference source of truth |
## Key Principle: DRY via bd prime
**NEVER duplicate CLI documentation in SKILL.md or resources.**
- `bd prime` outputs AI-optimized workflow context
- `bd <command> --help` provides specific usage
- Both auto-update with bd releases
**SKILL.md should only contain:**
- Decision frameworks (bd vs TodoWrite)
- Prerequisites (install verification)
- Resource index (progressive disclosure)
- Pointers to `bd prime` and `--help`
## Keeping the Skill Updated
### When bd releases new version:
1. **Check for new features**: `bd --help` for new commands
2. **Update SKILL.md frontmatter**: `version: "X.Y.Z"`
3. **Add resources for conceptual features** (agents, gates, chemistry patterns)
4. **Don't add CLI reference** — that's `bd prime`'s job
### What belongs in resources:
| Content Type | Belongs in Resources? | Why |
|--------------|----------------------|-----|
| Conceptual frameworks | ✅ Yes | bd prime doesn't explain "when to use" |
| Decision trees | ✅ Yes | Cognitive guidance, not CLI reference |
| Advanced patterns | ✅ Yes | Depth beyond `--help` |
| CLI command syntax | ❌ No | Use `bd <cmd> --help` |
| Workflow checklists | ❌ No | `bd prime` covers this |
### Resource update checklist:
```
[ ] Check if bd prime now covers this content
[ ] If yes, remove from resources (avoid duplication)
[ ] If no, update resource for new bd version
[ ] Update version compatibility in README.md
```
## File Roles
| File | Purpose | When to Update |
|------|---------|----------------|
| SKILL.md | Entry point, resource index | New features, version bumps |
| README.md | Human docs, installation | Structure changes |
| CLAUDE.md | This file, maintenance guide | Architecture changes |
| adr/*.md | Decision records | When making architectural decisions |
| resources/*.md | Deep-dive guides | New conceptual content |
## Testing Changes
After skill updates:
```bash
# Verify SKILL.md is within token budget
wc -w skills/beads/SKILL.md # Target: 400-600 words
# Verify links resolve
# (Manual check: ensure all resource links in SKILL.md exist)
# Verify bd prime still works
bd prime | head -20
```
## Attribution
Resources adapted from other sources should include attribution header:
```markdown
# Resource Title
> Adapted from [source]
```

120
claude-plugin/skills/beads/README.md Normal file
View File

@@ -0,0 +1,120 @@
# Beads Skill for Claude Code
A comprehensive skill for using [beads](https://github.com/steveyegge/beads) (bd) issue tracking with Claude Code.
## What This Skill Does
This skill teaches Claude Code how to use bd effectively for:
- **Multi-session work tracking** - Persistent memory across conversation compactions
- **Dependency management** - Graph-based issue relationships
- **Session handoff** - Writing notes that survive context resets
- **Molecules and wisps** (v0.34.0+) - Reusable work templates and ephemeral workflows
## Installation
Copy the `beads/` directory to your Claude Code skills location:
```bash
# Global installation
cp -r beads ~/.claude/skills/
# Or project-local
cp -r beads .claude/skills/
```
## When Claude Uses This Skill
The skill activates when conversations involve:
- "multi-session", "complex dependencies", "resume after weeks"
- "project memory", "persistent context", "side quest tracking"
- Work that spans multiple days or compaction cycles
- Tasks too complex for simple TodoWrite lists
## File Structure
```
beads/
├── SKILL.md # Main skill file (Claude reads this first)
├── CLAUDE.md # Maintenance guide for updating the skill
├── README.md # This file (for humans)
├── adr/ # Architectural Decision Records
│ └── 0001-bd-prime-as-source-of-truth.md
└── resources/ # Detailed documentation (loaded on demand)
├── BOUNDARIES.md # When to use bd vs TodoWrite
├── CLI_REFERENCE.md # CLI command reference
├── DEPENDENCIES.md # Dependency semantics (A blocks B vs B blocks A)
├── INTEGRATION_PATTERNS.md # TodoWrite and other tool integration
├── ISSUE_CREATION.md # When and how to create issues
├── MOLECULES.md # Protos, mols, wisps (v0.34.0+)
├── PATTERNS.md # Common usage patterns
├── RESUMABILITY.md # Writing notes for post-compaction recovery
├── STATIC_DATA.md # Using bd for reference databases
├── TROUBLESHOOTING.md # Common issues and fixes
├── WORKFLOWS.md # Step-by-step workflow guides
├── AGENTS.md # Agent bead tracking (v0.40+)
├── ASYNC_GATES.md # Human-in-the-loop gates
├── CHEMISTRY_PATTERNS.md # Mol vs Wisp decision tree
└── WORKTREES.md # Parallel development patterns
```
## Key Concepts
### bd vs TodoWrite
| Use bd when... | Use TodoWrite when... |
|----------------|----------------------|
| Work spans multiple sessions | Single-session tasks |
| Complex dependencies exist | Linear step-by-step work |
| Need to resume after weeks | Just need a quick checklist |
| Knowledge work with fuzzy boundaries | Clear, immediate tasks |
### The Dependency Direction Trap
`bd dep add A B` means **"A depends on B"** (B must complete before A can start).
```bash
# Want: "Setup must complete before Implementation"
bd dep add implementation setup # ✓ CORRECT
# NOT: bd dep add setup implementation # ✗ WRONG
```
### Surviving Compaction
When Claude's context gets compacted, conversation history is lost but bd state survives. Write notes as if explaining to a future Claude with zero context:
```bash
bd update issue-123 --notes "COMPLETED: JWT auth with RS256
KEY DECISION: RS256 over HS256 for key rotation
IN PROGRESS: Password reset flow
NEXT: Implement rate limiting"
```
## Requirements
- [bd CLI](https://github.com/steveyegge/beads) installed (`brew install steveyegge/beads/bd`)
- A git repository (bd requires git for sync)
- Initialized database (`bd init` in project root)
## Version Compatibility
| Version | Features |
|---------|----------|
| v0.43.0+ | Full support: agents, gates, worktrees, chemistry patterns |
| v0.40.0+ | Agent beads, async gates, worktree management |
| v0.34.0+ | Molecules, wisps, cross-project dependencies |
| v0.15.0+ | Core: dependencies, notes, status tracking |
| Earlier | Basic functionality, some features missing |
## Contributing
This skill is maintained at [github.com/steveyegge/beads](https://github.com/steveyegge/beads) in the `skills/beads/` directory.
Issues and PRs welcome for:
- Documentation improvements
- New workflow patterns
- Bug fixes in examples
- Additional troubleshooting scenarios
## License
MIT (same as beads)

100
claude-plugin/skills/beads/SKILL.md Normal file
View File

@@ -0,0 +1,100 @@
---
name: beads
description: >
Git-backed issue tracker for multi-session work with dependencies and persistent
memory across conversation compaction. Use when work spans sessions, has blockers,
or needs context recovery after compaction.
allowed-tools: "Read,Bash(bd:*)"
version: "0.43.0"
author: "Steve Yegge <https://github.com/steveyegge>"
license: "MIT"
---
# Beads - Persistent Task Memory for AI Agents
Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.
## bd vs TodoWrite
| bd (persistent) | TodoWrite (ephemeral) |
|-----------------|----------------------|
| Multi-session work | Single-session tasks |
| Complex dependencies | Linear execution |
| Survives compaction | Conversation-scoped |
| Git-backed, team sync | Local to session |
**Decision test**: "Will I need this context in 2 weeks?" → YES = bd
**When to use bd**:
- Work spans multiple sessions or days
- Tasks have dependencies or blockers
- Need to survive conversation compaction
- Exploratory/research work with fuzzy boundaries
- Collaboration with team (git sync)
**When to use TodoWrite**:
- Single-session linear tasks
- Simple checklist for immediate work
- All context is in current conversation
- Will complete within current session
## Prerequisites
```bash
bd --version # Requires v0.34.0+
```
- **bd CLI** installed and in PATH
- **Git repository** (bd requires git for sync)
- **Initialization**: `bd init` run once (humans do this, not agents)
## CLI Reference
**Run `bd prime`** for AI-optimized workflow context (auto-loaded by hooks).
**Run `bd <command> --help`** for specific command usage.
Essential commands: `bd ready`, `bd create`, `bd show`, `bd update`, `bd close`, `bd sync`
## Session Protocol
1. `bd ready` — Find unblocked work
2. `bd show <id>` — Get full context
3. `bd update <id> --status in_progress` — Start work
4. Add notes as you work (critical for compaction survival)
5. `bd close <id> --reason "..."` — Complete task
6. `bd sync` — Persist to git (always run at session end)
## Advanced Features
| Feature | CLI | Resource |
|---------|-----|----------|
| Molecules (templates) | `bd mol --help` | [MOLECULES.md](resources/MOLECULES.md) |
| Chemistry (pour/wisp) | `bd pour`, `bd wisp` | [CHEMISTRY_PATTERNS.md](resources/CHEMISTRY_PATTERNS.md) |
| Agent beads | `bd agent --help` | [AGENTS.md](resources/AGENTS.md) |
| Async gates | `bd gate --help` | [ASYNC_GATES.md](resources/ASYNC_GATES.md) |
| Worktrees | `bd worktree --help` | [WORKTREES.md](resources/WORKTREES.md) |
## Resources
| Resource | Content |
|----------|---------|
| [BOUNDARIES.md](resources/BOUNDARIES.md) | bd vs TodoWrite detailed comparison |
| [CLI_REFERENCE.md](resources/CLI_REFERENCE.md) | Complete command syntax |
| [DEPENDENCIES.md](resources/DEPENDENCIES.md) | Dependency system deep dive |
| [INTEGRATION_PATTERNS.md](resources/INTEGRATION_PATTERNS.md) | TodoWrite and tool integration |
| [ISSUE_CREATION.md](resources/ISSUE_CREATION.md) | When and how to create issues |
| [MOLECULES.md](resources/MOLECULES.md) | Proto definitions, component labels |
| [PATTERNS.md](resources/PATTERNS.md) | Common usage patterns |
| [RESUMABILITY.md](resources/RESUMABILITY.md) | Compaction survival guide |
| [STATIC_DATA.md](resources/STATIC_DATA.md) | Database schema reference |
| [TROUBLESHOOTING.md](resources/TROUBLESHOOTING.md) | Error handling and fixes |
| [WORKFLOWS.md](resources/WORKFLOWS.md) | Step-by-step workflow patterns |
| [AGENTS.md](resources/AGENTS.md) | Agent bead tracking (v0.40+) |
| [ASYNC_GATES.md](resources/ASYNC_GATES.md) | Human-in-the-loop gates |
| [CHEMISTRY_PATTERNS.md](resources/CHEMISTRY_PATTERNS.md) | Mol vs Wisp decision tree |
| [WORKTREES.md](resources/WORKTREES.md) | Parallel development patterns |
## Full Documentation
- **bd prime**: AI-optimized workflow context
- **GitHub**: [github.com/steveyegge/beads](https://github.com/steveyegge/beads)

59
claude-plugin/skills/beads/adr/0001-bd-prime-as-source-of-truth.md Normal file
View File

@@ -0,0 +1,59 @@
# ADR-0001: Use bd prime as CLI Reference Source of Truth
## Status
Accepted
## Context
The beads skill maintained CLI reference documentation in multiple locations:
- `SKILL.md` inline (~2,000+ words of CLI reference)
- `references/CLI_REFERENCE.md` (~2,363 words)
- Scattered examples throughout resource files
This created:
- **Duplication**: Same commands documented 2-3 times
- **Drift risk**: Documentation can fall behind bd versions
- **Token overhead**: ~3,000+ tokens loaded even for simple operations
Meanwhile, bd provides `bd prime` which generates AI-optimized workflow context automatically.
## Decision
Use `bd prime` as the single source of truth for CLI commands:
1. **SKILL.md** contains only value-add content (decision frameworks, cognitive patterns)
2. **CLI reference** points to `bd prime` (auto-loaded by hooks) and `bd --help`
3. **Resources** provide depth for advanced features (molecules, agents, gates)
## Consequences
### Positive
- **Zero maintenance**: CLI docs auto-update with bd versions
- **DRY**: Single source of truth
- **Accurate**: No version drift possible
- **Lighter SKILL.md**: ~500 words vs ~3,300
### Negative
- **Dependency on bd prime format**: If output changes significantly, may need adaptation
- **External tool requirement**: Skill assumes bd is installed
## Implementation
Files restructured:
- `SKILL.md` — Reduced from 3,306 to ~500 words
- `references/` → `resources/` — Directory rename for consistency
- New resources added: `agents.md`, `async-gates.md`, `chemistry-patterns.md`, `worktrees.md`
- Existing resources preserved with path updates
## Related
- Claude Code skill progressive disclosure guidelines
- Similar pattern implemented in other Claude Code skill ecosystems
## Date
2025-01-02

62
claude-plugin/skills/beads/resources/AGENTS.md Normal file
View File

@@ -0,0 +1,62 @@
# Agent Beads
> Adapted from ACF beads skill
**v0.40+**: First-class support for agent tracking via `type=agent` beads.
## When to Use Agent Beads
| Scenario | Agent Bead? | Why |
|----------|-------------|-----|
| Multi-agent orchestration | Yes | Track state, assign work via slots |
| Single Claude session | No | Overkill—just use regular beads |
| Long-running background agents | Yes | Heartbeats enable liveness detection |
| Role-based agent systems | Yes | Role beads define agent capabilities |
## Bead Types
| Type | Purpose | Has Slots? |
|------|---------|------------|
| `agent` | AI agent tracking | Yes (hook, role) |
| `role` | Role definitions for agents | No |
Other types (`task`, `bug`, `feature`, `epic`) remain unchanged.
## State Machine
Agent beads track state for coordination:
```
idle → spawning → running/working → done → idle
↓
stuck → (needs intervention)
```
**Key states**: `idle`, `spawning`, `running`, `working`, `stuck`, `done`, `stopped`, `dead`
The `dead` state is set by Witness (monitoring system) via heartbeat timeout—agents don't set this themselves.
## Slot Architecture
Slots are named references from agent beads to other beads:
| Slot | Cardinality | Purpose |
|------|-------------|---------|
| `hook` | 0..1 | Current work attached to agent |
| `role` | 1 | Role definition bead (required) |
**Why slots?** They enforce constraints (one work item at a time) and enable queries like "what is agent X working on?" or "which agent has this work?"
## Monitoring Integration
Agent beads enable:
- **Witness System**: Monitors agent health via heartbeats
- **State Coordination**: ZFC-compliant state machine for multi-agent systems
- **Work Attribution**: Track which agent owns which work
## CLI Reference
Run `bd agent --help` for state/heartbeat/show commands.
Run `bd slot --help` for set/clear/show commands.
Run `bd create --help` for `--type=agent` and `--type=role` options.

168
claude-plugin/skills/beads/resources/ASYNC_GATES.md Normal file
View File

@@ -0,0 +1,168 @@
# Async Gates for Workflow Coordination
> Adapted from ACF beads skill
`bd gate` provides async coordination primitives for cross-session and external-condition workflows. Gates are **wisps** (ephemeral issues) that block until a condition is met.
---
## Gate Types
| Type | Await Syntax | Use Case |
|------|--------------|----------|
| Human | `human:<prompt>` | Cross-session human approval |
| CI | `gh:run:<id>` | Wait for GitHub Actions completion |
| PR | `gh:pr:<id>` | Wait for PR merge/close |
| Timer | `timer:<duration>` | Deployment propagation delay |
| Mail | `mail:<pattern>` | Wait for matching email |
---
## Creating Gates
```bash
# Human approval gate
bd gate create --await human:deploy-approval \
--title "Approve production deploy" \
--timeout 4h
# CI gate (GitHub Actions)
bd gate create --await gh:run:123456789 \
--title "Wait for CI" \
--timeout 30m
# PR merge gate
bd gate create --await gh:pr:42 \
--title "Wait for PR approval" \
--timeout 24h
# Timer gate (deployment propagation)
bd gate create --await timer:15m \
--title "Wait for deployment propagation"
```
**Required options**:
- `--await <spec>` — Gate condition (see types above)
- `--timeout <duration>` — Recommended: prevents forever-open gates
**Optional**:
- `--title <text>` — Human-readable description
- `--notify <recipients>` — Email/beads addresses to notify
---
## Monitoring Gates
```bash
bd gate list # All open gates
bd gate list --all # Include closed
bd gate show <gate-id> # Details for specific gate
bd gate eval # Auto-close elapsed/completed gates
bd gate eval --dry-run # Preview what would close
```
**Auto-close behavior** (`bd gate eval`):
- `timer:*` — Closes when duration elapsed
- `gh:run:*` — Checks GitHub API, closes on success/failure
- `gh:pr:*` — Checks GitHub API, closes on merge/close
- `human:*` — Requires explicit `bd gate approve`
---
## Closing Gates
```bash
# Human gates require explicit approval
bd gate approve <gate-id>
bd gate approve <gate-id> --comment "Reviewed and approved by Steve"
# Manual close (any gate)
bd gate close <gate-id>
bd gate close <gate-id> --reason "No longer needed"
# Auto-close via evaluation
bd gate eval
```
---
## Best Practices
1. **Always set timeouts**: Prevents forever-open gates
```bash
bd gate create --await human:... --timeout 24h
```
2. **Clear titles**: Title should indicate what's being gated
```bash
--title "Approve Phase 2: Core Implementation"
```
3. **Eval periodically**: Run at session start to close elapsed gates
```bash
bd gate eval
```
4. **Clean up obsolete gates**: Close gates that are no longer needed
```bash
bd gate close <id> --reason "superseded by new approach"
```
5. **Check before creating**: Avoid duplicate gates
```bash
bd gate list | grep "spec-myfeature"
```
---
## Gates vs Issues
| Aspect | Gates (Wisp) | Issues |
|--------|--------------|--------|
| Persistence | Ephemeral (not synced) | Permanent (synced to git) |
| Purpose | Block on external condition | Track work items |
| Lifecycle | Auto-close when condition met | Manual close |
| Visibility | `bd gate list` | `bd list` |
| Use case | CI, approval, timers | Tasks, bugs, features |
Gates are designed to be temporary coordination primitives—they exist only until their condition is satisfied.
---
## Troubleshooting
### Gate won't close
```bash
# Check gate details
bd gate show <gate-id>
# For gh:run gates, verify the run exists
gh run view <run-id>
# Force close if stuck
bd gate close <gate-id> --reason "manual override"
```
### Can't find gate ID
```bash
# List all gates (including closed)
bd gate list --all
# Search by title pattern
bd gate list | grep "Phase 2"
```
### CI run ID detection fails
```bash
# Check GitHub CLI auth
gh auth status
# List runs manually
gh run list --branch <branch>
# Use specific workflow
gh run list --workflow ci.yml --branch <branch>
```

469
claude-plugin/skills/beads/resources/BOUNDARIES.md Normal file
View File

@@ -0,0 +1,469 @@
# 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:**
- Architecture decision requiring research into frameworks and trade-offs
- API design requiring research into multiple options
- Performance optimization requiring measurement and experimentation
- Documentation requiring understanding system architecture
**Why bd wins**: `design` and `acceptance_criteria` fields capture evolving understanding. Issues can be refined as exploration reveals more information.
#### Side Quests
Exploratory work that might pause the main task.
**Examples:**
- During feature work, discover a better pattern worth exploring
- While debugging, notice related architectural issue
- During code review, identify potential improvement
- While writing tests, find edge case requiring research
**Why bd wins**: Create issue with `discovered-from` dependency, pause main work safely. Context preserved for both tracks. Resume either one later.
#### Project Memory
Need to resume work after significant time with full context.
**Examples:**
- Open source contributions across months
- Part-time projects with irregular schedule
- Complex features split across sprints
- Research projects with long investigation periods
**Why bd wins**: 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: Database Migration Planning
**Scenario**: Planning migration from MySQL to PostgreSQL for production application.
**Why bd**:
- Multi-session work across days/weeks
- Fuzzy boundaries - scope emerges through investigation
- Side quests - discover schema incompatibilities requiring refactoring
- Dependencies - can't migrate data until schema validated
- Project memory - need to resume after interruptions
**bd structure**:
```
db-epic: "Migrate production database to PostgreSQL"
├─ db-1: "Audit current MySQL schema and queries"
├─ db-2: "Research PostgreSQL equivalents for MySQL features" (blocks schema design)
├─ db-3: "Design PostgreSQL schema with type mappings"
└─ db-4: "Create migration scripts and test data integrity" (blocked by db-3)
```
**TodoWrite role**: None initially. Might use TodoWrite for single-session testing sprints once migration scripts ready.
### Example 2: Simple Feature Implementation
**Scenario**: Add logging to existing endpoint based on clear specification.
**Why TodoWrite**:
- Single session work
- Linear execution - add import, call logger, add test
- All context in user message
- Completes within conversation
**TodoWrite**:
```
- [ ] Import logging library
- [ ] Add log statements to endpoint
- [ ] Add test for log output
- [ ] Run tests
```
**bd role**: None. Overkill for straightforward task.
### Example 3: Bug Investigation
**Initial assessment**: Seems simple, try TodoWrite first.
**TodoWrite**:
```
- [ ] Reproduce bug
- [ ] Identify root cause
- [ ] Implement fix
- [ ] Add regression test
```
**What actually happens**: Reproducing bug reveals it's intermittent. Root cause investigation shows multiple potential issues. Needs time to investigate.
**Transition to bd**:
```
Create bd issue: "Fix intermittent auth failure in production"
- Description: Initially seemed simple but reproduction shows complex race condition
- Design: Three potential causes identified, need to test each
- Created issues for each hypothesis with discovered-from dependency
Pause for day, resume next session from bd context
```
### Example 4: Refactoring with Dependencies
**Scenario**: Extract common validation logic from three controllers.
**Why bd**:
- Dependencies - must extract before modifying callers
- Multi-file changes need coordination
- Potential side quest - might discover better pattern during extraction
- Need to track which controllers updated
**bd structure**:
```
refactor-1: "Create shared validation module"
→ blocks refactor-2, refactor-3, refactor-4
refactor-2: "Update auth controller to use shared validation"
refactor-3: "Update user controller to use shared validation"
refactor-4: "Update payment controller to use shared validation"
```
**TodoWrite role**: Could use TodoWrite for individual controller updates as implementing.
**Why this works**: bd ensures you don't forget to update a controller. `bd ready` shows next available work. Dependencies prevent starting controller update before extraction complete.
## Common Mistakes
### Mistake 1: Using TodoWrite for Multi-Session Work
**What happens**:
- Next session, forget what was done
- Scroll conversation history to reconstruct
- Lose design decisions made during implementation
- Start over or duplicate work
**Solution**: Create bd issue instead. Persist context across sessions.
### Mistake 2: Using bd for Simple Linear Tasks
**What happens**:
- Overhead of creating issue not justified
- User can't see progress in conversation
- Extra tool use for no benefit
**Solution**: Use TodoWrite. It's designed for exactly this case.
### Mistake 3: Not Transitioning When Complexity Emerges
**What happens**:
- Start with TodoWrite for "simple" task
- Discover blockers and dependencies mid-way
- Keep using TodoWrite despite poor fit
- Lose context when conversation ends
**Solution**: Transition to bd when complexity signal appears. Not too late mid-session.
### Mistake 4: Creating Too Many bd Issues
**What happens**:
- Every tiny task gets an issue
- Database cluttered with trivial items
- Hard to find meaningful work in `bd ready`
**Solution**: Reserve bd for work that actually benefits from persistence. Use "2 week test" - would bd help resume after 2 weeks? If no, skip it.
### Mistake 5: Never Using bd Because TodoWrite is Familiar
**What happens**:
- Multi-session projects become markdown swamps
- Lose track of dependencies and blockers
- Can't resume work effectively
- Rotten half-implemented plans
**Solution**: Force yourself to use bd for next multi-session project. Experience the difference in organization and resumability.
### Mistake 6: Always Asking Before Creating Issues (or Never Asking)
**When to create directly** (no user question needed):
- **Bug reports**: Clear scope, specific problem ("Found: auth doesn't check profile permissions")
- **Research tasks**: Investigative work ("Research workaround for Slides export")
- **Technical TODOs**: Discovered during implementation ("Add validation to form handler")
- **Side quest capture**: Discoveries that need tracking ("Issue: MCP can't read Shared Drive files")
**Why create directly**: Asking slows discovery capture. User expects proactive issue creation for clear-cut problems.
**When to ask first** (get user input):
- **Strategic work**: Fuzzy boundaries, multiple valid approaches ("Should we implement X or Y pattern?")
- **Potential duplicates**: Might overlap with existing work
- **Large epics**: Multiple approaches, unclear scope ("Plan migration strategy")
- **Major scope changes**: Changing direction of existing issue
**Why ask**: Ensures alignment on fuzzy work, prevents duplicate effort, clarifies scope before investment.
**Rule of thumb**: If you can write a clear, specific issue title and description in one sentence, create directly. If you need user input to clarify the work, ask first.
**Examples**:
- ✅ Create directly: "workspace MCP: Google Doc → .docx export fails with UTF-8 encoding error"
- ✅ Create directly: "Research: Workarounds for reading Google Slides from Shared Drives"
- ❓ Ask first: "Should we refactor the auth system now or later?" (strategic decision)
- ❓ Ask first: "I found several data validation issues, should I file them all?" (potential overwhelming)
## The Transition Point
Most work starts with an implicit mental model:
**"This looks straightforward"** → TodoWrite
**As work progresses:**
✅ **Stays straightforward** → Continue with TodoWrite, complete in session
⚠️ **Complexity emerges** → Transition to bd, preserve context
The skill is recognizing the transition point:
**Transition signals:**
- "This is taking longer than expected"
- "I've discovered a blocker"
- "This needs more research"
- "I should pause this and investigate X first"
- "The user might not be available to continue today"
- "I found three related issues while working on this"
**When you notice these signals**: Create bd issue, preserve context, work from structured foundation.
## Summary Heuristics
Quick decision guides:
**Time horizon:**
- Same session → TodoWrite
- Multiple sessions → bd
**Dependency structure:**
- Linear steps → TodoWrite
- Blockers/prerequisites → bd
**Scope clarity:**
- Well-defined → TodoWrite
- Exploratory → bd
**Context complexity:**
- Conversation has everything → TodoWrite
- External context needed → bd
**User interaction:**
- User watching progress → TodoWrite visible in chat
- Background work → bd invisible structure
**Resume difficulty:**
- Easy from markdown → TodoWrite
- Need structured history → bd
When in doubt: **Use the 2-week test**. If you'd struggle to resume this work after 2 weeks without bd, use bd.

197
claude-plugin/skills/beads/resources/CHEMISTRY_PATTERNS.md Normal file
View File

@@ -0,0 +1,197 @@
# Chemistry Patterns
> Adapted from ACF beads skill
Beads uses a chemistry metaphor for work templates. This guide covers when and how to use each phase.
## Phase Transitions
```
┌─────────────────────────────────────────────────────────────┐
│ PROTO (Solid) │
│ Frozen template, reusable pattern │
│ .beads/ with template label │
└─────────────────────────┬───────────────────────────────────┘
│
┌───────────────┼───────────────┐
│ │ │
▼ │ ▼
┌─────────────────┐ │ ┌─────────────────┐
│ MOL (Liquid) │ │ │ WISP (Vapor) │
│ bd pour │ │ │ bd wisp create │
│ │ │ │ │
│ Persistent │ │ │ Ephemeral │
│ .beads/ │ │ │ .beads-wisp/ │
│ Git synced │ │ │ Gitignored │
└────────┬────────┘ │ └────────┬────────┘
│ │ │
│ │ ┌───────┴───────┐
│ │ │ │
▼ │ ▼ ▼
┌──────────┐ │ ┌─────────┐ ┌─────────┐
│ CLOSE │ │ │ SQUASH │ │ BURN │
│ normally │ │ │ → digest│ │ → gone │
└──────────┘ │ └─────────┘ └─────────┘
│
▼
┌───────────────┐
│ DISTILL │
│ Extract proto │
│ from ad-hoc │
│ epic │
└───────────────┘
```
## Decision Tree: Mol vs Wisp
```
Will this work be referenced later?
│
├─ YES → Does it need audit trail / git history?
│ │
│ ├─ YES → MOL (bd pour)
│ │ Examples: Features, bugs, specs
│ │
│ └─ NO → Could go either way
│ Consider: Will someone else see this?
│ │
│ ├─ YES → MOL
│ └─ NO → WISP (then squash if valuable)
│
└─ NO → WISP (bd wisp create)
Examples: Grooming, health checks, scratch work
End state: burn (no value) or squash (capture learnings)
```
## Quick Reference
| Scenario | Use | Command | End State |
|----------|-----|---------|-----------|
| New feature work | Mol | `bd pour spec` | Close normally |
| Bug fix | Mol | `bd pour bug` | Close normally |
| Grooming session | Wisp | `bd wisp create grooming` | Squash → digest |
| Code review | Wisp | `bd wisp create review` | Squash findings |
| Research spike | Wisp | `bd wisp create spike` | Squash or burn |
| Session health check | Wisp | `bd wisp create health` | Burn |
| Agent coordination | Wisp | `bd wisp create coordinator` | Burn |
## Common Patterns
### Pattern 1: Grooming Wisp
Use for periodic backlog maintenance.
```bash
# Start grooming
bd wisp create grooming --var date="2025-01-02"
# Work through checklist (stale, duplicates, verification)
# Track findings in wisp notes
# End: capture summary
bd mol squash <wisp-id> # Creates digest: "Closed 3, added 5 relationships"
```
**Why wisp?** Grooming is operational—you don't need permanent issues for "reviewed stale items."
### Pattern 2: Code Review Wisp
Use for PR review checklists.
```bash
# Start review
bd wisp create pr-review --var pr="123" --var repo="myproject"
# Track review findings (security, performance, style)
# Each finding is a child issue in the wisp
# End: promote real issues, discard noise
bd mol squash <wisp-id> # Creates permanent issues for real findings
```
**Why wisp?** Review checklists are ephemeral. Only actual findings become permanent issues.
### Pattern 3: Research Spike Wisp
Use for time-boxed exploration.
```bash
# Start spike (2 hour timebox)
bd wisp create spike --var topic="GraphQL pagination"
# Explore, take notes in wisp issues
# Track sources, findings, dead ends
# End: decide outcome
bd mol squash <wisp-id> # If valuable → creates research summary issue
# OR
bd mol burn <wisp-id> # If dead end → no trace
```
**Why wisp?** Research might lead nowhere. Don't pollute the database with abandoned explorations.
## Commands Reference
### Creating Work
```bash
# Persistent mol (solid → liquid)
bd pour <proto> # Synced to git
bd pour <proto> --var key=value
# Ephemeral wisp (solid → vapor)
bd wisp create <proto> # Not synced
bd wisp create <proto> --var key=value
```
### Ending Work
```bash
# Mol: close normally
bd close <mol-id>
# Wisp: squash (condense to digest)
bd mol squash <wisp-id> # Creates permanent digest issue
# Wisp: burn (evaporate, no trace)
bd mol burn <wisp-id> # Deletes with no record
```
### Managing
```bash
# List wisps
bd wisp list
# Garbage collect orphaned wisps
bd wisp gc
# View proto/mol structure
bd mol show <id>
# List available protos
bd mol catalog
```
## Storage Locations
| Type | Location | Git Behavior |
|------|----------|--------------|
| Proto | `.beads/` | Synced (template label) |
| Mol | `.beads/` | Synced |
| Wisp | `.beads-wisp/` | Gitignored |
## Anti-Patterns
| Don't | Do Instead |
|-------|------------|
| Create mol for one-time diagnostic | Use wisp, then burn |
| Create wisp for real feature work | Use mol (needs audit trail) |
| Burn wisp with valuable findings | Squash first (captures digest) |
| Let wisps accumulate | Burn or squash at session end |
| Create ad-hoc epics for repeatable patterns | Distill into proto |
## Related Resources
- [MOLECULES.md](MOLECULES.md) — Proto definitions
- [WORKFLOWS.md](WORKFLOWS.md) — General beads workflows

558
claude-plugin/skills/beads/resources/CLI_REFERENCE.md Normal file
View File

@@ -0,0 +1,558 @@
# CLI Command Reference
**For:** AI agents and developers using bd command-line interface
**Version:** 0.21.0+
## Quick Navigation
- [Basic Operations](#basic-operations)
- [Issue Management](#issue-management)
- [Dependencies & Labels](#dependencies--labels)
- [Filtering & Search](#filtering--search)
- [Advanced Operations](#advanced-operations)
- [Database Management](#database-management)
## Basic Operations
### Check Status
```bash
# Check database path and daemon status
bd info --json
# Example output:
# {
# "database_path": "/path/to/.beads/beads.db",
# "issue_prefix": "bd",
# "daemon_running": true
# }
```
### Find Work
```bash
# Find ready work (no blockers)
bd ready --json
# Find stale issues (not updated recently)
bd stale --days 30 --json # Default: 30 days
bd stale --days 90 --status in_progress --json # Filter by status
bd stale --limit 20 --json # Limit results
```
## Issue Management
### Create Issues
```bash
# Basic creation
# IMPORTANT: Always quote titles and descriptions with double quotes
bd create "Issue title" -t bug|feature|task -p 0-4 -d "Description" --json
# Create with explicit ID (for parallel workers)
bd create "Issue title" --id worker1-100 -p 1 --json
# Create with labels (--labels or --label work)
bd create "Issue title" -t bug -p 1 -l bug,critical --json
bd create "Issue title" -t bug -p 1 --label bug,critical --json
# Examples with special characters (all require quoting):
bd create "Fix: auth doesn't validate tokens" -t bug -p 1 --json
bd create "Add support for OAuth 2.0" -d "Implement RFC 6749 (OAuth 2.0 spec)" --json
# Create multiple issues from markdown file
bd create -f feature-plan.md --json
# Create epic with hierarchical child tasks
bd create "Auth System" -t epic -p 1 --json # Returns: bd-a3f8e9
bd create "Login UI" -p 1 --json # Auto-assigned: bd-a3f8e9.1
bd create "Backend validation" -p 1 --json # Auto-assigned: bd-a3f8e9.2
bd create "Tests" -p 1 --json # Auto-assigned: bd-a3f8e9.3
# Create and link discovered work (one command)
bd create "Found bug" -t bug -p 1 --deps discovered-from:<parent-id> --json
```
### Update Issues
```bash
# Update one or more issues
bd update <id> [<id>...] --status in_progress --json
bd update <id> [<id>...] --priority 1 --json
# Edit issue fields in $EDITOR (HUMANS ONLY - not for agents)
# NOTE: This command is intentionally NOT exposed via the MCP server
# Agents should use 'bd update' with field-specific parameters instead
bd edit <id> # Edit description
bd edit <id> --title # Edit title
bd edit <id> --design # Edit design notes
bd edit <id> --notes # Edit notes
bd edit <id> --acceptance # Edit acceptance criteria
```
### Close/Reopen Issues
```bash
# Complete work (supports multiple IDs)
bd close <id> [<id>...] --reason "Done" --json
# Reopen closed issues (supports multiple IDs)
bd reopen <id> [<id>...] --reason "Reopening" --json
```
### View Issues
```bash
# Show dependency tree
bd dep tree <id>
# Get issue details (supports multiple IDs)
bd show <id> [<id>...] --json
```
## Dependencies & Labels
### Dependencies
```bash
# Link discovered work (old way - two commands)
bd dep add <discovered-id> <parent-id> --type discovered-from
# Create and link in one command (new way - preferred)
bd create "Issue title" -t bug -p 1 --deps discovered-from:<parent-id> --json
```
### Labels
```bash
# Label management (supports multiple IDs)
bd label add <id> [<id>...] <label> --json
bd label remove <id> [<id>...] <label> --json
bd label list <id> --json
bd label list-all --json
```
## Filtering & Search
### Basic Filters
```bash
# Filter by status, priority, type
bd list --status open --priority 1 --json # Status and priority
bd list --assignee alice --json # By assignee
bd list --type bug --json # By issue type
bd list --id bd-123,bd-456 --json # Specific IDs
```
### Label Filters
```bash
# Labels (AND: must have ALL)
bd list --label bug,critical --json
# Labels (OR: has ANY)
bd list --label-any frontend,backend --json
```
### Text Search
```bash
# Title search (substring)
bd list --title "auth" --json
# Pattern matching (case-insensitive substring)
bd list --title-contains "auth" --json # Search in title
bd list --desc-contains "implement" --json # Search in description
bd list --notes-contains "TODO" --json # Search in notes
```
### Date Range Filters
```bash
# Date range filters (YYYY-MM-DD or RFC3339)
bd list --created-after 2024-01-01 --json # Created after date
bd list --created-before 2024-12-31 --json # Created before date
bd list --updated-after 2024-06-01 --json # Updated after date
bd list --updated-before 2024-12-31 --json # Updated before date
bd list --closed-after 2024-01-01 --json # Closed after date
bd list --closed-before 2024-12-31 --json # Closed before date
```
### Empty/Null Checks
```bash
# Empty/null checks
bd list --empty-description --json # Issues with no description
bd list --no-assignee --json # Unassigned issues
bd list --no-labels --json # Issues with no labels
```
### Priority Ranges
```bash
# Priority ranges
bd list --priority-min 0 --priority-max 1 --json # P0 and P1 only
bd list --priority-min 2 --json # P2 and below
```
### Combine Filters
```bash
# Combine multiple filters
bd list --status open --priority 1 --label-any urgent,critical --no-assignee --json
```
## Global Flags
Global flags work with any bd command and must appear **before** the subcommand.
### Sandbox Mode
**Auto-detection (v0.21.1+):** bd automatically detects sandboxed environments and enables sandbox mode.
When detected, you'll see: `ℹ️ Sandbox detected, using direct mode`
**Manual override:**
```bash
# Explicitly enable sandbox mode
bd --sandbox <command>
# Equivalent to combining these flags:
bd --no-daemon --no-auto-flush --no-auto-import <command>
```
**What it does:**
- Disables daemon (uses direct SQLite mode)
- Disables auto-export to JSONL
- Disables auto-import from JSONL
**When to use:** Sandboxed environments where daemon can't be controlled (permission restrictions), or when auto-detection doesn't trigger.
### Staleness Control
```bash
# Skip staleness check (emergency escape hatch)
bd --allow-stale <command>
# Example: access database even if out of sync with JSONL
bd --allow-stale ready --json
bd --allow-stale list --status open --json
```
**Shows:** `⚠️ Staleness check skipped (--allow-stale), data may be out of sync`
**⚠️ Caution:** May show stale or incomplete data. Use only when stuck and other options fail.
### Force Import
```bash
# Force metadata update even when DB appears synced
bd import --force -i .beads/issues.jsonl
```
**When to use:** `bd import` reports "0 created, 0 updated" but staleness errors persist.
**Shows:** `Metadata updated (database already in sync with JSONL)`
### Other Global Flags
```bash
# JSON output for programmatic use
bd --json <command>
# Force direct mode (bypass daemon)
bd --no-daemon <command>
# Disable auto-sync
bd --no-auto-flush <command> # Disable auto-export to JSONL
bd --no-auto-import <command> # Disable auto-import from JSONL
# Custom database path
bd --db /path/to/.beads/beads.db <command>
# Custom actor for audit trail
bd --actor alice <command>
```
**See also:**
- [TROUBLESHOOTING.md - Sandboxed environments](TROUBLESHOOTING.md#sandboxed-environments-codex-claude-code-etc) for detailed sandbox troubleshooting
- [DAEMON.md](DAEMON.md) for daemon mode details
## Advanced Operations
### Cleanup
```bash
# Clean up closed issues (bulk deletion)
bd admin cleanup --force --json # Delete ALL closed issues
bd admin cleanup --older-than 30 --force --json # Delete closed >30 days ago
bd admin cleanup --dry-run --json # Preview what would be deleted
bd admin cleanup --older-than 90 --cascade --force --json # Delete old + dependents
```
### Duplicate Detection & Merging
```bash
# Find and merge duplicate issues
bd duplicates # Show all duplicates
bd duplicates --auto-merge # Automatically merge all
bd duplicates --dry-run # Preview merge operations
# Merge specific duplicate issues
bd merge <source-id...> --into <target-id> --json # Consolidate duplicates
bd merge bd-42 bd-43 --into bd-41 --dry-run # Preview merge
```
### Compaction (Memory Decay)
```bash
# Agent-driven compaction
bd admin compact --analyze --json # Get candidates for review
bd admin compact --analyze --tier 1 --limit 10 --json # Limited batch
bd admin compact --apply --id bd-42 --summary summary.txt # Apply compaction
bd admin compact --apply --id bd-42 --summary - < summary.txt # From stdin
bd admin compact --stats --json # Show statistics
# Legacy AI-powered compaction (requires ANTHROPIC_API_KEY)
bd admin compact --auto --dry-run --all # Preview
bd admin compact --auto --all --tier 1 # Auto-compact tier 1
# Restore compacted issue from git history
bd restore <id> # View full history at time of compaction
```
### Rename Prefix
```bash
# Rename issue prefix (e.g., from 'knowledge-work-' to 'kw-')
bd rename-prefix kw- --dry-run # Preview changes
bd rename-prefix kw- --json # Apply rename
```
## Database Management
### Import/Export
```bash
# Import issues from JSONL
bd import -i .beads/issues.jsonl --dry-run # Preview changes
bd import -i .beads/issues.jsonl # Import and update issues
bd import -i .beads/issues.jsonl --dedupe-after # Import + detect duplicates
# Handle missing parents during import
bd import -i issues.jsonl --orphan-handling allow # Default: import orphans without validation
bd import -i issues.jsonl --orphan-handling resurrect # Auto-resurrect deleted parents as tombstones
bd import -i issues.jsonl --orphan-handling skip # Skip orphans with warning
bd import -i issues.jsonl --orphan-handling strict # Fail if parent is missing
# Configure default orphan handling behavior
bd config set import.orphan_handling "resurrect"
bd sync # Now uses resurrect mode by default
```
**Orphan handling modes:**
- **`allow` (default)** - Import orphaned children without parent validation. Most permissive, ensures no data loss even if hierarchy is temporarily broken.
- **`resurrect`** - Search JSONL history for deleted parents and recreate them as tombstones (Status=Closed, Priority=4). Preserves hierarchy with minimal data. Dependencies are also resurrected on best-effort basis.
- **`skip`** - Skip orphaned children with warning. Partial import succeeds but some issues are excluded.
- **`strict`** - Fail import immediately if a child's parent is missing. Use when database integrity is critical.
**When to use:**
- Use `allow` (default) for daily imports and auto-sync
- Use `resurrect` when importing from databases with deleted parents
- Use `strict` for controlled imports requiring guaranteed parent existence
- Use `skip` rarely - only for selective imports
See [CONFIG.md](CONFIG.md#example-import-orphan-handling) and [TROUBLESHOOTING.md](TROUBLESHOOTING.md#import-fails-with-missing-parent-errors) for more details.
### Migration
```bash
# Migrate databases after version upgrade
bd migrate # Detect and migrate old databases
bd migrate --dry-run # Preview migration
bd migrate --cleanup --yes # Migrate and remove old files
# AI-supervised migration (check before running bd migrate)
bd migrate --inspect --json # Show migration plan for AI agents
bd info --schema --json # Get schema, tables, config, sample IDs
```
**Migration workflow for AI agents:**
1. Run `--inspect` to see pending migrations and warnings
2. Check for `missing_config` (like issue_prefix)
3. Review `invariants_to_check` for safety guarantees
4. If warnings exist, fix config issues first
5. Then run `bd migrate` safely
**Migration safety invariants:**
- **required_config_present**: Ensures issue_prefix and schema_version are set
- **foreign_keys_valid**: No orphaned dependencies or labels
- **issue_count_stable**: Issue count doesn't decrease unexpectedly
These invariants prevent data loss and would have caught issues like GH #201 (missing issue_prefix after migration).
### Daemon Management
See [docs/DAEMON.md](DAEMON.md) for complete daemon management reference.
```bash
# List all running daemons
bd daemons list --json
# Check health (version mismatches, stale sockets)
bd daemons health --json
# Stop/restart specific daemon
bd daemons stop /path/to/workspace --json
bd daemons restart 12345 --json # By PID
# View daemon logs
bd daemons logs /path/to/workspace -n 100
bd daemons logs 12345 -f # Follow mode
# Stop all daemons
bd daemons killall --json
bd daemons killall --force --json # Force kill if graceful fails
```
### Sync Operations
```bash
# Manual sync (force immediate export/import/commit/push)
bd sync
# What it does:
# 1. Export pending changes to JSONL
# 2. Commit to git
# 3. Pull from remote
# 4. Import any updates
# 5. Push to remote
```
## Issue Types
- `bug` - Something broken that needs fixing
- `feature` - New functionality
- `task` - Work item (tests, docs, refactoring)
- `epic` - Large feature composed of multiple issues (supports hierarchical children)
- `chore` - Maintenance work (dependencies, tooling)
**Hierarchical children:** Epics can have child issues with dotted IDs (e.g., `bd-a3f8e9.1`, `bd-a3f8e9.2`). Children are auto-numbered sequentially. Up to 3 levels of nesting supported.
## Priorities
- `0` - Critical (security, data loss, broken builds)
- `1` - High (major features, important bugs)
- `2` - Medium (nice-to-have features, minor bugs)
- `3` - Low (polish, optimization)
- `4` - Backlog (future ideas)
## Dependency Types
- `blocks` - Hard dependency (issue X blocks issue Y)
- `related` - Soft relationship (issues are connected)
- `parent-child` - Epic/subtask relationship
- `discovered-from` - Track issues discovered during work
Only `blocks` dependencies affect the ready work queue.
**Note:** When creating an issue with a `discovered-from` dependency, the new issue automatically inherits the parent's `source_repo` field.
## Output Formats
### JSON Output (Recommended for Agents)
Always use `--json` flag for programmatic use:
```bash
# Single issue
bd show bd-42 --json
# List of issues
bd ready --json
# Operation result
bd create "Issue" -p 1 --json
```
### Human-Readable Output
Default output without `--json`:
```bash
bd ready
# bd-42 Fix authentication bug [P1, bug, in_progress]
# bd-43 Add user settings page [P2, feature, open]
```
## Common Patterns for AI Agents
### Claim and Complete Work
```bash
# 1. Find available work
bd ready --json
# 2. Claim issue
bd update bd-42 --status in_progress --json
# 3. Work on it...
# 4. Close when done
bd close bd-42 --reason "Implemented and tested" --json
```
### Discover and Link Work
```bash
# While working on bd-100, discover a bug
# Old way (two commands):
bd create "Found auth bug" -t bug -p 1 --json # Returns bd-101
bd dep add bd-101 bd-100 --type discovered-from
# New way (one command):
bd create "Found auth bug" -t bug -p 1 --deps discovered-from:bd-100 --json
```
### Batch Operations
```bash
# Update multiple issues at once
bd update bd-41 bd-42 bd-43 --priority 0 --json
# Close multiple issues
bd close bd-41 bd-42 bd-43 --reason "Batch completion" --json
# Add label to multiple issues
bd label add bd-41 bd-42 bd-43 urgent --json
```
### Session Workflow
```bash
# Start of session
bd ready --json # Find work
# During session
bd create "..." -p 1 --json
bd update bd-42 --status in_progress --json
# ... work ...
# End of session (IMPORTANT!)
bd sync # Force immediate sync, bypass debounce
```
**ALWAYS run `bd sync` at end of agent sessions** to ensure changes are committed/pushed immediately.
## See Also
- [AGENTS.md](../AGENTS.md) - Main agent workflow guide
- [DAEMON.md](DAEMON.md) - Daemon management and event-driven mode
- [GIT_INTEGRATION.md](GIT_INTEGRATION.md) - Git workflows and merge strategies
- [LABELS.md](../LABELS.md) - Label system guide
- [README.md](../README.md) - User documentation

747
claude-plugin/skills/beads/resources/DEPENDENCIES.md Normal file
View File

@@ -0,0 +1,747 @@
# Dependency Types Guide
Deep dive into bd's four dependency types: blocks, related, parent-child, and discovered-from.
## Contents
- [Overview](#overview) - Four types at a glance, which affect bd ready?
- [blocks - Hard Blocker](#blocks---hard-blocker)
- [When to Use](#when-to-use) - Prerequisites, sequential steps, build order
- [When NOT to Use](#when-not-to-use) - Soft preferences, parallel work
- [Examples](#examples) - API development, migrations, library dependencies
- [Creating blocks Dependencies](#creating-blocks-dependencies)
- [Common Patterns](#common-patterns) - Build foundation first, migration sequences, testing gates
- [Automatic Unblocking](#automatic-unblocking)
- [related - Soft Link](#related---soft-link)
- [When to Use](#when-to-use-1) - Context, related features, parallel work
- [When NOT to Use](#when-not-to-use-1)
- [Examples](#examples-1) - Feature context, research links, parallel development
- [Creating related Dependencies](#creating-related-dependencies)
- [Common Patterns](#common-patterns-1) - Context clusters, research threads, feature families
- [parent-child - Hierarchical](#parent-child---hierarchical)
- [When to Use](#when-to-use-2) - Epics/subtasks, phases
- [When NOT to Use](#when-not-to-use-2)
- [Examples](#examples-2) - Epic with subtasks, phased projects
- [Creating parent-child Dependencies](#creating-parent-child-dependencies)
- [Combining with blocks](#combining-with-blocks)
- [Common Patterns](#common-patterns-2) - Epic decomposition, nested hierarchies
- [discovered-from - Provenance](#discovered-from---provenance)
- [When to Use](#when-to-use-3) - Side quests, research findings
- [Why This Matters](#why-this-matters)
- [Examples](#examples-3) - Bug discovered during feature work, research branches
- [Creating discovered-from Dependencies](#creating-discovered-from-dependencies)
- [Common Patterns](#common-patterns-3) - Discovery during implementation, research expansion
- [Combining with blocks](#combining-with-blocks-1)
- [Decision Guide](#decision-guide)
- [Decision Tree](#decision-tree)
- [Quick Reference by Situation](#quick-reference-by-situation)
- [Common Mistakes](#common-mistakes)
- Using blocks for preferences, using discovered-from for planning, not using dependencies, over-using blocks, wrong direction
- [Advanced Patterns](#advanced-patterns)
- Diamond dependencies, optional dependencies, discovery cascade, epic with phases
- [Visualization](#visualization)
- [Summary](#summary)
## Overview
bd supports four dependency types that serve different purposes in organizing and tracking work:
| Type | Purpose | Affects `bd ready`? | Common Use |
|------|---------|---------------------|------------|
| **blocks** | Hard blocker | Yes - blocked issues excluded | Sequential work, prerequisites |
| **related** | Soft link | No - just informational | Context, related work |
| **parent-child** | Hierarchy | No - structural only | Epics and subtasks |
| **discovered-from** | Provenance | No - tracks origin | Side quests, research findings |
**Key insight**: Only `blocks` dependencies affect what work is ready. The other three provide structure and context.
---
## blocks - Hard Blocker
**Semantics**: Issue A blocks issue B. B cannot start until A is complete.
**Effect**: Issue B disappears from `bd ready` until issue A is closed.
### When to Use
Use `blocks` when work literally cannot proceed:
- **Prerequisites**: Database schema must exist before endpoints can use it
- **Sequential steps**: Migration step 1 must complete before step 2
- **Build order**: Foundation must be done before building on top
- **Technical blockers**: Library must be installed before code can use it
### When NOT to Use
Don't use `blocks` for:
- **Soft preferences**: "Should do X before Y but could do either"
- **Parallel work**: Both can proceed independently
- **Information links**: Just want to note relationship
- **Recommendations**: "Would be better if done in this order"
Use `related` instead for soft connections.
### Examples
**Example 1: API Development**
```
db-schema-1: "Create users table"
blocks
api-endpoint-2: "Add GET /users endpoint"
Why: Endpoint literally needs table to exist
Effect: api-endpoint-2 won't show in bd ready until db-schema-1 closed
```
**Example 2: Migration Sequence**
```
migrate-1: "Backup production database"
blocks
migrate-2: "Run schema migration"
blocks
migrate-3: "Verify data integrity"
Why: Each step must complete before next can safely proceed
Effect: bd ready shows only migrate-1; closing it reveals migrate-2, etc.
```
**Example 3: Library Installation**
```
setup-1: "Install JWT library"
blocks
auth-2: "Implement JWT validation"
Why: Code won't compile/run without library
Effect: Can't start auth-2 until setup-1 complete
```
### Creating blocks Dependencies
```bash
bd dep add prerequisite-issue blocked-issue
# or explicitly:
bd dep add prerequisite-issue blocked-issue --type blocks
```
**Direction matters**: `from_id` blocks `to_id`. Think: "prerequisite blocks dependent".
### Common Patterns
**Pattern: Build Foundation First**
```
foundation-1: "Set up authentication system"
blocks all of:
- feature-2: "Add user profiles"
- feature-3: "Add admin panel"
- feature-4: "Add API access"
One foundational issue blocks multiple dependent features.
```
**Pattern: Sequential Pipeline**
```
step-1 blocks step-2 blocks step-3 blocks step-4
Linear chain where each step depends on previous.
bd ready shows only current step.
```
**Pattern: Parallel Then Merge**
```
research-1: "Investigate option A"
research-2: "Investigate option B"
research-3: "Investigate option C"
All three block:
decision-4: "Choose approach based on research"
Multiple parallel tasks must complete before next step.
```
### Automatic Unblocking
When you close an issue that's blocking others:
```
1. Close db-schema-1
2. bd automatically updates: api-endpoint-2 is now ready
3. bd ready shows api-endpoint-2
4. No manual unblocking needed
```
This is why `blocks` is powerful - bd maintains ready state automatically.
---
## related - Soft Link
**Semantics**: Issues are related but neither blocks the other.
**Effect**: No impact on `bd ready`. Pure informational link.
### When to Use
Use `related` for context and discoverability:
- **Similar work**: "These tackle the same problem from different angles"
- **Shared context**: "Working on one provides insight for the other"
- **Alternative approaches**: "These are different ways to solve X"
- **Complementary features**: "These work well together but aren't required"
### When NOT to Use
Don't use `related` if:
- One actually blocks the other → use `blocks`
- One discovered the other → use `discovered-from`
- One is parent of the other → use `parent-child`
### Examples
**Example 1: Related Refactoring**
```
refactor-1: "Extract validation logic"
related to
refactor-2: "Extract error handling logic"
Why: Both are refactoring efforts, similar patterns, but independent
Effect: None on ready state; just notes the relationship
```
**Example 2: Documentation and Code**
```
feature-1: "Add OAuth login"
related to
docs-2: "Document OAuth setup"
Why: Docs and feature go together, but can be done in any order
Effect: Can work on either whenever; just notes they're connected
```
**Example 3: Alternative Approaches**
```
perf-1: "Investigate Redis caching"
related to
perf-2: "Investigate CDN caching"
Why: Both address performance, different approaches, explore both
Effect: Both show in bd ready; choosing one doesn't block the other
```
### Creating related Dependencies
```bash
bd dep add issue-1 issue-2 --type related
```
**Direction doesn't matter** for `related` - it's a symmetric link.
### Common Patterns
**Pattern: Cluster Related Work**
```
api-redesign related to:
- api-docs-update
- api-client-update
- api-tests-update
- api-versioning
Group of issues all related to API work.
Use related to show they're part of same initiative.
```
**Pattern: Cross-Cutting Concerns**
```
security-audit related to:
- auth-module
- api-endpoints
- database-access
- frontend-forms
Security audit touches multiple areas.
Related links show what areas it covers.
```
---
## parent-child - Hierarchical
**Semantics**: Issue A is parent of issue B. Typically A is an epic, B is a subtask.
**Effect**: No impact on `bd ready`. Creates hierarchical structure.
### When to Use
Use `parent-child` for breaking down large work:
- **Epics and subtasks**: Big feature split into smaller pieces
- **Hierarchical organization**: Logical grouping of related tasks
- **Progress tracking**: See completion of children relative to parent
- **Work breakdown structure**: Decompose complex work
### When NOT to Use
Don't use `parent-child` if:
- Siblings need ordering → add `blocks` between children
- Relationship is equality → use `related`
- Just discovered one from the other → use `discovered-from`
### Examples
**Example 1: Feature Epic**
```
oauth-epic: "Implement OAuth integration" (epic)
parent of:
- oauth-1: "Set up OAuth credentials" (task)
- oauth-2: "Implement authorization flow" (task)
- oauth-3: "Add token refresh" (task)
- oauth-4: "Create login UI" (task)
Why: Epic decomposed into implementable tasks
Effect: Hierarchical structure; all show in bd ready (unless blocked)
```
**Example 2: Research with Findings**
```
research-epic: "Investigate caching strategies" (epic)
parent of:
- research-1: "Redis evaluation"
- research-2: "Memcached evaluation"
- research-3: "CDN evaluation"
- decision-4: "Choose caching approach"
Why: Research project with multiple investigation threads
Effect: Can track progress across all investigations
```
### Creating parent-child Dependencies
```bash
bd dep add child-task-id parent-epic-id --type parent-child
```
**Direction matters**: The child depends on the parent. Think: "child depends on parent" or "task is part of epic".
### Combining with blocks
Parent-child gives structure; blocks gives ordering:
```
auth-epic (parent of all)
├─ auth-1: "Install library"
├─ auth-2: "Create middleware" (blocked by auth-1)
├─ auth-3: "Add endpoints" (blocked by auth-2)
└─ auth-4: "Add tests" (blocked by auth-3)
parent-child: Shows these are all part of auth epic
blocks: Shows they must be done in order
```
### Common Patterns
**Pattern: Epic with Independent Subtasks**
```
Epic with no ordering between children:
All children show in bd ready immediately.
Work on any child in any order.
Close 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.

407
claude-plugin/skills/beads/resources/INTEGRATION_PATTERNS.md Normal file
View File

@@ -0,0 +1,407 @@
# Integration Patterns with Other Skills
How bd-issue-tracking integrates with TodoWrite, writing-plans, and other skills for optimal workflow.
## Contents
- [TodoWrite Integration](#todowrite-integration) - Temporal layering pattern
- [writing-plans Integration](#writing-plans-integration) - Detailed implementation plans
- [Cross-Skill Workflows](#cross-skill-workflows) - Using multiple skills together
- [Decision Framework](#decision-framework) - When to use which tool
---
## TodoWrite Integration
**Both tools complement each other at different timescales:**
### Temporal Layering Pattern
**TodoWrite** (short-term working memory - this hour):
- Tactical execution: "Review Section 3", "Expand Q&A answers"
- Marked completed as you go
- Present/future tense ("Review", "Expand", "Create")
- Ephemeral: Disappears when session ends
**Beads** (long-term episodic memory - this week/month):
- Strategic objectives: "Continue work on strategic planning document"
- Key decisions and outcomes in notes field
- Past tense in notes ("COMPLETED", "Discovered", "Blocked by")
- Persistent: Survives compaction and session boundaries
**Key insight**: TodoWrite = working copy for the current hour. Beads = project journal for the current month.
### The Handoff Pattern
1. **Session start**: Read bead → Create TodoWrite items for immediate actions
2. **During work**: Mark TodoWrite items completed as you go
3. **Reach milestone**: Update bead notes with outcomes + context
4. **Session end**: TodoWrite disappears, bead survives with enriched notes
**After compaction**: TodoWrite is gone forever, but bead notes reconstruct what happened.
### Example: TodoWrite tracks execution, Beads capture meaning
**TodoWrite (ephemeral execution view):**
```
[completed] Implement login endpoint
[in_progress] Add password hashing with bcrypt
[pending] Create session middleware
```
**Corresponding bead notes (persistent context):**
```bash
bd update issue-123 --notes "COMPLETED: Login endpoint with bcrypt password
hashing (12 rounds). KEY DECISION: Using JWT tokens (not sessions) for stateless
auth - simplifies horizontal scaling. IN PROGRESS: Session middleware implementation.
NEXT: Need user input on token expiry time (1hr vs 24hr trade-off)."
```
**What's different**:
- TodoWrite: Task names (what to do)
- Beads: Outcomes and decisions (what was learned, why it matters)
**Don't duplicate**: TodoWrite tracks execution, Beads captures meaning and context.
### When to Update Each Tool
**Update TodoWrite** (frequently):
- Mark task completed as you finish each one
- Add new tasks as you break down work
- Update in_progress when switching tasks
**Update Beads** (at milestones):
- Completed a significant piece of work
- Made a key decision that needs documentation
- Hit a blocker that pauses progress
- About to ask user for input
- Session token usage > 70%
- End of session
**Pattern**: TodoWrite changes every few minutes. Beads updates every hour or at natural breakpoints.
### Full Workflow Example
**Scenario**: Implement OAuth authentication (multi-session work)
**Session 1 - Planning**:
```bash
# Create bd issue
bd create "Implement OAuth authentication" -t feature -p 0 --design "
JWT tokens with refresh rotation.
See BOUNDARIES.md for bd vs TodoWrite decision.
"
# Mark in_progress
bd update oauth-1 --status in_progress
# Create TodoWrite for today's work
TodoWrite:
- [ ] Research OAuth 2.0 refresh token flow
- [ ] Design token schema
- [ ] Set up test environment
```
**End of Session 1**:
```bash
# Update bd with outcomes
bd update oauth-1 --notes "COMPLETED: Researched OAuth2 refresh flow. Decided on 7-day refresh tokens.
KEY DECISION: RS256 over HS256 (enables key rotation per security review).
IN PROGRESS: Need to set up test OAuth provider.
NEXT: Configure test provider, then implement token endpoint."
# TodoWrite disappears when session ends
```
**Session 2 - Implementation** (after compaction):
```bash
# Read bd to reconstruct context
bd show oauth-1
# See: COMPLETED research, NEXT is configure test provider
# Create fresh TodoWrite from NEXT
TodoWrite:
- [ ] Configure test OAuth provider
- [ ] Implement token endpoint
- [ ] Add basic tests
# Work proceeds...
# Update bd at milestone
bd update oauth-1 --notes "COMPLETED: Test provider configured, token endpoint implemented.
TESTS: 5 passing (token generation, validation, expiry).
IN PROGRESS: Adding refresh token rotation.
NEXT: Implement rotation, add rate limiting, security review."
```
**For complete decision criteria and boundaries, see:** [BOUNDARIES.md](BOUNDARIES.md)
---
## writing-plans Integration
**For complex multi-step features**, the design field in bd issues can link to detailed implementation plans that break work into bite-sized RED-GREEN-REFACTOR steps.
### When to Create Detailed Plans
**Use detailed plans for:**
- Complex features with multiple components
- Multi-session work requiring systematic breakdown
- Features where TDD discipline adds value (core logic, critical paths)
- Work that benefits from explicit task sequencing
**Skip detailed plans for:**
- Simple features (single function, straightforward logic)
- Exploratory work (API testing, pattern discovery)
- Infrastructure setup (configuration, wiring)
**The test:** If you can implement it in one session without a checklist, skip the detailed plan.
### Using the writing-plans Skill
When design field needs detailed breakdown, reference the **writing-plans** skill:
**Pattern:**
```bash
# Create issue with high-level design
bd create "Implement OAuth token refresh" --design "
Add JWT refresh token flow with rotation.
See docs/plans/2025-10-23-oauth-refresh-design.md for detailed plan.
"
# Then use writing-plans skill to create detailed plan
# The skill creates: docs/plans/YYYY-MM-DD-<feature-name>.md
```
**Detailed plan structure** (from writing-plans):
- Bite-sized tasks (2-5 minutes each)
- Explicit RED-GREEN-REFACTOR steps per task
- Exact file paths and complete code
- Verification commands with expected output
- Frequent commit points
**Example task from detailed plan:**
```markdown
### Task 1: Token Refresh Endpoint
**Files:**
- Create: `src/auth/refresh.py`
- Test: `tests/auth/test_refresh.py`
**Step 1: Write failing test**
```python
def test_refresh_token_returns_new_access_token():
refresh_token = create_valid_refresh_token()
response = refresh_endpoint(refresh_token)
assert response.status == 200
assert response.access_token is not None
```
**Step 2: Run test to verify it fails**
Run: `pytest tests/auth/test_refresh.py::test_refresh_token_returns_new_access_token -v`
Expected: FAIL with "refresh_endpoint not defined"
**Step 3: Implement minimal code**
[... exact implementation ...]
**Step 4: Verify test passes**
[... verification ...]
**Step 5: Commit**
```bash
git add tests/auth/test_refresh.py src/auth/refresh.py
git commit -m "feat: add token refresh endpoint"
```
```
### Integration with bd Workflow
**Three-layer structure**:
1. **bd issue**: Strategic objective + high-level design
2. **Detailed plan** (writing-plans): Step-by-step execution guide
3. **TodoWrite**: Current task within the plan
**During planning phase:**
1. Create bd issue with high-level design
2. If complex: Use writing-plans skill to create detailed plan
3. Link plan in design field: `See docs/plans/YYYY-MM-DD-<topic>.md`
**During execution phase:**
1. Open detailed plan (if exists)
2. Use TodoWrite to track current task within plan
3. Update bd notes at milestones, not per-task
4. Close bd issue when all plan tasks complete
**Don't duplicate:** Detailed plan = execution steps. BD notes = outcomes and decisions.
**Example bd notes after using detailed plan:**
```bash
bd update oauth-5 --notes "COMPLETED: Token refresh endpoint (5 tasks from plan: endpoint + rotation + tests)
KEY DECISION: 7-day refresh tokens (vs 30-day) - reduces risk of token theft
TESTS: All 12 tests passing (auth, rotation, expiry, error handling)"
```
### When NOT to Use Detailed Plans
**Red flags:**
- Feature is simple enough to implement in one pass
- Work is exploratory (discovering patterns, testing APIs)
- Infrastructure work (OAuth setup, MCP configuration)
- Would spend more time planning than implementing
**Rule of thumb:** Use detailed plans when systematic breakdown prevents mistakes, not for ceremony.
**Pattern summary**:
- **Simple feature**: bd issue only
- **Complex feature**: bd issue + TodoWrite
- **Very complex feature**: bd issue + writing-plans + TodoWrite
---
## Cross-Skill Workflows
### Pattern: Research Document with Strategic Planning
**Scenario**: User asks "Help me write a strategic planning document for Q4"
**Tools used**: bd-issue-tracking + developing-strategic-documents skill
**Workflow**:
1. Create bd issue for tracking:
```bash
bd create "Q4 strategic planning document" -t task -p 0
bd update strat-1 --status in_progress
```
2. Use developing-strategic-documents skill for research and writing
3. Update bd notes at milestones:
```bash
bd update strat-1 --notes "COMPLETED: Research phase (reviewed 5 competitor docs, 3 internal reports)
KEY DECISION: Focus on market expansion over cost optimization per exec input
IN PROGRESS: Drafting recommendations section
NEXT: Get exec review of draft recommendations before finalizing"
```
4. TodoWrite tracks immediate writing tasks:
```
- [ ] Draft recommendation 1: Market expansion
- [ ] Add supporting data from research
- [ ] Create budget estimates
```
**Why this works**: bd preserves context across sessions (document might take days), skill provides writing framework, TodoWrite tracks current work.
### Pattern: Multi-File Refactoring
**Scenario**: Refactor authentication system across 8 files
**Tools used**: bd-issue-tracking + systematic-debugging (if issues found)
**Workflow**:
1. Create epic and subtasks:
```bash
bd create "Refactor auth system to use JWT" -t epic -p 0
bd create "Update login endpoint" -t task
bd create "Update token validation" -t task
bd create "Update middleware" -t task
bd create "Update tests" -t task
# Link hierarchy
bd dep add auth-epic login-1 --type parent-child
bd dep add auth-epic validation-2 --type parent-child
bd dep add auth-epic middleware-3 --type parent-child
bd dep add auth-epic tests-4 --type parent-child
# Add ordering
bd dep add validation-2 login-1 # validation depends on login
bd dep add middleware-3 validation-2 # middleware depends on validation
bd dep add tests-4 middleware-3 # tests depend on middleware
```
2. Work through subtasks in order, using TodoWrite for each:
```
Current: login-1
TodoWrite:
- [ ] Update login route signature
- [ ] Add JWT generation
- [ ] Update tests
- [ ] Verify backward compatibility
```
3. Update bd notes as each completes:
```bash
bd close login-1 --reason "Updated to JWT. Tests passing. Backward compatible with session auth."
```
4. If issues discovered, use systematic-debugging skill + create blocker issues
**Why this works**: bd tracks dependencies and progress across files, TodoWrite focuses on current file, skills provide specialized frameworks when needed.
---
## Decision Framework
### Which Tool for Which Purpose?
| Need | Tool | Why |
|------|------|-----|
| Track today's execution | TodoWrite | Lightweight, shows current progress |
| Preserve context across sessions | bd | Survives compaction, persistent memory |
| Detailed implementation steps | writing-plans | RED-GREEN-REFACTOR breakdown |
| Research document structure | developing-strategic-documents | Domain-specific framework |
| Debug complex issue | systematic-debugging | Structured debugging protocol |
### Decision Tree
```
Is this work done in this session?
├─ Yes → Use TodoWrite only
└─ No → Use bd
├─ Simple feature → bd issue + TodoWrite
└─ Complex feature → bd issue + writing-plans + TodoWrite
Will conversation history get compacted?
├─ Likely → Use bd (context survives)
└─ Unlikely → TodoWrite is sufficient
Does work have dependencies or blockers?
├─ Yes → Use bd (tracks relationships)
└─ No → TodoWrite is sufficient
Is this specialized domain work?
├─ Research/writing → developing-strategic-documents
├─ Complex debugging → systematic-debugging
├─ Detailed implementation → writing-plans
└─ General tracking → bd + TodoWrite
```
### Integration Anti-Patterns
**Don't**:
- Duplicate TodoWrite tasks into bd notes (different purposes)
- Create bd issues for single-session linear work (use TodoWrite)
- Put detailed implementation steps in bd notes (use writing-plans)
- Update bd after every TodoWrite task (update at milestones)
- Use writing-plans for exploratory work (defeats the purpose)
**Do**:
- Update bd when changing tools or reaching milestones
- Use TodoWrite as "working copy" of bd's NEXT section
- Link between tools (bd design field → writing-plans file path)
- Choose the right level of formality for the work complexity
---
## Summary
**Key principle**: Each tool operates at a different timescale and level of detail.
- **TodoWrite**: Minutes to hours (current execution)
- **bd**: Hours to weeks (persistent context)
- **writing-plans**: Days to weeks (detailed breakdown)
- **Other skills**: As needed (domain frameworks)
**Integration pattern**: Use the lightest tool sufficient for the task, add heavier tools only when complexity demands it.
**For complete boundaries and decision criteria, see:** [BOUNDARIES.md](BOUNDARIES.md)

139
claude-plugin/skills/beads/resources/ISSUE_CREATION.md Normal file
View File

@@ -0,0 +1,139 @@
# Issue Creation Guidelines
Guidance on when and how to create bd issues for maximum effectiveness.
## Contents
- [When to Ask First vs Create Directly](#when-to-ask)
- [Issue Quality](#quality)
- [Making Issues Resumable](#resumable)
- [Design vs Acceptance Criteria](#design-vs-acceptance)
## When to Ask First vs Create Directly {#when-to-ask}
### Ask the user before creating when:
- Knowledge work with fuzzy boundaries
- Task scope is unclear
- Multiple valid approaches exist
- User's intent needs clarification
### Create directly when:
- Clear bug discovered during implementation
- Obvious follow-up work identified
- Technical debt with clear scope
- Dependency or blocker found
**Why ask first for knowledge work?** Task boundaries in strategic/research work are often unclear until discussed, whereas technical implementation tasks are usually well-defined. Discussion helps structure the work properly before creating issues, preventing poorly-scoped issues that need immediate revision.
## Issue Quality {#quality}
Use clear, specific titles and include sufficient context in descriptions to resume work later.
### Field Usage
**Use --design flag for:**
- Implementation approach decisions
- Architecture notes
- Trade-offs considered
**Use --acceptance flag for:**
- Definition of done
- Testing requirements
- Success metrics
## Making Issues Resumable (Complex Technical Work) {#resumable}
For complex technical features spanning multiple sessions, enhance notes field with implementation details.
### Optional but valuable for technical work:
- Working API query code (tested, with response structure)
- Sample API responses showing actual data
- Desired output format examples (show, don't describe)
- Research context (why this approach, what was discovered)
### Example pattern:
```markdown
bd update issue-9 --notes "IMPLEMENTATION GUIDE:
WORKING CODE: service.about().get(fields='importFormats')
Returns: dict with 49 entries like {'text/markdown': [...]}
OUTPUT FORMAT: # Drive Import Formats (markdown with categorized list)
CONTEXT: text/markdown support added July 2024, not in static docs"
```
**When to add:** Multi-session technical features with APIs or specific formats. Skip for simple tasks.
**For detailed patterns and examples, read:** [RESUMABILITY.md](RESUMABILITY.md)
## Design vs Acceptance Criteria (Critical Distinction) {#design-vs-acceptance}
Common mistake: Putting implementation details in acceptance criteria. Here's the difference:
### DESIGN field (HOW to build it):
- "Use two-phase batchUpdate approach: insert text first, then apply formatting"
- "Parse with regex to find * and _ markers"
- "Use JWT tokens with 1-hour expiry"
- Trade-offs: "Chose batchUpdate over streaming API for atomicity"
### ACCEPTANCE CRITERIA (WHAT SUCCESS LOOKS LIKE):
- "Bold and italic markdown formatting renders correctly in the Doc"
- "Solution accepts markdown input and creates Doc with specified title"
- "Returns doc_id and webViewLink to caller"
- "User tokens persist across sessions and refresh automatically"
### Why this matters:
- Design can change during implementation (e.g., use library instead of regex)
- Acceptance criteria should remain stable across sessions
- Criteria should be **outcome-focused** ("what must be true?") not **step-focused** ("do these steps")
- Each criterion should be **verifiable** - you can definitively say yes/no
### The pitfall
Writing criteria like "- [ ] Use batchUpdate approach" locks you into one implementation.
Better: "- [ ] Formatting is applied atomically (all at once or not at all)" - allows flexible implementation.
### Test yourself
If you rewrote the solution using a different approach, would the acceptance criteria still apply? If not, they're design notes, not criteria.
### Example of correct structure
✅ **Design field:**
```
Two-phase Docs API approach:
1. Parse markdown to positions
2. Create doc + insert text in one call
3. Apply formatting in second call
Rationale: Atomic operations, easier to debug formatting separately
```
✅ **Acceptance criteria:**
```
- [ ] Markdown formatting renders in Doc (bold, italic, headings)
- [ ] Lists preserve order and nesting
- [ ] Links are clickable
- [ ] Large documents (>50KB) process without timeout
```
❌ **Wrong (design masquerading as criteria):**
```
- [ ] Use two-phase batchUpdate approach
- [ ] Apply formatting in second batchUpdate call
```
## Quick Reference
**Creating good issues:**
1. **Title**: Clear, specific, action-oriented
2. **Description**: Problem statement, context, why it matters
3. **Design**: Approach, architecture, trade-offs (can change)
4. **Acceptance**: Outcomes, success criteria (should be stable)
5. **Notes**: Implementation details, session handoffs (evolves over time)
**Common mistakes:**
- Vague titles: "Fix bug" → "Fix: auth token expires before refresh"
- Implementation in acceptance: "Use JWT" → "Auth tokens persist across sessions"
- Missing context: "Update database" → "Update database: add user_last_login for session analytics"

354
claude-plugin/skills/beads/resources/MOLECULES.md Normal file
View File

@@ -0,0 +1,354 @@
# Molecules and Wisps Reference
This reference covers bd's molecular chemistry system for reusable work templates and ephemeral workflows.
## The Chemistry Metaphor
bd v0.34.0 introduces a chemistry-inspired workflow system:
| Phase | Name | Storage | Synced? | Use Case |
|-------|------|---------|---------|----------|
| **Solid** | Proto | `.beads/` | Yes | Reusable template (epic with `template` label) |
| **Liquid** | Mol | `.beads/` | Yes | Persistent instance (real issues from template) |
| **Vapor** | Wisp | `.beads-wisp/` | No | Ephemeral instance (operational work, no audit trail) |
**Phase transitions:**
- `spawn` / `pour`: Solid (proto) → Liquid (mol)
- `wisp create`: Solid (proto) → Vapor (wisp)
- `squash`: Vapor (wisp) → Digest (permanent summary)
- `burn`: Vapor (wisp) → Nothing (deleted, no trace)
- `distill`: Liquid (ad-hoc epic) → Solid (proto)
## When to Use Molecules
### Use Protos/Mols When:
- **Repeatable patterns** - Same workflow structure used multiple times (releases, reviews, onboarding)
- **Team knowledge capture** - Encoding tribal knowledge as executable templates
- **Audit trail matters** - Work that needs to be tracked and reviewed later
- **Cross-session persistence** - Work spanning multiple days/sessions
### Use Wisps When:
- **Operational loops** - Patrol cycles, health checks, routine monitoring
- **One-shot orchestration** - Temporary coordination that shouldn't clutter history
- **Diagnostic runs** - Debugging workflows with no archival value
- **High-frequency ephemeral work** - Would create noise in permanent database
**Key insight:** Wisps prevent database bloat from routine operations while still providing structure during execution.
---
## Proto Management
### Creating a Proto
Protos are epics with the `template` label. Create manually or distill from existing work:
```bash
# Manual creation
bd create "Release Workflow" --type epic --label template
bd create "Run tests for {{component}}" --type task
bd dep add task-id epic-id --type parent-child
# Distill from ad-hoc work (extracts template from existing epic)
bd mol distill bd-abc123 --as "Release Workflow" --var version=1.0.0
```
**Proto naming convention:** Use `mol-` prefix for clarity (e.g., `mol-release`, `mol-patrol`).
### Listing Formulas
```bash
bd formula list # List all formulas (protos)
bd formula list --json # Machine-readable
```
### Viewing Proto Structure
```bash
bd mol show mol-release # Show template structure and variables
bd mol show mol-release --json # Machine-readable
```
---
## Spawning Molecules
### Basic Spawn (Creates Wisp by Default)
```bash
bd mol spawn mol-patrol # Creates wisp (ephemeral)
bd mol spawn mol-feature --pour # Creates mol (persistent)
bd mol spawn mol-release --var version=2.0 # With variable substitution
```
**Chemistry shortcuts:**
```bash
bd mol pour mol-feature # Shortcut for spawn --pour
bd mol wisp mol-patrol # Explicit wisp creation
```
### Spawn with Immediate Execution
```bash
bd mol run mol-release --var version=2.0
```
`bd mol run` does three things:
1. Spawns the molecule (persistent)
2. Assigns root issue to caller
3. Pins root issue for session recovery
**Use `mol run` when:** Starting durable work that should survive crashes. The pin ensures `bd ready` shows the work after restart.
### Spawn with Attachments
Attach additional protos in a single command:
```bash
bd mol spawn mol-feature --attach mol-testing --var name=auth
# Spawns mol-feature, then spawns mol-testing and bonds them
```
**Attach types:**
- `sequential` (default) - Attached runs after primary completes
- `parallel` - Attached runs alongside primary
- `conditional` - Attached runs only if primary fails
```bash
bd mol spawn mol-deploy --attach mol-rollback --attach-type conditional
```
---
## Bonding Molecules
### Bond Types
```bash
bd mol bond A B # Sequential: B runs after A
bd mol bond A B --type parallel # Parallel: B runs alongside A
bd mol bond A B --type conditional # Conditional: B runs if A fails
```
### Operand Combinations
| A | B | Result |
|---|---|--------|
| proto | proto | Compound proto (reusable template) |
| proto | mol | Spawn proto, attach to molecule |
| mol | proto | Spawn proto, attach to molecule |
| mol | mol | Join into compound molecule |
### Phase Control in Bonds
By default, spawned protos inherit target's phase. Override with flags:
```bash
# Found bug during wisp patrol? Persist it:
bd mol bond mol-critical-bug wisp-patrol --pour
# Need ephemeral diagnostic on persistent feature?
bd mol bond mol-temp-check bd-feature --wisp
```
### Custom Compound Names
```bash
bd mol bond mol-feature mol-deploy --as "Feature with Deploy"
```
---
## Wisp Lifecycle
### Creating Wisps
```bash
bd mol wisp mol-patrol # From proto
bd mol spawn mol-patrol # Same (spawn defaults to wisp)
bd mol spawn mol-check --var target=db # With variables
```
### Listing Wisps
```bash
bd mol wisp list # List all wisps
bd mol wisp list --json # Machine-readable
```
### Ending Wisps
**Option 1: Squash (compress to digest)**
```bash
bd mol squash wisp-abc123 # Auto-generate summary
bd mol squash wisp-abc123 --summary "Completed patrol" # Agent-provided summary
bd mol squash wisp-abc123 --keep-children # Keep children, just create digest
bd mol squash wisp-abc123 --dry-run # Preview
```
Squash creates a permanent digest issue summarizing the wisp's work, then deletes the wisp children.
**Option 2: Burn (delete without trace)**
```bash
bd mol burn wisp-abc123 # Delete wisp, no digest
```
Use burn for routine work with no archival value.
### Garbage Collection
```bash
bd mol wisp gc # Clean up orphaned wisps
```
---
## Distilling Protos
Extract a reusable template from ad-hoc work:
```bash
bd mol distill bd-o5xe --as "Release Workflow"
bd mol distill bd-abc --var feature_name=auth-refactor --var version=1.0.0
```
**What distill does:**
1. Loads existing epic and all children
2. Clones structure as new proto (adds `template` label)
3. Replaces concrete values with `{{variable}}` placeholders
**Variable syntax (both work):**
```bash
--var branch=feature-auth # variable=value (recommended)
--var feature-auth=branch # value=variable (auto-detected)
```
**Use cases:**
- Team develops good workflow organically, wants to reuse it
- Capture tribal knowledge as executable templates
- Create starting point for similar future work
---
## Cross-Project Dependencies
### Concept
Projects can depend on capabilities shipped by other projects:
```bash
# Project A ships a capability
bd ship auth-api # Marks capability as available
# Project B depends on it
bd dep add bd-123 external:project-a:auth-api
```
### Shipping Capabilities
```bash
bd ship <capability> # Ship capability (requires closed issue)
bd ship <capability> --force # Ship even if issue not closed
bd ship <capability> --dry-run # Preview
```
**How it works:**
1. Find issue with `export:<capability>` label
2. Validate issue is closed
3. Add `provides:<capability>` label
### Depending on External Capabilities
```bash
bd dep add <issue> external:<project>:<capability>
```
The dependency is satisfied when the external project has a closed issue with `provides:<capability>` label.
**`bd ready` respects external deps:** Issues blocked by unsatisfied external dependencies won't appear in ready list.
---
## Common Patterns
### Pattern: Weekly Review Proto
```bash
# Create proto
bd create "Weekly Review" --type epic --label template
bd create "Review open issues" --type task
bd create "Update priorities" --type task
bd create "Archive stale work" --type task
# Link as children...
# Use each week
bd mol spawn mol-weekly-review --pour
```
### Pattern: Ephemeral Patrol Cycle
```bash
# Patrol proto exists
bd mol wisp mol-patrol
# Execute patrol work...
# End patrol
bd mol squash wisp-abc123 --summary "Patrol complete: 3 issues found, 2 resolved"
```
### Pattern: Feature with Rollback
```bash
bd mol spawn mol-deploy --attach mol-rollback --attach-type conditional
# If deploy fails, rollback automatically becomes unblocked
```
### Pattern: Capture Tribal Knowledge
```bash
# After completing a good workflow organically
bd mol distill bd-release-epic --as "Release Process" --var version=X.Y.Z
# Now team can: bd mol spawn mol-release-process --var version=2.0.0
```
---
## CLI Quick Reference
| Command | Purpose |
|---------|---------|
| `bd formula list` | List available formulas/protos |
| `bd mol show <id>` | Show proto/mol structure |
| `bd mol spawn <proto>` | Create wisp from proto (default) |
| `bd mol spawn <proto> --pour` | Create persistent mol from proto |
| `bd mol run <proto>` | Spawn + assign + pin (durable execution) |
| `bd mol bond <A> <B>` | Combine protos or molecules |
| `bd mol distill <epic>` | Extract proto from ad-hoc work |
| `bd mol squash <mol>` | Compress wisp children to digest |
| `bd mol burn <wisp>` | Delete wisp without trace |
| `bd mol pour <proto>` | Shortcut for `spawn --pour` |
| `bd mol wisp <proto>` | Create ephemeral wisp |
| `bd mol wisp list` | List all wisps |
| `bd mol wisp gc` | Garbage collect orphaned wisps |
| `bd ship <capability>` | Publish capability for cross-project deps |
---
## Troubleshooting
**"Proto not found"**
- Check `bd formula list` for available formulas/protos
- Protos need `template` label on the epic
**"Variable not substituted"**
- Use `--var key=value` syntax
- Check proto for `{{key}}` placeholders with `bd mol show`
**"Wisp commands fail"**
- Wisps stored in `.beads-wisp/` (separate from `.beads/`)
- Check `bd mol wisp list` for active wisps
**"External dependency not satisfied"**
- Target project must have closed issue with `provides:<capability>` label
- Use `bd ship <capability>` in target project first

341
claude-plugin/skills/beads/resources/PATTERNS.md Normal file
View File

@@ -0,0 +1,341 @@
# Common Usage Patterns
Practical patterns for using bd effectively across different scenarios.
## Contents
- [Knowledge Work Session](#knowledge-work-session) - Resume long-running research or writing tasks
- [Side Quest Handling](#side-quest-handling) - Capture discovered work without losing context
- [Multi-Session Project Resume](#multi-session-project-resume) - Pick up work after time away
- [Status Transitions](#status-transitions) - When to change issue status
- [Compaction Recovery](#compaction-recovery) - Resume after conversation history is lost
- [Issue Closure](#issue-closure) - Documenting completion properly
---
## Knowledge Work Session
**Scenario**: User asks "Help me write a proposal for expanding the analytics platform"
**What you see**:
```bash
$ bd ready
# Returns: bd-42 "Research analytics platform expansion proposal" (in_progress)
$ bd show bd-42
Notes: "COMPLETED: Reviewed current stack (Mixpanel, Amplitude)
IN PROGRESS: Drafting cost-benefit analysis section
NEXT: Need user input on budget constraints before finalizing recommendations"
```
**What you do**:
1. Read notes to understand current state
2. Create TodoWrite for immediate work:
```
- [ ] Draft cost-benefit analysis
- [ ] Ask user about budget constraints
- [ ] Finalize recommendations
```
3. Work on tasks, mark TodoWrite items completed
4. At milestone, update bd notes:
```bash
bd update bd-42 --notes "COMPLETED: Cost-benefit analysis drafted.
KEY DECISION: User confirmed $50k budget cap - ruled out enterprise options.
IN PROGRESS: Finalizing recommendations (Posthog + custom ETL).
NEXT: Get user review of draft before closing issue."
```
**Outcome**: TodoWrite disappears at session end, but bd notes preserve context for next session.
**Key insight**: Notes field captures the "why" and context, TodoWrite tracks the "doing" right now.
---
## Side Quest Handling
**Scenario**: During main task, discover a problem that needs attention.
**Pattern**:
1. Create issue immediately: `bd create "Found: inventory system needs refactoring"`
2. Link provenance: `bd dep add main-task new-issue --type discovered-from`
3. Assess urgency: blocker or can defer?
4. **If blocker**:
- `bd update main-task --status blocked`
- `bd update new-issue --status in_progress`
- Work on the blocker
5. **If deferrable**:
- Note in new issue's design field
- Continue main task
- New issue persists for later
**Why this works**: Captures context immediately (before forgetting), preserves relationship to main work, allows flexible prioritization.
**Example (with MCP):**
Working on "Implement checkout flow" (checkout-1), discover payment validation security hole:
1. Create bug issue: `mcp__plugin_beads_beads__create` with `{title: "Fix: payment validation bypasses card expiry check", type: "bug", priority: 0}`
2. Link discovery: `mcp__plugin_beads_beads__dep` with `{from_issue: "checkout-1", to_issue: "payment-bug-2", type: "discovered-from"}`
3. Block current work: `mcp__plugin_beads_beads__update` with `{issue_id: "checkout-1", status: "blocked", notes: "Blocked by payment-bug-2: security hole in validation"}`
4. Start new work: `mcp__plugin_beads_beads__update` with `{issue_id: "payment-bug-2", status: "in_progress"}`
(CLI: `bd create "Fix: payment validation..." -t bug -p 0` then `bd dep add` and `bd update` commands)
---
## Multi-Session Project Resume
**Scenario**: Starting work after days or weeks away from a project.
**Pattern (with MCP)**:
1. **Check what's ready**: Use `mcp__plugin_beads_beads__ready` to see available work
2. **Check what's stuck**: Use `mcp__plugin_beads_beads__blocked` to understand blockers
3. **Check recent progress**: Use `mcp__plugin_beads_beads__list` with `status:"closed"` to see completions
4. **Read detailed context**: Use `mcp__plugin_beads_beads__show` for the issue you'll work on
5. **Update status**: Use `mcp__plugin_beads_beads__update` with `status:"in_progress"`
6. **Begin work**: Create TodoWrite from notes field's NEXT section
(CLI: `bd ready`, `bd blocked`, `bd list --status closed`, `bd show <id>`, `bd update <id> --status in_progress`)
**Example**:
```bash
$ bd ready
Ready to work on (3):
auth-5: "Add OAuth refresh token rotation" (priority: 0)
api-12: "Document REST API endpoints" (priority: 1)
test-8: "Add integration tests for payment flow" (priority: 2)
$ bd show auth-5
Title: Add OAuth refresh token rotation
Status: open
Priority: 0 (critical)
Notes:
COMPLETED: Basic JWT auth working
IN PROGRESS: Need to add token refresh
NEXT: Implement rotation per OWASP guidelines (7-day refresh tokens)
BLOCKER: None - ready to proceed
$ bd update auth-5 --status in_progress
# Now create TodoWrite based on NEXT section
```
**For complete session start workflow with checklist, see:** [WORKFLOWS.md](WORKFLOWS.md#session-start)
---
## Status Transitions
Understanding when to change issue status.
### Status Lifecycle
```
open → in_progress → closed
↓ ↓
blocked blocked
```
### When to Use Each Status
**open** (default):
- Issue created but not started
- Waiting for dependencies to clear
- Planned work not yet begun
- **Command**: Issues start as `open` by default
**in_progress**:
- Actively working on this issue right now
- Has been read and understood
- Making commits or changes related to this
- **Command**: `bd update issue-id --status in_progress`
- **When**: Start of work session on this issue
**blocked**:
- Cannot proceed due to external blocker
- Waiting for user input/decision
- Dependency not completed
- Technical blocker discovered
- **Command**: `bd update issue-id --status blocked`
- **When**: Hit a blocker, capture what blocks you in notes
- **Note**: Document blocker in notes field: "BLOCKER: Waiting for API key from ops team"
**closed**:
- Work completed and verified
- Tests passing
- Acceptance criteria met
- **Command**: `bd close issue-id --reason "Implemented with tests passing"`
- **When**: All work done, ready to move on
- **Note**: Issues remain in database, just marked complete
### Transition Examples
**Starting work**:
```bash
bd ready # See what's available
bd update auth-5 --status in_progress
# Begin working
```
**Hit a blocker**:
```bash
bd update auth-5 --status blocked --notes "BLOCKER: Need OAuth client ID from product team. Emailed Jane on 2025-10-23."
# Switch to different issue or create new work
```
**Unblocking**:
```bash
# Once blocker resolved
bd update auth-5 --status in_progress --notes "UNBLOCKED: Received OAuth credentials. Resuming implementation."
```
**Completing**:
```bash
bd close auth-5 --reason "Implemented OAuth refresh with 7-day rotation. Tests passing. PR #42 merged."
```
---
## Compaction Recovery
**Scenario**: Conversation history has been compacted. You need to resume work with zero conversation context.
**What survives compaction**:
- All bd issues and notes
- Complete work history
- Dependencies and relationships
**What's lost**:
- Conversation history
- TodoWrite lists
- Recent discussion
### Recovery Pattern
1. **Check in-progress work**:
```bash
bd list --status in_progress
```
2. **Read notes for context**:
```bash
bd show issue-id
# Read notes field - should explain current state
```
3. **Reconstruct TodoWrite from notes**:
- COMPLETED section: Done, skip
- IN PROGRESS section: Current state
- NEXT section: **This becomes your TodoWrite list**
4. **Report to user**:
```
"From bd notes: [summary of COMPLETED]. Currently [IN PROGRESS].
Next steps: [from NEXT]. Should I continue with that?"
```
### Example Recovery
**bd show returns**:
```
Issue: bd-42 "OAuth refresh token implementation"
Status: in_progress
Notes:
COMPLETED: Basic JWT validation working (RS256, 1hr access tokens)
KEY DECISION: 7-day refresh tokens per security review
IN PROGRESS: Implementing token rotation endpoint
NEXT: Add rate limiting (5 refresh attempts per 15min), then write tests
BLOCKER: None
```
**Recovery actions**:
1. Read notes, understand context
2. Create TodoWrite:
```
- [ ] Implement rate limiting on refresh endpoint
- [ ] Write tests for token rotation
- [ ] Verify security guidelines met
```
3. Report: "From notes: JWT validation is done with 7-day refresh tokens. Currently implementing rotation endpoint. Next: add rate limiting and tests. Should I continue?"
4. Resume work based on user response
**For complete compaction survival workflow, see:** [WORKFLOWS.md](WORKFLOWS.md#compaction-survival)
---
## Issue Closure
**Scenario**: Work is complete. How to close properly?
### Closure Checklist
Before closing, verify:
- [ ] **Acceptance criteria met**: All items checked off
- [ ] **Tests passing**: If applicable
- [ ] **Documentation updated**: If needed
- [ ] **Follow-up work filed**: New issues created for discovered work
- [ ] **Key decisions documented**: In notes field
### Closure Pattern
**Minimal closure** (simple tasks):
```bash
bd close task-123 --reason "Implemented feature X"
```
**Detailed closure** (complex work):
```bash
# Update notes with final state
bd update task-123 --notes "COMPLETED: OAuth refresh with 7-day rotation
KEY DECISION: RS256 over HS256 per security review
TESTS: 12 tests passing (auth, rotation, expiry, errors)
FOLLOW-UP: Filed perf-99 for token cleanup job"
# Close with summary
bd close task-123 --reason "Implemented OAuth refresh token rotation with rate limiting. All security guidelines met. Tests passing."
```
### Documenting Resolution (Outcome vs Design)
For issues where the outcome differed from initial design, use `--notes` to document what actually happened:
```bash
# Initial design was hypothesis - document actual outcome in notes
bd update bug-456 --notes "RESOLUTION: Not a bug - behavior is correct per OAuth spec. Documentation was unclear. Filed docs-789 to clarify auth flow in user guide."
bd close bug-456 --reason "Resolved: documentation issue, not bug"
```
**Pattern**: Design field = initial approach. Notes field = what actually happened (prefix with RESOLUTION: for clarity).
### Discovering Follow-up Work
When closing reveals new work:
```bash
# While closing auth feature, realize performance needs work
bd create "Optimize token lookup query" -t task -p 2
# Link the provenance
bd dep add auth-5 perf-99 --type discovered-from
# Now close original
bd close auth-5 --reason "OAuth refresh implemented. Discovered perf optimization needed (filed perf-99)."
```
**Why link with discovered-from**: Preserves the context of how you found the new work. Future you will appreciate knowing it came from the auth implementation.
---
## Pattern Summary
| Pattern | When to Use | Key Command | Preserves |
|---------|-------------|-------------|-----------|
| **Knowledge Work** | Long-running research, writing | `bd update --notes` | Context across sessions |
| **Side Quest** | Discovered during other work | `bd dep add --type discovered-from` | Relationship to original |
| **Multi-Session Resume** | Returning after time away | `bd ready`, `bd show` | Full project state |
| **Status Transitions** | Tracking work state | `bd update --status` | Current state |
| **Compaction Recovery** | History lost | Read notes field | All context in notes |
| **Issue Closure** | Completing work | `bd close --reason` | Decisions and outcomes |
**For detailed workflows with step-by-step checklists, see:** [WORKFLOWS.md](WORKFLOWS.md)

207
claude-plugin/skills/beads/resources/RESUMABILITY.md Normal file
View File

@@ -0,0 +1,207 @@
# Making Issues Resumable Across Sessions
## When Resumability Matters
**Use enhanced documentation for:**
- Multi-session technical features with API integration
- Complex algorithms requiring code examples
- Features with specific output format requirements
- Work with "occult" APIs (undocumented capabilities)
**Skip for:**
- Simple bug fixes with clear scope
- Well-understood patterns (CRUD operations, etc.)
- Single-session tasks
- Work with obvious acceptance criteria
**The test:** Would a fresh Claude instance (or you after 2 weeks) struggle to resume this work from the description alone? If yes, add implementation details.
## Anatomy of a Resumable Issue
### Minimal (Always Include)
```markdown
Description: What needs to be built and why
Acceptance Criteria: Concrete, testable outcomes (WHAT not HOW)
```
### Enhanced (Complex Technical Work)
```markdown
Notes Field - IMPLEMENTATION GUIDE:
WORKING CODE:
```python
# Tested code that queries the API
service = build('drive', 'v3', credentials=creds)
result = service.about().get(fields='importFormats').execute()
# Returns: {'text/markdown': ['application/vnd.google-apps.document'], ...}
```
API RESPONSE SAMPLE:
Shows actual data structure (not docs description)
DESIRED OUTPUT FORMAT:
```markdown
# Example of what the output should look like
Not just "return markdown" but actual structure
```
RESEARCH CONTEXT:
Why this approach? What alternatives were considered?
Key discoveries that informed the design.
```
## Real Example: Before vs After
### ❌ Not Resumable
```
Title: Add dynamic capabilities resources
Description: Query Google APIs for capabilities and return as resources
Acceptance: Resources return capability info
```
**Problem:** Future Claude doesn't know:
- Which API endpoints to call
- What the responses look like
- What format to return
### ✅ Resumable
```
Title: Add dynamic capabilities resources
Description: Query Google APIs for system capabilities (import formats,
themes, quotas) that aren't in static docs. Makes server self-documenting.
Notes: IMPLEMENTATION GUIDE
WORKING CODE (tested):
```python
from workspace_mcp.tools.drive import get_credentials
from googleapiclient.discovery import build
creds = get_credentials()
service = build('drive', 'v3', credentials=creds)
about = service.about().get(
fields='importFormats,exportFormats,folderColorPalette'
).execute()
# Returns:
# - importFormats: dict, 49 entries like {'text/markdown': [...]}
# - exportFormats: dict, 10 entries
# - folderColorPalette: list, 24 hex strings
```
OUTPUT FORMAT EXAMPLE:
```markdown
# Drive Import Formats
Google Drive supports 49 import formats:
## Text Formats
- **text/markdown** → Google Docs ✨ (NEW July 2024)
- text/plain → Google Docs
...
```
RESEARCH CONTEXT:
text/markdown support announced July 2024 but NOT in static Google docs.
Google's workspace-developer MCP server doesn't expose this.
This is why dynamic resources matter.
Acceptance Criteria:
- User queries workspace://capabilities/drive/import-formats
- Response shows all 49 formats including text/markdown
- Output is readable markdown, not raw JSON
- Queries live API (not static data)
```
**Result:** Fresh Claude instance can:
1. See working API query code
2. Understand response structure
3. Know desired output format
4. Implement with context
## Optional Template
Copy this into notes field for complex technical features:
```markdown
IMPLEMENTATION GUIDE FOR FUTURE SESSIONS:
WORKING CODE (tested):
```language
# Paste actual code that works
# Include imports and setup
# Show what it returns
```
API RESPONSE SAMPLE:
```json
{
"actualField": "actualValue",
"structure": "as returned by API"
}
```
DESIRED OUTPUT FORMAT:
```
Show what the final output should look like
Not just "markdown" but actual structure/style
```
RESEARCH CONTEXT:
- Why this approach?
- What alternatives considered?
- Key discoveries?
- Links to relevant docs/examples?
```
## Anti-Patterns
### ❌ Over-Documenting Simple Work
```markdown
Title: Fix typo in README
Notes: IMPLEMENTATION GUIDE
WORKING CODE: Open README.md, change "teh" to "the"...
```
**Problem:** Wastes tokens on obvious work.
### ❌ Design Details in Acceptance Criteria
```markdown
Acceptance:
- [ ] Use batchUpdate approach
- [ ] Call API with fields parameter
- [ ] Format as markdown with ## headers
```
**Problem:** Locks implementation. Should be in Design/Notes, not Acceptance.
### ❌ Raw JSON Dumps
```markdown
API RESPONSE:
{giant unformatted JSON blob spanning 100 lines}
```
**Problem:** Hard to read. Extract relevant parts, show structure.
### ✅ Right Balance
```markdown
API RESPONSE SAMPLE:
Returns dict with 49 entries. Example entries:
- 'text/markdown': ['application/vnd.google-apps.document']
- 'text/plain': ['application/vnd.google-apps.document']
- 'application/pdf': ['application/vnd.google-apps.document']
```
## When to Add This Detail
**During issue creation:**
- Already have working code from research? Include it.
- Clear output format in mind? Show example.
**During work (update notes):**
- Just got API query working? Add to notes.
- Discovered important context? Document it.
- Made key decision? Explain rationale.
**Session end:**
- If resuming will be hard, add implementation guide.
- If obvious, skip it.
**The principle:** Help your future self (or next Claude) resume without rediscovering everything.

54
claude-plugin/skills/beads/resources/STATIC_DATA.md Normal file
View File

@@ -0,0 +1,54 @@
# Using bd for Static Reference Data
bd is primarily designed for work tracking, but can also serve as a queryable database for static reference data with some adaptations.
## Work Tracking (Primary Use Case)
Standard bd workflow:
- Issues flow through states (open → in_progress → closed)
- Priorities and dependencies matter
- Status tracking is essential
- IDs are sufficient for referencing
## Reference Databases / Glossaries (Alternative Use)
When using bd for static data (terminology, glossaries, reference information):
**Characteristics:**
- Entities are mostly static (typically always open)
- No real workflow or state transitions
- Names/titles more important than IDs
- Minimal or no dependencies
**Recommended approach:**
- Use separate database (not mixed with work tracking) to avoid confusion
- Consider dual format: maintain markdown version alongside database for name-based lookup
- Example: A terminology database could use both `terms.db` (queryable via bd) and `GLOSSARY.md` (browsable by name)
**Key difference**: Work items have lifecycle; reference entities are stable knowledge.
## When to Use This Pattern
**Good fit:**
- Technical glossaries or terminology databases
- Reference documentation that needs dependency tracking
- Knowledge bases with relationships between entries
- Structured data that benefits from queryability
**Poor fit:**
- Data that changes frequently (use work tracking pattern)
- Simple lists (markdown is simpler)
- Data that needs complex queries (use proper database)
## Limitations
**bd show requires IDs, not names:**
- `bd show term-42` works
- `bd show "API endpoint"` doesn't work
- Workaround: `bd list | grep -i "api endpoint"` to find ID first
- This is why dual format (bd + markdown) is recommended for reference data
**No search by content:**
- bd searches by ID, title filters, status, labels
- For full-text search across descriptions/notes, use grep on the JSONL file
- Example: `grep -i "authentication" .beads/issues.jsonl`

489
claude-plugin/skills/beads/resources/TROUBLESHOOTING.md Normal file
View File

@@ -0,0 +1,489 @@
# Troubleshooting Guide
Common issues encountered when using bd and how to resolve them.
## Interface-Specific Troubleshooting
**MCP tools (local environment):**
- MCP tools require bd daemon running
- Check daemon status: `bd daemon --status` (CLI)
- If MCP tools fail, verify daemon is running and restart if needed
- MCP tools automatically use daemon mode (no --no-daemon option)
**CLI (web environment or local):**
- CLI can use daemon mode (default) or direct mode (--no-daemon)
- Direct mode has 3-5 second sync delay
- Web environment: Install via `npm install -g @beads/cli`
- Web environment: Initialize via `bd init <prefix>` before first use
**Most issues below apply to both interfaces** - the underlying database and daemon behavior is the same.
## Contents
- [Dependencies Not Persisting](#dependencies-not-persisting)
- [Status Updates Not Visible](#status-updates-not-visible)
- [Daemon Won't Start](#daemon-wont-start)
- [Database Errors on Cloud Storage](#database-errors-on-cloud-storage)
- [JSONL File Not Created](#jsonl-file-not-created)
- [Version Requirements](#version-requirements)
---
## Dependencies Not Persisting
### Symptom
```bash
bd dep add issue-2 issue-1 --type blocks
# Reports: ✓ Added dependency
bd show issue-2
# Shows: No dependencies listed
```
### Root Cause (Fixed in v0.15.0+)
This was a **bug in bd** (GitHub issue #101) where the daemon ignored dependencies during issue creation. **Fixed in bd v0.15.0** (Oct 21, 2025).
### Resolution
**1. Check your bd version:**
```bash
bd version
```
**2. If version < 0.15.0, update bd:**
```bash
# Via Homebrew (macOS/Linux)
brew upgrade bd
# Via go install
go install github.com/steveyegge/beads/cmd/bd@latest
# Via package manager
# See https://github.com/steveyegge/beads#installing
```
**3. Restart daemon after upgrade:**
```bash
pkill -f "bd daemon" # Kill old daemon
bd daemon # Start new daemon with fix
```
**4. Test dependency creation:**
```bash
bd create "Test A" -t task
bd create "Test B" -t task
bd dep add <B-id> <A-id> --type blocks
bd show <B-id>
# Should show: "Depends on (1): → <A-id>"
```
### Still Not Working?
If dependencies still don't persist after updating:
1. **Check daemon is running:**
```bash
ps aux | grep "bd daemon"
```
2. **Try without --no-daemon flag:**
```bash
# Instead of: bd --no-daemon dep add ...
# Use: bd dep add ... (let daemon handle it)
```
3. **Check JSONL file:**
```bash
cat .beads/issues.jsonl | jq '.dependencies'
# Should show dependency array
```
4. **Report to beads GitHub** with:
- `bd version` output
- Operating system
- Reproducible test case
---
## Status Updates Not Visible
### Symptom
```bash
bd --no-daemon update issue-1 --status in_progress
# Reports: ✓ Updated issue: issue-1
bd show issue-1
# Shows: Status: open (not in_progress!)
```
### Root Cause
This is **expected behavior**, not a bug. Understanding requires knowing bd's architecture:
**BD Architecture:**
- **JSONL files** (`.beads/issues.jsonl`): Human-readable export format
- **SQLite database** (`.beads/*.db`): Source of truth for queries
- **Daemon**: Syncs JSONL ↔ SQLite every 5 minutes
**What `--no-daemon` actually does:**
- **Writes**: Go directly to JSONL file
- **Reads**: Still come from SQLite database
- **Sync delay**: Daemon imports JSONL → SQLite periodically
### Resolution
**Option 1: Use daemon mode (recommended)**
```bash
# Don't use --no-daemon for CRUD operations
bd update issue-1 --status in_progress
bd show issue-1
# ✓ Status reflects immediately
```
**Option 2: Wait for sync (if using --no-daemon)**
```bash
bd --no-daemon update issue-1 --status in_progress
# Wait 3-5 seconds for daemon to sync
sleep 5
bd show issue-1
# ✓ Status should reflect now
```
**Option 3: Manual sync trigger**
```bash
bd --no-daemon update issue-1 --status in_progress
# Trigger sync by exporting/importing
bd export > /dev/null 2>&1 # Forces sync
bd show issue-1
```
### When to Use `--no-daemon`
**Use --no-daemon for:**
- Batch import scripts (performance)
- CI/CD environments (no persistent daemon)
- Testing/debugging
**Don't use --no-daemon for:**
- Interactive development
- Real-time status checks
- When you need immediate query results
---
## Daemon Won't Start
### Symptom
```bash
bd daemon
# Error: not in a git repository
# Hint: run 'git init' to initialize a repository
```
### Root Cause
bd daemon requires a **git repository** because it uses git for:
- Syncing issues to git remote (optional)
- Version control of `.beads/*.jsonl` files
- Commit history of issue changes
### Resolution
**Initialize git repository:**
```bash
# In your project directory
git init
bd daemon
# ✓ Daemon should start now
```
**Prevent git remote operations:**
```bash
# If you don't want daemon to pull from remote
bd daemon --global=false
```
**Flags:**
- `--global=false`: Don't sync with git remote
- `--interval=10m`: Custom sync interval (default: 5m)
- `--auto-commit=true`: Auto-commit JSONL changes
---
## Database Errors on Cloud Storage
### Symptom
```bash
# In directory: /Users/name/Google Drive/...
bd init myproject
# Error: disk I/O error (522)
# OR: Error: database is locked
```
### Root Cause
**SQLite incompatibility with cloud sync filesystems.**
Cloud services (Google Drive, Dropbox, OneDrive, iCloud) don't support:
- POSIX file locking (required by SQLite)
- Consistent file handles across sync operations
- Atomic write operations
This is a **known SQLite limitation**, not a bd bug.
### Resolution
**Move bd database to local filesystem:**
```bash
# Wrong location (cloud sync)
~/Google Drive/My Work/project/.beads/ # ✗ Will fail
# Correct location (local disk)
~/Repos/project/.beads/ # ✓ Works reliably
~/Projects/project/.beads/ # ✓ Works reliably
```
**Migration steps:**
1. **Move project to local disk:**
```bash
mv ~/Google\ Drive/project ~/Repos/project
cd ~/Repos/project
```
2. **Re-initialize bd (if needed):**
```bash
bd init myproject
```
3. **Import existing issues (if you had JSONL export):**
```bash
bd import < issues-backup.jsonl
```
**Alternative: Use global `~/.beads/` database**
If you must keep work on cloud storage:
```bash
# Don't initialize bd in cloud-synced directory
# Use global database instead
cd ~/Google\ Drive/project
bd create "My task"
# Uses ~/.beads/default.db (on local disk)
```
**Workaround limitations:**
- No per-project database isolation
- All projects share same issue prefix
- Manual tracking of which issues belong to which project
**Recommendation:** Keep code/projects on local disk, sync final deliverables to cloud.
---
## JSONL File Not Created
### Symptom
```bash
bd init myproject
bd --no-daemon create "Test" -t task
ls .beads/
# Only shows: .gitignore, myproject.db
# Missing: issues.jsonl
```
### Root Cause
**JSONL initialization coupling.** The `issues.jsonl` file is created by daemon on first startup, not by `bd init`.
### Resolution
**Start daemon once to initialize JSONL:**
```bash
bd daemon --global=false &
# Wait for initialization
sleep 2
# Now JSONL file exists
ls .beads/issues.jsonl
# ✓ File created
# Subsequent --no-daemon operations work
bd --no-daemon create "Task 1" -t task
cat .beads/issues.jsonl
# ✓ Shows task data
```
**Why this matters:**
- Daemon owns the JSONL export format
- First daemon run creates empty JSONL skeleton
- `--no-daemon` operations assume JSONL exists
**Pattern for batch scripts:**
```bash
#!/bin/bash
# Batch import script
bd init myproject
bd daemon --global=false & # Start daemon
sleep 3 # Wait for initialization
# Now safe to use --no-daemon for performance
for item in "${items[@]}"; do
bd --no-daemon create "$item" -t feature
done
# Daemon syncs JSONL → SQLite in background
sleep 5 # Wait for final sync
# Query results
bd stats
```
---
## Version Requirements
### Minimum Version for Dependency Persistence
**Issue:** Dependencies created but don't appear in `bd show` or dependency tree.
**Fix:** Upgrade to **bd v0.15.0+** (released Oct 2025)
**Check version:**
```bash
bd version
# Should show: bd version 0.15.0 or higher
```
**If using MCP plugin:**
```bash
# Update Claude Code beads plugin
claude plugin update beads
```
### Breaking Changes
**v0.15.0:**
- MCP parameter names changed from `from_id/to_id` to `issue_id/depends_on_id`
- Dependency creation now persists correctly in daemon mode
**v0.14.0:**
- Daemon architecture changes
- Auto-sync JSONL behavior introduced
---
## MCP-Specific Issues
### Dependencies Created Backwards
**Symptom:**
Using MCP tools, dependencies end up reversed from intended.
**Example:**
```python
# Want: "task-2 depends on task-1" (task-1 blocks task-2)
beads_add_dependency(issue_id="task-1", depends_on_id="task-2")
# Wrong! This makes task-1 depend on task-2
```
**Root Cause:**
Parameter confusion between old (`from_id/to_id`) and new (`issue_id/depends_on_id`) names.
**Resolution:**
**Correct MCP usage (bd v0.15.0+):**
```python
# Correct: task-2 depends on task-1
beads_add_dependency(
issue_id="task-2", # Issue that has dependency
depends_on_id="task-1", # Issue that must complete first
dep_type="blocks"
)
```
**Mnemonic:**
- `issue_id`: The issue that **waits**
- `depends_on_id`: The issue that **must finish first**
**Equivalent CLI:**
```bash
bd dep add task-2 task-1 --type blocks
# Meaning: task-2 depends on task-1
```
**Verify dependency direction:**
```bash
bd show task-2
# Should show: "Depends on: task-1"
# Not the other way around
```
---
## Getting Help
### Debug Checklist
Before reporting issues, collect this information:
```bash
# 1. Version
bd version
# 2. Daemon status
ps aux | grep "bd daemon"
# 3. Database location
echo $PWD/.beads/*.db
ls -la .beads/
# 4. Git status
git status
git log --oneline -1
# 5. JSONL contents (for dependency issues)
cat .beads/issues.jsonl | jq '.' | head -50
```
### Report to beads GitHub
If problems persist:
1. **Check existing issues:** https://github.com/steveyegge/beads/issues
2. **Create new issue** with:
- bd version (`bd version`)
- Operating system
- Debug checklist output (above)
- Minimal reproducible example
- Expected vs actual behavior
### Claude Code Skill Issues
If the **bd-issue-tracking skill** provides incorrect guidance:
1. **Check skill version:**
```bash
ls -la ~/.claude/skills/bd-issue-tracking/
head -20 ~/.claude/skills/bd-issue-tracking/SKILL.md
```
2. **Report via Claude Code feedback** or user's GitHub
---
## Quick Reference: Common Fixes
| Problem | Quick Fix |
|---------|-----------|
| Dependencies not saving | Upgrade to bd v0.15.0+ |
| Status updates lag | Use daemon mode (not `--no-daemon`) |
| Daemon won't start | Run `git init` first |
| Database errors on Google Drive | Move to local filesystem |
| JSONL file missing | Start daemon once: `bd daemon &` |
| Dependencies backwards (MCP) | Update to v0.15.0+, use `issue_id/depends_on_id` correctly |
---
## Related Documentation
- [CLI Reference](CLI_REFERENCE.md) - Complete command documentation
- [Dependencies Guide](DEPENDENCIES.md) - Understanding dependency types
- [Workflows](WORKFLOWS.md) - Step-by-step workflow guides
- [beads GitHub](https://github.com/steveyegge/beads) - Official documentation

623
claude-plugin/skills/beads/resources/WORKFLOWS.md Normal file
View File

@@ -0,0 +1,623 @@
# 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
- [Compaction Survival](#compaction-survival) - Recovering after compaction events
- [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
- [Session Handoff Workflow](#session-handoff) - Collaborative handoff between sessions
- [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/`).
---
## Compaction Survival {#compaction-survival}
**Critical**: After compaction events, conversation history is deleted but bd state persists. Beads are your only memory.
**Post-compaction recovery checklist:**
```
After Compaction:
- [ ] Run bd list --status in_progress to see active work
- [ ] Run bd show <issue-id> for each in_progress issue
- [ ] Read notes field to understand: COMPLETED, IN PROGRESS, BLOCKERS, KEY DECISIONS
- [ ] Check dependencies: bd dep tree <issue-id> for context
- [ ] If notes insufficient, check bd list --status open for related issues
- [ ] Reconstruct TodoWrite list from notes if needed
```
**Pattern**: Well-written notes enable full context recovery even with zero conversation history.
**Writing notes for compaction survival:**
**Good note (enables recovery):**
```
bd update issue-42 --notes "COMPLETED: User authentication - added JWT token
generation with 1hr expiry, implemented refresh token endpoint using rotating
tokens pattern. IN PROGRESS: Password reset flow. Email service integration
working. NEXT: Need to add rate limiting to reset endpoint (currently unlimited
requests). KEY DECISION: Using bcrypt with 12 rounds after reviewing OWASP
recommendations, tech lead concerned about response time but benchmarks show <100ms."
```
**Bad note (insufficient for recovery):**
```
bd update issue-42 --notes "Working on auth feature. Made some progress.
More to do later."
```
The good note contains:
- Specific accomplishments (what was implemented/configured)
- Current state (which part is working, what's in progress)
- Next concrete step (not just "continue")
- Key context (team concerns, technical decisions with rationale)
**After compaction**: `bd show issue-42` reconstructs the full context needed to continue work.
---
## 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, think in Ready Fronts, not phases.**
### The Ready Front Model
A **Ready Front** is the set of issues with all dependencies satisfied - what can be worked on *right now*. As issues close, the front advances. The dependency DAG IS the execution plan.
```
Ready Front = Issues where all dependencies are closed
(no blockers remaining)
Static view: Natural topology in the DAG (sync points, bottlenecks)
Dynamic view: Current wavefront of in-progress work
```
**Why Ready Fronts, not Phases?**
"Phases" trigger temporal reasoning that inverts dependencies:
```
⚠️ COGNITIVE TRAP:
"Phase 1 before Phase 2" → brain thinks "Phase 1 blocks Phase 2"
→ WRONG: bd dep add phase1 phase2
Correct: "Phase 2 needs Phase 1" → bd dep add phase2 phase1
```
**The fix**: Name issues by what they ARE, think about what they NEED.
### Epic Planning Workflow
```
Epic Planning with Ready Fronts:
- [ ] Create epic issue for high-level goal
- [ ] Walk backward from goal: "What does the end state need?"
- [ ] Create child issues named by WHAT, not WHEN
- [ ] Add deps using requirement language: "X needs Y" → bd dep add X Y
- [ ] Verify with bd blocked (tasks blocked BY prerequisites, not dependents)
- [ ] Use bd ready to work through in dependency order
```
### The Graph Walk Pattern
Walk **backward** from the goal to get correct dependencies:
```
Start: "What's the final deliverable?"
↓
"Integration tests passing" → gt-integration
↓
"What does that need?"
↓
"Streaming support" → gt-streaming
"Header display" → gt-header
↓
"What do those need?"
↓
"Message rendering" → gt-messages
↓
"What does that need?"
↓
"Buffer layout" → gt-buffer (foundation, no deps)
```
This produces correct deps because you're asking "X needs Y", not "X before Y".
### Ready Fronts Visualized
```
Ready Front 1: gt-buffer (foundation)
Ready Front 2: gt-messages (needs buffer)
Ready Front 3: gt-streaming, gt-header (parallel, need messages)
Ready Front 4: gt-integration (needs streaming, header)
```
At any moment, `bd ready` shows the current front. As issues close, blocked work becomes ready.
### Example: OAuth Integration
```bash
# Create epic (the goal)
bd create "OAuth integration" -t epic
# Walk backward: What does OAuth need?
bd create "Login/logout endpoints" -t task # needs token storage
bd create "Token storage and refresh" -t task # needs auth flow
bd create "Authorization code flow" -t task # needs credentials
bd create "OAuth client credentials" -t task # foundation
# Add deps using requirement language: "X needs Y"
bd dep add endpoints storage # endpoints need storage
bd dep add storage flow # storage needs flow
bd dep add flow credentials # flow needs credentials
# credentials has no deps - it's Ready Front 1
# Verify: bd blocked should show sensible blocking
bd blocked
# endpoints blocked by storage ✓
# storage blocked by flow ✓
# flow blocked by credentials ✓
# credentials ready ✓
```
### Validation
After adding deps, verify with `bd blocked`:
- Tasks should be blocked BY their prerequisites
- NOT blocked by their dependents
If `gt-integration` is blocked by `gt-setup` → correct
If `gt-setup` is blocked by `gt-integration` → deps are inverted, fix them
---
## 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.
---
## Session Handoff Workflow {#session-handoff}
**Collaborative handoff between sessions using notes field:**
This workflow enables smooth work resumption by updating beads notes when stopping, then reading them when resuming. Works in conjunction with compaction survival - creates continuity even after conversation history is deleted.
### At Session Start (Claude's responsibility)
```
Session Start with in_progress issues:
- [ ] Run bd list --status in_progress
- [ ] For each in_progress issue: bd show <issue-id>
- [ ] Read notes field to understand: COMPLETED, IN PROGRESS, NEXT
- [ ] Report to user with context from notes field
- [ ] Example: "workspace-mcp-server-2 is in_progress. Last session:
completed tidying. No code written yet. Next step: create
markdown_to_docs.py. Should I continue with that?"
- [ ] Wait for user confirmation or direction
```
**Pattern**: Notes field is the "read me first" guide for resuming work.
### At Session End (Claude prompts user)
When wrapping up work on an issue:
```
Session End Handoff:
- [ ] Notice work reaching a stopping point
- [ ] Prompt user: "We just completed X and started Y on <issue-id>.
Should I update the beads notes for next session?"
- [ ] If yes, suggest command:
bd update <issue-id> --notes "COMPLETED: X. IN PROGRESS: Y. NEXT: Z"
- [ ] User reviews and confirms
- [ ] Claude executes the update
- [ ] Notes saved for next session's resumption
```
**Pattern**: Update notes at logical stopping points, not after every keystroke.
### Notes Format (Current State, Not Cumulative)
```
Good handoff note (current state):
COMPLETED: Parsed markdown into structured format
IN PROGRESS: Implementing Docs API insertion
NEXT: Debug batchUpdate call - getting 400 error on formatting
BLOCKER: None
KEY DECISION: Using two-phase approach (insert text, then apply formatting) based on reference implementation
Bad handoff note (not useful):
Updated some stuff. Will continue later.
```
**Rules for handoff notes:**
- Current state only (overwrite previous notes, not append)
- Specific accomplishments (not vague progress)
- Concrete next step (not "continue working")
- Optional: Blockers, key decisions, references
- Written for someone with zero conversation context
### Session Handoff Checklist
For Claude at session end:
```
Session End Checklist:
- [ ] Work reaching logical stopping point
- [ ] Prompt user about updating notes
- [ ] If approved:
- [ ] Craft note with COMPLETED/IN_PROGRESS/NEXT
- [ ] Include blocker if stuck
- [ ] Include key decisions if relevant
- [ ] Suggest bd update command
- [ ] Execute approved update
- [ ] Confirm: "Saved handoff notes for next session"
```
For user (optional, but helpful):
```
User Tips:
- [ ] When stopping work: Let Claude suggest notes update
- [ ] When resuming: Let Claude read notes and report context
- [ ] Avoid: Trying to remember context manually (that's what notes are for!)
- [ ] Trust: Well-written notes will help next session pick up instantly
```
### Example: Real Session Handoff
**Scenario:** Implementing markdown→Docs feature (workspace-mcp-server-2)
**At End of Session 1:**
```bash
bd update workspace-mcp-server-2 --notes "COMPLETED: Set up skeleton with Docs
API connection verified. Markdown parsing logic 80% done (handles *, _ modifiers).
IN PROGRESS: Testing edge cases for nested formatting. NEXT: Implement
batchUpdate call structure for text insertion. REFERENCE: Reference pattern at
docs/markdown-to-docs-reference.md. No blockers, moving well."
```
**At Start of Session 2:**
```bash
bd show workspace-mcp-server-2
# Output includes notes field showing exactly where we left off
# Claude reports: "Markdown→Docs feature is 80% parsed. We were testing
# edge cases and need to implement batchUpdate next. Want to continue?"
```
Session resumes instantly with full context, no history scrolling needed.
---
## 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

94
claude-plugin/skills/beads/resources/WORKTREES.md Normal file
View File

@@ -0,0 +1,94 @@
# Git Worktree Support
> Adapted from ACF beads skill
**v0.40+**: First-class worktree management via `bd worktree` command.
## When to Use Worktrees
| Scenario | Worktree? | Why |
|----------|-----------|-----|
| Parallel agent work | Yes | Each agent gets isolated working directory |
| Long-running feature | Yes | Avoids stash/switch dance for interruptions |
| Quick branch switch | No | `git switch` is simpler |
| PR review isolation | Yes | Review without disturbing main work |
## Why `bd worktree` over `git worktree`
**Always use `bd worktree`** instead of raw `git worktree` commands.
```bash
bd worktree create .worktrees/{name} --branch feature/{name}
bd worktree remove .worktrees/{name}
```
**Why?** `bd worktree` auto-configures:
- Beads database redirect files
- Proper gitignore entries
- Daemon bypass for worktree operations
## Architecture
All worktrees share one `.beads/` database via redirect files:
```
main-repo/
├── .beads/ ← Single source of truth
└── .worktrees/
├── feature-a/
│ └── .beads ← Redirect file (not directory)
└── feature-b/
└── .beads ← Redirect file
```
**Key insight**: Daemon auto-bypasses for wisp operations in worktrees.
## Commands
```bash
# Create worktree with beads support
bd worktree create .worktrees/my-feature --branch feature/my-feature
# List worktrees
bd worktree list
# Show worktree info
bd worktree info .worktrees/my-feature
# Remove worktree cleanly
bd worktree remove .worktrees/my-feature
```
## Debugging
When beads commands behave unexpectedly in a worktree:
```bash
bd where # Shows actual .beads location (follows redirects)
bd doctor --deep # Validates graph integrity across all refs
```
## Protected Branch Workflows
For repos with protected `main` branch:
```bash
bd init --branch beads-metadata # Use separate branch for beads data
bd init --contributor # Auto-configure sync.remote=upstream for forks
```
This creates `.git/beads-worktrees/` for internal management.
## Multi-Clone Support
Multi-clone, multi-branch workflows:
- Hash-based IDs (`bd-abc`) eliminate collision across clones
- Each clone syncs independently via git
- See [WORKTREES.md](https://github.com/steveyegge/beads/blob/main/docs/WORKTREES.md) for comprehensive guide
## External References
- **Official Docs**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)
- **Sync Branch**: [PROTECTED_BRANCHES.md](https://github.com/steveyegge/beads/blob/main/docs/PROTECTED_BRANCHES.md)
- **Worktrees**: [WORKTREES.md](https://github.com/steveyegge/beads/blob/main/docs/WORKTREES.md)