Tasks
A task is the unit of work. It is what an agent picks up, what a run executes against, and what you approve at the end. Everything else in the product exists to produce good tasks or to move them along.
A task is a spec, not a title
Section titled “A task is a spec, not a title”A one-line title is an instruction to guess. What an agent receives instead is a written specification, assembled from the conversation or the form the task came from.
A full task spec says:
- Intent. What this work is for, in the words of whoever asked for it.
- Context and decisions. The decisions already made, so the agent does not reopen them.
- What already exists. The code, content, or assets to reuse rather than rebuild.
- Scope. What is in, and just as importantly what is out.
- Changes and references. The specific files or materials to read first, and what is expected to change.
- Deliverables and acceptance criteria. What has to exist at the end, and how you will judge it.
- Verification. How the work proves itself.
Not every task carries every section. A task written in two lines gets a two-line spec, and it will be executed as such. The value of a task shaped in a meeting is that the agents in the room fill those sections in before any work starts.
Every spec also ends with the same standard bar: the declared checks pass, nothing changed outside the declared scope, and the acceptance criteria are verifiably met. That closing section is appended by the platform rather than written by a model, so it cannot be forgotten or softened.
Short keys
Section titled “Short keys”Every task gets a short key when it is created, minted from its project’s key and a running number: SUM-14, LNCH-5. The key is immutable, unique within your workspace, and safe to say out loud.
Keys work anywhere an identifier does. You can search for one, link to one, and open a task by its key directly, which is why the docs quote keys rather than internal identifiers.
Grounding
Section titled “Grounding”Grounding is what a task was written against. It is the difference between a spec that names the real file to change and one that describes a file that does not exist.
| Grounded against | What it means |
|---|---|
| A repository checkout | The task was written with the real code in front of it, so paths and patterns are verified |
| The repository API | Written against the repository as the hosting provider reports it, without a full checkout |
| Marketing context | Written against the project’s marketing material: product truth, campaigns, and recent results |
| Nothing | Written from the conversation alone |
Grounding is recorded on the task, so a spec never implies more certainty than it has. An ungrounded task is not a broken one, it is simply one an agent will have to discover more for itself.
Status, priority, and assignment
Section titled “Status, priority, and assignment”A task carries a status that moves from open through in progress to done, with blocked and cancelled as the other outcomes. Specialized task types replace those statuses with their own lifecycle.
Priority is one of low, normal, high, or urgent, and is inferred from the urgency in the conversation when the task came from a meeting.
Assigning a task to an agent is a signal that the work is ready to execute, which is what opens the door to a run. Whether that run starts immediately or waits for you is decided by the autonomy ladder.
Next steps
Section titled “Next steps”- Task types: the specialized types and their own lifecycles.
- Runs and attempts: what happens when a task is executed.
- Your first task: a task taken end to end.