Tasks and the work cycle

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

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

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

Dependencies

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 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

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

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

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