Canonical bd prefix cutover (2026-04-02)

• Canonical Beads now creates new issues with the bd-* prefix.
• Legacy prefixes remain readable in the shared database via allowed_prefixes for historical continuity.
• Treat legacy prefixes as carry-forward context only. Do not start new canonical workflow from af-* or other legacy prefixes when a fresh bd-* issue is appropriate.
• Under the current local DX model, bd-* is the default workflow contract for new work in canonical repos.

Beads Workflow Guide

AI-supervised issue tracking with git-backed distributed database.

Command surface: Use bdx for coordination commands. Raw bd is local diagnostics/bootstrap/path-sensitive operations only.

Prefix note: Examples use the Beads prefix for this repo (e.g., bd-xyz). If you are working in another repository, substitute that repo's issue ID prefix everywhere {issue-id} is shown (branch names, Feature-Key trailers, dependency IDs). In agent-skills, do not rely on the Beads default issue prefix when creating new tracking work. If the active Beads context is af-* or another non-bd-* prefix, create or choose an explicit bd-* issue id before branch, commit, or PR work.

References:

• Beads MCP Plugin: https://github.com/steveyegge/beads/blob/main/docs/PLUGIN.md
• Beads README: https://github.com/steveyegge/beads/blob/main/README.md

Purpose

Beads provides persistent task memory across sessions, enabling:

• Feature-Key tracking across commits and PRs
• Discovering and filing new work during implementation
• Finding ready tasks with no blockers
• Managing dependencies between issues
• Durable memory retrieval across VMs and repos

Beads Memory Tiers (Canonical)

Use these tiers consistently:

1. bdx remember|memories|recall|forget for short global facts in Beads KV. These are prime-injected upstream and should use stable keys.
2. Closed Beads issues labeled memory for structured durable knowledge with metadata, provenance, staleness, and comments.
3. bdx comments add for task-local history only.

Do not use comments as fleet memory unless promoted to a memory record.

Structured Memory Metadata

Required metadata for memory issues:

• mem.scope: global|repo|tool|vendor|workflow
• mem.repo: repo name or global
• mem.source_issue: concrete Beads id or none
• mem.kind: decision|runbook|learning|gotcha|handoff|best_practice
• mem.maturity: draft|validated|core
• mem.confidence: low|medium|high

Optional metadata:

• mem.paths
• mem.stale_if_paths
• mem.source_commit
• mem.query_hint
• mem.symbols

Standalone/global memory records are valid when no single task is the source (mem.source_issue=none, mem.repo=global).

Canonical Contract

• Active Beads runtime is ~/.beads-runtime/.beads.
• Canonical coordination surface is bdx.
• ~/bd is legacy/rollback Git-backed state only.
• Canonical backend is Dolt server mode.
• Run Beads mutations from non-app directories; app repos should use worktrees for code and reference Beads IDs.
• Direct remote Dolt SQL endpoint settings are backend plumbing, not the normal agent coordination path.
• In agent-skills, active context must resolve to a repo-compatible bd-* issue id before commit or PR work. If bd-context surfaces af-* or another non-bd-* prefix here, stop early and create or choose the correct bd-* issue instead of carrying the mismatch forward.
• For mutating coordination commands, do not pass --repo/--repo=<name> to bdx writes. Use labels/metadata/cwd context to capture repo intent.
• No SQLite fallback for active fleet operation. If you see sqlite3: unable to open database file or unknown command "dolt", stop and repair runtime/binary first.
• Before dispatch waves, verify:

bdx dolt test --json
bdx preflight --json
bdx show <known-beads-id> --json

On macmini, do not use bdx ready --json as a tight-loop health probe. If you need to confirm CLI responsiveness, prefer:

bdx show <known-beads-id> --json

Broad readiness queries can be slow enough on macmini to look hung even when the Beads hub is healthy.

Before cross-VM, cross-repo, vendor/API, infra/auth/workflow, or repeated friction work, run targeted memory retrieval first:

bdx memories <keyword> --json
bdx search <keyword> --label memory --status all --json
bdx show <memory-id> --json
bdx comments <memory-id> --json

before acting, then use serena for symbol-aware edits when precision matters.

Fail-loud remediation (first response):

export PATH="$HOME/.local/bin:$PATH"
export BD_BIN="$HOME/.local/bin/bd"
export BEADS_DIR="$HOME/.beads-runtime/.beads"
hash -r
~/.agent/skills/health/bd-doctor/check.sh

