feat: add bd-issue-tracking skill

Based on upstream beads Claude Code skill with adaptations:
- YAML frontmatter for skill system
- Temporal layering guidance (TodoWrite + bd)
- Reference docs: CLI, dependencies, workflows, boundaries

Source: https://github.com/steveyegge/beads/tree/main/examples/claude-code-skill

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

.beads/issues.jsonl

@@ -3,6 +3,7 @@
 {"id":"skills-39g","title":"RFC: .skills manifest pattern for per-repo skill deployment","description":"Document the .skills file pattern where projects declare skills in a manifest, .envrc reads it, and agents can query/edit it.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-11-30T12:37:50.106992381-08:00","updated_at":"2025-11-30T12:43:04.155161727-08:00","closed_at":"2025-11-30T12:43:04.155161727-08:00"}
 {"id":"skills-3o7","title":"Fix ai-skills.nix missing sha256 hash","description":"modules/ai-skills.nix:16 has empty sha256 placeholder for opencode-skills npm package. Either get actual hash or remove/comment out the incomplete fetchFromNpm approach.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-11-30T11:58:24.404929863-08:00","updated_at":"2025-11-30T12:12:39.372107348-08:00","closed_at":"2025-11-30T12:12:39.372107348-08:00"}
 {"id":"skills-4yn","title":"Decide on screenshot-latest skill deployment","description":"DEPLOYED.md shows screenshot-latest as 'Not yet deployed - Pending decision'. Low risk skill that finds existing files. Need to decide whether to deploy or archive.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:33.099790809-08:00","updated_at":"2025-11-30T11:58:33.099790809-08:00"}
+{"id":"skills-7sh","title":"Set up bd-issue-tracking Claude Code skill from beads repo","description":"Install the beads Claude Code skill from https://github.com/steveyegge/beads/tree/main/examples/claude-code-skill\n\nThis skill teaches Claude how to effectively use beads for issue tracking across multi-session coding workflows. It provides strategic guidance on when/how to use beads, not just command syntax.\n\nFiles to install to ~/.claude/skills/bd-issue-tracking/:\n- SKILL.md - Core workflow patterns and decision criteria\n- BOUNDARIES.md - When to use beads vs markdown alternatives\n- CLI_REFERENCE.md - Complete command documentation\n- DEPENDENCIES.md - Relationship types and patterns\n- WORKFLOWS.md - Step-by-step procedures\n- ISSUE_CREATION.md - Quality guidelines\n- RESUMABILITY.md - Making work resumable across sessions\n- STATIC_DATA.md - Using beads as reference databases\n\nCan symlink or copy the files. Restart Claude Code after install.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-03T17:53:43.254007992-08:00","updated_at":"2025-12-03T20:04:53.416579381-08:00","closed_at":"2025-12-03T20:04:53.416579381-08:00"}
 {"id":"skills-a23","title":"Update main README to list all 9 skills","description":"Main README.md 'Skills Included' section only lists worklog and update-spec-kit. Repo actually has 9 skills: template, worklog, update-spec-kit, screenshot-latest, niri-window-capture, tufte-press, update-opencode, web-research, web-search.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:14.042397754-08:00","updated_at":"2025-11-30T12:00:18.916270858-08:00","dependencies":[{"issue_id":"skills-a23","depends_on_id":"skills-4yn","type":"blocks","created_at":"2025-11-30T12:01:30.306742184-08:00","created_by":"daemon"}]}
 {"id":"skills-cnc","title":"Add direnv helper for per-repo skill deployment","description":"Create sourceable helper script and documentation for the standard per-repo skill deployment pattern using direnv + nix build.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-11-30T12:19:20.71056749-08:00","updated_at":"2025-11-30T12:37:47.22638278-08:00","closed_at":"2025-11-30T12:37:47.22638278-08:00"}
 {"id":"skills-czz","title":"Research OpenCode agents for skill integration","description":"DEPLOYMENT.md:218 has TODO to research OpenCode agents. Need to understand how Build/Plan/custom agents work and whether skills need agent-specific handling.","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-30T11:58:24.855701141-08:00","updated_at":"2025-11-30T11:58:24.855701141-08:00"}

flake.nix

