diff --git a/examples/claude-code-skill/SKILL.md b/examples/claude-code-skill/SKILL.md index 3e01e06f..bb105bad 100644 --- a/examples/claude-code-skill/SKILL.md +++ b/examples/claude-code-skill/SKILL.md @@ -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 ` 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 diff --git a/examples/claude-code-skill/references/BOUNDARIES.md b/examples/claude-code-skill/references/BOUNDARIES.md index b88eb2f1..c98f5640 100644 --- a/examples/claude-code-skill/references/BOUNDARIES.md +++ b/examples/claude-code-skill/references/BOUNDARIES.md @@ -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: diff --git a/examples/claude-code-skill/references/CLI_REFERENCE.md b/examples/claude-code-skill/references/CLI_REFERENCE.md index 94e139cb..eb258d32 100644 --- a/examples/claude-code-skill/references/CLI_REFERENCE.md +++ b/examples/claude-code-skill/references/CLI_REFERENCE.md @@ -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 `, `bd create "title"`) must be approved per-use since arguments vary. Only static commands can be permanently whitelisted. + --- ## Tips diff --git a/examples/claude-code-skill/references/WORKFLOWS.md b/examples/claude-code-skill/references/WORKFLOWS.md index e4e6add8..f21522a6 100644 --- a/examples/claude-code-skill/references/WORKFLOWS.md +++ b/examples/claude-code-skill/references/WORKFLOWS.md @@ -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 for each in_progress issue +- [ ] Read notes field to understand: COMPLETED, IN PROGRESS, BLOCKERS, KEY DECISIONS +- [ ] Check dependencies: bd dep tree 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:**