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

Update Claude Code skill with compaction survival, enhanced TodoWrite integration, and CLI docs (#85)

Browse Source 
Thanks for accepting the original contribution! I've made some updates based on
real-world usage.

Some of the examples in the original were a bit idiosyncratic to my own work,
so I've generalized them to use universal programming scenarios (authentication,
database migrations, API design) that should be more relatable to any developer.

I've also added some broader improvements to the skill. Apologies for not doing
these as two separate pull requests - I hope bundling them together is OK.

These improvements came largely from asking Claude to reflect on what was useful
and difficult about using the skill - in particular, Claude felt that the
post-compaction scenario was a powerful one because normally a context compaction
causes severe loss of state.

Main changes:
- Add comprehensive compaction survival guide with note-taking patterns
- Replace basic TodoWrite integration with temporal layering pattern
- Add bd export/import documentation with collision resolution
- Clarify when to ask before creating issues vs creating directly
- Add database discovery rules for multi-DB scenarios
This commit is contained in:
spm1001
2025-10-19 17:33:24 +01:00
committed by GitHub
parent 98d53e2634
commit 69e8fb1f6d
4 changed files with 310 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
examples/claude-code-skill/SKILL.md
View File

@@ -28,6 +28,36 @@ bd is a graph-based issue tracker for persistent memory across sessions. Use for
**For detailed decision criteria and examples, read:** [references/BOUNDARIES.md](references/BOUNDARIES.md)
## Surviving Compaction Events
**Critical**: Compaction events delete conversation history but preserve beads. After compaction, bd state is your only persistent memory.
**What survives compaction:**
- All bead data (issues, notes, dependencies, status)
- Complete work history and context
**What doesn't survive:**
- Conversation history
- TodoWrite lists
- Recent discussion context
**Writing notes for post-compaction recovery:**
Write notes as if explaining to a future agent with zero conversation context:
**Pattern:**
```markdown
notes field format:
- COMPLETED: Specific deliverables ("implemented JWT refresh endpoint + rate limiting")
- IN PROGRESS: Current state + next immediate step ("testing password reset flow, need user input on email template")
- BLOCKERS: What's preventing progress
- KEY DECISIONS: Important context or user guidance
```
**After compaction:** `bd show <issue-id>` reconstructs full context from notes field.
**For complete compaction recovery workflow, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md#compaction-survival)
## Session Start Protocol
**bd is available when:**
@@ -76,6 +106,16 @@ bd automatically selects the appropriate database:
**Use case for global database**: Cross-project tracking, personal task management, knowledge work that doesn't belong to a specific project.
**When to use --db flag explicitly:**
- Accessing a specific database outside current directory
- Working with multiple databases (e.g., project database + reference database)
- Example: `bd --db /path/to/reference/terms.db list`
**Database discovery rules:**
- bd looks for `.beads/*.db` in current working directory
- If not found, uses `~/.beads/default.db`
- Shell cwd can reset between commands - use absolute paths with --db when operating on non-local databases
**For complete session start workflows, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md#session-start)
## Core Operations
@@ -218,27 +258,50 @@ bd supports four dependency types:
## Integration with TodoWrite
**Both tools can coexist in a session:**
**Both tools complement each other at different timescales:**
### Recommended Pattern
### Temporal Layering Pattern
1. **Use bd** for project-level issue tracking and dependencies
2. **Use TodoWrite** as "working copy" for current session's active tasks
3. **Sync status**: When completing TodoWrite items, update corresponding bd issues
**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
### Example Flow
**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
### 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:**
```
Session start:
- bd ready shows: "3 issues ready to work on"
- User chooses one: "Let's work on issue-123"
- Create TodoWrite checklist for implementation steps
- bd update issue-123 --status in_progress
- Work through TodoWrite items
- When done: bd close issue-123
- bd ready to see what unblocked
[completed] Implement login endpoint
[in_progress] Add password hashing with bcrypt
[pending] Create session middleware
```
**Corresponding bead notes:**
```
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)."
```
**Don't duplicate**: TodoWrite tracks execution, Beads captures meaning and context.
**For patterns on transitioning between tools mid-session, read:** [references/BOUNDARIES.md](references/BOUNDARIES.md#integration-patterns)
## Common Patterns
@@ -272,6 +335,28 @@ Starting work after time away:
**For complete workflow walkthroughs with checklists, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md)
## Use Pattern Variations
bd is designed for work tracking but can serve other purposes with appropriate adaptations:
### Work Tracking (Primary Use Case)
- 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)
- Entities are mostly static (typically always open)
- No real workflow or state transitions
- Names/titles more important than IDs
- Minimal or no dependencies
- Consider dual format: maintain markdown version alongside database for name-based lookup
- Use separate database (not mixed with work tracking) to avoid confusion
**Example**: A terminology database could use both `terms.db` (queryable) and `GLOSSARY.md` (browsable by name).
**Key difference**: Work items have lifecycle; reference entities are stable knowledge.
## Issue Creation Guidelines
### When to Ask First vs Create Directly
@@ -288,7 +373,7 @@ Starting work after time away:
- Technical debt with clear scope
- Dependency or blocker found
**Reason**: Creating issues helps clarify thinking, but for ambiguous knowledge work, discussion refines the task structure first.
**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
@@ -397,6 +482,12 @@ Use JSON output when you need to parse results programmatically or extract speci
- Filter by status: `bd list --status closed`
- Closed issues remain in database permanently
**If bd show can't find issue by name:**
- `bd show` requires issue IDs, not issue titles
- Workaround: `bd list | grep -i "search term"` to find ID first
- Then: `bd show issue-id` with the discovered ID
- For glossaries/reference databases where names matter more than IDs, consider using markdown format alongside the database
**If dependencies seem wrong:**
- Use `bd show issue-id` to see full dependency tree
- Use `bd dep tree issue-id` for visualization

