beads-integration_skill

Overview

This skill integrates with the Beads CLI (bd) to let Ralph query ready tasks, update statuses, add progress comments, and manage task metadata and dependencies. It enables autonomous execution loops using Beads' native memory and state, keeping task state consistent and traceable. Use it to programmatically drive work selection, execution, and reporting.

How this skill works

The skill runs bd CLI commands (prefer --json for machine parsing) to list ready tasks, mark tasks in_progress or closed, and read full task details. It updates priority, design, notes, labels, estimates, and dependency wiring using bd update/create/label/comments commands. For safe multiline content or complex descriptions it writes files and uses --body-file or -f when adding comments.

When to use it

• Select the next task for autonomous work: bd ready --parent <EPIC_ID> --limit 200 --json
• Begin work and mark a task in progress: bd update <task-id> --status in_progress
• Record progress or decisions: bd comments add <task-id> "..." or use -f for markdown files
• Close completed work: bd update <task-id> --status closed
• Create or enrich tasks with metadata: bd create / bd update with --description, --design, --notes, --acceptance
• Manage dependencies and hierarchical IDs when wiring parent/child relationships

Best practices

• Always use --json for programmatic parsing and guard against empty output
• Prefer direct mode (BD_NO_DAEMON=1) for setup flows to avoid daemon staleness when creating IDs or wiring deps
• Use --body-file or temp files for multiline descriptions or markdown comments
• Set status to open after creation (bd create does not accept --status); then move to in_progress when starting work
• Default priority to P2 unless blocking; use P0/P1 for blocking or high-impact tasks
• Populate description, design, notes, and acceptance fields to make tasks actionable and traceable

Example use cases

• Autonomous execution loop: bd ready -> bd update in_progress -> bd show -> implement -> bd comments add -> bd update closed
• Scope work to an epic to avoid missing ready items: bd ready --parent <EPIC_ID> --limit 200 --json
• Import a task with dependencies: bd create --title "..." --parent <parent-id> --deps <dep-id> --json then bd update <task-id> --status open
• Enrich tasks with architecture notes before implementation: bd update <task-id> --design "..." --notes "..." --acceptance "..."
• Add a progress comment with linked commits or files using a temporary markdown file and bd comments add -f /tmp/comment.md