Beads Integration

Use Beads CLI (bd) commands for task management, status tracking, and progress comments.

Prerequisites

Beads CLI (bd) installed and available in PATH
Beads database initialized (.beads/beads.db)
Recommended for setup workflows: Prefer direct mode to avoid daemon staleness during ID creation and dependency wiring:
```
export BD_NO_DAEMON=1
```

Core Commands

Query Ready Tasks

Get next available task:

bd ready --json

Scope ready work to an epic (recommended for Ralph):

bd ready --parent <EPIC_ID> --limit 200 --json

Get ready tasks for specific project:

bd ready --project <project-name> --json

bd ready --json returns an array of tasks that are in open status and have all dependencies met.
bd ready defaults to --limit 10, so increase the limit for epics to avoid hiding ready tasks.
Use --parent <EPIC_ID> when you need only tasks for a specific epic; this avoids missing tasks due to global sorting/limits.
Use jq -r '.[0]?.id // empty' for first task.
Guard against empty output.

Update Task Status

Mark task in progress:

bd update <task-id> --status in_progress

Mark task closed (completed):

bd update <task-id> --status closed

Reset task to open (if failed or abandoned):

bd update <task-id> --status open

Block a task:

bd update <task-id> --status blocked

Note: ready is NOT a valid settable status. Use open.

Manage Task Details

Set Priority:

bd update <task-id> --priority P0  # Critical
bd update <task-id> --priority P1  # High
bd update <task-id> --priority P2  # Medium (Default)
bd update <task-id> --priority P3  # Low

Add Design & Architecture Notes:

bd update <task-id> --design "Use Factory Pattern for widget creation. See design doc at docs/widgets.md"

Add General Notes:

bd update <task-id> --notes "Requires update to API schema first."

Set Estimate (Minutes):

bd update <task-id> --estimate 60  # 1 hour

Manage Labels:

bd update <task-id> --add-label "frontend" --add-label "ui"
bd update <task-id> --remove-label "bug"

Alternative label commands (equivalent in most workflows):

bd label list <task-id>
bd label add <task-id> "frontend"
bd label remove <task-id> "bug"

Add Progress Comments

List latest comments (required before starting work):

bd comments <task-id> --json

Add comment to task:

bd comments add <task-id> "<comment-text>"

Safe multiline/markdown (recommended when using backticks or code blocks):

cat <<'EOF' > /tmp/bd-comment.md
## Progress Update

