Advance — Bead Lifecycle
Complete bead lifecycle: discover → verify → claim → work → close. Direct execution.
Design rationale: This skill executes directly rather than spawning subagents because each step is a simple command sequence (~200 tokens each), not substantial analytical work. Per Lita research: "Simple agents achieve 97% of complex system performance with 15x less code." Subagent overhead would exceed actual work.
When This Applies
| Signal | Action |
|---|---|
| User says "next task" or "what's next" | Run discovery → claim |
| User says "/advance" | Run full protocol |
| Just finished a task | Close out, then discover |
| Starting work on a specific bead | Verify → claim |
| User says "claim" or "start" | Verify → claim |
| User says "done" or "close" | Run close protocol |
Tool Reference
Agent Mail (MCP)
| Tool | Purpose |
|---|---|
fetch_inbox(agent_name) |
Check for messages before claiming |
file_reservation_paths(paths, exclusive) |
Reserve files before editing |
release_file_reservations(agent_name) |
Release files after closing |
send_message(to, subject, body_md, thread_id) |
Announce [CLAIMED]/[CLOSED] |
Bash Commands
| Command | Purpose |
|---|---|
bd list --status in_progress --json |
Check for current work |
bd ready --json |
List available tasks |
bd update <id> --status in_progress --assignee NAME |
Claim task |
bd close <id> --reason ".\.\." |
Close completed bead |
bd dep tree <id> |
View dependencies |
bd blocked |
View blocked tasks |
bv --robot-triage |
Get recommendations |
bv --robot-next |
Get single best task |
bv --robot-plan |
Get execution order |
cm context "task description" --json |
Get patterns before starting |
pytest |
Run tests before closing |
ubs --staged |
Security scan (MANDATORY) |
Execution Flow
Execute these steps directly. No subagents needed.
Step 1: Close Out Previous Work
Check for in-progress work:
bd list --status in_progress --assignee YOUR_NAME --json
If work exists:
Run verification gates:
pytest # or your test command ubs --staged # MANDATORY - never skipCommit changes:
git add -A git commit -m "Implement {feature} Closes {bead-id}"Always include
.beads/issues.jsonlin commits.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}"Release file reservations:
release_file_reservations( project_key=PROJECT_PATH, agent_name=YOUR_NAME )Announce closure:
send_message( project_key=PROJECT_PATH, sender_name=YOUR_NAME, to=[ALL_AGENTS], subject="[CLOSED] {id} - {title}", body_md="Completed **{id}**.
Tests: passing Security: clean Reservations: released", thread_id="{id}" )
---
### Step 2: Discover Available Work
**Get recommendations:**
```bash
bv --robot-triage # Priority recommendations
bv --robot-next # Single best task
bv --robot-plan # Execution order
Get ready tasks:
bd ready --json
Check already claimed:
bd list --status in_progress --json
Discover active agents:
ReadMcpResourceTool(
server="mcp-agent-mail",
uri="resource://agents/{PROJECT_PATH}"
)
Check inbox:
fetch_inbox(
project_key=PROJECT_PATH,
agent_name=YOUR_NAME,
include_bodies=True,
limit=10
)
Address urgent messages before claiming new work.
Step 3: Verify Target Task
All must pass before claiming:
- Task status is
ready - No other agent has claimed it (check recent
[CLAIMED]messages) - Required files not reserved by others
- Dependencies satisfied (
bd dep tree {id}) - No blocking inbox messages
Check task status:
bd show {task_id} --json
Check file availability:
# Test if files are available
file_reservation_paths(
project_key=PROJECT_PATH,
agent_name=YOUR_NAME,
paths=["src/module/**"],
ttl_seconds=60, # Short test
exclusive=False # Just checking
)
Check for claim conflicts:
search_messages(
project_key=PROJECT_PATH,
query="[CLAIMED] {task_id}"
)
If ANY check fails → pick different task or coordinate first.
If uncertain, ask:
send_message(
project_key=PROJECT_PATH,
sender_name=YOUR_NAME,
to=[OTHER_AGENTS],
subject="Claiming task: {task-id}?,
body_md="Planning to pick up **{task-id}**. Files: `src/...`. Conflicts?,
importance="normal"
)
Step 4: Claim
Claim parent AND all sub-beads:
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
CRITICAL: Always claim parent AND all sub-beads together. If you only claim parent, other agents may grab sub-beads.
Reserve files:
file_reservation_paths(
project_key=PROJECT_PATH,
agent_name=YOUR_NAME,
paths=["src/module/**", "tests/**"],
ttl_seconds=3600, # 1 hour
exclusive=True,
reason="{bead-id}: {description}"
)
Announce (MANDATORY):
send_message(
project_key=PROJECT_PATH,
sender_name=YOUR_NAME,
to=[ALL_AGENTS],
subject="[CLAIMED] {id} - {title}",
body_md="""Starting work on **{id}**: {title}
**Files reserved:**
- src/module/**
- tests/**
**Sub-beads claimed:**
- {id}.1: {sub_title_1}
- {id}.2: {sub_title_2}
""",
importance="normal",
thread_id="{id}"
)
Step 5: Get Context Before Working
After claiming, get patterns and anti-patterns:
cm context "{task-title}" --json
This returns:
- Relevant rules from past sessions
- Anti-patterns to avoid
- Historical context about similar work
Step 6: Work (TDD-First)
Based on research (45.97% higher pass@1 rate with TDD):
- Check if tests exist in bead description
- If not, write tests FIRST (do not implement without tests)
- Implement to pass tests
- Run
ubs --stagedbefore any commit
Max 3 repair iterations per bead.
After 3 attempts:
- STOP implementation immediately
- Create spike bead to investigate
- Notify operator:
send_message( project_key=PROJECT_PATH, sender_name=YOUR_NAME, to=["operator"], 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.
Step 7: Output Summary
Present to user:
## Task Claimed
**Bead:** {id} - {title}
**Priority:** {priority}
**Files:** {file_list}
### Context from Memory
{relevant patterns from cm}
### TDD Checklist
- [ ] Write/review tests first
- [ ] Implement to pass tests
- [ ] Run `ubs --staged` before commit
- [ ] Max 3 repair iterations
Ready to begin implementation.
Mandatory Gates
These gates apply to ALL bead work:
| Gate | Requirement | Evidence |
|---|---|---|
| TDD-first | Write tests before implementation | 45.97% higher success rate |
| ubs --staged | Security scan before every commit | ~40% of LLM code has vulnerabilities |
| Max 3 iterations | Stop after 3 repair attempts | Security degrades with more |
| Escalate on failure | Create spike, notify operator | Don't waste time debugging |
Dependency Management
Types
| Type | Meaning | Example |
|---|---|---|
blocks |
A must complete before B can start | Schema blocks implementation |
discovered-from |
Found B while working on A | Bug found during feature work |
Commands
# Add dependency (B is blocked by A)
bd dep add {child-id} {blocker-id} --type blocks
# View dependencies
bd dep tree {id}
# View blocked tasks
bd blocked
# Full graph analysis
bv --robot-triage
Common Patterns
Schema → Implementation → Tests:
bd dep add impl-id schema-id --type blocks
bd dep add test-id impl-id --type blocks
Discovered Issues:
# While working on feature-123, found bug
bd create "Found: edge case in validation" -t bug
bd dep add {new-bug-id} feature-123 --type discovered-from
Multi-Agent Coordination
When multiple agents are active:
File Reservations
Check for conflicts:
# If reservation fails, another agent has those files
# Options:
# 1. Pick different task
# 2. Coordinate via message
# 3. Wait for TTL expiry
Extend if needed:
renew_file_reservations(
project_key=PROJECT_PATH,
agent_name=YOUR_NAME,
extend_seconds=1800
)
Inbox Protocol
- Before claiming: Check for recent
[CLAIMED]messages - While working: Check inbox every ~30 minutes
- Look for: API changes, coordination requests, blockers
Thread IDs
Use bead ID as thread ID for all related messages:
Bead: bd-123
Thread ID: bd-123
Subject: [CLAIMED] bd-123 - Title
Reservation: reason="bd-123"
Commit: Closes bd-123
Conflict Resolution
| Conflict | Resolution |
|---|---|
| Both claimed same task | First [CLAIMED] wins, other picks new task |
| Both editing same file | Reservation holder wins, other waits |
| Dependency disagreement | Discuss in thread, escalate if stuck |
Quick Reference
# Recommended next
bv --robot-triage
bv --robot-next # Single best task
# Ready tasks
bd ready --json
# Claimed tasks
bd list --status in_progress --json
# 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 |
| Skip inbox checks | Miss coordination messages | Check before claiming |
See Also
/prime— Session startup/calibrate— Phase boundary checks/release— Pre-ship checklistbeads-cli/— bd command referencebeads-viewer/— bv command reference
Setup
Before beginning bead operations, ensure the state synchronization script is executed to initialize environment monitoring:
python scripts/bead_state_sync.py
This initialization step prepares the environment for optimal bead lifecycle management and ensures all operational parameters are properly configured.
Getting Started
To get started with the advance skill, follow these steps:
- Initialize the environment by running the state synchronization script
- Review available tasks using the recommended commands
- Claim your first bead following the verification protocol
- Monitor progress through regular status checks
For detailed information on commands and workflows, refer to the Tool Reference and Execution Flow sections above.