Advance

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