Understand the task workflow

A task is the durable project record for a piece of work. It can be worked more than once. Choose Coding agent or Person when creating it; the type stays fixed. Each attempt is a work run with its own recorded work, review comments, and history.

1. Backlog is ready to organize or queue. Edit its details, then choose Queue when you want a coding agent to work on it.
2. Queued means a work run is waiting for a local listener. The task can show Awaiting local approval when a listener needs its operator to approve the selected command.
3. Agent working begins when a listener starts the coding-agent command. The task shows the active work and elapsed time.
4. Reviewing begins when the coding agent submits its change summary and AI hand-off. Open Review to inspect the result and decide what happens next.
5. Done means a reviewer marked the task complete. Its review history stays available.
6. Closed means the task is intentionally no longer active without claiming that its work was completed. The task, Plan membership, dependencies, comments, and work-run history remain available.

Queueing and coding-agent completion change state automatically. Editing a task's content or metadata does not create a work run, unless the edit changes its state to Queued and you choose a coding agent. A reviewer can also create another run by requesting follow-up work or starting fresh work.

Done is the only successful completion state. A Closed dependency remains incomplete, so closing a prerequisite does not silently unlock dependent work. Closed tasks are removed from active queue, listener, and review selections but remain discoverable through the task list's Show closed toggle.

Create a task with Task type set to Person, or publish a Person draft from Task Builder. In Backlog, choose Start work from its details or task row. The edit-page State menu also opens the matching lifecycle confirmation: every Person state is available from any other state. Choose In progress to start work, Reviewing or Done to submit or complete work (from Backlog, this starts and then submits or completes the work in one step), In progress or Reviewing from Done to reopen completed work, or Backlog to end incomplete work without submitting or completing it. Reopened work keeps the earlier completion in history, but that completion no longer counts toward metrics. Metadata saves before the confirmation opens, so each transition preserves its required history.

The assignee is the performer. You can start another current project member's assigned task without changing its assignment. For an unassigned task, Assign this task to me when work starts is checked by default. Leave it checked to confirm the assignment when you start, or cancel to leave the task unassigned. If the performer is no longer a project member, update the assignment before retrying. Starting with incomplete dependencies requires a separate acknowledgement; a Closed dependency is still incomplete.

A successful start moves the task to In progress and creates one active work run. The In progress badge shows elapsed time using the same compact display as Coding-agent work. The assignee remains visible in the task details. No coding agent is queued.

From In progress task details, choose Submit for review to provide Latest changes and an optional code-review link, or Mark done to complete work directly. Reviewing Person tasks offer Mark done and Return to work for the current assignee. See Submit and review Person work.

Person task metadata calls the task's work-effort size Weight. Coding-agent task metadata calls the same stored value Mass to describe review effort; the CLI uses --weight/--clear-weight for Person tasks and --mass/--clear-mass for Coding-agent tasks, both mapped to the same stored value.

If the task or membership changed, close the dialog, refresh, and review the current state before retrying. If work started but a view could not refresh, refresh the page before another action; the successful start is not undone by that refresh failure.

Open a task, choose Edit, and select the warning-colored Close button beside Delete when its work is superseded, duplicated, or intentionally no longer being pursued. Person tasks use their Backlog, In progress, Reviewing, Done, and Closed lifecycle. Close is available only on the edit page. The confirmation explains what happens to the task's current lifecycle state and warns when dependent tasks will remain blocked. Closing active Person work preserves its unfinished work-run history without submitting or completing it. Closing never cascades to dependents and does not remove dependency relationships. Confirming Close also saves your other edits immediately and returns you to the task details.

You may add Optional context in the confirmation. It is saved as an ordinary task comment, not as a required closure reason or category. Leave it blank when the task and discussion already explain the decision.

Closed work keeps its direct task route, Plan membership, dependencies, comments, and work-run and review history. Task details show when it was most recently closed. Turn on Show closed in the task list to find it later; turning it off returns to the normal active-work view.

To make the task active again, open it, choose Edit or open its review history, select Reopen, and confirm Reopen to Backlog. Task details do not offer Reopen. Reopening clears the Closed date and returns the task to Backlog without queueing a coding agent, satisfying dependencies, or changing preserved history. On the edit page, confirming Reopen also saves your other edits immediately and returns you to the task details, the same as Close; from review history there is no edit form to save, so Reopen only returns the task to Backlog. Choose Queue to resume Coding-agent work, or Start work to resume Person work.

Close and Reopen use the task version you loaded. If the task changed first, the dialog keeps the rejection visible while the page refreshes authoritative state; review the new state and retry only when the action still makes sense. If closure succeeds but optional context cannot be saved, the task remains Closed and the page directs you to add the note from Comments.

The task number, such as #12, identifies the task to people in its project. A work run is one execution of that task. A task can have more than one work run, and its review history shows each queued, started, and reviewed attempt.

Use Create and edit a task to prepare work, Queue a task to start an execution, and Review and recover task work to decide the outcome.