# Tasks and the work cycle (/docs/agent-orchestrator/tasks)

The task list is the team's single queue. Its two load-bearing guarantees:

* **Adding is idempotent.** A task's identity is a key derived from its title
  (or an explicit `--key`). Re-adding returns the original instead of creating
  a duplicate, so a planner can re-emit its whole plan after every
  conversation with you and the board stays clean.
* **Claiming is atomic.** One `UPDATE`, one winner. Two coders reaching for the
  same task never both get it; the loser's loop just receives the next ready
  task. Claims carry a lease (default 120 minutes, renewed while the session
  works), so a crashed session's tasks return to the pool on their own.

## The lifecycle [#the-lifecycle]

```
todo ──claim──▶ doing ──review──▶ review ──done──▶ done
  ▲                                  │
  └────────── reopen (with feedback) ┘
```

| Command                                                                    | What it does                          |
| -------------------------------------------------------------------------- | ------------------------------------- |
| `aisquare task add "<title>" [--role coder] [--detail "…"] [--needs <id>]` | add work (idempotent)                 |
| `aisquare task next --role coder --claim --as <id>`                        | atomically claim the next ready task  |
| `aisquare task review <id> --note "<how to verify>"`                       | hand it to the runner                 |
| `aisquare task done <id> --note "verified: …"`                             | close it                              |
| `aisquare task reopen <id> --reason "<what failed + repro>"`               | send it back with feedback            |
| `aisquare task block <id> --reason "…"` / `release <id>` / `drop <id>`     | park it / return a claim / discard it |

`release` only applies to tasks in `doing`, so nobody can accidentally
resurrect finished work; `reopen` is the deliberate path back to the pool.

## Dependencies [#dependencies]

```sh
first=$(aisquare --json task add "build the API" | jq -r .id)
aisquare task add "wire the UI" --needs "$first"
```

A task with unmet needs is visible on the board (marked `⧗ waits on …`) but
`task next` will not hand it out until everything it needs is done. Agents do
not have to reason about ordering; the queue simply never offers work that is
not ready.

## Role hints [#role-hints]

`--role coder` scopes pickup: a coder's `task next --role coder` sees tasks
hinted for coders plus unhinted tasks, and skips work hinted at other roles.
Hints are advisory vocabulary, not permissions, so agree on the role names your
team uses (the built-in cycles use `planner`, `coder`, `runner`).

## The feedback loop [#the-feedback-loop]

Reopen feedback is the heart of the system. When the runner reopens a task, the
reason lands on the shared event pipe attached to the task. Whichever coder
claims it next sees the feedback in its context automatically. Nobody forwards
anything, and the loop keeps going until the runner closes the task for real.

## Watching from the outside [#watching-from-the-outside]

You are also a participant. Every command works from any shell (no `--as`
needed; your actions are attributed to `cli`):

```sh
aisquare task list --status review    # what the runner has waiting
aisquare task done tsk_abc --note "verified manually"
aisquare team log -n 30               # the raw pipe
```