# Beads Task Tracking

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-trebormc-drupal-ai-agents-beads-task-tracking`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [trebormc](https://agentstack.voostack.com/s/trebormc)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [trebormc](https://github.com/trebormc)
- **Source:** https://github.com/trebormc/drupal-ai-agents/tree/main/.claude/skills/beads-task-tracking

## Install

```sh
agentstack add skill-trebormc-drupal-ai-agents-beads-task-tracking
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## 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)

```bash
# 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.

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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):**
```bash
# 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+):**
```bash
# 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](https://github.com/trebormc)
- **Source:** [trebormc/drupal-ai-agents](https://github.com/trebormc/drupal-ai-agents)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-trebormc-drupal-ai-agents-beads-task-tracking
- Seller: https://agentstack.voostack.com/s/trebormc
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.