50
examples/claude-code-skill/references/BOUNDARIES.md
View File

@@ -59,7 +59,7 @@ Work with blockers, prerequisites, or hierarchical structure.
Tasks with fuzzy boundaries, exploration, or strategic thinking.
**Examples:**
- Policy proposal requiring stakeholder analysis and evidence gathering
- 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
@@ -248,27 +248,27 @@ Rare, but happens when bd issue turns out simpler than expected.
## Real-World Examples
### Example 1: Strategic Document Development
### Example 1: Database Migration Planning
**Scenario**: Developing policy proposal requiring research, stakeholder analysis, evidence gathering.
**Scenario**: Planning migration from MySQL to PostgreSQL for production application.
**Why bd**:
- Multi-session research across days
- Multi-session work across days/weeks
- Fuzzy boundaries - scope emerges through investigation
- Side quests - discover related policies to analyze
- Dependencies - can't write recommendations until research complete
- Side quests - discover schema incompatibilities requiring refactoring
- Dependencies - can't migrate data until schema validated
- Project memory - need to resume after interruptions
**bd structure**:
```
barb-epic: "Develop BARB metrics policy proposal"
├─ barb-1: "Research existing BARB documentation"
├─ barb-2: "Analyze stakeholder positions" (blocks recommendations)
├─ barb-3: "Gather evidence for alternative approaches"
└─ barb-4: "Draft policy recommendations" (blocked by barb-2)
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 writing sprints once research complete.
**TodoWrite role**: None initially. Might use TodoWrite for single-session testing sprints once migration scripts ready.
### Example 2: Simple Feature Implementation
@@ -388,6 +388,32 @@ refactor-4: "Update payment controller to use shared validation"
**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:

119
examples/claude-code-skill/references/CLI_REFERENCE.md
View File

@@ -20,6 +20,9 @@ Complete command reference for bd (beads) CLI tool. All commands support `--json
- [Monitoring Commands](#monitoring-commands)
- [bd stats](#bd-stats) - Project statistics
- [bd blocked](#bd-blocked) - Find blocked work
- [Data Management Commands](#data-management-commands)
- [bd export](#bd-export) - Export database to JSONL
- [bd import](#bd-import) - Import issues from JSONL
- [Setup Commands](#setup-commands)
- [bd init](#bd-init) - Initialize database
- [bd quickstart](#bd-quickstart) - Show quick start guide
@@ -44,6 +47,8 @@ Complete command reference for bd (beads) CLI tool. All commands support `--json
| `bd dep cycles` | Detect circular dependencies | (no flags) |
| `bd stats` | Get project statistics | `--json` |
| `bd blocked` | Find blocked issues | `--json` |
| `bd export` | Export issues to JSONL | `--json` |
| `bd import` | Import issues from JSONL | `--resolve-collisions` |
| `bd init` | Initialize bd in directory | `--prefix` |
| `bd quickstart` | Show quick start guide | (no flags) |
@@ -235,6 +240,61 @@ Use to identify bottlenecks when ready list is empty.
---
## Data Management Commands
### bd export
Export all issues to JSONL format.
```bash
bd export > issues.jsonl
bd export --json # Same output, explicit flag
```
**Use cases:**
- Manual backup before risky operations
- Sharing issues across databases
- Version control / git tracking
- Data migration or analysis
**Note**: bd auto-exports to `.beads/*.jsonl` after each operation (5s debounce). Manual export is rarely needed.
---
### bd import
Import issues from JSONL format.
```bash
bd import < issues.jsonl
bd import --resolve-collisions < issues.jsonl
```
**Flags:**
- `--resolve-collisions` - Automatically remap conflicting issue IDs
**Use cases for --resolve-collisions:**
- **Reimporting** after manual JSONL edits - if you closed an issue in the JSONL that's still open in DB
- **Merging databases** - importing issues from another database with overlapping IDs
- **Restoring from backup** - when database state has diverged from JSONL
**What --resolve-collisions does:**
1. Detects ID conflicts (same ID, different status/content)
2. Remaps conflicting imports to new IDs
3. Updates all references and dependencies to use new IDs
4. Reports remapping (e.g., "mit-1 → bd-4")
**Without --resolve-collisions**: Import fails on first conflict.
**Example scenario:**
```bash
# You have: mit-1 (open) in database
# Importing: mit-1 (closed) from JSONL
# Result: Import creates bd-4 with closed status, preserves existing mit-1
```
---
## Setup Commands
### bd init
@@ -343,6 +403,65 @@ bd automatically syncs with git:
- `.beads/*.jsonl` - Source of truth (git-tracked)
- `.beads/*.db` - Local cache (gitignored)
### Git Integration Troubleshooting
**Problem: `.gitignore` ignores entire `.beads/` directory**
**Symptom**: JSONL file not tracked in git, can't commit beads
**Cause**: Incorrect `.gitignore` pattern blocks everything
**Fix**:
```bash
# Check .gitignore
cat .gitignore | grep beads
# ❌ WRONG (ignores everything including JSONL):
.beads/
# ✅ CORRECT (ignores only SQLite cache):
.beads/*.db
.beads/*.db-*
```
**After fixing**: Remove the `.beads/` line and add the specific patterns. Then `git add .beads/issues.jsonl`.
---
### Permission Troubleshooting
**Problem: bd commands prompt for permission despite whitelist**
**Symptom**: `bd` commands ask for confirmation even with `Bash(bd:*)` in settings.local.json
**Root Cause**: Wildcard patterns in settings.local.json don't actually work - not for bd, not for git, not for any Bash commands. This is a general Claude Code limitation, not bd-specific.
**How It Actually Works**:
- Individual command approvals (like `Bash(bd ready)`) DO persist across sessions
- These are stored server-side by Claude Code, not in local config files
- Commands like `git status` work without prompting because they've been individually approved many times, creating the illusion of a working wildcard pattern
**Permanent Solution**:
1. Trigger each bd subcommand you use frequently (see command list below)
2. When prompted, click "Yes, and don't ask again" (NOT "Allow this time")
3. That specific command will be permanently approved across all future sessions
**Common bd Commands to Approve**:
```bash
bd ready
bd list
bd stats
bd blocked
bd export
bd version
bd quickstart
bd dep cycles
bd --help
bd [command] --help # For any subcommand help
```
**Note**: Dynamic commands with arguments (like `bd show <issue-id>`, `bd create "title"`) must be approved per-use since arguments vary. Only static commands can be permanently whitelisted.
---
## Tips

47
examples/claude-code-skill/references/WORKFLOWS.md
View File

@@ -5,6 +5,7 @@ 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
@@ -42,6 +43,52 @@ Session Start (when bd is available):
---
## 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:**