Beads Task Tracking

Environment

Beads runs in its own DDEV container (ddev-{project}-beads). A wrapper script at /usr/local/bin/bd is installed in your container, so all bd commands work directly -- they are transparently delegated to the Beads container via SSH.

The .beads/ directory lives in the project root (/var/www/html/.beads/) and is shared across all containers through the project volume.

Session Start (ALWAYS DO THIS FIRST)

# 1. Initialize Beads if not already done
ls -la .beads/ 2>/dev/null || bd init --quiet

# 2. Get context from previous sessions (prints a project/task summary — if it
#    prints without error, Beads is working)
bd prime

# 3. See what tasks are ready
bd ready --json

If bd fails

| Symptom | Cause | Fix | |---------|-------|-----| | bd: command not found or SSH errors | Beads container down | Ask the user to run ddev restart on the host | | Unknown subcommand / flag error | Wrong syntax | Check available commands with bd --help | | Command hangs | You ran bd edit | Never use bd edit — use bd update --flags |

Creating Tasks

bd create is NOT idempotent — running it twice creates two tasks. Before creating, check the task does not already exist (bd ready --json or bd list --json). If a previous create attempt failed ambiguously (e.g., SSH error), verify with bd ready --json before retrying.

# Create a task with priority (P0-P3)
bd create "Implement user authentication" -p 1 --json

# Create a subtask under a parent
bd create "Add validation for edge case" -p 2 --parent  --json

# Create multiple tasks for a feature
bd create "Create service class" -p 1 --json
bd create "Add form handler" -p 1 --json
bd create "Write unit tests" -p 2 --json

Priority Levels

| Level | Meaning | When to use | |-------|---------|-------------| | P0 | Critical | Blockers, security issues, broken builds | | P1 | High | Core features, main deliverables | | P2 | Medium | Normal tasks, enhancements | | P3 | Low | Nice-to-haves, polish, cleanup |

Working on Tasks

# Mark a task as in progress
bd update  --status in_progress

# Add progress notes as you work
bd update  --notes "Implemented service, working on form validation"

# Close when done
bd close  --reason "Implemented and all tests passing" --json

Querying Tasks

# List all ready tasks
bd ready --json

# Show details of a specific task
bd show  --json

Session End ("Land the Plane") - MANDATORY

Before finishing any work session, ALWAYS complete these steps:

# 1. File follow-up tasks for remaining work
bd create "TODO: Add integration tests" -p 2 --json

# 2. Close all completed tasks
bd close  --reason "Done: implemented service and unit tests" --json

# 3. Document paused state for in-progress tasks
bd update  --notes "Paused at: form validation logic, needs edge case handling"

Quick Reference

| Action | Command | |--------|---------| | Initialize | bd init --quiet | | Get context | bd prime | | List ready | bd ready --json | | Create task | bd create "Title" -p 1 --json | | Create subtask | bd create "Title" -p 2 --parent --json | | Show task | bd show --json | | Mark active | bd update --status in_progress | | Add notes | bd update --notes "..." | | Close task | bd close --reason "Done" --json |

Integration with Ralph Loop

When running inside Ralph Loop ([RALPH LOOP - Iteration X]):

Planning Phase (Iteration 1):

# Read requirements and create tasks
bd create "Task from requirements" -p 1 --json
bd create "Another task" -p 2 --json
# Signal completion
echo "PLANNING_COMPLETE"

Execution Phase (Iterations 2+):

# Get next task
bd ready --json
# Work on it
bd update  --status in_progress
# ... do the work ...
bd close  --reason "Completed" --json
# Create new subtasks if discovered
bd create "New discovered task" -p 2 --json

The loop exits automatically when bd ready returns an empty array [].

Rules

1. NEVER use bd edit -- it opens an interactive editor that will hang
2. NEVER run git commit or git push -- leave all git operations to the user
3. Always use --json flag on create, close, and show for parseable output
4. Always close tasks with a reason -- this documents what was accomplished
5. Reference task IDs in commit messages -- suggest format: "Add feature X (bd-a1b2)"

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: trebormc
• Source: trebormc/drupal-ai-agents
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.