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:

1. Write content to temporary file
2. Use

   --body-file

   flag instead of

   --description

   or

   --notes

3. 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

1. Select Next Task:

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

2. Mark In Progress:

   bd update <task-id> --status in_progress

3. Read Details:

   bd show <task-id> --json

   (Check

   description

   ,

   design

   ,

   notes

   ,

   acceptance_criteria

   )
4. Implement: Write code, run tests.
5. Log Progress:

   bd comments add <task-id> "..."

6. 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:

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

Rich Metadata

Always populate these fields when enriching tasks:

1. 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."
2. 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."
3. 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."
4. 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):

1. Extract from plan document: Use plan's "Objective", "Acceptance Criteria", architecture notes, and context
2. Populate description: Convert objective to clear description
3. Add design notes: Extract architecture considerations, technical constraints, patterns
4. Add general notes: Include context, file references, related work, quality gates
5. 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.