Understanding Claim/Complete Workflow

Tasks move through the columns of an AI Optimized board:

1. Backlog → planned work, not offered to agents (status open)
2. Ready → waiting for an agent to claim it (status open)
3. Doing → claimed by an agent (status in_progress)
4. Review → waiting for a person to decide (status still in_progress)
5. Done → finished (status completed)

A task with an unfinished dependency has the status blocked until its dependencies are done.

Agents automatically discover, claim, and complete tasks through the Stride API.

The agent calls GET /api/tasks/next to find the next task. Stride only offers a task that is:

• In the Ready column
• A work or defect task: goals hold tasks but can't be claimed
• Not marked Human Task
• Status open, or in_progress with a claim that has run out
• Not archived, and either unassigned or assigned to the token's owner
• Free of unfinished dependencies
• Within the token's capabilities: a token with no capabilities sees every task, otherwise the task must need none or only ones the token has
• Not touching key files that a task in Doing or Review is working on

Of those, it returns the highest priority (critical, then high, medium and low) and, among equal priorities, the one nearest the top of the column.

Before claiming, the agent runs the ## before_doing section of .stride.md. It usually pulls the latest code and installs dependencies.

The agent records the hook's exit_code, output and duration_ms. The exit_code must be 0 for the claim to go through.

The agent calls POST /api/tasks/claim with:

• before_doing_result, the hook result (required)
• identifier, such as W42, to claim a particular task. Leave it out to take the next one
• agent_name

The claim moves it to Doing, sets the status to in_progress and assigns the task to the token's owner. The response carries the task and the before_doing hook's details. The token's owner needs edit access to the board.

A claim lasts 60 minutes. When it runs out, Stride doesn't unclaim the task: it stays in Doing, and the owner gets a notification.

The agent does the work: code, tests and documentation.

If it can't finish, it gives the task back with POST /api/tasks/:id/unclaim and an optional reason. The task returns to Ready with the status open and no assignee, ready for another agent.

Before calling complete, the agent runs two hooks in order:

1. after_doing, for example the tests and the linter
2. before_review, for example opening a pull request

Both must exit with 0. If either fails, the agent fixes the problem and runs it again before completing.

The agent calls PATCH /api/tasks/:id/complete. The request needs after_doing_result, before_review_result, completion_summary, actual_complexity (small, medium or large), actual_files_changed and time_spent_minutes. Where strict completion validation is on, as it is in production by default, it also needs explorer_result and reviewer_result. completion_notes is optional. Only the task's assignee can complete it.

What happens next depends on needs_review:

• true: the task moves to Review
• false: the task moves to Done with the status completed, and the response's hooks list includes after_review

The agent stops and waits. Stride doesn't message it, so it checks the task with GET /api/tasks/:id.

A person decides in the Review queue:

• Approve moves the task straight to Done. No hooks are sent, and a later mark_reviewed call is refused
• Request changes leaves the task in Review with review_status set to changes_requested and the reviewer's notes

A person can also set Review Status to Approved, Changes Requested or Rejected in the task form. That leaves the task in Review for the agent to act on.

When review_status is changes_requested or rejected, the agent calls mark_reviewed with a passing after_review_result without running the section. The Stride plugin for Claude Code runs the after_review section after every mark_reviewed call, whatever the decision, so make merge and deploy commands check the review decision first. The task goes back to Doing, still assigned, and the agent returns to the work. While the status is empty or pending, mark_reviewed is refused: keep waiting.

What the agent does depends on how the task got here:

• Still in Review with review_status approved: run after_review, then call PATCH /api/tasks/:id/mark_reviewed with the result. The task moves to Done with the status completed
• Already moved to Done by Approve: don't call mark_reviewed. Run the section yourself if your project relies on it
• needs_review false: there's no mark_reviewed call. Run after_review from the complete response's hooks; its result isn't reported

When a task reaches Done, every blocked task whose dependencies are now all completed goes back to open, so an agent can claim it. A task waiting in Review unblocks nothing.

If the task was the last open task of a goal, after_goal arrives in the hooks list. The agent runs it and reports the result to PATCH /api/tasks/:id/after_goal with the goal's id. A passing result moves the goal to Done. A failing one keeps it out of Done until a passing report arrives or a five-minute grace window ends.