Tasks and the work cycle
How work moves through the team in rlx. Numbered tasks that are safe to re-add, claims that exactly one agent wins, contracts printed to whoever claims, dependencies that hold work back until it is ready, and review feedback that finds its way back to whoever picks the task up next.
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 claimis refused (claim_lost), and atask next --claimmoves 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).
The lifecycle
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.
A task from start to finish
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 7bd20e44Every 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
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 FILEreads the contract from a file instead.--rules testing,gitcites 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:orboundaries:gets a warning when it is added.[team] brief_blockssets which blocks are checked, and[team] brief_strict = truerefuses the add instead.
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
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
| 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. |
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
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 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
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
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.
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 evidenceThe 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
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. 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>, ortask claim <n>from the session that should have it;- in a fleet,
fleet stop,fleet reaporfleet 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-claimsafter 30 minutes of silence (its--older-than).
A restart or a switch carries the claims over to the replacement.
Receipts you can re-prove
A receipt is a promise; team verify checks it:
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 #12A receipt that lives on a different board is reported as not found, with the name of the board that holds it.
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.
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 boardThe fleet uses one itself: rlx fleet pause sets fleet-paused, and the
manager spawns nothing while it is on.
From your own shell
You are a participant too. Every command above works from any terminal in the project:
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 streamThe board
The board in rlx is the team's shared working memory. What needs you in one line, who is working, every task with a number and a status icon, and a feed of everything the team decided and did.
Connect more than one Claude account
Add your other Claude accounts in rlx so the fleet uses them as one pool. New agents start on an account with room, and an agent that hits its usage limit moves to another account and carries on.