bead-workflow

name	bead-workflow
description	Manage beads correctly including claiming, closing, announcements, and dependencies. Use when starting work on a task, when finishing a task, when the user mentions beads or tasks, or when coordinating with other agents on task ownership. Use when this capability is needed.
metadata	{"author":"eaasxt"}

Bead Workflow

Proper bead lifecycle: claim → work → close.

---

When This Applies

Signal	Action
Starting work on a task	Run claim protocol
Finishing a task	Run close protocol
User says "claim" or "start"	Run claim protocol
User says "done" or "close"	Run close protocol
Multiple agents active	Extra care on announcements

---

Claim Protocol

1. CHECK
   Inbox, reservations, blockers
        ↓
2. CLAIM
   Parent + ALL sub-beads + assignee
        ↓
3. RESERVE
   Files you'll touch
        ↓
4. ANNOUNCE
   [CLAIMED] message to all agents

Step 1: Check

# What's ready?
bd ready --json

# What's recommended?
bv --robot-next

# Who's active? (multi-agent)
# ReadMcpResourceTool: resource://agents/{project}

# What's reserved?
# Check file_reservation_status

Step 2: Claim

CRITICAL: Claim parent AND all sub-beads together.

bd update {id} --status in_progress --assignee {YOUR_NAME}
bd update {id}.1 --status in_progress --assignee {YOUR_NAME}
bd update {id}.2 --status in_progress --assignee {YOUR_NAME}
# ... all sub-beads

Why: If you only claim parent, other agents see sub-beads as "ready" → conflict.

Step 3: Reserve Files

file_reservation_paths(
    project_key=PROJECT_PATH,
    agent_name=YOUR_NAME,
    paths=["src/module/**", "tests/test_module.py"],
    ttl_seconds=3600,
    exclusive=True,
    reason="{bead-id}: {description}"
)

Step 4: Announce

send_message(
    project_key=PROJECT_PATH,
    sender_name=YOUR_NAME,
    to=[ALL_AGENTS],
    subject="[CLAIMED] {id} - {title}",
    body_md="Starting work on **{id}**.\n\nSub-beads: .1, .2, .3\nFiles: `src/module/**`",
    importance="normal",
    thread_id="{id}"
)

---

Close Protocol

1. VERIFY
   Tests pass, ubs clean
        ↓
2. COMMIT
   Include .beads/issues.jsonl
        ↓
3. CLOSE
   Sub-beads FIRST, then parent
        ↓
4. RELEASE
   File reservations
        ↓
5. ANNOUNCE
   [CLOSED] message

Step 1: Verify (MANDATORY GATES)

# Run tests
pytest  # or your test command

# Security gate (MANDATORY - do not skip)
ubs --staged

Gate requirements:

• All tests must pass
• ubs --staged must return zero high/critical findings
• Medium findings require documented justification

If ubs reports issues: Fix them. This counts toward your 3-iteration cap.

Step 2: Commit

git add -A  # Includes .beads/issues.jsonl
git commit -m "Implement {feature}

Closes {bead-id}"

Step 3: Close

CRITICAL: Close sub-beads FIRST, then parent.

bd close {id}.1 --reason "Completed: {summary}"
bd close {id}.2 --reason "Completed: {summary}"
bd close {id} --reason "Completed: {summary}"

Step 4: Release

release_file_reservations(
    project_key=PROJECT_PATH,
    agent_name=YOUR_NAME
)

Step 5: Announce

send_message(
    project_key=PROJECT_PATH,
    sender_name=YOUR_NAME,
    to=[ALL_AGENTS],
    subject="[CLOSED] {id} - {title}",
    body_md="Completed **{id}**.\n\nFiles changed: ...\nTests: passing\nReservations released.",
    thread_id="{id}"
)

---

TDD-First & Security Gates (2025 Research)

Based on research/052-llm-security-vulnerabilities.md, research/053-feedback-loop-security.md, and research/054-tdd-ai-code-gen.md:

Before Starting Any Bead

1. Check if tests exist in bead description
2. If not, write tests FIRST (do not implement without tests)
3. TDD yields 45.97% higher pass@1 rate—this is not optional

During Implementation

Max 3 repair iterations per bead.

After 3 attempts:

1. STOP implementation immediately
2. Spawn spike bead to investigate root cause
3. Notify operator via Agent Mail with importance: high

send_message(
    project_key=PROJECT_PATH,
    sender_name=YOUR_NAME,
    to=["operator"],  # or broadcast
    subject="[BLOCKED] {id} - Needs investigation",
    body_md="Bead {id} failed after 3 repair attempts.\n\nLast error: ...\nSpike created: {spike-id}",
    importance="high",
    thread_id="{id}"
)

Why the cap? Security degrades with repeated self-correction. Models flip-flop on correct answers. Failing fast is safer than debugging loops.

Before Closing Any Bead

1. Run ubs --staged
2. If findings, fix them (counts toward 3-iteration cap)
3. Only close when ubs passes with zero high/critical

Gate: Bead cannot close if ubs --staged reports high/critical findings.

---

Quick Reference

# Find work
bd ready --json
bv --robot-next

# Claim (always include sub-beads + assignee)
bd update {id} --status in_progress --assignee YOUR_NAME

# Close (sub-beads first)
bd close {id}.1 --reason "..."
bd close {id} --reason "..."

# Dependencies
bd dep add {child} {blocker} --type blocks
bd dep tree {id}
bd blocked

---

Anti-Patterns

Don't	Why	Do Instead
Claim only parent	Sub-beads appear "ready" to others	Claim all sub-beads
Skip assignee	Can't track who's working	Always --assignee
Skip [CLAIMED]	Duplicate work	Always announce
Skip [CLOSED]	Stale state	Always announce
Close parent first	Sub-beads orphaned	Close sub-beads first
Hoard tasks	Blocks others	One task at a time
Skip file reservations	Merge conflicts	Reserve before editing
Implement before tests	45.97% lower success rate	TDD-first always
Skip ubs --staged	~40% of LLM code has vulnerabilities	Mandatory gate
Unlimited repair loops	Security degrades, models flip-flop	Max 3 iterations
Continue after 3 failures	Wastes time, introduces bugs	Stop, spike, escalate

---

See Also

• dependencies.md — Dependency management patterns
• multi-agent.md — Coordination with other agents

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.