- \`bd ready --parent <EPIC_ID>\`
- Added tests and updated docs
EOF

bd comments add <task-id> -f /tmp/bd-comment.md
rm /tmp/bd-comment.md

Comment Format:

Use markdown formatting.
Include timestamps and reasoning.
Link to files changed or external references.

Example:

bd comments add bd-a3f8.1 "## Progress Update

- ✅ Completed function implementation
- ✅ Added unit tests
- 📝 Updated documentation"

Import Tasks from JSON Payload

Create Task:

bd create --title "<title>" --description "<desc>" --priority P2 --labels "engineering" --json
# Note: bd create does NOT support --status flag. Set status after creation:
# bd update <task-id> --status open

Import with Dependencies:

bd create --title "<child>" --parent <parent-id> --deps <dep-id> --json
# Note: bd create does NOT support --status flag. Set status after creation:
# bd update <task-id> --status open
# Also note: Use --deps (not --depends-on) for dependencies

Hierarchical Task IDs

Beads supports hierarchical task IDs (e.g., project-abc.1, project-abc.1.1):

Parent relationship is automatically inferred from the ID structure
Do NOT use --parent flag when creating tasks with hierarchical IDs
Example: bd create --id project-abc.1 --title "Task" automatically sets parent to project-abc

Common mistake:

# ❌ WRONG - will error: "cannot specify both --id and --parent flags"
bd create --id project-abc.1 --parent project-abc --title "Task"

# ✅ CORRECT
bd create --id project-abc.1 --title "Task"

Handling Multiline Content

For descriptions or notes with newlines:

Write content to temporary file
Use --body-file flag instead of --description or --notes
Clean up temp file after creation

Example:

echo "Line 1\nLine 2" > /tmp/desc.txt
bd create --title "Task" --body-file /tmp/desc.txt
rm /tmp/desc.txt

Why use --body-file?

Inline --description with newlines can cause parsing errors
--body-file handles multiline content reliably
Always use --body-file for descriptions containing newlines

Using --force Flag

The --force flag is required when:

Creating tasks with explicit IDs that match the database prefix
Overriding prefix validation warnings

When to use:

# When creating task with explicit ID matching database prefix
bd create --id project-abc.1 --title "Task" --force

# When prefix validation requires override
bd create --id project-abc.1 --title "Task" --force --json

When NOT to use:

Don't use --force to bypass dependency checks
Don't use --force if you're unsure about prefix compatibility
Always verify prefix matches database before using --force

Prefix Detection:

# First, try to get prefix from database configuration (most reliable)
DB_PREFIX=$(bd config get issue_prefix 2>/dev/null | tr -d '\n' | grep -v "Error\|not found" || echo "")

# Fallback: try to get prefix from existing tasks
if [ -z "$DB_PREFIX" ] || [ "$DB_PREFIX" = "" ]; then
  DB_PREFIX=$(bd list --json 2>/dev/null | jq -r '.[0].id' | cut -d'-' -f1-2)
fi

# Final fallback: use directory name (matches bd init default behavior)
if [ -z "$DB_PREFIX" ] || [ "$DB_PREFIX" = "null" ] || [ "$DB_PREFIX" = "" ]; then
  DB_PREFIX=$(basename "$(pwd)")
  # Last resort: default to "bd" only if directory name is invalid
  if [ -z "$DB_PREFIX" ] || [ "$DB_PREFIX" = "." ] || [ "$DB_PREFIX" = ".." ]; then
    DB_PREFIX="bd"
  fi
fi

Important: bd init stores the prefix in database configuration (issue_prefix). Always query the configured prefix first using bd config get issue_prefix to avoid mismatches between what bd init set and what we detect from tasks.

Workflow Patterns

Autonomous Execution Loop

Select Next Task: bd ready --parent <EPIC_ID> --limit 200 --json
Mark In Progress: bd update <task-id> --status in_progress
Read Details: bd show <task-id> --json (Check description, design, notes, acceptance_criteria)
Implement: Write code, run tests.
Log Progress: bd comments add <task-id> "..."
Mark Complete: bd update <task-id> --status closed

Dependency Management

Check Dependencies:

bd show <task-id> --json

Check depends_on array. Tasks with incomplete dependencies will not appear in bd ready.

Error Handling

Invalid Status: Do not use ready as a status. Use open.
Task Not Found: Check ID.
Locked DB: If DB is locked, wait and retry.

Best Practices

Task Creation & Naming

Core Principle: Atomicity

Create focused, single-purpose tasks with clear, actionable titles
Each task should be small enough for fast agent processing
Break large tasks into smaller, atomic beads

Title Guidelines: ✅ Good Task Titles:

"Add user authentication endpoint"
"Fix memory leak in WebSocket handler"
"Create database migration for user schema"
"Update TypeScript interface for HealthResponse"
"Remove CPU metrics from healthcheck UI"

❌ Poor Task Titles:

"Fix stuff"
"Update code"
"Make it better"
"Handle edge cases"
"Do the thing"

Title Format Rules:

Start with action verb (imperative mood): "Add", "Fix", "Create", "Update", "Refactor", "Document"
Be specific: Include what and where (e.g., "Add pagination to user list endpoint")
Keep concise: Aim for 50-70 characters
Use consistent terminology: Align with codebase vocabulary

Rich Metadata

Always populate these fields when enriching tasks:

Description (--description):
- Clear objective explaining what the task accomplishes
- Link to planning documents when available (include specific path)
- Example: "Update /api/health to return only relevant metrics for Vercel serverless architecture. See plan document: .devagent/workspace/tasks/active/2026-01-10_healthcheck-improvements/plan/2026-01-10_healthcheck-plan.md for full context."
Design (--design):
- Architecture and design decisions
- Technical considerations and constraints
- Patterns to follow or avoid
- Example: "Vercel serverless functions are stateless and ephemeral. Focus on metrics that persist: database connectivity, environment info, deployment status. Avoid collecting metrics that don't persist across invocations."
Notes (--notes):
- Context, constraints, or prerequisites
- References to related work or documentation (always include specific paths)
- Implementation hints or warnings
- Example: "Interface changes affect api.health.ts, health.tsx, and app.health.tsx. Plan document: .devagent/workspace/tasks/active/2026-01-10_healthcheck-improvements/plan/2026-01-10_healthcheck-plan.md. See plan document for interface requirements."
Acceptance Criteria (--acceptance):

Measurable, verifiable outcomes
Specific conditions for task completion
Format: Semicolon-separated list of criteria
Example: "CPU metrics removed from interface; Memory metrics removed from interface; Interface only contains relevant serverless metrics"

Priority Guidelines

P0 (Critical): Blocking work or high-impact items that unblock other tasks
P1 (High): Important features or fixes with significant impact
P2 (Medium): Default priority for most tasks
P3 (Low): Nice-to-have improvements, non-critical work

Default to P2 unless the task is clearly blocking or high-impact.

Task Enrichment Workflow

When enriching existing tasks (e.g., from plan-to-beads conversion):

Extract from plan document: Use plan's "Objective", "Acceptance Criteria", architecture notes, and context
Populate description: Convert objective to clear description
Add design notes: Extract architecture considerations, technical constraints, patterns
Add general notes: Include context, file references, related work, quality gates
Set acceptance criteria: Convert acceptance criteria list to semicolon-separated format

Example enrichment:

bd update task-id \
  --description "Update API endpoint to return simplified health metrics for serverless architecture. See plan document: `.devagent/workspace/tasks/active/2026-01-10_healthcheck-improvements/plan/2026-01-10_healthcheck-plan.md` for full context." \
  --design "Vercel serverless functions are stateless. Focus on: database connectivity, environment info, deployment status. Avoid CPU/memory/uptime metrics." \
  --notes "Endpoint: /api/health. Plan document: `.devagent/workspace/tasks/active/2026-01-10_healthcheck-improvements/plan/2026-01-10_healthcheck-plan.md`. Maintain backward compatibility for 'status' field." \
  --acceptance "CPU metrics removed; Memory metrics removed; Database connectivity included; Deployment info included when available"

Traceability

Comment on tasks: Add progress comments with every commit or significant step
Link to commits: Reference commit SHAs in comments for traceability
Document decisions: Use design field to capture architectural decisions during implementation
Update notes: Add implementation discoveries or constraints to notes field

JSON Output

Always use --json flag for programmatic interaction with Beads CLI to ensure consistent parsing.