# Tasks and the work cycle (/docs/rlx/tasks)

The task list is the team's single queue. The manager fills it, coders drain
it, testers and reviewers check what comes out, and you can work it from any
shell. Four guarantees make it safe for several agents at once:

* **Every task has a number on its board**: `#1`, `#2`, … in the order tasks
  were added. You and the agents say `#12`, not a long id.
* **Adding is idempotent.** A task's identity is a key derived from its title
  (or an explicit `--key`). Adding it again returns the original instead of a
  duplicate, so the manager can re-emit its whole plan and the board stays
  clean.
* **Claiming is atomic.** Two coders reaching for the same task never both get
  it: one wins. The other's `task claim` is refused (`claim_lost`), and a
  `task next --claim` moves on to the next ready task instead.
* **Claims are leased.** A claim lasts 120 minutes and is renewed while its
  session works. Once a crashed session's lease runs out, its task can be
  claimed again by name (see [Leases and crashed sessions](#leases-and-crashed-sessions)).

## The lifecycle [#the-lifecycle]

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

Besides that main path: `block` parks a task as blocked with a reason,
`release` gives a claimed task back to the pool, and `drop` discards it.

On the board each status has an icon: ○ to do, ⧗ waiting on a task it needs,
▶ doing, 👀 in review, ⛔ blocked, ✓ done, ✗ dropped. See
[The board](/docs/rlx/board).

## A task from start to finish [#a-task-from-start-to-finish]

```sh
rlx task add "Add rate limiting to /api/search" --role coder \
  --detail "objective: … · why: … · known: … · acceptance: 429 after 100 req/min · boundaries: …"
# ✓ added: #12 tsk_01m4… Add rate limiting to /api/search · seq 41 on prj_8c1e…

rlx task add "Document the rate limit" --needs 12      # held until #12 is done or dropped

rlx task next --role coder --claim --as 3fa9c2d1      # a coder claims the next ready task
# ✓ claimed: #12 tsk_01m4… [doing] Add rate limiting to /api/search · seq 43 on prj_8c1e…
# (then the contract, any reopen feedback, and `rlx task show 12`)

rlx task review 12 --note "run pytest tests/test_limits.py; PR #88" --as 3fa9c2d1
rlx task next --status review --as 7bd20e44            # a tester picks up the review pool
rlx task reopen 12 --reason "returns 500, not 429, at the limit; repro in note" --as 7bd20e44
# #12 is to do again, unclaimed, with the reason attached; a coder claims it, fixes it, and:
rlx task review 12 --note "429 now; regression test added" --as 3fa9c2d1
rlx task done 12 --note "verified: 429 at request 101; tests green" --as 7bd20e44
```

Every write prints a **receipt**: what happened, the task's number and id, its
status (`task add` prints none), and `· seq N on <board id>`, the event that recorded it and the board
it landed on. Under `--json` a task write prints the task itself plus
`delivered: true` (and a `warning`, when there is one); the `seq` is in the
text receipt only.

## The contract travels with the claim [#the-contract-travels-with-the-claim]

A task's `--detail` is its contract. The manager writes it in five blocks,
`objective`, `why`, `known`, `acceptance` and `boundaries`, and whoever claims
the task sees it: `task claim` and `task next --claim` print the contract under
the receipt, then why the task was last reopened, if it was, then the command
for the whole task. `task next` without `--claim` only says the task has a
contract.

* `--detail-file FILE` reads the contract from a file instead.
* `--rules testing,git` cites rules files by name
  (`.aisquare/rules/testing.md`, …), so a contract points at them instead of
  repeating them. A missing one refuses the add.
* A contract missing `objective:`, `acceptance:` or `boundaries:` gets a
  warning when it is added. `[team] brief_blocks` sets which blocks are
  checked, and `[team] brief_strict = true` refuses the add instead.

## Task numbers [#task-numbers]

Any task command, `--needs`, `--task` and the MCP task tools take `12` or `#12`
(quote `'#12'` in a shell, where `#` starts a comment), or the id. A number is
only ever a number on the caller's board: the board of the `--as` session, or
else the board of the directory you are in. If that board has no task #12, the
command says `no task #12 on this board (<name>)`; it never matches a task on
another project's board, or a task whose id happens to end in `12`.

## Task keys in any language [#task-keys-in-any-language]

The key that makes `task add` idempotent is the title's letters, digits and
marks, in any script, normalised and lower-cased: `Исправить вход` keys as
`исправить-вход` and `修复登录` as itself, so two titles in Russian or Chinese
are two tasks. A title of emoji alone is keyed by a hash of it. An ASCII title
keys exactly as it always did.

## Commands [#commands]

| Command                           | What it does                                                                                                                                                                                                             |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `task add "<title>"`              | Add work, idempotently. `--role` suggests an owner, `--detail` or `--detail-file` holds the contract, `--rules` cites rules files, `--needs <task>` (repeatable) orders it after other tasks, `--key` sets the identity. |
| `task list`                       | The board's tasks; `--status todo\|doing\|review\|blocked\|done\|dropped` filters.                                                                                                                                       |
| `task show <task>`                | One task in full.                                                                                                                                                                                                        |
| `task next`                       | The next ready task. `--role` narrows to a role (and unhinted tasks), `--status review` draws from the review pool, `--task` asks for one task only, `--claim` claims it atomically (to-do tasks only).                  |
| `task claim <task>`               | Claim one task by number or id, and print its contract.                                                                                                                                                                  |
| `task review <task>`              | Hand it to review; `--note` says how to verify.                                                                                                                                                                          |
| `task done <task>`                | Close it; `--note` records the evidence. A task a work brief links must pass [the evidence gate](#work-briefs-and-the-evidence-gate).                                                                                    |
| `task reopen <task> --reason "…"` | Send it back with what failed.                                                                                                                                                                                           |
| `task block <task> --reason "…"`  | Park it, saying on what.                                                                                                                                                                                                 |
| `task release <task>`             | Give a claimed task back to the pool. Only a task in `doing` can be released, so finished work is never resurrected by accident.                                                                                         |
| `task drop <task>`                | Discard it.                                                                                                                                                                                                              |

Every command that changes a task takes `--as <session>`, and every command
takes the global `--json`. A fleet agent's own assigned task always comes first
in its `task next`.

## Dependencies [#dependencies]

A task with `--needs` shows ⧗ on the board until everything it needs is done
(or dropped: a dropped need releases its dependants too),
and `task next` never hands it out before then. Agents do not 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 ones, and skips work hinted for other roles.
Hints are advisory, not permissions. The manager hints implementation tasks
for `coder`, and verifiers draw from the review pool with `--status review`.

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

When a tester reopens a task, the reason is attached to the task on the board.
Whichever coder claims it next sees that feedback printed with the contract, so
nobody forwards anything, and the loop runs until a verifier closes the task
for real. A task the manager sees bounce more than once is its cue to re-spec
or split it.

## Work briefs and the evidence gate [#work-briefs-and-the-evidence-gate]

For work where "done" has to be proven, the manager can write a **work brief**:
your request as numbered requirements (`R1`, `R2`, …), each linked to the
board's own tasks. The ids stay for the brief's whole life; a correction
changes the revision of what it touched, and checks recorded against the old
revision go stale.

```sh
rlx brief create "CSV export on the reports page" \
  -r "Export button on /reports" -r "CSV matches the table" --check "R2=pytest tests/test_export.py"
rlx brief link B1 12 -r R1 -r R2                       # task #12 covers R1 and R2 of brief B1
rlx exec --project api --task 12 -- pytest tests/test_export.py # run the check and save a report
rlx brief evidence B1 R2 --task 12 --verdict pass \
  --summary "CSV matches the table" --report <report-id>
rlx brief show B1                                      # each requirement's standing and evidence
```

**The gate.** `rlx task done` on a task a brief links refuses until that
task has recorded a fresh pass for each of its requirements, and names what is
missing, failed, blocked or stale. A pass backed by an `rlx exec --project`
report must come from a run that exited 0 on the same source the checkout has
now. A pass backed by `--artifact` (a screenshot, say) is labelled manual, and
only the validator can judge it. A task no brief links is done exactly as
before.

`rlx exec -- <command>` runs any command once and saves a report of it: its
arguments, exit status, timing and output, and with `--project` the checkout's
source identity before and after. `rlx reports list` and
`rlx reports show <id>` read them back. Reports are kept owner-only under `~/.aisquare/reports/`,
for 14 days and at most the newest 64. `rlx brief --help` lists the rest
(`list`, `update`, `check`, `finding`).

## Leases and crashed sessions [#leases-and-crashed-sessions]

A claim's lease is 120 minutes by default (`AISQUARE_TEAM_LEASE_MIN` changes
it) and is renewed by the session's own lifecycle hooks while it works. A
session that dies stops renewing. &#x2A;*An expired lease does not put the task
back in the pool by itself:** the task stays ▶ doing, `task next` does not
offer it, and only an explicit `rlx task claim <n>` can take it over.
Free it with any of these:

* `rlx task release <n>`, or `task claim <n>` from the session that
  should have it;
* in a fleet, `fleet stop`, `fleet reap` or `fleet shutdown`, which release an
  ended agent's claims at once and name them;
* `rlx team prune`, which releases the claims of a session silent for 4
  hours, or with `--release-claims` after 30 minutes of silence (its
  `--older-than`).

A restart or a switch carries the claims over to the replacement.

## Receipts you can re-prove [#receipts-you-can-re-prove]

A receipt is a promise; `team verify` checks it:

```sh
rlx team verify 42                  # is seq 42 really on this board? exit 0 or 1
rlx team show 42                    # that event in full
rlx team log --mine --as 3fa9c2d1   # read back your own recent writes
rlx team log --task 12 -n 50        # everything that happened to #12
```

A receipt that lives on a different board is reported as not found, with the
name of the board that holds it.

## Signals [#signals]

For states other agents act on, use a named signal instead of prose. A watcher
grepping notes for `READY` would fire on "NOT READY"; a signal is a structured
event with `name`, `value`, `prev` and `set_by` fields.

```sh
rlx team signal release-ready on     # set
rlx team signal release-ready        # read: the value, who set it, when
rlx team signals                     # every signal on the board
```

The fleet uses one itself: `rlx fleet pause` sets `fleet-paused`, and the
manager spawns nothing while it is on.

## From your own shell [#from-your-own-shell]

You are a participant too. Every command above works from any terminal in the
project:

```sh
rlx task list --status review          # what is waiting to be checked
rlx task done 12 --note "verified by hand on staging"
rlx team log -n 30                     # the raw event stream
```

<Cards>
  <Card title="The board" href="/docs/rlx/board" description="Where the tasks, sessions and feed live." />

  <Card title="Run a fleet" href="/docs/rlx/fleet" description="The manager that writes these tasks, and the agents that work them." />

  <Card title="Remote agents (MCP)" href="/docs/rlx/remote-agents" description="The same task tools for clients outside your terminals." />
</Cards>
