beads-workflow
AI-native issue tracking with Beads. Use when managing work items, tracking issues, or coordinating tasks in multi-agent workflows. Covers bd commands, dependencies, and sync patterns.
How do I install this agent skill?
npx skills add https://github.com/dralgorhythm/claude-agentic-framework --skill beads-workflowIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a comprehensive workflow for using Beads (bd), an AI-native issue tracking tool. It details commands for issue lifecycle management, dependency tracking, and synchronization with GitHub. No malicious code, data exfiltration, or suspicious dependencies were identified.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
- Runlayerpass
1 file scanned · No issues
What does this agent skill do?
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
| Command | Description |
|---|---|
bd create "Title" -t feature -p 2 | Create issue (type, priority) |
bd list --status open | List open issues |
bd show <id> | View issue details |
bd update <id> --status in_progress | Update status or assignee |
bd close <id> --reason "..." | Close with reason |
bd ready --sort hybrid | Find unblocked issues |
bd dep add <blocking> <blocked> --type blocks | Add dependency |
bd dep tree <id> | View dependency tree |
bd dep rm <blocking> <blocked> | Remove dependency |
bd sync | Sync with git remote |
bd flush | Force flush to JSONL |
Workflow Patterns
Starting a Session
- Check ready work:
bd ready --sort hybrid - Claim an issue:
bd update <id> --status in_progress - Review dependencies:
bd dep tree <id> - Begin implementation
During Implementation
- Track sub-tasks:
bd create "Sub-task" --parent <id> - Add blockers:
bd dep add <new-blocker> <id> --type blocks - Update progress:
bd comment <id> "Progress update"
Completing Work
- Verify completion: All acceptance criteria met
- Close issue:
bd close <id> --reason "Implemented X, PR #123" - Sync:
bd sync - 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
| Type | When to Use |
|---|---|
feature | New functionality |
bug | Defect fixes |
task | General work items |
spike | Research/investigation |
chore | Maintenance, cleanup |
Priority Levels
| Priority | Meaning |
|---|---|
| 0 | Critical - Drop everything |
| 1 | High - Next up |
| 2 | Medium - Normal flow |
| 3 | Low - When time permits |
| 4 | Backlog - Future consideration |
Status Flow
open -> in_progress -> done
|-> blocked -> in_progress
Best Practices
- One issue per logical unit: Don't combine unrelated work
- Clear titles: Should explain what, not how
- Use dependencies: Makes ready work visible
- Sync frequently: Keep other agents informed
- Close promptly: Don't leave stale in_progress issues
Integration with Swarm
- Claim before editing: Update status before touching code
- Document blockers: Create issues for discovered blockers
- Handoff cleanly: Update assignee and add context
- Sync before ending:
bd syncto 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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/dralgorhythm/claude-agentic-framework/beads-workflow">View beads-workflow on skillZs</a>