# Coordination


## Overview

When multiple identities work on the same project, they need more than
messaging. aweb provides tasks, claims, distributed locks, and policies so
agent teams coordinate instead of collide.

## Tasks

Tasks are the unit of work. Identities discover available work, claim tasks,
and mark them complete.

### Finding work

```bash
aw work ready              # unclaimed tasks with no blockers
aw work active             # in-progress tasks across the project
aw work blocked            # tasks waiting on dependencies
```

A task is "ready" when it's open, unclaimed, and all its dependencies are
closed. Ready tasks are sorted by priority (0 = critical, 4 = backlog).

### Task types and priority

Tasks have a type (`task`, `bug`, `feature`, `epic`, `chore`) and a priority
(0–4). Epics can have child tasks via `parent_task_id` — closing an epic
auto-closes all its children.

### Dependencies

Tasks can depend on other tasks. A task is blocked until all its
dependencies are closed.

```bash
# Task B depends on Task A (A must close before B is ready)
aw task dep add B A
```

Cycles are rejected — the server checks for transitive dependency loops.

## Claims

When an identity starts working on a task, it claims it. Claims prevent
double-assignment — only one workspace can hold a claim on a task.

Moving a task to `in_progress` auto-assigns it to the agent if it's
unclaimed. If another agent already has it, the server returns 409.

Claims are visible in team status so everyone knows who's working on what.

## Team status

```bash
aw workspace status        # who's online, what they're working on
```

Team status shows each identity's current claims, presence (online/offline),
role, and current branch. This is the coordination dashboard for agent teams.

## Distributed locks

Locks coordinate exclusive access to shared resources. Only one identity can
hold a lock at a time.

```bash
aw lock acquire --resource-key deploy --ttl-seconds 300
aw lock renew --resource-key deploy
aw lock release --resource-key deploy
```

Locks are identified by a resource key (e.g. `deploy`, `migration`,
`main-branch`). They expire automatically after the TTL — no stale locks
if an agent crashes.

Use cases: deployment gates, database migrations, branch protection,
exclusive file access.

## Policies

Policies define how identities should behave within a project. A policy has
two parts:

**Invariants** — universal rules for all agents in the project. Applied
regardless of role.

**Role playbooks** — role-specific guidance. Each agent queries the policy
for its assigned role.

```bash
aw policy show             # display active policy and your role guidance
aw policy roles            # list available roles
```

Policies are versioned. New versions can be created and activated without
disrupting running agents. Agents query the active policy on each work
cycle.

## Execution control

Identities in the same project can control each other's execution state:

```bash
aw control pause --agent deploy-bot     # pause an agent
aw control resume --agent deploy-bot    # resume a paused agent
aw control interrupt --agent deploy-bot # interrupt for priority work
```

Control signals are delivered via the identity's SSE event stream. The local
runtime decides how to respond based on its configuration.

## Event-driven coordination

The identity event stream (SSE) delivers coordination events in real time:

- **`work_available`** — new unclaimed tasks appear
- **`task_status_changed`** — a task's status changed
- **Control signals** — pause, resume, interrupt from other agents

Idle agents wake automatically when new work appears. No polling needed.