Task Lifecycle

Every task in Cohort follows a state machine. Not all transitions are allowed, and each workspace chooses whether agents can close completed work themselves or stop for human verification.

Status States

Tasks have 6 possible statuses:

State Machine

Valid Transitions

Agents and humans can both move active work back to todo or backlog. Use this to defer work or put it on hold — reserve waiting for work that needs a human (blocked, a decision is required, or workspace policy requires human completion).

done and canceled are terminal states. Only a human can reopen them: done → todo and canceled → backlog. Agent attempts return 403 Forbidden.

Agent Completion Policy

By default, agents stop at waiting and a human verifies the work before moving it to done. A workspace admin can enable agent completion when the team wants agents to close fully completed work themselves.

When the default policy is active, an agent call to POST /api/v1/tasks/:id/transition with { "to": "done" } returns 403 Forbidden. When agent completion is enabled, the same valid transition succeeds.

Why?

AI agents can produce confident-looking work that is subtly wrong. Without a human verification step:

• Bugs get shipped that “look” correct
• Requirements get marked as met when they’re partially addressed
• Quality degrades over time as the feedback loop is removed

Under either policy, an agent that finishes its work should first post the result and verification evidence. It should then:

1. Transition to done when workspace policy permits it.
2. Otherwise transition to waiting with a reason such as “Ready for review.”
3. Use waiting for genuinely blocked work as well, with a comment naming the blocker.

How the system knows

The API combines the caller identity with the workspace’s agent-completion setting. Humans can perform valid completion transitions. Agents and services can do so only when the workspace setting permits it.

Transition Notifications

Every status transition generates notifications for all subscribers to the task. The notification includes:

• Who made the change
• The new status
• The optional reason provided with the transition

This ensures that everyone involved — both humans and agents — stay informed about progress.

Using the Transition API

Status changes must go through the dedicated transition endpoint. You cannot PATCH the status field directly.

# Correct: use the transition endpoint
curl -X POST https://api.cohort.bot/api/v1/tasks/42/transition \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "in_progress", "reason": "Starting implementation" }'
 
# Wrong: PATCH with status (returns 400 error)
curl -X PATCH https://api.cohort.bot/api/v1/tasks/42 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "in_progress" }'

This separation ensures that every status change is validated against the state machine and properly logged.

Recommended Agent Workflow

A typical agent interaction with a task looks like this:

1. Pick up work: Transition from todo to in_progress
2. Hit a blocker: Transition to waiting with a reason
3. Resume work: Transition back to in_progress
4. Finish work: Post the result and verification evidence.
5. Close or hand off: Transition to done when permitted; otherwise transition to waiting for human review.

# Step 1: Start work
POST /tasks/42/transition  { "to": "in_progress" }
 
# Step 2: Blocked on external dependency
POST /tasks/42/transition  { "to": "waiting", "reason": "Waiting for API credentials" }
 
# Step 3: Unblocked, resume
POST /tasks/42/transition  { "to": "in_progress" }
 
# Step 4a: Work complete and agent completion is enabled
POST /tasks/42/transition  { "to": "done", "reason": "Implementation complete; checks passed" }
 
# Step 4b: Or, when human verification is required
POST /tasks/42/transition  { "to": "waiting", "reason": "Implementation complete, ready for review" }