beads
Beads (bd) Dolt-backed issue tracker for agent task memory. Covers CLI ops, molecules, Dolt sync, Linear/Jira/GitLab. Use when tracking tasks and dependencies with the Beads CLI, syncing issues via Dolt, or integrating with Linear/Jira/GitLab. Keywords: bd, beads, Dolt, issue tracker.
What this skill does
# Beads (bd) Distributed, Dolt-backed (Git-like) graph issue tracker for AI coding agents. Persistent memory with dependency-aware task tracking. ## Quick Start Install: `brew install beads` or use the install scripts/binaries from the [GitHub repo](https://github.com/gastownhall/beads). ```bash # Initialize in repo (humans run once) bd init # Tell your agent echo "Use 'bd' for task tracking" >> AGENTS.md ``` ## When to Use - AI agent needs persistent task memory across sessions - Tracking dependencies between tasks (`blocks:`, `depends_on:`) - Multi-agent/multi-branch workflows (hash-based IDs prevent conflicts) - Incremental delivery with molecules/gates - Sync issues with GitLab, Linear, Jira, GitHub ## Essential Commands | Command | Action | | ----------------------------- | ----------------------------------------- | | `bd ready` | List tasks with no open blockers | | `bd ready --explain` | Explain why tasks are or are not ready | | `bd ready --gated` | Tasks waiting at gate checkpoints | | `bd ready --exclude-type=X` | Exclude specific issue types | | `bd create "Title" -p 0` | Create P0 task | | `bd show <id>` | View task details and audit trail | | `bd update <id> --status=X` | Update status (open/in_progress/done) | | `bd close <id>` | Close task | | `bd close <id> --claim-next` | Close current task and claim next | | `bd dep add <child> <parent>` | Link tasks (blocks, related, parent) | | `bd list` | List issues (default: 50, non-closed) | | `bd list --format json` | JSON output (alias for `--json`) | | `bd show --current` | Show active issue (no ID needed) | | `bd update <id> --claim` | Atomically claim issue for work | | `bd note <id> "text"` | Append note (shorthand) | | `bd import -i <file>` | Import JSONL incrementally | | `bd sync` | Sync database state | | `bd dolt pull` | Pull latest DB changes (advanced) | | `bd dolt push` | Push DB changes (advanced) | | `bd bootstrap` | Repair/bootstrap workspace identity | | `bd context` | Show current workspace/task context | | `bd kv set <key> <value>` | Store key-value pair | | `bd kv get <key>` | Retrieve stored value | | `bd dolt show` | Show Dolt connection/remote settings | | `bd config set-many` | Apply multiple config changes in one step | | `bd ado sync` | Sync with Azure DevOps work items | | `bd ado status` | Check Azure DevOps sync status | | `bd ado projects` | List Azure DevOps projects | | `bd gitlab sync` | Sync with GitLab | | `bd github sync` | Sync with GitHub Issues | | `bd remember` | Write persistent agent memory | | `bd recall` | Read persistent agent memory | | `bd purge` | Delete closed ephemeral beads (wisps) | ## Hash-Based IDs Issues use hash-based IDs like `bd-a1b2` to prevent merge conflicts: ```bash bd create "Fix login bug" -p 1 # Created: bd-x7k3 bd show bd-x7k3 ``` ### Hierarchical IDs ``` bd-a3f8 (Epic) bd-a3f8.1 (Task) bd-a3f8.1.1 (Sub-task) ``` Use `bd children <id>` to view hierarchy. ## References | File | Purpose | | --------------------------------------- | ------------------------------------- | | [workflow.md](references/workflow.md) | Daily operations, status flow, sync | | [authoring.md](references/authoring.md) | Writing quality issues, EARS patterns | | [molecules.md](references/molecules.md) | Molecules, gates, formulas, compounds | | [sync.md](references/sync.md) | Dolt sync, upgrades, and integrations | ## Key Concepts ### Dolt as Database Beads stores issues in a Dolt database. Team synchronization happens via Dolt-style `pull`/`push`, not by committing JSONL files into your repo history. ### Dependency Graph ```bash bd dep add bd-child bd-parent --blocks # child blocks parent bd dep add bd-a bd-b --related # related items bd ready # only shows unblocked work ``` ### Molecules (Advanced) Molecules group related issues with gates for incremental delivery: ```bash bd mol create "Feature X" --steps=3 # Create 3-step molecule bd mol progress bd-xyz # Check progress bd mol burn bd-xyz # Complete molecule ``` ### Stealth Mode Use Beads locally without committing to repo: ```bash bd init --stealth ``` ### Contributor vs Maintainer ```bash # Contributor (forked repos) — separate planning repo bd init --contributor # Maintainer auto-detected via SSH/HTTPS credentials ``` ## Configuration Config stored in `.beads/config.yaml`: The exact schema evolves between releases. Prefer using CLI helpers to inspect and validate your current setup: - `bd dolt show` to see current Dolt connection/remote settings - `bd dolt test` to validate connectivity - `bd doctor` / `bd doctor --deep` for health checks ## Storage Backend (Dolt) Beads uses Dolt as its primary backend. Depending on your setup, Dolt can run: - Embedded (single-writer, no daemon) - Server mode (multi-writer) Use `bd doctor` (and `bd doctor --server` when applicable) to validate your environment. For legacy stores, use `bd migrate` workflows. ## Agent Integration ### Tell Agent About Beads Add to `AGENTS.md`: ```markdown ## Task Tracking Use `bd` for task tracking. Run `bd ready` to find work. ``` ### Agent-Optimized Output ```bash BD_AGENT_MODE=1 bd list --json # Ultra-compact JSON output bd list --json # Standard JSON output ``` ### MCP Plugin Beads includes Claude Code MCP plugin for direct integration. ## Release Highlights (1.0.3–1.0.4) - **Workflow/config ergonomics**: `bd -C` changes working directory before running, `bd close` gains `--reason-file`, and setup/bootstrap flows gain better remote/server config handling. - **Linear sync**: OAuth client-credentials, idempotency markers, stale-data signaling, per-workspace sync locks, richer type mappings, and batch create/update make larger sync loops safer and faster. - **Security/export defaults**: Beads now refuses to write secret keys into git-tracked config, and exports exclude memories and ephemeral wisps by default unless you opt back in. - **Dependencies/data paths**: JSONL bulk dependency add and several hook/bootstrap/init fixes reduce friction in automated and shared-server environments. ## Release Highlights (1.0.0–1.0.2) - **Distribution**: precompiled binaries now cover Linux, macOS (Intel/Apple Silicon), Windows (AMD64/ARM64), Android/Termux, and FreeBSD. - **Automation**: `bd init --non-interactive` / `--role` and `bd bootstrap --non-interactive` improve CI/cloud-agent setup. - **Workflow**: `bd ready --explain`, `bd config set-many`, batch dependency listing, and comma-separated status filters improve agent ergonomics. - **Authoring/modeling**: `spike`, `story`, and `milestone` are now first-class issue types; custom statuses/types moved to normalized tables. - **Integrations/sync**: GitLab sync adds better dedup + epic→milestone mapping, ADO sync respects more filters, and embedded/shared-server recovery got safer. ## Release Highlights (0.62.0–0.63.3) - **Azure DevOps integration**: `bd ado` CLI commands (sync, status, projects) for work item tracking. - **Embedded Dolt su
Related in AI Agents
skill-development
IncludedComprehensive meta-skill for creating, managing, validating, auditing, and distributing Claude Code skills and slash commands (unified in v2.1.3+). Provides skill templates, creation workflows, validation patterns, audit checklists, naming conventions, YAML frontmatter guidance, progressive disclosure examples, and best practices lookup. Use when creating new skills, validating existing skills, auditing skill quality, understanding skill architecture, needing skill templates, learning about YAML frontmatter requirements, progressive disclosure patterns, tool restrictions (allowed-tools), skill composition, skill naming conventions, troubleshooting skill activation issues, creating custom slash commands, configuring command frontmatter, using command arguments ($ARGUMENTS, $1, $2), bash execution in commands, file references in commands, command namespacing, plugin commands, MCP slash commands, Skill tool configuration, or deciding between skills vs slash commands. Delegates to docs-management skill for official documentation.
reprompter
IncludedTransform messy prompts into well-structured, effective prompts — single or multi-agent. Use when: "reprompt", "reprompt this", "clean up this prompt", "structure my prompt", rough text needing XML tags and best practices, "reprompter teams", "repromptception", "run with quality", "smart run", "smart agents", multi-agent tasks, audits, parallel work, anything going to agent teams. Don't use when: simple Q&A, pure chat, immediate execution-only tasks. See "Don't Use When" section for details. Outputs: Structured XML/Markdown prompt, quality score (before/after), optional team brief + per-agent sub-prompts, agent team output files. Success criteria: Single mode quality score ≥ 7/10; Repromptception per-agent prompt quality score 8+/10; all required sections present, actionable and specific.
adaptive-compaction
IncludedAdaptive add-on policy and recovery layer that decides WHEN to compact, prune, snapshot, or fork -- replacing fixed-percent auto-compaction across Claude Code, Codex, and MCP-capable hosts. Trigger on auto-compact timing or damage: "when should I compact", "is it safe to compact now or start a fresh session", "auto-compact fires too early/mid-task", "switching to an unrelated task but the window still has space", "context rot", "answers get worse the longer the session runs", "the agent forgot the plan or my decisions after it summarized", "add a layer on top that manages context without changing the agent", raising autoCompactWindow to give the policy room, or installing/tuning a cross-tool compaction policy or PreCompact hook -- even when "compaction" is never said but the problem is context-window pressure or post-summarization memory loss. Do NOT use to summarize a conversation, build RAG, write a summarization prompt (decides WHEN not HOW), or answer max-context-length trivia.
agent-skill-creator
IncludedCreate cross-platform agent skills from workflow descriptions. Activates when users ask to create an agent, automate a repetitive workflow, create a custom skill, or need advanced agent creation. Triggers on phrases like create agent for, automate workflow, create skill for, every day I have to, daily I need to, turn process into agent, need to automate, create a cross-platform skill, validate this skill, export this skill, migrate this skill. Supports single skills, multi-agent suites, transcript processing, template-based creation, interactive configuration, cross-platform export, and spec validation.
llm-wiki
IncludedUse when building or maintaining a persistent personal knowledge base (second brain) in Obsidian where an LLM incrementally ingests sources, updates entity/concept pages, maintains cross-references, and keeps a synthesis current. Triggers include "second brain", "Obsidian wiki", "personal knowledge management", "ingest this paper/article/book", "build a research wiki", "compound knowledge", "Memex", or whenever the user wants knowledge to accumulate across sessions instead of being re-derived by RAG on every query.
skill-master
IncludedAgent Skills authoring, evaluation, and optimization. Create, edit, validate, benchmark, and improve skills following the agentskills.io specification. Use when designing SKILL.md files, structuring skill folders (references, scripts, assets), ingesting external documentation into skills, running trigger evals, benchmarking skill quality, optimizing descriptions, or performing blind A/B comparisons. Keywords: agentskills.io, SKILL.md, skill authoring, eval, benchmark, trigger optimization.