> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentdesk.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Waiting and Blocked tasks

> Why a task waits, blocks or stays Ready, how to get it running again, and how to write tasks that run to Done.

A task stops when its agent needs something it cannot get by itself. The task shows why; your answer or fix lets it continue.

| Status | Meaning |
| - | - |
| **Waiting** | The agent asked a question or is waiting for input. It resumes when answered. |
| **Blocked** | A real obstacle stops the work: missing access, broken environment, billing, a decision. |
| **Ready, not started** | Approved, but the agent is busy with another task or the workspace runtime is full. |

## Ready but not running

A Ready task whose agent is busy stays **Ready** and starts by itself when the agent is free. This is not an error and needs no action. Each agent runs one task at a time; tasks and chats share the workspace's parallel runs.

If it still does not start, check that the agent is not paused, the task's dependencies are done, the runtime is not full and the model connection still has quota. To run sooner, assign the task to an idle agent before it starts.

## Unblock a Waiting task

1. Open the task and read the **Waiting reason**. The agent states what it waits for.
2. Use **Current execution** → **Open session** to open the task's session.
3. Answer the agent's exact question with a concrete choice, for example: "Use option B; keep going until Done."
4. The agent resumes. If it does not, set the status to **In Progress** (it needs an assignee) or **Ready**.

Answer early: a task left Waiting for a long time may move to Blocked.

## Unblock a Blocked task

1. Read the **Blocked reason** and fix the obstacle (grant access, restore billing, provide data, make the decision).
2. Write what you fixed in the task's session so the agent knows when it runs again.
3. Set the status to **Ready** with a short reason, for example "CI billing restored, run CI again".
4. Do not move a Blocked task straight to **In Progress**; the server refuses it. From Ready the task is dispatched to its agent again.

If the work is finished and only a manual check remains, check it yourself and set the task to **Done**; waiving proof is recorded in the task history. To stop the work, archive it or return it to Inbox.

To nudge an agent, a short message in the task session is enough: "Continue this task until Done." The agent rereads the task, spec, proof and rules.

## Common traps

* **A comment does not wake the agent.** Comments are for people; the agent reads answers in the task's session.
* **Vague answers** ("ok, continue") lead to the same question again. Answer with a specific option.
* **Unblocking without saying what changed** makes the agent hit the same obstacle and block again.
* **Contradictory rules** (for example "never merge" but acceptance requires a deployed check) make the agent ask for permission each time. Fix the rule, not each answer.
* **Two tasks editing the same files in parallel** conflict. Merge them into one task or add a dependency.

## Write tasks that run to Done

1. **Define an observable Done**: merged to the right branch, checks green, deployed where allowed, proof in **Proofs**, results in **Deliveries**. "Committed" or "tested locally" is not Done.
2. **Write acceptance criteria the agent can check itself.** For a step only a person can check, either let the agent note "not automatically verifiable: …" and still finish, or make that step a separate task.
3. **State granted permissions in PROJECT.md**: which branch it may merge, which environment it may deploy, which tools it may download. The agent will not ask again.
4. **Do not wait for CI or another change.** Waiting for CI belongs inside the agent's run; rebase on the latest main instead of a fixed merge order.
5. **Declare real dependencies** with **Task Dependencies** instead of writing "wait for task X" in the description.
6. **One executing agent per task**, and no parallel tasks on the same files.
7. **Prepare up front**: test accounts, test data, repository and CI access, a model connection with quota.
8. **When the agent must ask**, it should offer options and a default. Answer in the task's session.

A rules block at the top of a description helps a task run without stopping:

```text theme={null}
RUN END TO END WITHOUT WAITING FOR PEOPLE.
- Decide by the spec; ask only for production, money, secrets or deleting data.
- A step you cannot verify automatically: note "not automatically verifiable: ..." and still finish.
- Missing test data: use mocks or fixtures and note the limitation.
```

Every stop is a chance to improve the process: put the fix in PROJECT.md, a skill or the agent's memory so the next run handles it alone.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.