When to Use This Skill

• Creating or tracking issues (bugs, features, tasks)
• Finding next work ("what should I work on?")
• Updating issue status during workflow
• Managing dependencies (blocks, related, discovered-from)
• Understanding Beads integration in workflow skills
• Creating epics with automatic branch setup
• Creating features with automatic branch setup

⚠️ CRITICAL: Always Set Dependencies

Problem: Without dependencies, targeted task selection and BV graph analysis can't identify blocked tasks or critical paths.

Rule: When creating ANY issue, ALWAYS ask yourself:

1. Does this block something? → Add bdx dep <blocker> --blocks <blocked>
2. Does this depend on something? → Add bdx dep add <blocked> <blocker>
3. Is this discovered from parent work? → Create it with --parent <parent-id> or use bdx dep relate
4. Is this an epic subtask? → Create it with --parent <epic-id>

Dependency Commands

# When creating with dependency
bdx create --title "Impl: OAuth" --type feature --deps "bd-research-task"

# Add dependency to existing issue
bdx dep bd-required-api --blocks bd-new-feature
# Equivalent:
bdx dep add bd-new-feature bd-required-api

# Discovery: I found a bug while working on a feature
bdx create --title "Bug: <short-description>" --type bug --parent bd-parent-feature

# Epic subtask
bdx create --title "Impl: OAuth" --type feature --parent bd-epic

Dependency Types

Type	Meaning	Affects Ready Queue?
blocks	Hard blocker	✅ Yes
related	Soft connection	❌ No
parent-child	Epic hierarchy	❌ No
discovered-from	Found during work	❌ No

Only blocks prevents a task from appearing in bdx ready.

Epic Creation Workflow (AUTOMATED)

When: User confirms this is epic-level work (weeks, multiple phases)

Steps:

1. Set Beads context
2. Create epic with FEATURE_KEY title (sanitized from description)
3. Create phase tasks (Research → Spec → Implementation → Testing)
4. Link tasks with dependency chain
5. Create git branch: feature-<FEATURE_KEY>
6. Checkout branch
7. Start first task (Research)
8. Confirm to user

Example execution:

# 1. Check context
bd-context

# 2. Create epic
# Use bdx create with JSON or flags
bdx create --title "AUTHENTICATION_SYSTEM" --type epic --priority 1 --description "OAuth + JWT..."

# Output: Created issue bd-xyz (AUTHENTICATION_SYSTEM)

# 3. Create phase tasks
bdx create --title "Research: OAuth" --type task --priority 1
# bd-xyz.1

bdx create --title "Spec: Auth flow" --type task --priority 1 --deps "bd-xyz.1" --parent bd-xyz
# bd-xyz.2

bdx create --title "Impl: OAuth" --type feature --priority 1 --deps "bd-xyz.2" --parent bd-xyz
# bd-xyz.3

# 4. Create and checkout branch
git checkout -b feature-AUTHENTICATION_SYSTEM

# 5. Start first task
bdx update bd-xyz.1 status=in_progress

# 6. Confirm
echo "✅ Created epic bd-xyz with phase tasks"

Branch naming: feature-<TITLE> where TITLE is sanitized (uppercase, underscores, no spaces)

Feature Creation Workflow (AUTOMATED)

When: User confirms this is feature-level work (days, single capability)

Steps:

1. Set Beads context
2. Create single feature issue
3. Create git branch: feature-<FEATURE_KEY>
4. Checkout branch
5. Start feature work
6. Confirm to user

Example execution:

# 1. Check context
bd-context

# 2. Create feature
bdx create --title "OAUTH_LOGIN_BUTTON" --type feature --priority 2 --description "Single OAuth login component..."
# Output: Created issue bd-abc

# 3. Create and checkout branch
git checkout -b feature-OAUTH_LOGIN_BUTTON

# 4. Start feature
bdx update bd-abc status=in_progress

# 5. Confirm
echo "✅ Created feature bd-abc"

Quick Reference

Find Work

Ready tasks (no blockers):

bdx ready

All issues:

bdx list --status open

Current context:

bd-context

Track Work

Show issue:

bdx show bd-abc123

Update status:

bdx update bd-abc123 status=in_progress notes="Working on X"

Complete:

bdx close bd-abc123 reason="Completed: X"

Create Work

New issue:

