mcpField
B
beads-workflow

beads-workflow

github.com/dralgorhythmAgent workflows12954 installsUpdated 14w ago
Repository

About beads-workflow

A workflow skill for using Beads, an issue tracker built for agent workflows, with issues stored in the repository and synchronized through git. It covers issue management, dependencies, progress tracking, and multi-agent handoffs.

Key features

  1. 01Create and manage issues
  2. 02Track issue status and priority
  3. 03Model issue dependencies
  4. 04Sync state through git
  5. 05Coordinate multi-agent handoffs

Use cases

  1. 01Finding unblocked work for an agent
  2. 02Tracking implementation tasks and blockers
  3. 03Handing work between agents
  4. 04Keeping issue state synchronized with git

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/dralgorhythm/claude-agentic-framework --skill beads-workflow

After installing, type/beads-workflowin Claude Code to confirm it loaded.

Details

From the project README

Beads Workflow

Beads is an AI-native issue tracker designed for agent workflows. Issues live in your repo, sync via git, and require no web UI.

Core Commands

CommandDescription
bd create "Title" -t feature -p 2Create issue (type, priority)
bd list --status openList open issues
bd show <id>View issue details
bd update <id> --status in_progressUpdate status or assignee
bd close <id> --reason "..."Close with reason
bd ready --sort hybridFind unblocked issues
bd dep add <blocking> <blocked> --type blocksAdd dependency
bd dep tree <id>View dependency tree
bd dep rm <blocking> <blocked>Remove dependency
bd syncSync with git remote
bd flushForce flush to JSONL

Workflow Patterns

Starting a Session
  1. Check ready work: bd ready --sort hybrid
  2. Claim an issue: bd update <id> --status in_progress
  3. Review dependencies: bd dep tree <id>
  4. Begin implementation
During Implementation
  1. Track sub-tasks: bd create "Sub-task" --parent <id>
  2. Add blockers: bd dep add <new-blocker> <id> --type blocks
  3. Update progress: bd comment <id> "Progress update"
Completing Work
  1. Verify completion: All acceptance criteria met
  2. Close issue: bd close <id> --reason "Implemented X, PR #123"
  3. Sync: bd sync
  4. Check next: bd ready
Multi-Agent Coordination
# See who's working on what
bd list --status in_progress --json | jq '.[] | {id, title, assignee}'

# Hand off work
bd update <id> --assignee other-agent
bd comment <id> "Handoff: context and next steps"

Issue Types

TypeWhen to Use
featureNew functionality
bugDefect fixes
taskGeneral work items
spikeResearch/investigation
choreMaintenance, cleanup

Priority Levels

PriorityMeaning
0Critical - Drop everything
1High - Next up
2Medium - Normal flow
3Low - When time permits
4Backlog - Future consideration

Status Flow

open -> in_progress -> done
         |-> blocked -> in_progress

Best Practices

  1. One issue per logical unit: Don't combine unrelated work
  2. Clear titles: Should explain what, not how
  3. Use dependencies: Makes ready work visible
  4. Sync frequently: Keep other agents informed
  5. Close promptly: Don't leave stale in_progress issues

Integration with Swarm

  1. Claim before editing: Update status before touching code
  2. Document blockers: Create issues for discovered blockers
  3. Handoff cleanly: Update assignee and add context
  4. Sync before ending: bd sync to share state

Troubleshooting

# Check daemon health
bd daemons health

# View daemon logs
bd daemons logs

# Force reimport from JSONL
bd import --force

# Check for conflicts
bd sync --dry-run

Comments

Markdown supported