> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pivotal.app/llms.txt.
> For full documentation content, see https://docs.pivotal.app/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pivotal.app/_mcp/server.

# Subtasks

Subtasks are the checklist beneath a task. They share most fields with their parent (`title`, `assignee`, `due_date`, `done`) but stay one level deep. The parent task auto-completes the moment every subtask is checked. Below are the questions people ask once they've used subtasks for an hour.

## How deep can subtasks go?

One level. A task can have subtasks. A subtask can't have its own subtasks. The product enforces this in the UI (no **Add subtask** button on a subtask) and in the API (`POST /tasks/:id/subtasks` returns 422 if `:id` is itself a subtask). This is a deliberate constraint. Two levels become a project plan and we want you to use a separate onboarding for that.

## When should I use a subtask instead of a separate task?

Use a subtask when the work is one logical chunk that you want to split into steps, and you want the parent's `done` flag to track the whole thing. Three common patterns:

* **Checklist**: "Provision sandbox" with subtasks for each system to provision. The parent closes when the sandbox is fully up.
* **Acceptance criteria**: "UAT sign-off" with subtasks for each test case the customer needs to verify.
* **Handoff**: "Engineering handoff complete" with subtasks for code merge, docs updated, on-call briefed.

Use separate tasks when the items have different `assignee`s who need their own due dates and notifications, or when they belong in different phases.

## Can subtasks be assigned to different people?

Yes. Every subtask carries its own `assignee` and `due_date`. The parent task's assignee receives notifications when subtasks are completed, and each subtask's assignee receives their own notifications. The parent doesn't auto-reassign based on subtask owners.

## Do subtasks have to live in the same phase as the parent?

Yes. Subtasks inherit `phase` from the parent. Moving the parent task to another phase moves all subtasks with it. You can't have a parent in **Integration** and subtasks in **UAT**.

## What happens when the parent task is completed manually with open subtasks?

You're prompted to either complete the open subtasks or leave them open. Leaving them open is unusual but allowed. The parent closes with `done: true` and the open subtasks stick around as orphan checklist items. They still appear on the task detail panel and Pi flags them. To clean them up, reopen the parent, finish or delete the subtasks, then re-complete the parent.

## Can a [phase template](/product/onboardings/phase-templates) include subtasks?

Yes. Each task in a template can declare a `subtasks[]` array with the same fields. The subtasks land pre-populated when you apply the template. Templates are the right place to encode your standard acceptance criteria so they don't drift across customers.

## How do subtasks show in the customer portal?

Subtasks inherit the parent task's `customer_facing` flag. A customer-facing task shows its subtasks as a nested checklist. An internal task hides them. You can't override the flag per subtask; flip it on the parent.

## Related

* [Task completion](/product/onboardings/task-completion)
* [Phase templates](/product/onboardings/phase-templates)
* [Comments and attachments](/product/onboardings/comments-and-attachments)

Email **[help@pivotal.app](mailto:help@pivotal.app)** with a screenshot of where you got stuck and the customer or onboarding id from the URL.