bdx create --title "Description" --type feature --priority 2

Link to PR:

bd-link-pr <pr-number>

Manage Dependencies

Add blocker:

bdx dep bd-required-api --blocks bd-new-feature

Track discovery:

bdx create --title "Bug: <short-description>" --type bug --parent bd-parent-feature

Integration with Workflow Skills

sync-feature-branch

Uses Beads:

• Checks issue exists for Feature-Key
• Updates status to "in_progress"
• Commits with Feature-Key trailer

When invoked: "commit my work", "save progress"

create-pull-request

Uses Beads:

• Ensures issue exists (creates if missing)
• Links PR to issue via bd-link-pr
• References issue in PR body

When invoked: "create PR", "merge into master"

DX Tooling (Centralized Database Pattern)

Automated Beads Operations:

• dx-check.sh - Primary operator entrypoint (dx-status + optional auto-fix via dx-hydrate)
• dx-status.sh - Read-only diagnostics
• dx-hydrate.sh - Bootstrap/repair path when setup is missing
• dx-doctor.sh - Optional advanced coordinator diagnostics (not required for normal Beads ops)

Manual Tools:

• bd-doctor - Diagnose/repair canonical Beads connectivity and lock issues
• beads-dolt-fleet - Fleet-wide convergence and service health operations

When invoked: Database recovery, fleet convergence, environment bootstrap

See also: ~/agent-skills/docs/BEADS_DX_QUICK_REFERENCE.md

Beads MCP Tools Reference

Core Operations

mcp__plugin_beads_beads__ready

• Find tasks with no blockers
• Returns: List of ready issues
• Use when: Starting session, looking for next work

mcp__plugin_beads_beads__list

• Query issues with filters
• Filters: status, priority, type, assignee
• Use when: Surveying project state

mcp__plugin_beads_beads__show

• Get full issue details
• Includes: dependencies, dependents, history
• Use when: Understanding issue context

mcp__plugin_beads_beads__create

• File new issues
• Types: bug, feature, task, epic, chore
• Use when: Discovering work during implementation

mcp__plugin_beads_beads__update

• Modify issue fields
• Fields: status, priority, design, notes, assignee
• Use when: Tracking progress, refining plans

mcp__plugin_beads_beads__close

• Complete issues
• Requires: reason (what was done)
• Use when: Work fully implemented and tested

bdx dep

• Manage blocker edges
• Use bdx dep <blocker> --blocks <blocked> or bdx dep add <blocked> <blocker>
• Use bdx dep relate <id-a> <id-b> only for soft links

mcp__plugin_beads_beads__blocked

• Find blocked issues
• Shows: what dependencies block each issue
• Use when: Understanding bottlenecks

mcp__plugin_beads_beads__stats

• Project statistics
• Metrics: total, open, in_progress, closed, ready
• Use when: Progress reporting

Helper Scripts

bd-context

• Shows current Beads context
• Output: Issue, branch, feature key, ready count
• Use when: Session start, status checks

bd-link-pr

• Links PR to Beads issue
• Auto-detects or creates issue
• Prevents duplicate linking
• Use when: PR created (called by create-pull-request skill)

Service Integration

Canonical runtime service:

• Linux canonical VMs: systemctl --user status beads-dolt.service
• macOS canonical host: launchctl print gui/$(id -u)/com.starsend.beads-dolt

Result: Beads availability is managed as a host service, not per-repo JSONL sync hooks.

Workflow Patterns

Starting Session

1. Check context:

   bd-context
   

2. Find ready work:

   mcp__plugin_beads_beads__ready()
   

3. Claim task:

   mcp__plugin_beads_beads__update(
     issue_id="<id>",
     status="in_progress"
   )
   

During Implementation

Discover bug/TODO:

mcp__plugin_beads_beads__create(
  title="Bug: X doesn't handle Y",
  issue_type="bug",
  priority=1
)

Use `bdx create --parent <current-feature-id>` for discovered child work, or
`bdx create --deps "discovered-from:<current-feature-id>"` when a typed origin
edge is specifically required.

Update progress:

mcp__plugin_beads_beads__update(
  issue_id="<current-id>",
  notes="Implemented X, testing Y"
)

Completing Work

1. Commit:

   • Use sync-feature-branch skill
   • Auto-updates Beads status

2. Create PR:

   • Use create-pull-request skill
   • Auto-links to Beads issue

