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

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

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:

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 <issue-id>`, `bd create "title"`) must be approved per-use since arguments vary. Only static commands can be permanently whitelisted.
+
 ---
 
 ## Tips

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 <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:**