# Agent Beads

> Adapted from ACF beads skill

**v0.40+**: First-class support for agent tracking via `type=agent` beads.

## When to Use Agent Beads

| Scenario | Agent Bead? | Why |
|----------|-------------|-----|
| Multi-agent orchestration | Yes | Track state, assign work via slots |
| Single assistant session | No | Overkill—just use regular beads |
| Long-running background agents | Yes | Heartbeats enable liveness detection |
| Role-based agent systems | Yes | Role beads define agent capabilities |

## Bead Types

| Type | Purpose | Has Slots? |
|------|---------|------------|
| `agent` | AI agent tracking | Yes (hook, role) |
| `role` | Role definitions for agents | No |

Other types (`task`, `bug`, `feature`, `epic`) remain unchanged.

## State Machine

Agent beads track state for coordination:

```
idle → spawning → running/working → done → idle
                       ↓
                    stuck → (needs intervention)
```

**Key states**: `idle`, `spawning`, `running`, `working`, `stuck`, `done`, `stopped`, `dead`

The `dead` state is set by Witness (monitoring system) via heartbeat timeout—agents don't set this themselves.

## Slot Architecture

Slots are named references from agent beads to other beads:

| Slot | Cardinality | Purpose |
|------|-------------|---------|
| `hook` | 0..1 | Current work attached to agent |
| `role` | 1 | Role definition bead (required) |

**Why slots?** They enforce constraints (one work item at a time) and enable queries like "what is agent X working on?" or "which agent has this work?"

## Monitoring Integration

Agent beads enable:

- **Witness System**: Monitors agent health via heartbeats
- **State Coordination**: ZFC-compliant state machine for multi-agent systems
- **Work Attribution**: Track which agent owns which work

## CLI Reference

Run `bd agent --help` for state/heartbeat/show commands.
Run `bd slot --help` for set/clear/show commands.
Run `bd create --help` for `--type=agent` and `--type=role` options.