From 025142d55e192941487cfee5c2dbf7afc6a4d229 Mon Sep 17 00:00:00 2001 From: Peter Chanthamynavong Date: Fri, 2 Jan 2026 12:39:45 -0800 Subject: [PATCH] docs(skill): restructure for progressive disclosure pattern (#857) Align beads skill with Claude Code best practices: - Restructure SKILL.md from 3,306 to ~510 words (85% reduction) - Use bd prime as CLI reference source of truth (DRY) - Rename references/ to resources/ per Claude Code conventions - Add v0.43.0 feature documentation (agents, gates, worktrees) - Add ADR-0001 documenting the bd prime decision - Add CLAUDE.md maintenance guide New resources: - agents.md - Agent bead tracking - async-gates.md - Human-in-the-loop gates - chemistry-patterns.md - Mol vs Wisp decision tree - worktrees.md - Parallel development patterns BREAKING: references/ path changed to resources/ Fixes #855 --- skills/beads/CLAUDE.md | 86 ++ skills/beads/README.md | 23 +- skills/beads/SKILL.md | 855 ++---------------- .../adr/0001-bd-prime-as-source-of-truth.md | 59 ++ skills/beads/resources/AGENTS.md | 62 ++ skills/beads/resources/ASYNC_GATES.md | 168 ++++ .../{references => resources}/BOUNDARIES.md | 0 skills/beads/resources/CHEMISTRY_PATTERNS.md | 197 ++++ .../CLI_REFERENCE.md | 0 .../{references => resources}/DEPENDENCIES.md | 0 .../INTEGRATION_PATTERNS.md | 0 .../ISSUE_CREATION.md | 0 .../{references => resources}/MOLECULES.md | 0 .../{references => resources}/PATTERNS.md | 0 .../{references => resources}/RESUMABILITY.md | 0 .../{references => resources}/STATIC_DATA.md | 0 .../TROUBLESHOOTING.md | 0 .../{references => resources}/WORKFLOWS.md | 0 skills/beads/resources/WORKTREES.md | 94 ++ 19 files changed, 749 insertions(+), 795 deletions(-) create mode 100644 skills/beads/CLAUDE.md create mode 100644 skills/beads/adr/0001-bd-prime-as-source-of-truth.md create mode 100644 skills/beads/resources/AGENTS.md create mode 100644 skills/beads/resources/ASYNC_GATES.md rename skills/beads/{references => resources}/BOUNDARIES.md (100%) create mode 100644 skills/beads/resources/CHEMISTRY_PATTERNS.md rename skills/beads/{references => resources}/CLI_REFERENCE.md (100%) rename skills/beads/{references => resources}/DEPENDENCIES.md (100%) rename skills/beads/{references => resources}/INTEGRATION_PATTERNS.md (100%) rename skills/beads/{references => resources}/ISSUE_CREATION.md (100%) rename skills/beads/{references => resources}/MOLECULES.md (100%) rename skills/beads/{references => resources}/PATTERNS.md (100%) rename skills/beads/{references => resources}/RESUMABILITY.md (100%) rename skills/beads/{references => resources}/STATIC_DATA.md (100%) rename skills/beads/{references => resources}/TROUBLESHOOTING.md (100%) rename skills/beads/{references => resources}/WORKFLOWS.md (100%) create mode 100644 skills/beads/resources/WORKTREES.md diff --git a/skills/beads/CLAUDE.md b/skills/beads/CLAUDE.md new file mode 100644 index 00000000..9f476452 --- /dev/null +++ b/skills/beads/CLAUDE.md @@ -0,0 +1,86 @@ +# Beads Skill Maintenance Guide + +## Architecture Decisions + +ADRs in `adr/` document key decisions. These are NOT loaded during skill invocation—they're reference material for maintainers making changes. + +| ADR | Decision | +|-----|----------| +| [ADR-0001](adr/0001-bd-prime-as-source-of-truth.md) | Use `bd prime` as CLI reference source of truth | + +## Key Principle: DRY via bd prime + +**NEVER duplicate CLI documentation in SKILL.md or resources.** + +- `bd prime` outputs AI-optimized workflow context +- `bd --help` provides specific usage +- Both auto-update with bd releases + +**SKILL.md should only contain:** +- Decision frameworks (bd vs TodoWrite) +- Prerequisites (install verification) +- Resource index (progressive disclosure) +- Pointers to `bd prime` and `--help` + +## Keeping the Skill Updated + +### When bd releases new version: + +1. **Check for new features**: `bd --help` for new commands +2. **Update SKILL.md frontmatter**: `version: "X.Y.Z"` +3. **Add resources for conceptual features** (agents, gates, chemistry patterns) +4. **Don't add CLI reference** — that's `bd prime`'s job + +### What belongs in resources: + +| Content Type | Belongs in Resources? | Why | +|--------------|----------------------|-----| +| Conceptual frameworks | ✅ Yes | bd prime doesn't explain "when to use" | +| Decision trees | ✅ Yes | Cognitive guidance, not CLI reference | +| Advanced patterns | ✅ Yes | Depth beyond `--help` | +| CLI command syntax | ❌ No | Use `bd --help` | +| Workflow checklists | ❌ No | `bd prime` covers this | + +### Resource update checklist: + +``` +[ ] Check if bd prime now covers this content +[ ] If yes, remove from resources (avoid duplication) +[ ] If no, update resource for new bd version +[ ] Update version compatibility in README.md +``` + +## File Roles + +| File | Purpose | When to Update | +|------|---------|----------------| +| SKILL.md | Entry point, resource index | New features, version bumps | +| README.md | Human docs, installation | Structure changes | +| CLAUDE.md | This file, maintenance guide | Architecture changes | +| adr/*.md | Decision records | When making architectural decisions | +| resources/*.md | Deep-dive guides | New conceptual content | + +## Testing Changes + +After skill updates: + +```bash +# Verify SKILL.md is within token budget +wc -w skills/beads/SKILL.md # Target: 400-600 words + +# Verify links resolve +# (Manual check: ensure all resource links in SKILL.md exist) + +# Verify bd prime still works +bd prime | head -20 +``` + +## Attribution + +Resources adapted from other sources should include attribution header: + +```markdown +# Resource Title + +> Adapted from [source] +``` diff --git a/skills/beads/README.md b/skills/beads/README.md index 25a68484..1d51d91a 100644 --- a/skills/beads/README.md +++ b/skills/beads/README.md @@ -35,10 +35,13 @@ The skill activates when conversations involve: ``` beads/ ├── SKILL.md # Main skill file (Claude reads this first) +├── CLAUDE.md # Maintenance guide for updating the skill ├── README.md # This file (for humans) -└── references/ # Detailed documentation (loaded on demand) +├── adr/ # Architectural Decision Records +│ └── 0001-bd-prime-as-source-of-truth.md +└── resources/ # Detailed documentation (loaded on demand) ├── BOUNDARIES.md # When to use bd vs TodoWrite - ├── CLI_BOOTSTRAP_ADMIN.md # CLI command reference + ├── CLI_REFERENCE.md # CLI command reference ├── DEPENDENCIES.md # Dependency semantics (A blocks B vs B blocks A) ├── INTEGRATION_PATTERNS.md # TodoWrite and other tool integration ├── ISSUE_CREATION.md # When and how to create issues @@ -47,7 +50,11 @@ beads/ ├── RESUMABILITY.md # Writing notes for post-compaction recovery ├── STATIC_DATA.md # Using bd for reference databases ├── TROUBLESHOOTING.md # Common issues and fixes - └── WORKFLOWS.md # Step-by-step workflow guides + ├── WORKFLOWS.md # Step-by-step workflow guides + ├── AGENTS.md # Agent bead tracking (v0.40+) + ├── ASYNC_GATES.md # Human-in-the-loop gates + ├── CHEMISTRY_PATTERNS.md # Mol vs Wisp decision tree + └── WORKTREES.md # Parallel development patterns ``` ## Key Concepts @@ -90,9 +97,13 @@ NEXT: Implement rate limiting" ## Version Compatibility -- **v0.34.0+**: Full support including molecules, wisps, and cross-project dependencies -- **v0.15.0+**: Core functionality (dependencies, notes, status tracking) -- **Earlier versions**: Basic functionality but some features may be missing +| Version | Features | +|---------|----------| +| v0.43.0+ | Full support: agents, gates, worktrees, chemistry patterns | +| v0.40.0+ | Agent beads, async gates, worktree management | +| v0.34.0+ | Molecules, wisps, cross-project dependencies | +| v0.15.0+ | Core: dependencies, notes, status tracking | +| Earlier | Basic functionality, some features missing | ## Contributing diff --git a/skills/beads/SKILL.md b/skills/beads/SKILL.md index fe3a6947..8577d44f 100644 --- a/skills/beads/SKILL.md +++ b/skills/beads/SKILL.md @@ -1,13 +1,11 @@ --- name: beads description: > - Tracks complex, multi-session work using the Beads issue tracker and dependency graphs, and provides - persistent memory that survives conversation compaction. Use when work spans multiple sessions, has - complex dependencies, or needs persistent context across compaction cycles. Trigger with phrases like - "create task for", "what's ready to work on", "show task", "track this work", "what's blocking", or - "update status". + Git-backed issue tracker for multi-session work with dependencies and persistent + memory across conversation compaction. Use when work spans sessions, has blockers, + or needs context recovery after compaction. allowed-tools: "Read,Bash(bd:*)" -version: "0.34.0" +version: "0.43.0" author: "Steve Yegge " license: "MIT" --- @@ -16,808 +14,87 @@ license: "MIT" Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies. -## Overview +## bd vs TodoWrite -**bd (beads)** replaces markdown task lists with a dependency-aware graph stored in git. Unlike TodoWrite (session-scoped), bd persists across compactions and tracks complex dependencies. +| bd (persistent) | TodoWrite (ephemeral) | +|-----------------|----------------------| +| Multi-session work | Single-session tasks | +| Complex dependencies | Linear execution | +| Survives compaction | Conversation-scoped | +| Git-backed, team sync | Local to session | -**Key Distinction**: -- **bd**: Multi-session work, dependencies, survives compaction, git-backed -- **TodoWrite**: Single-session tasks, linear execution, conversation-scoped +**Decision test**: "Will I need this context in 2 weeks?" → YES = bd -**Core Capabilities**: -- 📊 **Dependency Graphs**: Track what blocks what (blocks, parent-child, discovered-from, related) -- 💾 **Compaction Survival**: Tasks persist when conversation history is compacted -- 🐙 **Git Integration**: Issues versioned in `.beads/issues.jsonl`, sync with `bd sync` -- 🔍 **Smart Discovery**: Auto-finds ready work (`bd ready`), blocked work (`bd blocked`) -- 📝 **Audit Trails**: Complete history of status changes, notes, and decisions -- 🏷️ **Rich Metadata**: Priority (P0-P4), types (bug/feature/task/epic), labels, assignees +**When to use bd**: +- Work spans multiple sessions or days +- Tasks have dependencies or blockers +- Need to survive conversation compaction +- Exploratory/research work with fuzzy boundaries +- Collaboration with team (git sync) -**When to Use bd vs TodoWrite**: -- ❓ "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 -- ❓ "Will this be done in this session?" → **YES** = TodoWrite -- ❓ "Is this just a task list for me right now?" → **YES** = TodoWrite - -**Decision Rule**: If resuming in 2 weeks would be hard without bd, use bd. +**When to use TodoWrite**: +- Single-session linear tasks +- Simple checklist for immediate work +- All context is in current conversation +- Will complete within current session ## Prerequisites -**Required**: -- **bd CLI**: Version 0.34.0 or later installed and in PATH -- **Git Repository**: Current directory must be a git repo -- **Initialization**: `bd init` must be run once (humans do this, not agents) - -**Verify Installation**: ```bash -bd --version # Should return 0.34.0 or later +bd --version # Requires v0.34.0+ ``` -**First-Time Setup** (humans run once): -```bash -cd /path/to/your/repo -bd init # Creates .beads/ directory with database -``` +- **bd CLI** installed and in PATH +- **Git repository** (bd requires git for sync) +- **Initialization**: `bd init` run once (humans do this, not agents) -**Optional**: -- **BEADS_DIR** environment variable for alternate database location -- **Daemon** for background sync: `bd daemon --start` +## CLI Reference -## Instructions +**Run `bd prime`** for AI-optimized workflow context (auto-loaded by hooks). +**Run `bd --help`** for specific command usage. -### Session Start Protocol +Essential commands: `bd ready`, `bd create`, `bd show`, `bd update`, `bd close`, `bd sync` -**Every session, start here:** +## Session Protocol -#### Step 1: Check for Ready Work +1. `bd ready` — Find unblocked work +2. `bd show ` — Get full context +3. `bd update --status in_progress` — Start work +4. Add notes as you work (critical for compaction survival) +5. `bd close --reason "..."` — Complete task +6. `bd sync` — Persist to git (always run at session end) -```bash -bd ready -``` +## Advanced Features -Shows tasks with no open blockers, sorted by priority (P0 → P4). - -**What this shows**: -- Task ID (e.g., `myproject-abc`) -- Title -- Priority level -- Issue type (bug, feature, task, epic) - -**Example output**: -``` -claude-code-plugins-abc [P1] [task] open - Implement user authentication - -claude-code-plugins-xyz [P0] [epic] in_progress - Refactor database layer -``` - -#### Step 2: Pick Highest Priority Task - -Choose the highest priority (P0 > P1 > P2 > P3 > P4) task that's ready. - -#### Step 3: Get Full Context - -```bash -bd show -``` - -Displays: -- Full task description -- Dependency graph (what blocks this, what this blocks) -- Audit trail (all status changes, notes) -- Metadata (created, updated, assignee, labels) - -#### Step 4: Start Working - -```bash -bd update --status in_progress -``` - -Marks task as actively being worked on. - -#### Step 5: Add Notes as You Work - -```bash -bd update --notes "Completed: X. In progress: Y. Blocked by: Z" -``` - -**Critical for compaction survival**: Write notes as if explaining to a future agent with zero conversation context. - -**Note Format** (best practice): -``` -COMPLETED: Specific deliverables (e.g., "implemented JWT refresh endpoint + rate limiting") -IN PROGRESS: Current state + next immediate step -BLOCKERS: What's preventing progress -KEY DECISIONS: Important context or user guidance -``` - ---- - -### Task Creation Workflow - -#### When to Create Tasks - -Create bd tasks when: -- User mentions tracking work across sessions -- User says "we should fix/build/add X" -- Work has dependencies or blockers -- Exploratory/research work with fuzzy boundaries - -#### Basic Task Creation - -```bash -bd create "Task title" -p 1 --type task -``` - -**Arguments**: -- **Title**: Brief description (required) -- **Priority**: 0-4 where 0=critical, 1=high, 2=medium, 3=low, 4=backlog (default: 2) -- **Type**: bug, feature, task, epic, chore (default: task) - -**Example**: -```bash -bd create "Fix authentication bug" -p 0 --type bug -``` - -#### Create with Description - -```bash -bd create "Implement OAuth" -p 1 --description "Add OAuth2 support for Google, GitHub, Microsoft. Use passport.js library." -``` - -#### Epic with Children - -```bash -# Create parent epic -bd create "Epic: OAuth Implementation" -p 0 --type epic -# Returns: myproject-abc - -# Create child tasks -bd create "Research OAuth providers" -p 1 --parent myproject-abc -bd create "Implement auth endpoints" -p 1 --parent myproject-abc -bd create "Add frontend login UI" -p 2 --parent myproject-abc -``` - ---- - -### Update & Progress Workflow - -#### Change Status - -```bash -bd update --status -``` - -**Status Values**: -- `open` - Not started -- `in_progress` - Actively working -- `blocked` - Stuck, waiting on something -- `closed` - Completed - -**Example**: -```bash -bd update myproject-abc --status blocked -``` - -#### Add Progress Notes - -```bash -bd update --notes "Progress update here" -``` - -**Appends** to existing notes field (doesn't replace). - -#### Change Priority - -```bash -bd update -p 0 # Escalate to critical -``` - -#### Add Labels - -```bash -bd label add backend -bd label add security -``` - -Labels provide cross-cutting categorization beyond status/type. - ---- - -### Dependency Management - -#### Add Dependencies - -```bash -bd dep add -``` - -**Meaning**: `` blocks `` (parent must be completed first). - -**Dependency Types**: -- **blocks**: Parent must close before child becomes ready -- **parent-child**: Hierarchical relationship (epics and subtasks) -- **discovered-from**: Task A led to discovering task B -- **related**: Tasks are related but not blocking - -**Example**: -```bash -# Deployment blocked by tests passing -bd dep add deploy-task test-task # test-task blocks deploy-task -``` - -#### View Dependencies - -```bash -bd dep list -``` - -Shows: -- What this task blocks (dependents) -- What blocks this task (blockers) - -#### Circular Dependency Prevention - -bd automatically prevents circular dependencies. If you try to create a cycle, the command fails. - ---- - -### Completion Workflow - -#### Close a Task - -```bash -bd close --reason "Completion summary" -``` - -**Best Practice**: Always include a reason describing what was accomplished. - -**Example**: -```bash -bd close myproject-abc --reason "Completed: OAuth endpoints implemented with Google, GitHub providers. Tests passing." -``` - -#### Check Newly Unblocked Work - -After closing a task, run: - -```bash -bd ready -``` - -Closing a task may unblock dependent tasks, making them newly ready. - -#### Close Epics When Children Complete - -```bash -bd epic close-eligible -``` - -Automatically closes epics where all child tasks are closed. - ---- - -### Git Sync Workflow - -#### All-in-One Sync - -```bash -bd sync -``` - -**Performs**: -1. Export database to `.beads/issues.jsonl` -2. Commit changes to git -3. Pull from remote (merge if needed) -4. Import updated JSONL back to database -5. Push local commits to remote - -**Use when**: End of session, before handing off to teammate, after major progress. - -#### Export Only - -```bash -bd export -o backup.jsonl -``` - -Creates JSONL backup without git operations. - -#### Import Only - -```bash -bd import -i backup.jsonl -``` - -Imports JSONL file into database. - -#### Background Daemon - -```bash -bd daemon --start # Auto-sync in background -bd daemon --status # Check daemon health -bd daemon --stop # Stop auto-sync -``` - -Daemon watches for database changes and auto-exports to JSONL. - ---- - -### Find & Search Commands - -#### Find Ready Work - -```bash -bd ready -``` - -Shows tasks with no open blockers. - -#### List All Tasks - -```bash -bd list --status open # Only open tasks -bd list --priority 0 # Only P0 (critical) -bd list --type bug # Only bugs -bd list --label backend # Only labeled "backend" -bd list --assignee alice # Only assigned to alice -``` - -#### Show Task Details - -```bash -bd show -``` - -Full details: description, dependencies, audit trail, metadata. - -#### Search by Text - -```bash -bd search "authentication" # Search titles and descriptions -bd search login --status open # Combine with filters -``` - -#### Find Blocked Work - -```bash -bd blocked -``` - -Shows all tasks that have open blockers preventing them from being worked on. - -#### Project Statistics - -```bash -bd stats -``` - -Shows: -- Total issues by status (open, in_progress, blocked, closed) -- Issues by priority (P0-P4) -- Issues by type (bug, feature, task, epic, chore) -- Completion rate - ---- - -### Complete Command Reference - -| Command | When to Use | Example | -|---------|-------------|---------| -| **FIND COMMANDS** | | | -| `bd ready` | Find unblocked tasks | User asks "what should I work on?" | -| `bd list` | View all tasks (with filters) | "Show me all open bugs" | -| `bd show ` | Get task details | "Show me task bd-42" | -| `bd search ` | Text search across tasks | "Find tasks about auth" | -| `bd blocked` | Find stuck work | "What's blocking us?" | -| `bd stats` | Project metrics | "How many tasks are open?" | -| **CREATE COMMANDS** | | | -| `bd create` | Track new work | "Create a task for this bug" | -| `bd template create` | Use issue template | "Create task from bug template" | -| `bd init` | Initialize beads | "Set up beads in this repo" (humans only) | -| **UPDATE COMMANDS** | | | -| `bd update ` | Change status/priority/notes | "Mark as in progress" | -| `bd dep add` | Link dependencies | "This blocks that" | -| `bd label add` | Tag with labels | "Label this as backend" | -| `bd comments add` | Add comment | "Add comment to task" | -| `bd reopen ` | Reopen closed task | "Reopen bd-42, found regression" | -| `bd rename-prefix` | Rename issue prefix | "Change prefix from bd- to proj-" | -| `bd epic status` | Check epic progress | "Show epic completion %" | -| **COMPLETE COMMANDS** | | | -| `bd close ` | Mark task done | "Close this task, it's done" | -| `bd epic close-eligible` | Auto-close complete epics | "Close epics where all children done" | -| **SYNC COMMANDS** | | | -| `bd sync` | Git sync (all-in-one) | "Sync tasks to git" | -| `bd export` | Export to JSONL | "Backup all tasks" | -| `bd import` | Import from JSONL | "Restore from backup" | -| `bd daemon` | Background sync manager | "Start auto-sync daemon" | -| **CLEANUP COMMANDS** | | | -| `bd delete ` | Delete issues | "Delete test task" (requires --force) | -| `bd admin compact` | Archive old closed tasks | "Compress database" | -| **REPORTING COMMANDS** | | | -| `bd stats` | Project metrics | "Show project health" | -| `bd audit record` | Log interactions | "Record this LLM call" | -| `bd workflow` | Show workflow guide | "How do I use beads?" | -| **ADVANCED COMMANDS** | | | -| `bd prime` | Refresh AI context | "Load bd workflow rules" | -| `bd daemons` | Multi-repo daemon mgmt | "Manage all beads daemons" | -| `bd version` | Version check | "Check bd version" | -| `bd restore ` | Restore compacted issue | "Get full history from git" | - ---- - -## Output - -This skill produces: - -**Task IDs**: Format `-` (e.g., `claude-code-plugins-abc`, `myproject-xyz`) - -**Status Summaries**: -``` -5 open, 2 in_progress, 1 blocked, 47 closed -``` - -**Dependency Graphs** (visual tree): -``` -myproject-abc: Deploy to production [P0] [blocked] - Blocked by: - ↳ myproject-def: Run integration tests [P1] [in_progress] - ↳ myproject-ghi: Fix failing tests [P1] [open] -``` - -**Audit Trails** (complete history): -``` -2025-12-22 10:00 - Created by alice (P2, task) -2025-12-22 10:15 - Priority changed: P2 → P0 -2025-12-22 10:30 - Status changed: open → in_progress -2025-12-22 11:00 - Notes added: "Implemented JWT auth..." -2025-12-22 14:00 - Status changed: in_progress → blocked -2025-12-22 14:01 - Notes added: "Blocked: API endpoint returns 503" -``` - ---- - -## Error Handling - -### Common Failures - -#### 1. `bd: command not found` -**Cause**: bd CLI not installed or not in PATH -**Solution**: Install from https://github.com/steveyegge/beads -```bash -# macOS/Linux -curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash - -# Or via npm -npm install -g @beads/bd - -# Or via Homebrew -brew install steveyegge/beads/bd -``` - -#### 2. `No .beads database found` -**Cause**: beads not initialized in this repository -**Solution**: Run `bd init` (humans do this once, not agents) -```bash -bd init # Creates .beads/ directory -``` - -#### 3. `Task not found: ` -**Cause**: Invalid task ID or task doesn't exist -**Solution**: Use `bd list` to see all tasks and verify ID format -```bash -bd list # See all tasks -bd search # Find task by title -``` - -#### 4. `Circular dependency detected` -**Cause**: Attempting to create a dependency cycle (A blocks B, B blocks A) -**Solution**: bd prevents circular dependencies automatically. Restructure dependency graph. -```bash -bd dep list # View current dependencies -``` - -#### 5. Git merge conflicts in `.beads/issues.jsonl` -**Cause**: Multiple users modified same issue -**Solution**: bd sync handles JSONL conflicts automatically. If manual intervention needed: -```bash -# View conflict -git status - -# bd provides conflict resolution tools -bd sync --merge # Attempt auto-resolution -``` - -#### 6. `Database is locked` -**Cause**: Daemon or another process has exclusive lock -**Solution**: Restart daemon or wait for lock to release -```bash -bd daemon --stop -bd daemon --start -``` - -#### 7. Sync failures -**Cause**: Network issues, authentication failures, or git configuration -**Solution**: Check git remote access and credentials -```bash -git fetch # Test connectivity -git status # Verify repo state -``` - ---- - -## Examples - -### Example 1: Multi-Session Feature (Epic with Children) - -**User Request**: "We need to implement OAuth, this will take multiple sessions" - -**Agent Response**: -```bash -# Create epic -bd create "Epic: OAuth Implementation" -p 0 --type epic -# Returns: claude-code-plugins-abc - -# Create child tasks -bd create "Research OAuth providers (Google, GitHub, Microsoft)" -p 1 --parent claude-code-plugins-abc -# Returns: claude-code-plugins-abc.1 - -bd create "Implement backend auth endpoints" -p 1 --parent claude-code-plugins-abc -# Returns: claude-code-plugins-abc.2 - -bd create "Add frontend login UI components" -p 2 --parent claude-code-plugins-abc -# Returns: claude-code-plugins-abc.3 - -# Add dependencies (backend must complete before frontend) -bd dep add claude-code-plugins-abc.3 claude-code-plugins-abc.2 - -# Start with research -bd update claude-code-plugins-abc.1 --status in_progress -``` - -**Result**: Work structured, ready to resume after compaction. - ---- - -### Example 2: Tracking Blocked Work - -**Scenario**: Agent discovers API is down during implementation - -**Agent Actions**: -```bash -# Mark current task as blocked -bd update claude-code-plugins-xyz --status blocked --notes "API endpoint /auth returns 503, reported to backend team" - -# Create blocker task -bd create "Fix /auth endpoint 503 error" -p 0 --type bug -# Returns: claude-code-plugins-blocker - -# Link dependency (blocker blocks original task) -bd dep add claude-code-plugins-xyz claude-code-plugins-blocker - -# Find other ready work -bd ready -# Shows tasks that aren't blocked - agent can switch to those -``` - -**Result**: Blocked work documented, agent productive on other tasks. - ---- - -### Example 3: Session Resume After Compaction - -**Session 1**: -```bash -bd create "Implement user authentication" -p 1 -bd update myproject-auth --status in_progress -bd update myproject-auth --notes "COMPLETED: JWT library integrated. IN PROGRESS: Testing token refresh. NEXT: Rate limiting" -# [Conversation compacted - history deleted] -``` - -**Session 2** (weeks later): -```bash -bd ready -# Shows: myproject-auth [P1] [task] in_progress - -bd show myproject-auth -# Full context preserved: -# - Title: Implement user authentication -# - Status: in_progress -# - Notes: "COMPLETED: JWT library integrated. IN PROGRESS: Testing token refresh. NEXT: Rate limiting" -# - No conversation history needed! - -# Agent continues exactly where it left off -bd update myproject-auth --notes "COMPLETED: Token refresh working. IN PROGRESS: Rate limiting implementation" -``` - -**Result**: Zero context loss despite compaction. - ---- - -### Example 4: Complex Dependencies (3-Level Graph) - -**Scenario**: Build feature with prerequisites - -```bash -# Create tasks -bd create "Deploy to production" -p 0 -# Returns: deploy-prod - -bd create "Run integration tests" -p 1 -# Returns: integration-tests - -bd create "Fix failing unit tests" -p 1 -# Returns: fix-tests - -# Create dependency chain -bd dep add deploy-prod integration-tests # Integration blocks deploy -bd dep add integration-tests fix-tests # Fixes block integration - -# Check what's ready -bd ready -# Shows: fix-tests (no blockers) -# Hides: integration-tests (blocked by fix-tests) -# Hides: deploy-prod (blocked by integration-tests) - -# Work on ready task -bd update fix-tests --status in_progress -# ... fix tests ... -bd close fix-tests --reason "All unit tests passing" - -# Check ready again -bd ready -# Shows: integration-tests (now unblocked!) -# Still hides: deploy-prod (still blocked) -``` - -**Result**: Dependency chain enforces correct order automatically. - ---- - -### Example 5: Team Collaboration (Git Sync) - -**Alice's Session**: -```bash -bd create "Refactor database layer" -p 1 -bd update db-refactor --status in_progress -bd update db-refactor --notes "Started: Migrating to Prisma ORM" - -# End of day - sync to git -bd sync -# Commits tasks to git, pushes to remote -``` - -**Bob's Session** (next day): -```bash -# Start of day - sync from git -bd sync -# Pulls latest tasks from remote - -bd ready -# Shows: db-refactor [P1] [in_progress] (assigned to alice) - -# Bob checks status -bd show db-refactor -# Sees Alice's notes: "Started: Migrating to Prisma ORM" - -# Bob works on different task (no conflicts) -bd create "Add API rate limiting" -p 2 -bd update rate-limit --status in_progress - -# End of day -bd sync -# Both Alice's and Bob's tasks synchronized -``` - -**Result**: Distributed team coordination through git. - ---- +| Feature | CLI | Resource | +|---------|-----|----------| +| Molecules (templates) | `bd mol --help` | [MOLECULES.md](resources/MOLECULES.md) | +| Chemistry (pour/wisp) | `bd pour`, `bd wisp` | [CHEMISTRY_PATTERNS.md](resources/CHEMISTRY_PATTERNS.md) | +| Agent beads | `bd agent --help` | [AGENTS.md](resources/AGENTS.md) | +| Async gates | `bd gate --help` | [ASYNC_GATES.md](resources/ASYNC_GATES.md) | +| Worktrees | `bd worktree --help` | [WORKTREES.md](resources/WORKTREES.md) | ## Resources -### When to Use bd vs TodoWrite (Decision Tree) +| Resource | Content | +|----------|---------| +| [BOUNDARIES.md](resources/BOUNDARIES.md) | bd vs TodoWrite detailed comparison | +| [CLI_REFERENCE.md](resources/CLI_REFERENCE.md) | Complete command syntax | +| [DEPENDENCIES.md](resources/DEPENDENCIES.md) | Dependency system deep dive | +| [INTEGRATION_PATTERNS.md](resources/INTEGRATION_PATTERNS.md) | TodoWrite and tool integration | +| [ISSUE_CREATION.md](resources/ISSUE_CREATION.md) | When and how to create issues | +| [MOLECULES.md](resources/MOLECULES.md) | Proto definitions, component labels | +| [PATTERNS.md](resources/PATTERNS.md) | Common usage patterns | +| [RESUMABILITY.md](resources/RESUMABILITY.md) | Compaction survival guide | +| [STATIC_DATA.md](resources/STATIC_DATA.md) | Database schema reference | +| [TROUBLESHOOTING.md](resources/TROUBLESHOOTING.md) | Error handling and fixes | +| [WORKFLOWS.md](resources/WORKFLOWS.md) | Step-by-step workflow patterns | +| [AGENTS.md](resources/AGENTS.md) | Agent bead tracking (v0.40+) | +| [ASYNC_GATES.md](resources/ASYNC_GATES.md) | Human-in-the-loop gates | +| [CHEMISTRY_PATTERNS.md](resources/CHEMISTRY_PATTERNS.md) | Mol vs Wisp decision tree | +| [WORKTREES.md](resources/WORKTREES.md) | Parallel development patterns | -**Use bd when**: -- ✅ Work spans multiple sessions or days -- ✅ Tasks have dependencies or blockers -- ✅ Need to survive conversation compaction -- ✅ Exploratory/research work with fuzzy boundaries -- ✅ Collaboration with team (git sync) +## Full Documentation -**Use TodoWrite when**: -- ✅ Single-session linear tasks -- ✅ Simple checklist for immediate work -- ✅ All context is in current conversation -- ✅ Will complete within current session - -**Decision Rule**: If resuming in 2 weeks would be hard without bd, use bd. - ---- - -### Essential Commands Quick Reference - -Top 10 most-used commands: - -| Command | Purpose | -|---------|---------| -| `bd ready` | Show tasks ready to work on | -| `bd create "Title" -p 1` | Create new task | -| `bd show ` | View task details | -| `bd update --status in_progress` | Start working | -| `bd update --notes "Progress"` | Add progress notes | -| `bd close --reason "Done"` | Complete task | -| `bd dep add ` | Add dependency | -| `bd list` | See all tasks | -| `bd search ` | Find tasks by keyword | -| `bd sync` | Sync with git remote | - ---- - -### Session Start Protocol (Every Session) - -1. **Run** `bd ready` first -2. **Pick** highest priority ready task -3. **Run** `bd show ` to get full context -4. **Update** status to `in_progress` -5. **Add notes** as you work (critical for compaction survival) - ---- - -### Database Selection - -bd uses `.beads/` directory by default. - -**Alternate Database**: -```bash -export BEADS_DIR=/path/to/alternate/beads -bd ready # Uses alternate database -``` - -**Multiple Databases**: Use `BEADS_DIR` to switch between projects. - ---- - -### Advanced Features - -For complex scenarios, see references: - -- **Compaction Strategies**: `{baseDir}/references/WORKFLOWS.md` - - Tier 1/2/ultra compaction for old closed issues - - Semantic summarization to reduce database size - -- **Epic Management**: `{baseDir}/references/WORKFLOWS.md` - - Nested epics (epics containing epics) - - Bulk operations on epic children - -- **Template System**: `{baseDir}/references/WORKFLOWS.md` - - Custom issue templates - - Template variables and defaults - -- **Git Integration**: `{baseDir}/references/GIT_INTEGRATION.md` - - Merge conflict resolution - - Daemon architecture - - Branching strategies - -- **Team Collaboration**: `{baseDir}/references/TEAM_COLLABORATION.md` - - Multi-user workflows - - Worktree support - - Prefix strategies - ---- - -### Full Documentation - -Complete reference: https://github.com/steveyegge/beads - -Existing detailed guides: -- `{baseDir}/references/CLI_REFERENCE.md` - Complete command syntax -- `{baseDir}/references/WORKFLOWS.md` - Detailed workflow patterns -- `{baseDir}/references/DEPENDENCIES.md` - Dependency system deep dive -- `{baseDir}/references/RESUMABILITY.md` - Compaction survival guide -- `{baseDir}/references/BOUNDARIES.md` - bd vs TodoWrite detailed comparison -- `{baseDir}/references/STATIC_DATA.md` - Database schema reference - ---- - -**Progressive Disclosure**: This skill provides essential instructions for all 30 beads commands. For advanced topics (compaction, templates, team workflows), see the references directory. Slash commands (`/bd-create`, `/bd-ready`, etc.) remain available as explicit fallback for power users. +- **bd prime**: AI-optimized workflow context +- **GitHub**: [github.com/steveyegge/beads](https://github.com/steveyegge/beads) diff --git a/skills/beads/adr/0001-bd-prime-as-source-of-truth.md b/skills/beads/adr/0001-bd-prime-as-source-of-truth.md new file mode 100644 index 00000000..8ea79968 --- /dev/null +++ b/skills/beads/adr/0001-bd-prime-as-source-of-truth.md @@ -0,0 +1,59 @@ +# ADR-0001: Use bd prime as CLI Reference Source of Truth + +## Status + +Accepted + +## Context + +The beads skill maintained CLI reference documentation in multiple locations: + +- `SKILL.md` inline (~2,000+ words of CLI reference) +- `references/CLI_REFERENCE.md` (~2,363 words) +- Scattered examples throughout resource files + +This created: +- **Duplication**: Same commands documented 2-3 times +- **Drift risk**: Documentation can fall behind bd versions +- **Token overhead**: ~3,000+ tokens loaded even for simple operations + +Meanwhile, bd provides `bd prime` which generates AI-optimized workflow context automatically. + +## Decision + +Use `bd prime` as the single source of truth for CLI commands: + +1. **SKILL.md** contains only value-add content (decision frameworks, cognitive patterns) +2. **CLI reference** points to `bd prime` (auto-loaded by hooks) and `bd --help` +3. **Resources** provide depth for advanced features (molecules, agents, gates) + +## Consequences + +### Positive + +- **Zero maintenance**: CLI docs auto-update with bd versions +- **DRY**: Single source of truth +- **Accurate**: No version drift possible +- **Lighter SKILL.md**: ~500 words vs ~3,300 + +### Negative + +- **Dependency on bd prime format**: If output changes significantly, may need adaptation +- **External tool requirement**: Skill assumes bd is installed + +## Implementation + +Files restructured: +- `SKILL.md` — Reduced from 3,306 to ~500 words +- `references/` → `resources/` — Directory rename for consistency +- New resources added: `agents.md`, `async-gates.md`, `chemistry-patterns.md`, `worktrees.md` +- Existing resources preserved with path updates + +## Related + +- Claude Code skill progressive disclosure guidelines +- Similar pattern implemented in other Claude Code skill ecosystems + +## Date + +2025-01-02 diff --git a/skills/beads/resources/AGENTS.md b/skills/beads/resources/AGENTS.md new file mode 100644 index 00000000..807af0b0 --- /dev/null +++ b/skills/beads/resources/AGENTS.md @@ -0,0 +1,62 @@ +# Agent Beads + +> Adapted from ACF beads skill + +**v0.40+**: First-class support for agent tracking via `type=agent` beads. + +## When to Use Agent Beads + +| Scenario | Agent Bead? | Why | +|----------|-------------|-----| +| Multi-agent orchestration | Yes | Track state, assign work via slots | +| Single Claude session | No | Overkill—just use regular beads | +| Long-running background agents | Yes | Heartbeats enable liveness detection | +| Role-based agent systems | Yes | Role beads define agent capabilities | + +## Bead Types + +| Type | Purpose | Has Slots? | +|------|---------|------------| +| `agent` | AI agent tracking | Yes (hook, role) | +| `role` | Role definitions for agents | No | + +Other types (`task`, `bug`, `feature`, `epic`) remain unchanged. + +## State Machine + +Agent beads track state for coordination: + +``` +idle → spawning → running/working → done → idle + ↓ + stuck → (needs intervention) +``` + +**Key states**: `idle`, `spawning`, `running`, `working`, `stuck`, `done`, `stopped`, `dead` + +The `dead` state is set by Witness (monitoring system) via heartbeat timeout—agents don't set this themselves. + +## Slot Architecture + +Slots are named references from agent beads to other beads: + +| Slot | Cardinality | Purpose | +|------|-------------|---------| +| `hook` | 0..1 | Current work attached to agent | +| `role` | 1 | Role definition bead (required) | + +**Why slots?** They enforce constraints (one work item at a time) and enable queries like "what is agent X working on?" or "which agent has this work?" + +## Monitoring Integration + +Agent beads enable: + +- **Witness System**: Monitors agent health via heartbeats +- **State Coordination**: ZFC-compliant state machine for multi-agent systems +- **Work Attribution**: Track which agent owns which work + +## CLI Reference + +Run `bd agent --help` for state/heartbeat/show commands. +Run `bd slot --help` for set/clear/show commands. +Run `bd create --help` for `--type=agent` and `--type=role` options. diff --git a/skills/beads/resources/ASYNC_GATES.md b/skills/beads/resources/ASYNC_GATES.md new file mode 100644 index 00000000..526ac6ca --- /dev/null +++ b/skills/beads/resources/ASYNC_GATES.md @@ -0,0 +1,168 @@ +# Async Gates for Workflow Coordination + +> Adapted from ACF beads skill + +`bd gate` provides async coordination primitives for cross-session and external-condition workflows. Gates are **wisps** (ephemeral issues) that block until a condition is met. + +--- + +## Gate Types + +| Type | Await Syntax | Use Case | +|------|--------------|----------| +| Human | `human:` | Cross-session human approval | +| CI | `gh:run:` | Wait for GitHub Actions completion | +| PR | `gh:pr:` | Wait for PR merge/close | +| Timer | `timer:` | Deployment propagation delay | +| Mail | `mail:` | Wait for matching email | + +--- + +## Creating Gates + +```bash +# Human approval gate +bd gate create --await human:deploy-approval \ + --title "Approve production deploy" \ + --timeout 4h + +# CI gate (GitHub Actions) +bd gate create --await gh:run:123456789 \ + --title "Wait for CI" \ + --timeout 30m + +# PR merge gate +bd gate create --await gh:pr:42 \ + --title "Wait for PR approval" \ + --timeout 24h + +# Timer gate (deployment propagation) +bd gate create --await timer:15m \ + --title "Wait for deployment propagation" +``` + +**Required options**: +- `--await ` — Gate condition (see types above) +- `--timeout ` — Recommended: prevents forever-open gates + +**Optional**: +- `--title ` — Human-readable description +- `--notify ` — Email/beads addresses to notify + +--- + +## Monitoring Gates + +```bash +bd gate list # All open gates +bd gate list --all # Include closed +bd gate show # Details for specific gate +bd gate eval # Auto-close elapsed/completed gates +bd gate eval --dry-run # Preview what would close +``` + +**Auto-close behavior** (`bd gate eval`): +- `timer:*` — Closes when duration elapsed +- `gh:run:*` — Checks GitHub API, closes on success/failure +- `gh:pr:*` — Checks GitHub API, closes on merge/close +- `human:*` — Requires explicit `bd gate approve` + +--- + +## Closing Gates + +```bash +# Human gates require explicit approval +bd gate approve +bd gate approve --comment "Reviewed and approved by Steve" + +# Manual close (any gate) +bd gate close +bd gate close --reason "No longer needed" + +# Auto-close via evaluation +bd gate eval +``` + +--- + +## Best Practices + +1. **Always set timeouts**: Prevents forever-open gates + ```bash + bd gate create --await human:... --timeout 24h + ``` + +2. **Clear titles**: Title should indicate what's being gated + ```bash + --title "Approve Phase 2: Core Implementation" + ``` + +3. **Eval periodically**: Run at session start to close elapsed gates + ```bash + bd gate eval + ``` + +4. **Clean up obsolete gates**: Close gates that are no longer needed + ```bash + bd gate close --reason "superseded by new approach" + ``` + +5. **Check before creating**: Avoid duplicate gates + ```bash + bd gate list | grep "spec-myfeature" + ``` + +--- + +## Gates vs Issues + +| Aspect | Gates (Wisp) | Issues | +|--------|--------------|--------| +| Persistence | Ephemeral (not synced) | Permanent (synced to git) | +| Purpose | Block on external condition | Track work items | +| Lifecycle | Auto-close when condition met | Manual close | +| Visibility | `bd gate list` | `bd list` | +| Use case | CI, approval, timers | Tasks, bugs, features | + +Gates are designed to be temporary coordination primitives—they exist only until their condition is satisfied. + +--- + +## Troubleshooting + +### Gate won't close + +```bash +# Check gate details +bd gate show + +# For gh:run gates, verify the run exists +gh run view + +# Force close if stuck +bd gate close --reason "manual override" +``` + +### Can't find gate ID + +```bash +# List all gates (including closed) +bd gate list --all + +# Search by title pattern +bd gate list | grep "Phase 2" +``` + +### CI run ID detection fails + +```bash +# Check GitHub CLI auth +gh auth status + +# List runs manually +gh run list --branch + +# Use specific workflow +gh run list --workflow ci.yml --branch +``` diff --git a/skills/beads/references/BOUNDARIES.md b/skills/beads/resources/BOUNDARIES.md similarity index 100% rename from skills/beads/references/BOUNDARIES.md rename to skills/beads/resources/BOUNDARIES.md diff --git a/skills/beads/resources/CHEMISTRY_PATTERNS.md b/skills/beads/resources/CHEMISTRY_PATTERNS.md new file mode 100644 index 00000000..95f89f7e --- /dev/null +++ b/skills/beads/resources/CHEMISTRY_PATTERNS.md @@ -0,0 +1,197 @@ +# Chemistry Patterns + +> Adapted from ACF beads skill + +Beads uses a chemistry metaphor for work templates. This guide covers when and how to use each phase. + +## Phase Transitions + +``` +┌─────────────────────────────────────────────────────────────┐ +│ PROTO (Solid) │ +│ Frozen template, reusable pattern │ +│ .beads/ with template label │ +└─────────────────────────┬───────────────────────────────────┘ + │ + ┌───────────────┼───────────────┐ + │ │ │ + ▼ │ ▼ +┌─────────────────┐ │ ┌─────────────────┐ +│ MOL (Liquid) │ │ │ WISP (Vapor) │ +│ bd pour │ │ │ bd wisp create │ +│ │ │ │ │ +│ Persistent │ │ │ Ephemeral │ +│ .beads/ │ │ │ .beads-wisp/ │ +│ Git synced │ │ │ Gitignored │ +└────────┬────────┘ │ └────────┬────────┘ + │ │ │ + │ │ ┌───────┴───────┐ + │ │ │ │ + ▼ │ ▼ ▼ + ┌──────────┐ │ ┌─────────┐ ┌─────────┐ + │ CLOSE │ │ │ SQUASH │ │ BURN │ + │ normally │ │ │ → digest│ │ → gone │ + └──────────┘ │ └─────────┘ └─────────┘ + │ + ▼ + ┌───────────────┐ + │ DISTILL │ + │ Extract proto │ + │ from ad-hoc │ + │ epic │ + └───────────────┘ +``` + +## Decision Tree: Mol vs Wisp + +``` +Will this work be referenced later? +│ +├─ YES → Does it need audit trail / git history? +│ │ +│ ├─ YES → MOL (bd pour) +│ │ Examples: Features, bugs, specs +│ │ +│ └─ NO → Could go either way +│ Consider: Will someone else see this? +│ │ +│ ├─ YES → MOL +│ └─ NO → WISP (then squash if valuable) +│ +└─ NO → WISP (bd wisp create) + Examples: Grooming, health checks, scratch work + End state: burn (no value) or squash (capture learnings) +``` + +## Quick Reference + +| Scenario | Use | Command | End State | +|----------|-----|---------|-----------| +| New feature work | Mol | `bd pour spec` | Close normally | +| Bug fix | Mol | `bd pour bug` | Close normally | +| Grooming session | Wisp | `bd wisp create grooming` | Squash → digest | +| Code review | Wisp | `bd wisp create review` | Squash findings | +| Research spike | Wisp | `bd wisp create spike` | Squash or burn | +| Session health check | Wisp | `bd wisp create health` | Burn | +| Agent coordination | Wisp | `bd wisp create coordinator` | Burn | + +## Common Patterns + +### Pattern 1: Grooming Wisp + +Use for periodic backlog maintenance. + +```bash +# Start grooming +bd wisp create grooming --var date="2025-01-02" + +# Work through checklist (stale, duplicates, verification) +# Track findings in wisp notes + +# End: capture summary +bd mol squash # Creates digest: "Closed 3, added 5 relationships" +``` + +**Why wisp?** Grooming is operational—you don't need permanent issues for "reviewed stale items." + +### Pattern 2: Code Review Wisp + +Use for PR review checklists. + +```bash +# Start review +bd wisp create pr-review --var pr="123" --var repo="myproject" + +# Track review findings (security, performance, style) +# Each finding is a child issue in the wisp + +# End: promote real issues, discard noise +bd mol squash # Creates permanent issues for real findings +``` + +**Why wisp?** Review checklists are ephemeral. Only actual findings become permanent issues. + +### Pattern 3: Research Spike Wisp + +Use for time-boxed exploration. + +```bash +# Start spike (2 hour timebox) +bd wisp create spike --var topic="GraphQL pagination" + +# Explore, take notes in wisp issues +# Track sources, findings, dead ends + +# End: decide outcome +bd mol squash # If valuable → creates research summary issue +# OR +bd mol burn # If dead end → no trace +``` + +**Why wisp?** Research might lead nowhere. Don't pollute the database with abandoned explorations. + +## Commands Reference + +### Creating Work + +```bash +# Persistent mol (solid → liquid) +bd pour # Synced to git +bd pour --var key=value + +# Ephemeral wisp (solid → vapor) +bd wisp create # Not synced +bd wisp create --var key=value +``` + +### Ending Work + +```bash +# Mol: close normally +bd close + +# Wisp: squash (condense to digest) +bd mol squash # Creates permanent digest issue + +# Wisp: burn (evaporate, no trace) +bd mol burn # Deletes with no record +``` + +### Managing + +```bash +# List wisps +bd wisp list + +# Garbage collect orphaned wisps +bd wisp gc + +# View proto/mol structure +bd mol show + +# List available protos +bd mol catalog +``` + +## Storage Locations + +| Type | Location | Git Behavior | +|------|----------|--------------| +| Proto | `.beads/` | Synced (template label) | +| Mol | `.beads/` | Synced | +| Wisp | `.beads-wisp/` | Gitignored | + +## Anti-Patterns + +| Don't | Do Instead | +|-------|------------| +| Create mol for one-time diagnostic | Use wisp, then burn | +| Create wisp for real feature work | Use mol (needs audit trail) | +| Burn wisp with valuable findings | Squash first (captures digest) | +| Let wisps accumulate | Burn or squash at session end | +| Create ad-hoc epics for repeatable patterns | Distill into proto | + +## Related Resources + +- [MOLECULES.md](MOLECULES.md) — Proto definitions +- [WORKFLOWS.md](WORKFLOWS.md) — General beads workflows diff --git a/skills/beads/references/CLI_REFERENCE.md b/skills/beads/resources/CLI_REFERENCE.md similarity index 100% rename from skills/beads/references/CLI_REFERENCE.md rename to skills/beads/resources/CLI_REFERENCE.md diff --git a/skills/beads/references/DEPENDENCIES.md b/skills/beads/resources/DEPENDENCIES.md similarity index 100% rename from skills/beads/references/DEPENDENCIES.md rename to skills/beads/resources/DEPENDENCIES.md diff --git a/skills/beads/references/INTEGRATION_PATTERNS.md b/skills/beads/resources/INTEGRATION_PATTERNS.md similarity index 100% rename from skills/beads/references/INTEGRATION_PATTERNS.md rename to skills/beads/resources/INTEGRATION_PATTERNS.md diff --git a/skills/beads/references/ISSUE_CREATION.md b/skills/beads/resources/ISSUE_CREATION.md similarity index 100% rename from skills/beads/references/ISSUE_CREATION.md rename to skills/beads/resources/ISSUE_CREATION.md diff --git a/skills/beads/references/MOLECULES.md b/skills/beads/resources/MOLECULES.md similarity index 100% rename from skills/beads/references/MOLECULES.md rename to skills/beads/resources/MOLECULES.md diff --git a/skills/beads/references/PATTERNS.md b/skills/beads/resources/PATTERNS.md similarity index 100% rename from skills/beads/references/PATTERNS.md rename to skills/beads/resources/PATTERNS.md diff --git a/skills/beads/references/RESUMABILITY.md b/skills/beads/resources/RESUMABILITY.md similarity index 100% rename from skills/beads/references/RESUMABILITY.md rename to skills/beads/resources/RESUMABILITY.md diff --git a/skills/beads/references/STATIC_DATA.md b/skills/beads/resources/STATIC_DATA.md similarity index 100% rename from skills/beads/references/STATIC_DATA.md rename to skills/beads/resources/STATIC_DATA.md diff --git a/skills/beads/references/TROUBLESHOOTING.md b/skills/beads/resources/TROUBLESHOOTING.md similarity index 100% rename from skills/beads/references/TROUBLESHOOTING.md rename to skills/beads/resources/TROUBLESHOOTING.md diff --git a/skills/beads/references/WORKFLOWS.md b/skills/beads/resources/WORKFLOWS.md similarity index 100% rename from skills/beads/references/WORKFLOWS.md rename to skills/beads/resources/WORKFLOWS.md diff --git a/skills/beads/resources/WORKTREES.md b/skills/beads/resources/WORKTREES.md new file mode 100644 index 00000000..d62edeca --- /dev/null +++ b/skills/beads/resources/WORKTREES.md @@ -0,0 +1,94 @@ +# Git Worktree Support + +> Adapted from ACF beads skill + +**v0.40+**: First-class worktree management via `bd worktree` command. + +## When to Use Worktrees + +| Scenario | Worktree? | Why | +|----------|-----------|-----| +| Parallel agent work | Yes | Each agent gets isolated working directory | +| Long-running feature | Yes | Avoids stash/switch dance for interruptions | +| Quick branch switch | No | `git switch` is simpler | +| PR review isolation | Yes | Review without disturbing main work | + +## Why `bd worktree` over `git worktree` + +**Always use `bd worktree`** instead of raw `git worktree` commands. + +```bash +bd worktree create .worktrees/{name} --branch feature/{name} +bd worktree remove .worktrees/{name} +``` + +**Why?** `bd worktree` auto-configures: +- Beads database redirect files +- Proper gitignore entries +- Daemon bypass for worktree operations + +## Architecture + +All worktrees share one `.beads/` database via redirect files: + +``` +main-repo/ +├── .beads/ ← Single source of truth +└── .worktrees/ + ├── feature-a/ + │ └── .beads ← Redirect file (not directory) + └── feature-b/ + └── .beads ← Redirect file +``` + +**Key insight**: Daemon auto-bypasses for wisp operations in worktrees. + +## Commands + +```bash +# Create worktree with beads support +bd worktree create .worktrees/my-feature --branch feature/my-feature + +# List worktrees +bd worktree list + +# Show worktree info +bd worktree info .worktrees/my-feature + +# Remove worktree cleanly +bd worktree remove .worktrees/my-feature +``` + +## Debugging + +When beads commands behave unexpectedly in a worktree: + +```bash +bd where # Shows actual .beads location (follows redirects) +bd doctor --deep # Validates graph integrity across all refs +``` + +## Protected Branch Workflows + +For repos with protected `main` branch: + +```bash +bd init --branch beads-metadata # Use separate branch for beads data +bd init --contributor # Auto-configure sync.remote=upstream for forks +``` + +This creates `.git/beads-worktrees/` for internal management. + +## Multi-Clone Support + +Multi-clone, multi-branch workflows: + +- Hash-based IDs (`bd-abc`) eliminate collision across clones +- Each clone syncs independently via git +- See [WORKTREES.md](https://github.com/steveyegge/beads/blob/main/docs/WORKTREES.md) for comprehensive guide + +## External References + +- **Official Docs**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs) +- **Sync Branch**: [PROTECTED_BRANCHES.md](https://github.com/steveyegge/beads/blob/main/docs/PROTECTED_BRANCHES.md) +- **Worktrees**: [WORKTREES.md](https://github.com/steveyegge/beads/blob/main/docs/WORKTREES.md)