Beads Task Tracker

Git-backed issue tracker for AI agents. Use when managing tasks, dependencies, or multi-step work. Triggers on task tracking, issue management, dependency graphs, ready work queues, or mentions of "beads" / "bd" CLI.

Security Scan

The skill is internally consistent with a git-backed issue tracker, but missing provenance and it will install/execute a third‑party binary that modifies git repositories and can push/pull using your git credentials — review before installing.

Purpose & Capability

Name/description match the declared requirements: the skill needs a 'bd' CLI and the SKILL.md contains only bd commands for creating, updating, and syncing a git-backed task store (.beads/). The brew and npm install specs both produce the expected 'bd' binary, so requested capabilities align with purpose.

Instruction Scope

Instructions are limited to running the bd CLI and interacting with the repo (.beads/, git hooks, sync). They do not request unrelated environment variables or arbitrary file reads, but they do direct the agent to run git operations (commit/pull/push) and to install git hooks that will modify the repo. bd's auto-sync behavior can cause network I/O (push/pull) using whatever git credentials are configured.

Install Mechanism

Install methods are brew (formula) and npm (@beads/bd). Both are common package distribution mechanisms (lower risk than arbitrary URL downloads) but still carry normal supply-chain risk: the skill has no source URL or homepage in metadata, so there's no immediate way to inspect the package origin from the registry metadata provided here.

Credentials

The skill declares no required env vars or secrets, and the instructions do not attempt to read unrelated environment variables. However, the CLI's git operations will implicitly use the system's git credentials (SSH keys, credential helpers, or tokens), which is expected but worth noting since bd sync/push/pull could expose repository state to remotes.

Persistence & Privilege

always:false (good). The skill will create .beads/, may install git hooks (writes into .git/hooks), and the CLI mentions an auto-sync daemon with 30s debounce — these introduce persistent artifacts in repositories and potential recurring network activity. It does not request system-wide privileges or modify other skills' configurations according to the provided metadata.

What to consider before installing

This skill appears to do what it says (a git-backed task tracker) but you should be cautious before installing. Key things to consider: - Provenance: there is no homepage/source URL or maintainer info in the metadata. Before installing, find and inspect the brew formula and the npm package (@beads/bd) to verify their source and contents. - Inspect code: review the npm tarball or the formula's upstream URL to see what bd does, especially any code that auto-syncs, runs daemons, or executes arbitrary commands. - Test in a sandbox: install and run bd in an isolated or disposable git repository (not a sensitive project) to see what files (.beads/, hooks) it creates and what network calls it makes. - Git credentials: bd sync will use whatever git auth is configured (SSH keys, tokens). Avoid installing/using bd in repositories where pushing/pulling could leak sensitive data or trigger CI/jobs you don't intend. - Git hooks: bd hooks install will write to .git/hooks and may run on commits; inspect these hooks before enabling them in important repos. - Installation scope: prefer local or per-project install rather than global, and avoid running it on systems with elevated access until you trust the package. If you want to proceed, first locate the package sources (npm/brew formula), audit the scripts and hooks, and run bd in a throwaway repo to observe behavior. If you cannot find or inspect the upstream source, treat the package as higher risk.

Beads

Distributed, git-backed graph issue tracker for AI agents. Replaces markdown plans with a dependency-aware task graph stored as JSONL in .beads/.

Quick Start

# Initialize (non-interactive for agents)
bd init --quiet

# Check ready work
bd ready --json

# Create a task
bd create "Complete task X" -p 1 --json

# View task
bd show bd-a1b2 --json

Core Workflow

1. bd ready --json — Find unblocked work
2. bd update <id> --status in_progress — Claim task
3. Do the work
4. bd close <id> --reason "Done" — Complete task
5. bd sync — Force sync before ending session

Agent-Critical Rules

• Always use --json for machine-readable output
• Never use bd edit — opens $EDITOR, unusable by agents
• Use bd update instead: bd update <id> --title "New title" --description "New desc"
• Run bd sync at end of session to flush changes to git

Commands

Initialize

bd init --quiet              # Non-interactive, auto-installs hooks
bd init --prefix myproj      # Custom ID prefix
bd init --stealth            # Local only, don't commit .beads/
bd init --contributor        # Fork workflow (separate planning repo)

Create Issues

bd create "Title" -p 1 --json                    # Priority 1 (0=critical, 3=low)
bd create "Title" -t epic -p 0 --json            # Create epic
bd create "Subtask" -p 1 --json                  # Under epic: bd-a3f8.1, .2, .3
bd create "Found issue" --deps discovered-from:bd-a1b2 --json

Types: task, bug, feature, epic Priorities: 0 (P0/critical) to 3 (P3/low)

Query Issues

bd ready --json                    # Unblocked tasks (the work queue)
bd ready --priority 0 --json       # Only P0s
bd ready --assignee agent-1 --json # Assigned to specific agent

bd list --json                     # All issues
bd list --status open --json       # Open issues
bd list --priority 1 --json        # P1 issues

bd show bd-a1b2 --json             # Issue details + audit trail
bd blocked --json                  # Issues waiting on dependencies
bd stats --json                    # Statistics

Update Issues

bd update bd-a1b2 --status in_progress --json
bd update bd-a1b2 --title "New title" --json
bd update bd-a1b2 --description "Details" --json
bd update bd-a1b2 --priority 0 --json
bd update bd-a1b2 --assignee agent-1 --json
bd update bd-a1b2 --design "Design notes" --json
bd update bd-a1b2 --notes "Additional notes" --json

Status values: open, in_progress, blocked, closed

Close Issues

bd close bd-a1b2 --reason "Completed" --json
bd close bd-a1b2 bd-b2c3 --reason "Batch close" --json

Dependencies

bd dep add bd-child bd-parent      # child blocked by parent
bd dep add bd-a1b2 bd-b2c3 --type related    # Related link
bd dep add bd-a1b2 bd-epic --type parent     # Parent-child

bd dep tree bd-a1b2                # Visualize dependency tree
bd dep remove bd-child bd-parent   # Remove dependency
bd dep cycles                      # Detect circular deps

Dependency types: blocks (default), related, parent, discovered-from

Git Sync

bd sync                    # Export → commit → pull → import → push
bd hooks install           # Install git hooks for auto-sync

The daemon auto-syncs with 30s debounce. Use bd sync to force immediate sync.

Maintenance

bd admin compact --dry-run --json   # Preview compaction
bd admin compact --days 90          # Compact issues closed >90 days
bd doctor                           # Check database health

Hierarchical IDs (Epics)

bd create "Project Alpha" -t epic -p 1 --json   # Returns: bd-a3f8
bd create "Phase 1" -p 1 --json                 # Returns: bd-a3f8.1
bd create "Research" -p 1 --json                # Returns: bd-a3f8.2
bd create "Review" -p 1 --json                  # Returns: bd-a3f8.3

Up to 3 levels: bd-a3f8 → bd-a3f8.1 → bd-a3f8.1.1

Multi-Agent Coordination

# Agent claims work
bd update bd-a1b2 --status in_progress --assignee agent-1 --json

# Query assigned work
bd ready --assignee agent-1 --json

# Track discovered work
bd create "Found issue" --deps discovered-from:bd-a1b2 --json

Commit Convention (Optional)

For git-tracked projects, include issue ID in commit messages for traceability:

git commit -m "Complete research phase (bd-a1b2)"

Session End Checklist

Before ending a session:

bd sync                    # Flush all changes
bd ready --json            # Show next work for handoff