@@ -13,6 +13,7 @@
       
       # List of available skills
       availableSkills = [
+        "bd-issue-tracking"
         "niri-window-capture"
         "orch"
         "screenshot-latest"

skills/bd-issue-tracking/README.md

@@ -0,0 +1,41 @@
+# bd Issue Tracking Skill
+
+A Claude Code skill for effective beads (bd) issue tracking across multi-session coding workflows.
+
+## What This Skill Provides
+
+- Decision framework for when to use bd vs TodoWrite
+- Session protocols for starting and ending work
+- Compaction survival strategies
+- Issue creation guidelines
+- Dependency management patterns
+
+## Installation
+
+This skill is deployed via the ai-skills Home Manager module. Add `"bd-issue-tracking"` to your `claudeCodeSkills` list.
+
+## Source
+
+Based on the upstream beads Claude Code skill:
+https://github.com/steveyegge/beads/tree/main/examples/claude-code-skill
+
+## Philosophy
+
+This skill teaches **temporal layering** - using both TodoWrite and bd for different time horizons:
+
+- **TodoWrite**: Single-session micro-tasks (visible progress, ephemeral)
+- **bd**: Multi-session strategic work (persistent, survives compaction)
+
+The key insight: bd provides structured context that persists across long gaps, while TodoWrite excels at immediate session tracking.
+
+## Contents
+
+- `SKILL.md` - Main skill instructions for Claude
+- `references/` - Detailed documentation:
+  - `BOUNDARIES.md` - When to use bd vs TodoWrite
+  - `CLI_REFERENCE.md` - Complete command reference
+  - `DEPENDENCIES.md` - Dependency types guide
+  - `WORKFLOWS.md` - Step-by-step procedures
+  - `ISSUE_CREATION.md` - Issue quality guidelines
+  - `RESUMABILITY.md` - Cross-session patterns
+  - `STATIC_DATA.md` - Reference database usage

skills/bd-issue-tracking/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: bd-issue-tracking
+description: Guide for effective beads (bd) issue tracking across multi-session coding workflows. Use when working on complex features, bug investigations, or any work spanning multiple sessions. Teaches temporal layering with TodoWrite for single-session tasks and bd for persistent strategic work.
+---
+
+# bd Issue Tracking Skill
+
+Guide for using bd (beads) for persistent issue tracking across coding sessions.
+
+## When to Use
+
+This skill activates when:
+- Starting work on a project with `.beads/` directory
+- Planning multi-session features or investigations
+- Managing complex work with dependencies
+- Deciding between bd and TodoWrite for task tracking
+
+## Core Philosophy: Temporal Layering
+
+Use both tools for different time horizons:
+
+| Tool | Use Case | Persistence |
+|------|----------|-------------|
+| **TodoWrite** | Single-session micro-tasks | Ephemeral (conversation only) |
+| **bd** | Multi-session strategic work | Persistent (survives compaction) |
+
+**The 2-week test**: Would bd help you resume this work after 2 weeks away? If yes, use bd.
+
+## Session Start Protocol
+
+When starting work where bd is available:
+
+1. Run `bd ready --json` to see available work
+2. Report status to user: "X items ready: [summary]"
+3. If none ready, check `bd blocked --json`
+4. Review in_progress issues with `bd show <id>`
+5. Read notes field for context from previous sessions
+
+## During Work
+
+### Creating Issues
+
+**Create directly** (no user question needed):
+- Clear bugs discovered during implementation
+- Obvious follow-up work identified
+- Technical debt with clear scope
+
+**Ask first** (get user input):
+- Knowledge work with fuzzy boundaries
+- Multiple valid approaches exist
+- User's intent needs clarification
+
+### Status Maintenance
+
+- `open` → `in_progress` when starting work
+- Update notes field with progress
+- Add dependencies as blockers discovered
+- Close with summary when complete
+
+### Discovery Pattern
+
+When finding new work during implementation:
+
+```bash
+# Create and link in one command
+bd create "Found issue" -t bug -p 1 --deps discovered-from:<current-id> --json
+```
+
+## Session End Protocol
+
+Before ending a session:
+
+1. Update notes field with current state:
+   ```
+   COMPLETED: What was finished
+   IN PROGRESS: Current state
+   NEXT: Concrete next step
+   KEY DECISION: Important choices made (with rationale)
+   ```
+
+2. Run `bd sync` to ensure changes are committed
+
+## Compaction Survival
+
+After compaction events, conversation history is deleted but bd state persists.
+
+**Recovery checklist:**
+1. `bd list --status in_progress` - see active work
+2. `bd show <id>` for each - read notes field
+3. Reconstruct context from COMPLETED/IN PROGRESS/NEXT
+
+## Reference Documentation
+
+For detailed guidance, see the references/ subdirectory:
+
+- **BOUNDARIES.md** - Decision criteria: bd vs TodoWrite
+- **CLI_REFERENCE.md** - Complete command documentation
+- **DEPENDENCIES.md** - Dependency types and patterns
+- **WORKFLOWS.md** - Step-by-step procedures with checklists
+- **ISSUE_CREATION.md** - Quality guidelines for creating issues
+- **RESUMABILITY.md** - Making work resumable across sessions
+- **STATIC_DATA.md** - Using bd as reference database
+
+## Quick Command Reference
+
+```bash
+# Find work
+bd ready --json              # Unblocked issues
+bd blocked --json            # See what's stuck
+
+# Manage issues
+bd create "Title" -t bug -p 1 --json
+bd update <id> --status in_progress --json
+bd close <id> --reason "Done" --json
+
+# Dependencies
+bd dep add <blocker> <blocked>
+bd dep tree <id>
+
+# Session end
+bd sync                      # Force sync to git
+```

skills/bd-issue-tracking/references/BOUNDARIES.md

@@ -0,0 +1,82 @@
+# Boundaries: When to Use bd vs TodoWrite
+
+Decision criteria for choosing between bd issue tracking and TodoWrite.
+
+## The Core Question
+
+**"Could I resume this work after 2 weeks away?"**
+
+- If bd would help you resume → **use bd**
+- If markdown skim would suffice → **TodoWrite is fine**
+
+## Decision Matrix
+
+### Use bd for:
+
+| Scenario | Why |
+|----------|-----|
+| **Multi-session work** | Issues capture context that survives compaction |
+| **Complex dependencies** | Dependency graph shows blockers, `bd ready` surfaces work |
+| **Knowledge work** | Design notes capture evolving understanding |
+| **Side quests** | `discovered-from` preserves context for both tracks |
+| **Project memory** | Git-backed database persists indefinitely |
+
+### Use TodoWrite for:
+
+| Scenario | Why |
+|----------|-----|
+| **Single-session tasks** | Simple checklist for linear execution |
+| **Linear execution** | Steps are predetermined and sequential |
+| **Immediate context** | All information already in conversation |
+| **Simple tracking** | Just need visible progress for user |
+
+## Detailed Comparison
+
+| Aspect | bd | TodoWrite |
+|--------|-----|-----------|
+| **Persistence** | Git-backed, survives compaction | Session-only |
+| **Dependencies** | Graph-based, automatic ready detection | Manual |
+| **Visibility** | Background structure | Visible in conversation |
+| **Best for** | Complex, multi-session, explorative | Simple, single-session, linear |
+
+## Integration Patterns
+
+### Pattern 1: bd Strategic, TodoWrite Tactical
+
+- bd tracks high-level issues and dependencies
+- TodoWrite tracks current session's execution steps
+
+### Pattern 2: TodoWrite as Working Copy
+
+1. Start with bd issue containing full context
+2. Create TodoWrite from acceptance criteria
+3. Update bd as TodoWrite items complete
+
+### Pattern 3: Transition Mid-Session
+
+**From TodoWrite to bd** when:
+- Discovering blockers or dependencies
+- Realizing work won't complete this session
+- Finding side quests
+
+**How to transition:**
+1. Create bd issue with current TodoWrite content
+2. Note: "Discovered this is multi-session work"
+3. Add dependencies as discovered
+4. Update bd issue before session ends
+
+## Common Mistakes
+
+1. **TodoWrite for multi-session work** - Lose context after conversation
+2. **bd for simple linear tasks** - Overhead not justified
+3. **Not transitioning when complexity emerges** - Keep TodoWrite despite poor fit
+4. **Creating too many bd issues** - Reserve bd for work needing persistence
+
+## Summary Heuristics
+
+| Factor | TodoWrite | bd |
+|--------|-----------|-----|
+| **Time horizon** | Same session | Multiple sessions |
+| **Dependencies** | Linear steps | Blockers/prerequisites |
+| **Scope** | Well-defined | Exploratory |
+| **Resume difficulty** | Easy | Need structured history |

skills/bd-issue-tracking/references/CLI_REFERENCE.md

@@ -0,0 +1,158 @@
+# CLI Command Reference
+
+Complete bd command-line interface documentation.
+
+## Basic Operations
+
+### Check Status
+
+```bash
+bd info --json                    # Database path, daemon status
+bd ready --json                   # Find ready work (no blockers)
+bd stale --days 30 --json         # Find stale issues
+```
+
+## Issue Management
+
+### Create Issues
+
+```bash
+# Basic creation
+bd create "Issue title" -t bug|feature|task -p 0-4 -d "Description" --json
+
+# With labels
+bd create "Issue title" -t bug -p 1 -l bug,critical --json
+
+# Create and link discovered work
+bd create "Found bug" -t bug -p 1 --deps discovered-from:<parent-id> --json
+
+# Create epic with hierarchical children
+bd create "Auth System" -t epic -p 1 --json         # Returns: bd-a3f8e9
+bd create "Login UI" -p 1 --json                     # Auto-assigned: bd-a3f8e9.1
+```
+
+### Update Issues
+
+```bash
+bd update <id> --status in_progress --json
+bd update <id> --priority 1 --json
+bd update <id> --notes "COMPLETED: X. IN PROGRESS: Y. NEXT: Z"
+bd update <id> --design "Implementation approach notes"
+```
+
+### Close/Reopen Issues
+
+```bash
+bd close <id> [<id>...] --reason "Done" --json
+bd reopen <id> --reason "Reopening" --json
+```
+
+### View Issues
+
+```bash
+bd show <id> --json               # Issue details
+bd dep tree <id>                  # Dependency tree
+```
+
+## Dependencies & Labels
+
+### Dependencies
+
+```bash
+bd dep add <blocker-id> <blocked-id>                    # blocker blocks blocked
+bd dep add <id> <parent> --type discovered-from         # Provenance link
+bd dep add <child> <parent> --type parent-child         # Hierarchy
+bd dep add <id1> <id2> --type related                   # Soft link
+```
+
+### Labels
+
+```bash
+bd label add <id> <label> --json
+bd label remove <id> <label> --json
+bd label list <id> --json
+```
+
+## Filtering & Search
+
+```bash
+# By status, priority, type
+bd list --status open --priority 1 --json
+bd list --type bug --json
+
+# By labels (AND)
+bd list --label bug,critical --json
+
+# By labels (OR)
+bd list --label-any frontend,backend --json
+
+# Text search
+bd list --title "auth" --json
+bd list --desc-contains "implement" --json
+
+# Date filters
+bd list --created-after 2024-01-01 --json
+bd list --updated-after 2024-06-01 --json
+```
+
+## Global Flags
+
+```bash
+bd --json <command>               # JSON output
+bd --sandbox <command>            # Sandbox mode (auto-detected)
+bd --allow-stale <command>        # Skip staleness check
+bd --no-daemon <command>          # Direct mode
+```
+
+## Sync Operations
+
+```bash
+bd sync                           # Force immediate sync
+# Does: export → commit → pull → import → push
+```
+
+**ALWAYS run `bd sync` at end of agent sessions.**
+
+## Issue Types
+
+- `bug` - Something broken
+- `feature` - New functionality
+- `task` - Work item
+- `epic` - Large feature with children
+- `chore` - Maintenance work
+
+## Priorities
+
+- `0` - Critical (security, data loss)
+- `1` - High (major features, important bugs)
+- `2` - Medium (nice-to-have)
+- `3` - Low (polish)
+- `4` - Backlog (future ideas)
+
+## Dependency Types
+
+- `blocks` - Hard dependency (affects `bd ready`)
+- `related` - Soft link (informational only)
+- `parent-child` - Epic/subtask hierarchy
+- `discovered-from` - Track provenance
+
+Only `blocks` dependencies affect the ready work queue.
+
+## Common Patterns
+
+### Claim and Complete Work
+
+```bash
+bd ready --json                               # Find work
+bd update bd-42 --status in_progress --json   # Claim
+# ... work ...
+bd close bd-42 --reason "Done" --json         # Complete
+```
+
+### Batch Operations
+
+```bash
+bd update bd-41 bd-42 bd-43 --priority 0 --json
+bd close bd-41 bd-42 bd-43 --reason "Batch" --json
+bd label add bd-41 bd-42 urgent --json
+```

skills/bd-issue-tracking/references/DEPENDENCIES.md

@@ -0,0 +1,141 @@
+# Dependency Types Guide
+
+Deep dive into bd's four dependency types.
+
+## Overview
+
+| Type | Purpose | Affects `bd ready`? | Common Use |
+|------|---------|---------------------|------------|
+| **blocks** | Hard blocker | Yes | Sequential work, prerequisites |
+| **related** | Soft link | No | Context, related work |
+| **parent-child** | Hierarchy | No | Epics and subtasks |
+| **discovered-from** | Provenance | No | Side quests, research findings |
+
+**Key insight**: Only `blocks` dependencies affect what work is ready.
+
+## blocks - Hard Blocker
+
+**Semantics**: Issue A blocks issue B. B cannot start until A is complete.
+
+### When to Use
+
+- **Prerequisites**: Database schema must exist before endpoints
+- **Sequential steps**: Migration step 1 before step 2
+- **Build order**: Foundation before building on top
+
+### When NOT to Use
+
+- Soft preferences ("should do X before Y")
+- Parallel work
+- Information links
+
+### Creating
+
+```bash
+bd dep add prerequisite-id blocked-id
+# Direction: from_id blocks to_id
+```
+
+### Automatic Unblocking
+
+When you close a blocking issue, blocked issues automatically become ready.
+
+## related - Soft Link
+
+**Semantics**: Issues are related but neither blocks the other.
+
+### When to Use
+
+- Similar work tackling same problem
+- Shared context
+- Alternative approaches
+- Complementary features
+
+### Creating
+
+```bash
+bd dep add issue-1 issue-2 --type related
+# Direction doesn't matter - symmetric link
+```
+
+## parent-child - Hierarchical
+
+**Semantics**: Issue A is parent of issue B (epic/subtask).
+
+### When to Use
+
+- Epics and subtasks
+- Hierarchical organization
+- Progress tracking
+- Work breakdown structure
+
+### Creating
+
+```bash
+bd dep add child-id parent-id --type parent-child
+# Child depends on parent
+```
+
+### Combining with blocks
+
+parent-child gives structure; blocks gives ordering:
+
+```
+auth-epic (parent of all)
+  ├─ auth-1: "Install library"
+  ├─ auth-2: "Create middleware" (blocked by auth-1)
+  ├─ auth-3: "Add endpoints" (blocked by auth-2)
+  └─ auth-4: "Add tests" (blocked by auth-3)
+```
+
+## discovered-from - Provenance
+
+**Semantics**: Issue B was discovered while working on issue A.
+
+### When to Use
+
+- Side quests found during implementation
+- Research findings
+- Bug found during feature work
+- Follow-up work
+
+### Why This Matters
+
+Knowing where an issue came from helps:
+- Understand context
+- Reconstruct thinking
+- Assess relevance
+
+### Creating
+
+```bash
+bd dep add original-work-id discovered-issue-id --type discovered-from
+# to_id was discovered while working on from_id
+```
+
+## Decision Tree
+
+```
+Does Issue A prevent Issue B from starting?
+  YES → blocks
+  NO ↓
+
+Is Issue B a subtask of Issue A?
+  YES → parent-child
+  NO ↓
+
+Was Issue B discovered while working on Issue A?
+  YES → discovered-from
+  NO ↓
+
+Are Issues A and B just related?
+  YES → related
+```
+
+## Common Mistakes
+
+1. **Using blocks for preferences** - Use related instead
+2. **Using discovered-from for planning** - Use parent-child instead
+3. **Not using dependencies** - Add structure with dependencies
+4. **Over-using blocks** - Allow parallel work where possible
+5. **Wrong direction** - "from_id blocks to_id"

skills/bd-issue-tracking/references/ISSUE_CREATION.md

@@ -0,0 +1,104 @@
+# Issue Creation Guidelines
+
+When and how to create bd issues for maximum effectiveness.
+
+## When to Ask First vs Create Directly
+
+### Create directly when:
+
+- **Clear bug discovered** during implementation
+- **Obvious follow-up work** identified
+- **Technical debt** with clear scope
+- **Dependency or blocker** found
+
+### Ask first when:
+
+- Knowledge work with **fuzzy boundaries**
+- **Multiple valid approaches** exist
+- **User's intent** needs clarification
+- **Large epics** with unclear scope
+
+**Rule of thumb**: If you can write a clear, specific issue title in one sentence, create directly.
+
+## Issue Quality
+
+### Field Usage
+
+**Title**: Clear, specific, action-oriented
+- Good: "Fix: auth token expires before refresh"
+- Bad: "Fix bug"
+
+**Description**: Problem statement, context, why it matters
+- Good: "Update database: add user_last_login for session analytics"
+- Bad: "Update database"
+
+**Design field** (--design): Implementation approach
+- Architecture decisions
+- Trade-offs considered
+- Can change during implementation
+
+**Acceptance criteria** (--acceptance): Definition of done
+- Outcomes, not implementation steps
+- Should remain stable across sessions
+- Each criterion should be verifiable
+
+**Notes field**: Session handoffs, implementation details
+- COMPLETED/IN_PROGRESS/NEXT format
+- Evolves over time
+
+## Design vs Acceptance Criteria
+
+Common mistake: Putting implementation details in acceptance criteria.
+
+### DESIGN field (HOW to build):
+
+```
+"Use two-phase batchUpdate approach: insert text first, then apply formatting"
+"Parse with regex to find markers"
+"Use JWT tokens with 1-hour expiry"
+```
+
+### ACCEPTANCE CRITERIA (WHAT success looks like):
+
+```
+"Bold and italic formatting renders correctly"
+"User tokens persist across sessions"
+"Returns doc_id and webViewLink to caller"
+```
+
+### Why this matters:
+
+- Design can change during implementation
+- Acceptance criteria should remain stable
+- Criteria should be **outcome-focused** not **step-focused**
+- Each criterion should be **verifiable** (yes/no)
+
+### The test:
+
+If you rewrote the solution using a different approach, would the acceptance criteria still apply? If not, they're design notes.
+
+### Example
+
+**Wrong (design masquerading as criteria):**
+```
+- [ ] Use two-phase batchUpdate approach
+- [ ] Apply formatting in second call
+```
+
+**Right:**
+```
+Design: Two-phase Docs API approach for atomic operations
+
+Acceptance:
+- [ ] Markdown formatting renders in Doc
+- [ ] Lists preserve order and nesting
+- [ ] Large documents process without timeout
+```
+
+## Quick Reference
+
+1. **Title**: Clear, specific, action-oriented
+2. **Description**: Problem statement, context
+3. **Design**: Approach, trade-offs (can change)
+4. **Acceptance**: Outcomes (should be stable)
+5. **Notes**: Implementation details, session handoffs

skills/bd-issue-tracking/references/RESUMABILITY.md

@@ -0,0 +1,171 @@
+# Making Issues Resumable Across Sessions
+
+How to document issues so work can be resumed after days or weeks.
+
+## When Resumability Matters
+
+**Use enhanced documentation for:**
+- Multi-session technical features with API integration
+- Complex algorithms requiring code examples
+- Features with specific output format requirements
+- Work with undocumented API capabilities
+
+**Skip for:**
+- Simple bug fixes with clear scope
+- Well-understood patterns
+- Single-session tasks
+
+**The test:** Would a fresh Claude instance struggle to resume from the description alone?
+
+## Anatomy of a Resumable Issue
+
+### Minimal (Always Include)
+
+```
+Description: What needs to be built and why
+Acceptance Criteria: Concrete, testable outcomes
+```
+
+### Enhanced (Complex Technical Work)
+
+```
+Notes Field - IMPLEMENTATION GUIDE:
+
+WORKING CODE:
+```python
+# Tested code that works
+service = build('drive', 'v3', credentials=creds)
+result = service.about().get(fields='importFormats').execute()
+```
+
+API RESPONSE SAMPLE:
+Shows actual data structure
+
+DESIRED OUTPUT FORMAT:
+```markdown
+# Example of actual output structure
+```
+
+RESEARCH CONTEXT:
+Why this approach? What alternatives considered?
+```
+
+## Real Example
+
+### Not Resumable
+
+```
+Title: Add dynamic capabilities resources
+Description: Query Google APIs for capabilities
+Acceptance: Resources return capability info
+```
+
+**Problem:** Future Claude doesn't know:
+- Which API endpoints to call
+- What responses look like
+- What format to return
+
+### Resumable
+
+```
+Title: Add dynamic capabilities resources
+Description: Query Google APIs for system capabilities that aren't in static docs.
+
+Notes: IMPLEMENTATION GUIDE
+
+WORKING CODE (tested):
+```python
+service = build('drive', 'v3', credentials=creds)
+about = service.about().get(
+    fields='importFormats,exportFormats'
+).execute()
+# Returns: importFormats dict with 49 entries
+```
+
+OUTPUT FORMAT:
+```markdown
+# Drive Import Formats
+- **text/markdown** → Google Docs (NEW July 2024)
+```
+
+RESEARCH CONTEXT:
+text/markdown support not in static docs.
+
+Acceptance:
+- Query returns all formats including text/markdown
+- Output is readable markdown
+- Queries live API
+```
+
+**Result:** Fresh Claude can implement with full context.
+
+## Template
+
+For complex technical features:
+
+```markdown
+IMPLEMENTATION GUIDE:
+
+WORKING CODE (tested):
+```language
+# Actual working code
+# Include imports and setup
+```
+
+API RESPONSE SAMPLE:
+```json
+{ "actualField": "actualValue" }
+```
+
+DESIRED OUTPUT FORMAT:
+```
+Actual structure/style, not just "markdown"
+```
+
+RESEARCH CONTEXT:
+- Why this approach?
+- Alternatives considered?
+- Key discoveries?
+```
+
+## Anti-Patterns
+
+### Over-Documenting Simple Work
+
+```
+Title: Fix typo in README
+Notes: IMPLEMENTATION GUIDE...
+```
+Wastes tokens on obvious work.
+
+### Design in Acceptance Criteria
+
+```
+Acceptance:
+- [ ] Use batchUpdate approach
+- [ ] Call API with fields parameter
+```
+Locks implementation. Put in Design/Notes.
+
+### Raw JSON Dumps
+
+```
+API RESPONSE: {giant unformatted blob}
+```
+Extract relevant parts, show structure.
+
+## When to Add Detail
+
+**During issue creation:**
+- Already have working code from research? Include it.
+- Clear output format? Show example.
+
+**During work:**
+- Got API query working? Add to notes.
+- Made key decision? Explain rationale.
+
+**Session end:**
+- If resuming will be hard, add implementation guide.
+- If obvious, skip it.
+
+**Principle:** Help your future self resume without rediscovering everything.

skills/bd-issue-tracking/references/STATIC_DATA.md

@@ -0,0 +1,59 @@
+# Using bd for Static Reference Data
+
+bd is primarily for work tracking, but can serve as a queryable database for reference data.
+
+## Work Tracking (Primary Use Case)
+
+Standard bd workflow:
+- Issues flow through states (open → in_progress → closed)
+- Priorities and dependencies matter
+- Status tracking is essential
+
+## Reference Databases (Alternative Use)
+
+When using bd for static data (terminology, glossaries):
+
+**Characteristics:**
+- Entities are mostly static (typically always open)
+- No workflow or state transitions
+- Names/titles more important than IDs
+
+**Recommended approach:**
+- Use separate database (not mixed with work tracking)
+- Consider dual format: bd + markdown for name-based lookup
+
+## When to Use This Pattern
+
+**Good fit:**
+- Technical glossaries
+- Reference documentation with relationships
+- Knowledge bases with dependencies
+- Structured data needing queryability
+
+**Poor fit:**
+- Data that changes frequently
+- Simple lists (markdown is simpler)
+- Complex queries (use proper database)
+
+## Limitations
+
+**bd show requires IDs:**
+- `bd show term-42` works
+- `bd show "API endpoint"` doesn't work
+- Workaround: `bd list | grep -i "term"` to find ID
+
+**No full-text search:**
+- bd searches by ID, title, status, labels
+- For content search: `grep -i "term" .beads/issues.jsonl`
+
+## Summary
+
+Use bd for static reference data when:
+- You need relationships/dependencies between entries
+- Queryability matters
+- Dual format (bd + markdown) acceptable
+
+Stick with markdown for:
+- Simple lists
+- No relationships needed
+- Name-based lookup is primary use case

skills/bd-issue-tracking/references/WORKFLOWS.md

@@ -0,0 +1,178 @@
+# Workflows and Checklists
+
+Step-by-step workflows for common bd usage patterns.
+
+## Session Start Workflow
+
+```
+Session Start (when bd is available):
+- [ ] Run bd ready --json
+- [ ] Report: "X items ready to work on: [summary]"
+- [ ] If none ready, check bd blocked --json
+- [ ] Suggest next action based on findings
+```
+
+## Compaction Survival
+
+After compaction events, conversation history is deleted but bd state persists.
+
+```
+Post-Compaction Recovery:
+- [ ] Run bd list --status in_progress
+- [ ] Run bd show <id> for each in_progress issue
+- [ ] Read notes field: COMPLETED, IN PROGRESS, BLOCKERS, KEY DECISIONS
+- [ ] Check dependencies: bd dep tree <id>
+- [ ] Reconstruct context from issue data
+```
+
+### Writing Notes for Compaction Survival
+
+**Good note (enables recovery):**
+```
+COMPLETED: User authentication - added JWT token generation with 1hr expiry.
+IN PROGRESS: Password reset flow. Email service integration working.
+NEXT: Add rate limiting to reset endpoint.
+KEY DECISION: Using bcrypt with 12 rounds per OWASP recommendations.
+```
+
+**Bad note:**
+```
+Working on auth feature. Made some progress. More to do later.
+```
+
+## Discovery and Issue Creation
+
+```
+Discovery Workflow:
+- [ ] Notice bug, improvement, or follow-up work
+- [ ] Assess: Can defer or is blocker?
+- [ ] Create issue with bd create
+- [ ] Add discovered-from dependency
+- [ ] If blocker: pause and switch; if not: continue current work
+```
+
+## Status Maintenance
+
+```
+Issue Lifecycle:
+- [ ] Start: Update status to in_progress
+- [ ] During: Add design notes as decisions made
+- [ ] During: Update acceptance criteria if requirements clarify
+- [ ] During: Add dependencies if blockers discovered
+- [ ] Complete: Close with summary
+- [ ] After: Check bd ready for unblocked work
+```
+
+## Epic Planning
+
+```
+Epic Planning Workflow:
+- [ ] Create epic issue for high-level goal
+- [ ] Break down into child task issues
+- [ ] Add parent-child dependencies
+- [ ] Add blocks dependencies between children if order matters
+- [ ] Use bd ready to work through tasks
+```
+
+## Side Quest Handling
+
+```
+Side Quest Workflow:
+- [ ] During main work, discover problem
+- [ ] Create issue for side quest
+- [ ] Add discovered-from dependency
+- [ ] Assess: blocker or deferrable?
+- [ ] If blocker: mark main work blocked, switch
+- [ ] If deferrable: note in issue, continue main work
+```
+
+## Session Handoff
+
+### At Session Start
+
+```
+- [ ] Run bd list --status in_progress
+- [ ] For each: bd show <id>
+- [ ] Read notes field for context
+- [ ] Report to user with context
+- [ ] Wait for confirmation
+```
+
+### At Session End
+
+```
+- [ ] Notice work reaching stopping point
+- [ ] Prompt user about updating notes
+- [ ] Craft note with COMPLETED/IN_PROGRESS/NEXT
+- [ ] Execute bd update command
+- [ ] Run bd sync
+```
+
+## Multi-Session Resume
+
+```
+Resume Workflow:
+- [ ] Run bd ready for available work
+- [ ] Run bd stats for project overview
+- [ ] Show details on issue to work on
+- [ ] Review design notes and acceptance criteria
+- [ ] Update status to in_progress
+- [ ] Begin work with full context
+```
+
+## Unblocking Work
+
+```
+Unblocking Workflow:
+- [ ] Run bd blocked --json
+- [ ] Show details on blocked issues
+- [ ] Identify blocker issues
+- [ ] Choose: work on blocker, or reassess dependency
+- [ ] If reassess: remove incorrect dependency
+- [ ] If work on blocker: close it, check ready again
+```
+
+## Integration with TodoWrite
+
+```
+Hybrid Workflow:
+- [ ] Check bd for high-level context
+- [ ] Choose bd issue to work on
+- [ ] Mark bd issue in_progress
+- [ ] Create TodoWrite from acceptance criteria
+- [ ] Work through TodoWrite items
+- [ ] Update bd design notes as you learn
+- [ ] When TodoWrite complete, close bd issue
+```
+
+## Common Patterns
+
+### Bug Investigation
+
+```
+1. Create bug issue
+2. Reproduce: note steps in description
+3. Investigate: track hypotheses in design field
+4. Fix: implement solution
+5. Test: verify acceptance criteria
+6. Close with root cause and fix explanation
+```
+
+### Refactoring with Dependencies
+
+```
+1. Create issues for each refactoring step
+2. Add blocks dependencies for correct order
+3. Work through in dependency order
+4. bd ready automatically shows next step
+```
+
+### Spike Investigation
+
+```
+1. Create spike issue
+2. Time-box exploration
+3. Document findings in design field
+4. Create follow-up issues with discovered-from
+5. Close spike with recommendation
+```