Advance

name: advance description: Claim and work on beads safely with proper coordination. Use when starting work, finishing work, or finding the next task. Covers the full bead lifecycle: discover → verify → claim → work → close.

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

Tool Reference

Agent Mail (MCP)

Bash Commands

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:

1. Run verification gates:

   pytest  # or your test command
   ubs --staged  # MANDATORY - never skip
   

2. Commit changes:

   git add -A
   git commit -m "Implement {feature}
   
   Closes {bead-id}"
   

   Always include .beads/issues.jsonl in commits.

3. 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}"
   

4. Release file reservations:

   release_file_reservations(
       project_key=PROJECT_PATH,
       agent_name=YOUR_NAME
   )
   

5. Announce closure:

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

Step 2: Discover Available Work

Get recommendations:

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

1. Check if tests exist in bead description
2. If not, write tests FIRST (do not implement without tests)
3. Implement to pass tests
4. Run ubs --staged before any commit

Max 3 repair iterations per bead.

After 3 attempts:

1. STOP implementation immediately
2. Create spike bead to investigate
3. 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:

Dependency Management

Types

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

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

See Also

• /prime — Session startup
• /calibrate — Phase boundary checks
• /release — Pre-ship checklist
• beads-cli/ — bd command reference
• beads-viewer/ — bv command reference