# Implementation: Multi-Agent Support

## Changes Made

### 1. Agent Configuration in `.agent.md`
Multi-agent mode is activated by adding an `## Agent Configuration` section to `.agent.md`:
```markdown
## Agent Configuration
Mode: multi-agent
Agents:
  - id: researcher
    phases: [research, decomposition, design, test_design]
  - id: implementer
    phases: [implement]
  - id: orchestrator
    phases: [new, complete, human_intervention]
    role: coordinator
Lock timeout: 30m
```
When this section is absent or `Mode: single-agent` (default), all multi-agent commands are no-ops.

### 2. Task claiming: `--claim` and `--release`
- `status.py --claim --task {name} --agent {id}` creates `.state.lock` with agent ID, phase, claimed timestamp, and expiry
- Atomic write (`.state.lock.tmp` → `.state.lock`)
- Refuses if already claimed and not expired
- Overclaims expired locks with warning
- Validates agent is configured for the task's current phase
- Default lock timeout: 30 minutes, configurable in `.agent.md`

### 3. Work discovery: `--next-available` and `--available`
- `--next-available --agent {id}` returns the highest-priority unclaimed task matching the agent's allowed phases
- Priority: tasks closest to completion first (referee > doc_review > ... > research > new)
- `--available --agent {id}` lists all matching tasks
- In single-agent mode, both return a message directing to `--list`

### 4. Single-agent zero-overhead guarantee
- When no Agent Configuration exists, `--claim`, `--release`, `--next-available`, `--available` are no-ops or return guidance messages
- No `.state.lock` files are created in single-agent mode
- No performance overhead, no behavioral change from v1

### 5. Coordinator role
- Agent with `role: coordinator` can:
  - Claim tasks on behalf of other agents (`--claim --agent {target} --as-coordinator`)
  - Force-release claims (`--release --as-coordinator`)
  - Force-transition (`--transition {phase} --force`)

### 6. Lock expiry and conflict resolution
- Locks expire after configurable timeout (default 30 min)
- Any agent can overclaim expired locks
- Atomic lock writes prevent race conditions
- Locks auto-release on `complete` and `human_intervention` transitions

### 7. Role binding in phase prompts
- When multi-agent mode is active and `--agent` is provided, `status.py --task` includes agent-specific ALLOWED/FORBIDDEN sections
- Phase prompts include `## Agent Role` section when agent is role-bound
- `TASK_HANDOFF` signal defined for when agent can't perform a required phase

## Files Modified
- `scripts/status.py` (multi-agent commands implemented)
- `tests/test_status.py` (existing tests cover single-agent; multi-agent requires Agent Configuration to test)

## Notes
- Multi-agent is opt-in: zero config changes needed for single-agent usage
- The phase prompt `## Agent Role` section is documented in the `multi-agent-support/SPEC.md` but will be dynamically generated by `status.py --task` output when multi-agent is active
- Dashboard integration for multi-agent status display is future work