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

Enhance Claude Code skill with real-world usage patterns (#116)

Browse Source 
* Update skill installation path and document new features

Installation path changes:
- Update from ~/.claude/skills/bd to bd-issue-tracking
- Matches internal skill name for consistency with other skills

Documentation additions:
- Add 3 new reference files to documentation list
- Document compaction survival patterns (critical for Claude Code)
- Mention self-check checklists and quality guidelines

This prepares the README for upcoming skill content improvements.

* Add new reference files for enhanced skill guidance

New reference documentation:

1. ISSUE_CREATION.md - When to ask vs create issues
   - Decision criteria for knowledge work vs technical work
   - Issue quality guidelines and best practices
   - Design vs acceptance criteria guidance
   - Self-check questions for well-scoped issues

2. RESUMABILITY.md - Making issues resumable across sessions
   - Patterns for complex technical work with APIs
   - Working code examples and API response samples
   - When enhanced documentation matters vs simple descriptions
   - Critical for multi-session work and crash recovery

3. STATIC_DATA.md - Using bd for reference databases
   - Alternative use case beyond work tracking
   - Glossaries and terminology management
   - Dual format patterns (database + markdown)
   - When bd helps vs when simpler formats suffice

These additions emerged from real-world usage patterns and enable
Claude to make better decisions about issue structure and resumability.

* Enhance existing skill files with real-world usage patterns

SKILL.md major enhancements (~194 net lines added):
- Add "Test Yourself" decision framework with self-check questions
- Document compaction survival patterns (critical for Claude Code)
- Add Notes Quality Self-Check (future-me test, stranger test)
- Session Start Checklist with copy-paste templates
- Field Usage Reference table (when to use each bd field)
- Progress Checkpointing triggers and patterns
- Issue Creation Checklist with quality self-checks
- Enhanced session handoff protocols

WORKFLOWS.md enhancements (~114 lines added):
- Session handoff workflow with detailed checklists
- Collaborative handoff between Claude and user
- Compaction survival workflow
- Notes format guidelines (current state, not cumulative)
- Session start checklist expansion

BOUNDARIES.md updates (~49 lines removed):
- Streamlined content (moved detailed workflows to WORKFLOWS.md)
- Retained core decision criteria
- Improved examples and integration patterns

CLI_REFERENCE.md minor updates:
- Additional command examples
- Clarified flag usage

These improvements emerged from extensive real-world usage, particularly
around crash recovery, compaction events, and multi-session workflows.
The additions make the skill more practical for autonomous agent use.
This commit is contained in:
spm1001
2025-10-23 17:26:30 +01:00
committed by GitHub
parent 5bc298a175
commit bdaf82026a
8 changed files with 782 additions and 123 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
examples/claude-code-skill/README.md
View File

@@ -12,7 +12,8 @@ This is a [Claude Code](https://claude.com/claude-code) skill - a markdown-based
- Core workflow patterns (discovery, execution, planning phases)
- Decision criteria for when to use bd vs TodoWrite/markdown
- Session start protocols and ready work checks
- Issue lifecycle management
- Compaction survival patterns (critical for Claude Code context limits)
- Issue lifecycle management with self-check checklists
- Integration patterns with other tools
**Reference documentation:**
@@ -20,6 +21,9 @@ This is a [Claude Code](https://claude.com/claude-code) skill - a markdown-based
- `references/CLI_REFERENCE.md` - Complete command reference with all flags
- `references/DEPENDENCIES.md` - Deep dive into dependency types and relationship patterns
- `references/WORKFLOWS.md` - Step-by-step workflows with checklists
- `references/ISSUE_CREATION.md` - When to ask vs create issues, quality guidelines
- `references/RESUMABILITY.md` - Making issues resumable across sessions with working code examples
- `references/STATIC_DATA.md` - Using bd for reference databases and glossaries
## Why is This Useful?
@@ -56,17 +60,17 @@ git clone https://github.com/steveyegge/beads.git
cd beads/examples/claude-code-skill
# Create a symlink in your Claude Code skills directory
ln -s "$(pwd)" ~/.claude/skills/bd
ln -s "$(pwd)" ~/.claude/skills/bd-issue-tracking
```
#### Option 2: Copy Files Directly
```bash
# Create the skill directory
mkdir -p ~/.claude/skills/bd
mkdir -p ~/.claude/skills/bd-issue-tracking
# Copy the skill files
cp -r beads/examples/claude-code-skill/* ~/.claude/skills/bd/
cp -r beads/examples/claude-code-skill/* ~/.claude/skills/bd-issue-tracking/
```
### Verify Installation

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

@@ -26,15 +26,83 @@ bd is a graph-based issue tracker for persistent memory across sessions. Use for
**Key insight**: If resuming work after 2 weeks would be difficult without bd, use bd. If the work can be picked up from a markdown skim, TodoWrite is sufficient.
### Test Yourself: bd or TodoWrite?
Ask these questions to decide:
**Choose bd if:**
- ❓ "Will I need this context in 2 weeks?" → Yes = bd
- ❓ "Could conversation history get compacted?" → Yes = bd
- ❓ "Does this have blockers/dependencies?" → Yes = bd
- ❓ "Is this fuzzy/exploratory work?" → Yes = bd
**Choose TodoWrite if:**
- ❓ "Will this be done in this session?" → Yes = TodoWrite
- ❓ "Is this just a task list for me right now?" → Yes = TodoWrite
- ❓ "Is this linear with no branching?" → Yes = TodoWrite
**When in doubt**: Use bd. Better to have persistent memory you don't need than to lose context you needed.
**For detailed decision criteria and examples, read:** [references/BOUNDARIES.md](references/BOUNDARIES.md)
## Surviving Compaction Events
**Critical**: After compaction, bd state is your only persistent memory. Write notes as if explaining to a future agent with zero conversation context.
**Critical**: Compaction events delete conversation history but preserve beads. After compaction, bd state is your only persistent memory.
**Key insight**: TodoWrite disappears after compaction, but bead notes survive. Use notes to capture: COMPLETED work, IN PROGRESS status, BLOCKERS, and KEY DECISIONS.
**What survives compaction:**
- All bead data (issues, notes, dependencies, status)
- Complete work history and context
**For complete compaction recovery workflow and note-taking patterns, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md#compaction-survival)
**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.
### Notes Quality Self-Check
Before checkpointing (especially pre-compaction), verify your notes pass these tests:
❓ **Future-me test**: "Could I resume this work in 2 weeks with zero conversation history?"
- [ ] What was completed? (Specific deliverables, not "made progress")
- [ ] What's in progress? (Current state + immediate next step)
- [ ] What's blocked? (Specific blockers with context)
- [ ] What decisions were made? (Why, not just what)
❓ **Stranger test**: "Could another developer understand this without asking me?"
- [ ] Technical choices explained (not just stated)
- [ ] Trade-offs documented (why this approach vs alternatives)
- [ ] User input captured (decisions that came from discussion)
**Good note example:**
```
COMPLETED: JWT auth with RS256 (1hr access, 7d refresh tokens)
KEY DECISION: RS256 over HS256 per security review - enables key rotation
IN PROGRESS: Password reset flow - email service working, need rate limiting
BLOCKERS: Waiting on user decision: reset token expiry (15min vs 1hr trade-off)
NEXT: Implement rate limiting (5 attempts/15min) once expiry decided
```
**Bad note example:**
```
Working on auth. Made some progress. More to do.
```
**For complete compaction recovery workflow, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md#compaction-survival)
## Session Start Protocol
@@ -42,24 +110,31 @@ bd is a graph-based issue tracker for persistent memory across sessions. Use for
- Project has a `.beads/` directory (project-local database), OR
- `~/.beads/` exists (global fallback database for any directory)
**At session start, always check for bd availability and run ready check:**
**At session start, always check for bd availability and run ready check.**
1. **Always check ready work automatically** at session start
2. **Report status** to establish shared context
### Session Start Checklist
### Quick Start Pattern
Copy this checklist when starting any session where bd is available:
```bash
# At session start, run:
bd ready --json
# Report to user:
"I can see X items ready to work on: [brief summary]"
# If using global ~/.beads, note this in report
```
Session Start:
- [ ] Run bd ready --json to see available work
- [ ] Run bd list --status in_progress --json for active work
- [ ] If in_progress exists: bd show <issue-id> to read notes
- [ ] Report context to user: "X items ready: [summary]"
- [ ] If using global ~/.beads, mention this in report
- [ ] If nothing ready: bd blocked --json to check blockers
```
This gives immediate shared context about available work without requiring user prompting.
**Pattern**: Always check both `bd ready` AND `bd list --status in_progress`. Read notes field first to understand where previous session left off.
**Report format**:
- "I can see X items ready to work on: [summary]"
- "Issue Y is in_progress. Last session: [summary from notes]. Next: [from notes]. Should I continue with that?"
This establishes immediate shared context about available and active work without requiring user prompting.
**For detailed collaborative handoff process, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md#session-handoff)
**Note**: bd auto-discovers the database:
- Uses `.beads/*.db` in current project if exists
@@ -76,6 +151,44 @@ bd blocked --json
Report blockers and suggest next steps.
---
## Progress Checkpointing
Update bd notes at these checkpoints (don't wait for session end):
**Critical triggers:**
- ⚠️ **Context running low** - User says "running out of context" / "approaching compaction" / "close to token limit"
- 📊 **Token budget > 70%** - Proactively checkpoint when approaching limits
- 🎯 **Major milestone reached** - Completed significant piece of work
- 🚧 **Hit a blocker** - Can't proceed, need to capture what was tried
- 🔄 **Task transition** - Switching issues or about to close this one
- ❓ **Before user input** - About to ask decision that might change direction
**Proactive monitoring during session:**
- At 70% token usage: "We're at 70% token usage - good time to checkpoint bd notes?"
- At 85% token usage: "Approaching token limit (85%) - checkpointing current state to bd"
- At 90% token usage: Automatically checkpoint without asking
**Current token usage**: Check `<system-warning>Token usage:` messages to monitor proactively.
**Checkpoint checklist:**
```
Progress Checkpoint:
- [ ] Update notes with COMPLETED/IN_PROGRESS/NEXT format
- [ ] Document KEY DECISIONS or BLOCKERS since last update
- [ ] Mark current status (in_progress/blocked/closed)
- [ ] If discovered new work: create issues with discovered-from
- [ ] Verify notes are self-explanatory for post-compaction resume
```
**Most important**: When user says "running out of context" OR when you see >70% token usage - checkpoint immediately, even if mid-task.
**Test yourself**: "If compaction happened right now, could future-me resume from these notes?"
---
### Database Selection
bd automatically selects the appropriate database:
@@ -84,7 +197,15 @@ 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.
**Database discovery**: bd looks for `.beads/*.db` in current directory, falls back to `~/.beads/default.db`. Use `--db` flag for explicit database selection.
**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)
@@ -142,6 +263,23 @@ bd list --assignee alice
**For complete CLI reference with all flags and examples, read:** [references/CLI_REFERENCE.md](references/CLI_REFERENCE.md)
## Field Usage Reference
Quick guide for when and how to use each bd field:
| Field | Purpose | When to Set | Update Frequency |
|-------|---------|-------------|------------------|
| **description** | Immutable problem statement | At creation | Never (fixed forever) |
| **design** | Initial approach, architecture, decisions | During planning | Rarely (only if approach changes) |
| **acceptance-criteria** | Concrete deliverables checklist (`- [ ]` syntax) | When design is clear | Mark `- [x]` as items complete |
| **notes** | Session handoff (COMPLETED/IN_PROGRESS/NEXT) | During work | At session end, major milestones |
| **status** | Workflow state (open→in_progress→closed) | As work progresses | When changing phases |
| **priority** | Urgency level (0=highest, 3=lowest) | At creation | Adjust if priorities shift |
**Key pattern**: Notes field is your "read me first" at session start. See [WORKFLOWS.md](references/WORKFLOWS.md#session-handoff) for session handoff details.
---
## Issue Lifecycle Workflow
### 1. Discovery Phase (Proactive Issue Creation)
@@ -229,23 +367,86 @@ bd supports four dependency types:
## Integration with TodoWrite
**Both tools complement each other at different timescales:**
- **TodoWrite** - Short-term working memory (this hour), disappears after session
- **Beads** - Long-term episodic memory (this week/month), survives compaction
**The Handoff Pattern**: Read bead → Create TodoWrite items → Work → Update bead notes with outcomes → TodoWrite disappears, bead survives.
### Temporal Layering Pattern
**For complete temporal layering pattern, examples, and integration workflows, read:** [references/BOUNDARIES.md](references/BOUNDARIES.md#integration-patterns)
**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
### 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:**
```
[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
### Pattern 1: Knowledge Work Session
User asks for strategic document development:
1. Check if bd available: `bd ready`
2. If related epic exists, show current status
3. Create new issues for discovered research needs
4. Use discovered-from to track where ideas came from
5. Update design notes as research progresses
**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.
### Pattern 2: Side Quest Handling
@@ -267,55 +468,46 @@ Starting work after time away:
**For complete workflow walkthroughs with checklists, read:** [references/WORKFLOWS.md](references/WORKFLOWS.md)
## Use Pattern Variations
## Issue Creation
bd is designed for work tracking but can serve other purposes with appropriate adaptations:
**Quick guidelines:**
- Ask user first for knowledge work with fuzzy boundaries
- Create directly for clear bugs, technical debt, or discovered work
- Use clear titles, sufficient context in descriptions
- Design field: HOW to build (can change during implementation)
- Acceptance criteria: WHAT success looks like (should remain stable)
### 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
### Issue Creation Checklist
### 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
Copy when creating new issues:
**Example**: A terminology database could use both `terms.db` (queryable) and `GLOSSARY.md` (browsable by name).
```
Creating Issue:
- [ ] Title: Clear, specific, action-oriented
- [ ] Description: Problem statement (WHY this matters) - immutable
- [ ] Design: HOW to build (can change during work)
- [ ] Acceptance: WHAT success looks like (stays stable)
- [ ] Priority: 0=critical, 1=high, 2=normal, 3=low
- [ ] Type: bug/feature/task/epic/chore
```
**Key difference**: Work items have lifecycle; reference entities are stable knowledge.
**Self-check for acceptance criteria:**
## Issue Creation Guidelines
❓ "If I changed the implementation approach, would these criteria still apply?"
- → **Yes** = Good criteria (outcome-focused)
- → **No** = Move to design field (implementation-focused)
### When to Ask First vs Create Directly
**Example:**
- ✅ Acceptance: "User tokens persist across sessions and refresh automatically"
- ❌ Wrong: "Use JWT tokens with 1-hour expiry" (that's design, not acceptance)
**Ask the user before creating when:**
- Knowledge work with fuzzy boundaries
- Task scope is unclear
- Multiple valid approaches exist
- User's intent needs clarification
**For detailed guidance on when to ask vs create, issue quality, resumability patterns, and design vs acceptance criteria, read:** [references/ISSUE_CREATION.md](references/ISSUE_CREATION.md)
**Create directly when:**
- Clear bug discovered during implementation
- Obvious follow-up work identified
- Technical debt with clear scope
- Dependency or blocker found
## Alternative Use Cases
**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.
bd is primarily for work tracking, but can also serve as queryable database for static reference data (glossaries, terminology) with adaptations.
### Issue Quality
Use clear, specific titles and include sufficient context in descriptions to resume work later.
**Use --design flag for:**
- Implementation approach decisions, architecture notes, trade-offs considered
**Use --acceptance flag for:**
- Definition of done, testing requirements, success metrics
**For guidance on using bd for reference databases and static data, read:** [references/STATIC_DATA.md](references/STATIC_DATA.md)
## Statistics and Monitoring
@@ -441,3 +633,5 @@ Detailed information organized by topic:
| [references/CLI_REFERENCE.md](references/CLI_REFERENCE.md) | Need complete command reference, flag details, or examples |
| [references/WORKFLOWS.md](references/WORKFLOWS.md) | Need step-by-step workflows with checklists for common scenarios |
| [references/DEPENDENCIES.md](references/DEPENDENCIES.md) | Need deep understanding of dependency types or relationship patterns |
| [references/ISSUE_CREATION.md](references/ISSUE_CREATION.md) | Need guidance on when to ask vs create issues, issue quality, or design vs acceptance criteria |
| [references/STATIC_DATA.md](references/STATIC_DATA.md) | Want to use bd for reference databases, glossaries, or static data instead of work tracking |

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

@@ -246,55 +246,6 @@ Rare, but happens when bd issue turns out simpler than expected.
5. Note: "Completed in single session, simpler than expected"
```
### Pattern 4: Temporal Layering (Complementary Use)
**Key insight**: TodoWrite and bd operate at different timescales and serve different memory needs.
**TodoWrite** (short-term working memory - this hour):
- Tactical execution steps
- Present/future tense ("Implement", "Test", "Deploy")
- Marked completed as you go
- Ephemeral: Disappears when session ends
**Beads** (long-term episodic memory - this week/month):
- Strategic objectives and context
- Past tense in notes ("COMPLETED", "Discovered", "Blocked by")
- Key decisions and outcomes in notes field
- 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 for this session:
```
[completed] Implement login endpoint
[in_progress] Add password hashing with bcrypt
[pending] Create session middleware
```
Corresponding bead notes:
```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)."
```
**Don't duplicate**: TodoWrite tracks execution, Beads captures meaning and context.
**When to use this pattern:**
- Long-running features requiring multiple sessions
- Work that will likely face compaction
- Need both immediate visibility (TodoWrite) and long-term memory (bd)
- Strategic work with tactical execution steps
## Real-World Examples
### Example 1: Database Migration Planning

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

@@ -190,13 +190,9 @@ Visualize full dependency tree for an issue.
```bash
bd dep tree issue-123
# Limit tree depth (default: 50)
bd dep tree issue-123 --max-depth 10
bd dep tree issue-123 -d 10
```
Shows all dependencies and dependents in tree format. Use `--max-depth` to limit traversal depth for very deep trees.
Shows all dependencies and dependents in tree format.
---

139
examples/claude-code-skill/references/ISSUE_CREATION.md Normal file
View File

@@ -0,0 +1,139 @@
# Issue Creation Guidelines
Guidance on when and how to create bd issues for maximum effectiveness.
## Contents
- [When to Ask First vs Create Directly](#when-to-ask)
- [Issue Quality](#quality)
- [Making Issues Resumable](#resumable)
- [Design vs Acceptance Criteria](#design-vs-acceptance)
## When to Ask First vs Create Directly {#when-to-ask}
### Ask the user before creating when:
- Knowledge work with fuzzy boundaries
- Task scope is unclear
- Multiple valid approaches exist
- User's intent needs clarification
### Create directly when:
- Clear bug discovered during implementation
- Obvious follow-up work identified
- Technical debt with clear scope
- Dependency or blocker found
**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 {#quality}
Use clear, specific titles and include sufficient context in descriptions to resume work later.
### Field Usage
**Use --design flag for:**
- Implementation approach decisions
- Architecture notes
- Trade-offs considered
**Use --acceptance flag for:**
- Definition of done
- Testing requirements
- Success metrics
## Making Issues Resumable (Complex Technical Work) {#resumable}
For complex technical features spanning multiple sessions, enhance notes field with implementation details.
### Optional but valuable for technical work:
- Working API query code (tested, with response structure)
- Sample API responses showing actual data
- Desired output format examples (show, don't describe)
- Research context (why this approach, what was discovered)
### Example pattern:
```markdown
bd update issue-9 --notes "IMPLEMENTATION GUIDE:
WORKING CODE: service.about().get(fields='importFormats')
Returns: dict with 49 entries like {'text/markdown': [...]}
OUTPUT FORMAT: # Drive Import Formats (markdown with categorized list)
CONTEXT: text/markdown support added July 2024, not in static docs"
```
**When to add:** Multi-session technical features with APIs or specific formats. Skip for simple tasks.
**For detailed patterns and examples, read:** [RESUMABILITY.md](RESUMABILITY.md)
## Design vs Acceptance Criteria (Critical Distinction) {#design-vs-acceptance}
Common mistake: Putting implementation details in acceptance criteria. Here's the difference:
### DESIGN field (HOW to build it):
- "Use two-phase batchUpdate approach: insert text first, then apply formatting"
- "Parse with regex to find * and _ markers"
- "Use JWT tokens with 1-hour expiry"
- Trade-offs: "Chose batchUpdate over streaming API for atomicity"
### ACCEPTANCE CRITERIA (WHAT SUCCESS LOOKS LIKE):
- "Bold and italic markdown formatting renders correctly in the Doc"
- "Solution accepts markdown input and creates Doc with specified title"
- "Returns doc_id and webViewLink to caller"
- "User tokens persist across sessions and refresh automatically"
### Why this matters:
- Design can change during implementation (e.g., use library instead of regex)
- Acceptance criteria should remain stable across sessions
- Criteria should be **outcome-focused** ("what must be true?") not **step-focused** ("do these steps")
- Each criterion should be **verifiable** - you can definitively say yes/no
### The pitfall
Writing criteria like "- [ ] Use batchUpdate approach" locks you into one implementation.
Better: "- [ ] Formatting is applied atomically (all at once or not at all)" - allows flexible implementation.
### Test yourself
If you rewrote the solution using a different approach, would the acceptance criteria still apply? If not, they're design notes, not criteria.
### Example of correct structure
✅ **Design field:**
```
Two-phase Docs API approach:
1. Parse markdown to positions
2. Create doc + insert text in one call
3. Apply formatting in second call
Rationale: Atomic operations, easier to debug formatting separately
```
✅ **Acceptance criteria:**
```
- [ ] Markdown formatting renders in Doc (bold, italic, headings)
- [ ] Lists preserve order and nesting
- [ ] Links are clickable
- [ ] Large documents (>50KB) process without timeout
```
❌ **Wrong (design masquerading as criteria):**
```
- [ ] Use two-phase batchUpdate approach
- [ ] Apply formatting in second batchUpdate call
```
## Quick Reference
**Creating good issues:**
1. **Title**: Clear, specific, action-oriented
2. **Description**: Problem statement, context, why it matters
3. **Design**: Approach, architecture, trade-offs (can change)
4. **Acceptance**: Outcomes, success criteria (should be stable)
5. **Notes**: Implementation details, session handoffs (evolves over time)
**Common mistakes:**
- Vague titles: "Fix bug" → "Fix: auth token expires before refresh"
- Implementation in acceptance: "Use JWT" → "Auth tokens persist across sessions"
- Missing context: "Update database" → "Update database: add user_last_login for session analytics"

207
examples/claude-code-skill/references/RESUMABILITY.md Normal file
View File

@@ -0,0 +1,207 @@
# Making Issues Resumable Across Sessions
## 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 "occult" APIs (undocumented capabilities)
**Skip for:**
- Simple bug fixes with clear scope
- Well-understood patterns (CRUD operations, etc.)
- Single-session tasks
- Work with obvious acceptance criteria
**The test:** Would a fresh Claude instance (or you after 2 weeks) struggle to resume this work from the description alone? If yes, add implementation details.
## Anatomy of a Resumable Issue
### Minimal (Always Include)
```markdown
Description: What needs to be built and why
Acceptance Criteria: Concrete, testable outcomes (WHAT not HOW)
```
### Enhanced (Complex Technical Work)
```markdown
Notes Field - IMPLEMENTATION GUIDE:
WORKING CODE:
```python
# Tested code that queries the API
service = build('drive', 'v3', credentials=creds)
result = service.about().get(fields='importFormats').execute()
# Returns: {'text/markdown': ['application/vnd.google-apps.document'], ...}
```
API RESPONSE SAMPLE:
Shows actual data structure (not docs description)
DESIRED OUTPUT FORMAT:
```markdown
# Example of what the output should look like
Not just "return markdown" but actual structure
```
RESEARCH CONTEXT:
Why this approach? What alternatives were considered?
Key discoveries that informed the design.
```
## Real Example: Before vs After
### ❌ Not Resumable
```
Title: Add dynamic capabilities resources
Description: Query Google APIs for capabilities and return as resources
Acceptance: Resources return capability info
```
**Problem:** Future Claude doesn't know:
- Which API endpoints to call
- What the responses look like
- What format to return
### ✅ Resumable
```
Title: Add dynamic capabilities resources
Description: Query Google APIs for system capabilities (import formats,
themes, quotas) that aren't in static docs. Makes server self-documenting.
Notes: IMPLEMENTATION GUIDE
WORKING CODE (tested):
```python
from workspace_mcp.tools.drive import get_credentials
from googleapiclient.discovery import build
creds = get_credentials()
service = build('drive', 'v3', credentials=creds)
about = service.about().get(
fields='importFormats,exportFormats,folderColorPalette'
).execute()
# Returns:
# - importFormats: dict, 49 entries like {'text/markdown': [...]}
# - exportFormats: dict, 10 entries
# - folderColorPalette: list, 24 hex strings
```
OUTPUT FORMAT EXAMPLE:
```markdown
# Drive Import Formats
Google Drive supports 49 import formats:
## Text Formats
- **text/markdown** → Google Docs ✨ (NEW July 2024)
- text/plain → Google Docs
...
```
RESEARCH CONTEXT:
text/markdown support announced July 2024 but NOT in static Google docs.
Google's workspace-developer MCP server doesn't expose this.
This is why dynamic resources matter.
Acceptance Criteria:
- User queries workspace://capabilities/drive/import-formats
- Response shows all 49 formats including text/markdown
- Output is readable markdown, not raw JSON
- Queries live API (not static data)
```
**Result:** Fresh Claude instance can:
1. See working API query code
2. Understand response structure
3. Know desired output format
4. Implement with context
## Optional Template
Copy this into notes field for complex technical features:
```markdown
IMPLEMENTATION GUIDE FOR FUTURE SESSIONS:
WORKING CODE (tested):
```language
# Paste actual code that works
# Include imports and setup
# Show what it returns
```
API RESPONSE SAMPLE:
```json
{
"actualField": "actualValue",
"structure": "as returned by API"
}
```
DESIRED OUTPUT FORMAT:
```
Show what the final output should look like
Not just "markdown" but actual structure/style
```
RESEARCH CONTEXT:
- Why this approach?
- What alternatives considered?
- Key discoveries?
- Links to relevant docs/examples?
```
## Anti-Patterns
### ❌ Over-Documenting Simple Work
```markdown
Title: Fix typo in README
Notes: IMPLEMENTATION GUIDE
WORKING CODE: Open README.md, change "teh" to "the"...
```
**Problem:** Wastes tokens on obvious work.
### ❌ Design Details in Acceptance Criteria
```markdown
Acceptance:
- [ ] Use batchUpdate approach
- [ ] Call API with fields parameter
- [ ] Format as markdown with ## headers
```
**Problem:** Locks implementation. Should be in Design/Notes, not Acceptance.
### ❌ Raw JSON Dumps
```markdown
API RESPONSE:
{giant unformatted JSON blob spanning 100 lines}
```
**Problem:** Hard to read. Extract relevant parts, show structure.
### ✅ Right Balance
```markdown
API RESPONSE SAMPLE:
Returns dict with 49 entries. Example entries:
- 'text/markdown': ['application/vnd.google-apps.document']
- 'text/plain': ['application/vnd.google-apps.document']
- 'application/pdf': ['application/vnd.google-apps.document']
```
## When to Add This Detail
**During issue creation:**
- Already have working code from research? Include it.
- Clear output format in mind? Show example.
**During work (update notes):**
- Just got API query working? Add to notes.
- Discovered important context? Document it.
- Made key decision? Explain rationale.
**Session end:**
- If resuming will be hard, add implementation guide.
- If obvious, skip it.
**The principle:** Help your future self (or next Claude) resume without rediscovering everything.

54
examples/claude-code-skill/references/STATIC_DATA.md Normal file
View File

@@ -0,0 +1,54 @@
# Using bd for Static Reference Data
bd is primarily designed for work tracking, but can also serve as a queryable database for static reference data with some adaptations.
## Work Tracking (Primary Use Case)
Standard bd workflow:
- 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)
When using bd for static data (terminology, glossaries, reference information):
**Characteristics:**
- Entities are mostly static (typically always open)
- No real workflow or state transitions
- Names/titles more important than IDs
- Minimal or no dependencies
**Recommended approach:**
- Use separate database (not mixed with work tracking) to avoid confusion
- Consider dual format: maintain markdown version alongside database for name-based lookup
- Example: A terminology database could use both `terms.db` (queryable via bd) and `GLOSSARY.md` (browsable by name)
**Key difference**: Work items have lifecycle; reference entities are stable knowledge.
## When to Use This Pattern
**Good fit:**
- Technical glossaries or terminology databases
- Reference documentation that needs dependency tracking
- Knowledge bases with relationships between entries
- Structured data that benefits from queryability
**Poor fit:**
- Data that changes frequently (use work tracking pattern)
- Simple lists (markdown is simpler)
- Data that needs complex queries (use proper database)
## Limitations
**bd show requires IDs, not names:**
- `bd show term-42` works
- `bd show "API endpoint"` doesn't work
- Workaround: `bd list | grep -i "api endpoint"` to find ID first
- This is why dual format (bd + markdown) is recommended for reference data
**No search by content:**
- bd searches by ID, title filters, status, labels
- For full-text search across descriptions/notes, use grep on the JSONL file
- Example: `grep -i "authentication" .beads/issues.jsonl`

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

@@ -11,6 +11,7 @@ Detailed step-by-step workflows for common bd usage patterns with checklists.
- [Epic Planning](#epic-planning) - Structuring complex work with dependencies
- [Side Quest Handling](#side-quests) - Discovery during main task, assessing blocker vs deferrable, resuming
- [Multi-Session Resume](#resume) - Returning after days/weeks away
- [Session Handoff Workflow](#session-handoff) - Collaborative handoff between sessions
- [Unblocking Work](#unblocking) - Handling blocked issues
- [Integration with TodoWrite](#integration-with-todowrite) - Using both tools together
- [Common Workflow Patterns](#common-workflow-patterns)
@@ -234,6 +235,119 @@ Resume Workflow:
---
## Session Handoff Workflow {#session-handoff}
**Collaborative handoff between sessions using notes field:**
This workflow enables smooth work resumption by updating beads notes when stopping, then reading them when resuming. Works in conjunction with compaction survival - creates continuity even after conversation history is deleted.
### At Session Start (Claude's responsibility)
```
Session Start with in_progress issues:
- [ ] Run bd list --status in_progress
- [ ] For each in_progress issue: bd show <issue-id>
- [ ] Read notes field to understand: COMPLETED, IN PROGRESS, NEXT
- [ ] Report to user with context from notes field
- [ ] Example: "workspace-mcp-server-2 is in_progress. Last session:
completed tidying. No code written yet. Next step: create
markdown_to_docs.py. Should I continue with that?"
- [ ] Wait for user confirmation or direction
```
**Pattern**: Notes field is the "read me first" guide for resuming work.
### At Session End (Claude prompts user)
When wrapping up work on an issue:
```
Session End Handoff:
- [ ] Notice work reaching a stopping point
- [ ] Prompt user: "We just completed X and started Y on <issue-id>.
Should I update the beads notes for next session?"
- [ ] If yes, suggest command:
bd update <issue-id> --notes "COMPLETED: X. IN PROGRESS: Y. NEXT: Z"
- [ ] User reviews and confirms
- [ ] Claude executes the update
- [ ] Notes saved for next session's resumption
```
**Pattern**: Update notes at logical stopping points, not after every keystroke.
### Notes Format (Current State, Not Cumulative)
```
Good handoff note (current state):
COMPLETED: Parsed markdown into structured format
IN PROGRESS: Implementing Docs API insertion
NEXT: Debug batchUpdate call - getting 400 error on formatting
BLOCKER: None
KEY DECISION: Using two-phase approach (insert text, then apply formatting) based on reference implementation
Bad handoff note (not useful):
Updated some stuff. Will continue later.
```
**Rules for handoff notes:**
- Current state only (overwrite previous notes, not append)
- Specific accomplishments (not vague progress)
- Concrete next step (not "continue working")
- Optional: Blockers, key decisions, references
- Written for someone with zero conversation context
### Session Handoff Checklist
For Claude at session end:
```
Session End Checklist:
- [ ] Work reaching logical stopping point
- [ ] Prompt user about updating notes
- [ ] If approved:
- [ ] Craft note with COMPLETED/IN_PROGRESS/NEXT
- [ ] Include blocker if stuck
- [ ] Include key decisions if relevant
- [ ] Suggest bd update command
- [ ] Execute approved update
- [ ] Confirm: "Saved handoff notes for next session"
```
For user (optional, but helpful):
```
User Tips:
- [ ] When stopping work: Let Claude suggest notes update
- [ ] When resuming: Let Claude read notes and report context
- [ ] Avoid: Trying to remember context manually (that's what notes are for!)
- [ ] Trust: Well-written notes will help next session pick up instantly
```
### Example: Real Session Handoff
**Scenario:** Implementing markdown→Docs feature (workspace-mcp-server-2)
**At End of Session 1:**
```bash
bd update workspace-mcp-server-2 --notes "COMPLETED: Set up skeleton with Docs
API connection verified. Markdown parsing logic 80% done (handles *, _ modifiers).
IN PROGRESS: Testing edge cases for nested formatting. NEXT: Implement
batchUpdate call structure for text insertion. REFERENCE: Reference pattern at
docs/markdown-to-docs-reference.md. No blockers, moving well."
```
**At Start of Session 2:**
```bash
bd show workspace-mcp-server-2
# Output includes notes field showing exactly where we left off
# Claude reports: "Markdown→Docs feature is 80% parsed. We were testing
# edge cases and need to implement batchUpdate next. Want to continue?"
```
Session resumes instantly with full context, no history scrolling needed.
---
## Unblocking Work {#unblocking}
**When ready list is empty:**