fix: Restore skill files accidentally deleted by bd sync (GH#738)
Files from PR #722 were inadvertently removed by a bd sync commit. Restoring: README.md, MOLECULES.md, PATTERNS.md, TROUBLESHOOTING.md, INTEGRATION_PATTERNS.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
109
skills/beads/README.md
Normal file
109
skills/beads/README.md
Normal file
@@ -0,0 +1,109 @@
|
||||
# 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)
|
||||
├── README.md # This file (for humans)
|
||||
└── references/ # Detailed documentation (loaded on demand)
|
||||
├── BOUNDARIES.md # When to use bd vs TodoWrite
|
||||
├── CLI_BOOTSTRAP_ADMIN.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
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
- **v0.34.0+**: Full support including molecules, wisps, and cross-project dependencies
|
||||
- **v0.15.0+**: Core functionality (dependencies, notes, status tracking)
|
||||
- **Earlier versions**: Basic functionality but some features may be 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)
|
||||
407
skills/beads/references/INTEGRATION_PATTERNS.md
Normal file
407
skills/beads/references/INTEGRATION_PATTERNS.md
Normal 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)
|
||||
354
skills/beads/references/MOLECULES.md
Normal file
354
skills/beads/references/MOLECULES.md
Normal 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 Protos
|
||||
|
||||
```bash
|
||||
bd mol catalog # List all protos
|
||||
bd mol catalog --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 pour mol-feature # Shortcut for spawn --pour
|
||||
bd wisp create 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 wisp create 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 wisp list # List all wisps
|
||||
bd 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 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 wisp create 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 mol catalog` | List available 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 pour <proto>` | Shortcut for `spawn --pour` |
|
||||
| `bd wisp create <proto>` | Create ephemeral wisp |
|
||||
| `bd wisp list` | List all wisps |
|
||||
| `bd wisp gc` | Garbage collect orphaned wisps |
|
||||
| `bd ship <capability>` | Publish capability for cross-project deps |
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**"Proto not found"**
|
||||
- Check `bd mol catalog` for available 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 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
skills/beads/references/PATTERNS.md
Normal file
341
skills/beads/references/PATTERNS.md
Normal 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)
|
||||
489
skills/beads/references/TROUBLESHOOTING.md
Normal file
489
skills/beads/references/TROUBLESHOOTING.md
Normal 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
|
||||
Reference in New Issue
Block a user