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

# Run a Coding Task

> From a natural-language instruction to a shipped pull request.

A **task** is a unit of coding work the platform runs for you in a sandbox. You describe what you want; specialist agents plan, build, and render it; you review the result and send it to your developers.

## The lifecycle

<Steps>
  <Step title="Start">
    `start_task(project_id, workspace_id, instruction)` returns a `task_id` immediately and `status = running`. The work executes in the background - don't block waiting on the call.
  </Step>

  <Step title="Poll">
    Poll `get_task(project_id, task_id)`. Report progress as you go. The task is done when its status is terminal (`COMPLETED` / `DISCARDED`) or when it needs your input.
  </Step>

  <Step title="Review">
    `get_task_messages` shows what the agent said and did. `get_task_pr_diff` returns the unified git diff - the "Files Changed" view - so you can pull the changes into the editor even before a PR exists.
  </Step>

  <Step title="Iterate">
    Reply or redirect with `continue_task(project_id, task_id, instruction)`. If a run is going the wrong way, `stop_task` cancels the in-flight agent so you can continue with new guidance.
  </Step>

  <Step title="Ship">
    When the user has approved the changes, `complete_task` finalizes the task and opens or updates the pull request. This is the irreversible "send to devs" action - only call it on approval.
  </Step>
</Steps>

<Warning>
  `complete_task` is a real handoff: it opens/updates a PR for your developers. Treat it like clicking **Send to Devs** in Studio - call it only when the user has explicitly approved the changes.
</Warning>

## Versions

A task can produce multiple **versions** of its output. `get_task` shows the active version; `checkout_task_version` switches to another; `get_task_pr_diff(version=N)` diffs a specific one. To throw away sandbox changes without deleting the task, use `discard_task_changes`.

## Working with tasks

* `list_tasks` - all your tasks for a project, most recently active first.
* `rename_task` - set the human-facing title.
* `archive_task` - hide a task (non-destructive; the PR is untouched).
* `update_task_env` - re-sync a running task's sandbox after you change project env vars.

## The plan (spec) document

Before building, you can shape the plan the agent follows:

* `list_spec_versions` / `get_task_spec_version` - read the versioned plan document.
* `update_spec_content` - edit the latest plan in place.
* `create_spec_version` - save a new plan version, keeping history.

## Agent transparency

To see exactly what ran: `list_agent_histories` lists one row per agent run/turn, and `get_agent_history_detail` returns the full message and tool-call trace for a single run.

<Tip>
  Load the built-in walkthrough any time with `load_autonomy_skill name="tasks"`.
</Tip>