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
This commit is contained in:
Peter Chanthamynavong
committed by
GitHub
GitHub
parent
f48ecce2b7
commit
025142d55e
86
skills/beads/CLAUDE.md
Normal file
86
skills/beads/CLAUDE.md
Normal file
@@ -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 <command> --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 <cmd> --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]
|
||||
```
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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 <https://github.com/steveyegge>"
|
||||
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 <command> --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 <id>` — Get full context
|
||||
3. `bd update <id> --status in_progress` — Start work
|
||||
4. Add notes as you work (critical for compaction survival)
|
||||
5. `bd close <id> --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 <task-id>
|
||||
```
|
||||
|
||||
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 <task-id> --status in_progress
|
||||
```
|
||||
|
||||
Marks task as actively being worked on.
|
||||
|
||||
#### Step 5: Add Notes as You Work
|
||||
|
||||
```bash
|
||||
bd update <task-id> --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 <task-id> --status <new-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 <task-id> --notes "Progress update here"
|
||||
```
|
||||
|
||||
**Appends** to existing notes field (doesn't replace).
|
||||
|
||||
#### Change Priority
|
||||
|
||||
```bash
|
||||
bd update <task-id> -p 0 # Escalate to critical
|
||||
```
|
||||
|
||||
#### Add Labels
|
||||
|
||||
```bash
|
||||
bd label add <task-id> backend
|
||||
bd label add <task-id> security
|
||||
```
|
||||
|
||||
Labels provide cross-cutting categorization beyond status/type.
|
||||
|
||||
---
|
||||
|
||||
### Dependency Management
|
||||
|
||||
#### Add Dependencies
|
||||
|
||||
```bash
|
||||
bd dep add <child-id> <parent-id>
|
||||
```
|
||||
|
||||
**Meaning**: `<parent-id>` blocks `<child-id>` (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 <task-id>
|
||||
```
|
||||
|
||||
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 <task-id> --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 <task-id>
|
||||
```
|
||||
|
||||
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 <id>` | Get task details | "Show me task bd-42" |
|
||||
| `bd search <query>` | 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 <id>` | 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 <id>` | 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 <id>` | 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 <id>` | 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 <id>` | Restore compacted issue | "Get full history from git" |
|
||||
|
||||
---
|
||||
|
||||
## Output
|
||||
|
||||
This skill produces:
|
||||
|
||||
**Task IDs**: Format `<prefix>-<hash>` (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: <id>`
|
||||
**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 <partial-title> # 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 <id> # 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 <id>` | View task details |
|
||||
| `bd update <id> --status in_progress` | Start working |
|
||||
| `bd update <id> --notes "Progress"` | Add progress notes |
|
||||
| `bd close <id> --reason "Done"` | Complete task |
|
||||
| `bd dep add <child> <parent>` | Add dependency |
|
||||
| `bd list` | See all tasks |
|
||||
| `bd search <query>` | 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 <id>` 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)
|
||||
|
||||
59
skills/beads/adr/0001-bd-prime-as-source-of-truth.md
Normal file
59
skills/beads/adr/0001-bd-prime-as-source-of-truth.md
Normal file
@@ -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
|
||||
62
skills/beads/resources/AGENTS.md
Normal file
62
skills/beads/resources/AGENTS.md
Normal file
@@ -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.
|
||||
168
skills/beads/resources/ASYNC_GATES.md
Normal file
168
skills/beads/resources/ASYNC_GATES.md
Normal file
@@ -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:<prompt>` | Cross-session human approval |
|
||||
| CI | `gh:run:<id>` | Wait for GitHub Actions completion |
|
||||
| PR | `gh:pr:<id>` | Wait for PR merge/close |
|
||||
| Timer | `timer:<duration>` | Deployment propagation delay |
|
||||
| Mail | `mail:<pattern>` | 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 <spec>` — Gate condition (see types above)
|
||||
- `--timeout <duration>` — Recommended: prevents forever-open gates
|
||||
|
||||
**Optional**:
|
||||
- `--title <text>` — Human-readable description
|
||||
- `--notify <recipients>` — Email/beads addresses to notify
|
||||
|
||||
---
|
||||
|
||||
## Monitoring Gates
|
||||
|
||||
```bash
|
||||
bd gate list # All open gates
|
||||
bd gate list --all # Include closed
|
||||
bd gate show <gate-id> # 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 <gate-id>
|
||||
bd gate approve <gate-id> --comment "Reviewed and approved by Steve"
|
||||
|
||||
# Manual close (any gate)
|
||||
bd gate close <gate-id>
|
||||
bd gate close <gate-id> --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 <id> --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 <gate-id>
|
||||
|
||||
# For gh:run gates, verify the run exists
|
||||
gh run view <run-id>
|
||||
|
||||
# Force close if stuck
|
||||
bd gate close <gate-id> --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 <branch>
|
||||
|
||||
# Use specific workflow
|
||||
gh run list --workflow ci.yml --branch <branch>
|
||||
```
|
||||
197
skills/beads/resources/CHEMISTRY_PATTERNS.md
Normal file
197
skills/beads/resources/CHEMISTRY_PATTERNS.md
Normal file
@@ -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 <wisp-id> # 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 <wisp-id> # 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 <wisp-id> # If valuable → creates research summary issue
|
||||
# OR
|
||||
bd mol burn <wisp-id> # 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 <proto> # Synced to git
|
||||
bd pour <proto> --var key=value
|
||||
|
||||
# Ephemeral wisp (solid → vapor)
|
||||
bd wisp create <proto> # Not synced
|
||||
bd wisp create <proto> --var key=value
|
||||
```
|
||||
|
||||
### Ending Work
|
||||
|
||||
```bash
|
||||
# Mol: close normally
|
||||
bd close <mol-id>
|
||||
|
||||
# Wisp: squash (condense to digest)
|
||||
bd mol squash <wisp-id> # Creates permanent digest issue
|
||||
|
||||
# Wisp: burn (evaporate, no trace)
|
||||
bd mol burn <wisp-id> # 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 <id>
|
||||
|
||||
# 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
|
||||
94
skills/beads/resources/WORKTREES.md
Normal file
94
skills/beads/resources/WORKTREES.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user