3. Close issue (after merge):

   mcp__plugin_beads_beads__close(
     issue_id="<id>",
     reason="Completed: merged PR#123"
   )
   

Issue Types

feature - New functionality (priority 2 default) bug - Defects to fix (priority 1 default) task - General work (priority 2 default) epic - Large features with subtasks (priority 2 default) chore - Maintenance work (priority 3 default)

Priority Levels

0 - Critical (production down) 1 - High (blocking work, major bugs) 2 - Normal (features, improvements) 3 - Low (nice-to-have) 4 - Backlog (future consideration)

Dependency Types

blocks - Hard blocker (prevents work) related - Soft connection parent-child - Epic → subtask discovered-from - Found during parent work

Only "blocks" affects ready queue.

Epic Workflows (Large Features)

When to Use Epics

Use epics for features requiring multiple sub-tasks:

• Large system implementations
• Multi-phase rollouts
• Features with distinct milestones

Creating Epics with MCP

epic = mcp__plugin_beads_beads__create(
  title="Authentication System",
  issue_type="epic",
  priority=1,
  design="Overall architecture notes"
)

# Create sub-tasks
subtask1 = mcp__plugin_beads_beads__create(
  title="JWT token generation",
  issue_type="task",
  priority=1
)

Create subtasks with `--parent "$epic_id"` so hierarchy is represented by the
native parent field.

Epic Patterns

Progressive breakdown:

1. Create epic for large feature
2. Break into tasks as design clarifies
3. Link tasks with --parent
4. Track epic completion via dependencies

Priority Filtering

All ready tasks:

mcp__plugin_beads_beads__ready()

High-priority only:

mcp__plugin_beads_beads__ready(priority=1)

Ref: https://github.com/steveyegge/beads/blob/main/docs/QUICKSTART.md#hierarchical-issues-epics

Best Practices

1. File as you discover - Don't lose TODO comments, file as issues
2. Link discoveries - Use --parent or --deps "discovered-from:<id>" to track origin
3. Update status - Keep Beads current (workflow skills do this)
4. Use Feature-Keys - Match branch names to issue IDs
5. Close with context - Explain what was done in reason
6. Check ready queue - Start sessions with bd-ready

Anti-Patterns

❌ Creating issues without descriptions ❌ Leaving issues in "in_progress" after completion ❌ Not linking discovered work to parent ❌ Forgetting to update status during long features ❌ Closing without reason/context

Troubleshooting

Beads CLI not found:

• Check: which bd
• Ensure ~/bin or scripts/ in PATH

Beads service unavailable or stale:

• Run: beads-dolt dolt test --json
• Check: beads-dolt status --json
• Verify host service is active (beads-dolt.service on Linux or launchd agent on macOS)

Issue not found:

• List all: bdx list --status open
• Check ID format: bd-abc123 (not just abc123)
• Verify Beads backend is initialized and healthy: beads-dolt dolt test --json

Dolt lock contention (database ... is locked):

• Ensure only one Dolt server process is using ~/.beads-runtime/.beads/dolt on the host
• Restart managed service (systemctl --user restart beads-dolt.service on Linux)
• Re-check with beads-dolt dolt test --json

beads.role not configured warning or hung mutations:

• This is local host config drift, not a hub/service outage.

• If beads-dolt dolt test --json succeeds, the Beads hub is healthy.

• Deterministic fix:

• bd config set beads.role maintainer

• Retry the mutation after setting the role. Do not escalate to hub diagnostics if the Dolt connection test passes.

• Agents performing mutating coordination commands (bdx create/update/close/dep) should self-heal this before declaring Beads broken.

---

Last Updated: 2025-02-09 Related Skills: sync-feature-branch, create-pull-request Helper Scripts: bd-context, bd-link-pr References:

• Beads MCP: https://github.com/steveyegge/beads/blob/main/docs/PLUGIN.md
• Beads README: https://github.com/steveyegge/beads/blob/main/README.md

Dolt truth guardrail (required)

Before any Beads truth inspection on canonical hosts, run:

~/agent-skills/scripts/beads-truth-guard

If Dolt mode is detected, treat CLI results as source of truth and do not treat these files as live truth:

• ~/.beads-runtime/.beads/issues.jsonl
• ~/.beads-runtime/.beads/backup/issues.jsonl

Use:

• bdx show <id> --json
• bdx list --json
• beads-dolt status --json