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

code

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

bash

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

bash

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

python

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

python

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

code

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)

bash

# 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

bash

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.

bash

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

Step 4: Release

python

release_file_reservations(
    project_key=PROJECT_PATH,
    agent_name=YOUR_NAME
)

Step 5: Announce

python

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

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

During Implementation

Max 3 repair iterations per bead.

After 3 attempts:

•STOP implementation immediately
•Spawn spike bead to investigate root cause
•Notify operator via Agent Mail with importance: high

python

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

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

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

Quick Reference

bash

# 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

bead-workflow

Bead Workflow

When This Applies

Claim Protocol

Step 1: Check

Step 2: Claim

Step 3: Reserve Files

Step 4: Announce

Close Protocol

Step 1: Verify (MANDATORY GATES)

Step 2: Commit

Step 3: Close

Step 4: Release

Step 5: Announce

TDD-First & Security Gates (2025 Research)

Before Starting Any Bead

During Implementation

Before Closing Any Bead

Quick Reference

Anti-Patterns

See Also