bostonaholic/beads
.agents/skills/beads/SKILL.md
Dolt-powered 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. Trigger with "create task", "what's ready", "track this work", "resume after compaction". Make sure to use this skill whenever managing multi-session work, tracking dependencies, or recovering context.
testing
Updated Apr 16, 2026
$ install --global
skillsauthnpx skillsauth add bostonaholic/team beadsInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 24, 2026, 8:54 PM1.8s1 file scanned
SKILL.md
- name:
- beads
- description:
- >
- allowed-tools:
- Read,Bash(bd:*)
- version:
- 0.60.0
- author:
- Steve Yegge <[email protected]>
- license:
- MIT
- compatible-with:
- claude-code
- tags:
- [issue-tracking, task-management, multi-session, dependencies]
Beads - Persistent Task Memory for AI Agents
Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.
bd vs TodoWrite
Decision test: "Will I need this context in 2 weeks?" YES = bd, NO = TodoWrite.
| bd (persistent) | TodoWrite (ephemeral) | |-----------------|----------------------| | Multi-session, dependencies, compaction survival | Single-session linear tasks | | Dolt-backed team sync | Conversation-scoped |
See BOUNDARIES.md for detailed comparison.
Prerequisites
bd --version # Requires v0.60.0+
- bd CLI installed and in PATH
- Git repository (optional — use
BEADS_DIR+--stealthfor git-free operation) - Initialization:
bd initrun once (humans do this, not agents)
CLI Reference
Run bd prime for AI-optimized workflow context (auto-loaded by hooks).
Run bd <command> --help for specific command usage.
Essential commands: bd ready, bd create, bd show, bd update, bd close, bd dolt push
Session Protocol
bd ready— Find unblocked workbd show <id>— Get full contextbd update <id> --claim— Claim and start work atomically- Add notes as you work (critical for compaction survival)
bd close <id> --reason "..."— Complete taskbd dolt push— Push to Dolt remote (if configured)
Output
Append --json to any command for structured output. Use bd show <id> --long for extended metadata. Status icons: ○ open ◐ in_progress ● blocked ✓ closed ❄ deferred.
Error Handling
| Error | Fix |
|-------|-----|
| database not found | bd init <prefix> in project root |
| not in a git repository | git init first |
| disk I/O error (522) | Move .beads/ off cloud-synced filesystem |
| Status updates lag | Use server mode: bd dolt start |
See TROUBLESHOOTING.md for full details.
Examples
Track a multi-session feature:
bd create "OAuth integration" -t epic -p 1 --json
bd create "Token storage" -t task --deps blocks:oauth-id --json
bd ready --json # Shows unblocked work
bd update <id> --claim --json # Claim and start
bd close <id> --reason "Implemented with refresh tokens" --json
Recover after compaction: bd list --status in_progress --json then bd show <id> --long
Discover work mid-task: bd create "Found bug" -t bug -p 1 --deps discovered-from:<current-id> --json
Advanced Features
| Feature | CLI | Resource |
|---------|-----|----------|
| Molecules (templates) | bd mol --help | MOLECULES.md |
| Chemistry (pour/wisp) | bd pour, bd wisp | CHEMISTRY_PATTERNS.md |
| Agent beads | bd agent --help | AGENTS.md |
| Async gates | bd gate --help | ASYNC_GATES.md |
| Worktrees | bd worktree --help | WORKTREES.md |
Resources
| Category | Files | |----------|-------| | Getting Started | BOUNDARIES.md, CLI_REFERENCE.md, WORKFLOWS.md | | Core Concepts | DEPENDENCIES.md, ISSUE_CREATION.md, PATTERNS.md | | Resilience | RESUMABILITY.md, TROUBLESHOOTING.md | | Advanced | MOLECULES.md, CHEMISTRY_PATTERNS.md, AGENTS.md, ASYNC_GATES.md, WORKTREES.md | | Reference | STATIC_DATA.md, INTEGRATION_PATTERNS.md |
Validation
If bd --version reports newer than 0.60.0, this skill may be stale. Run bd prime for current CLI guidance — it auto-updates with each bd release and is the canonical source of truth (ADR-0001).
Related Skills
bostonaholic/progress-tracking
data-ai
VerifiedTrustedCommunity
Todo-first progress convention for multi-step procedures — loaded by every multi-step agent to track its own steps without drift
3SKILL.mdUpdated Jun 2, 2026
bostonaholic/eng-design-doc-review
testing
VerifiedTrustedCommunity
Adversarially review a technical design document with fresh context before the human gate. Dispatches the built-in `general-purpose` subagent (clean context, no shared history with the design-author) against `docs/plans/<id>/design.md` and presents its verdict — APPROVE, REQUEST CHANGES, or COMMENT. Optional, not part of the QRSPI pipeline. Trigger on "review the design doc", "audit design.md", "is this design ready", or `/eng-design-doc-review`.
3SKILL.mdUpdated May 23, 2026
bostonaholic/code-review
development
VerifiedTrustedCommunity
Generator-evaluator separation and review methodology — loaded by review agents to enforce fresh-context review discipline, Conventional Comments format, and gate verdicts
3SKILL.mdUpdated May 2, 2026
bostonaholic/team-worktree
data-ai
VerifiedTrustedCommunity
Prepare one or more isolated git worktrees — one per repository the topic touches. Router action — no agent. Trigger on "set up the worktree", "isolate this work", or "/team-worktree".
3SKILL.mdUpdated Apr 23, 2026