# pm_task
{{< badge content="Vanguard" color="blue" class="tier-badge" >}}

The `pm_task` tool is the workhorse of the Valdr MCP surface. It covers the full task lifecycle — creation, search, status transitions, checklists, comments, and event history. Every agent session runs against a task, so this is the most-called tool in most workflows.

{{< callout type="info" >}}
Most actions look up tasks by `taskKey` (e.g., `"PROJ-123"`). `plan` accepts either `taskId` or `taskKey`.
{{< /callout >}}

## Actions

`create`, `get`, `plan`, `get_prompt`, `update`, `delete`, `search`, `change_status`, `checklist_toggle`, `checklist_lookup`, `event_list`, `comment_create`, `comment_list`, `comment_delete`, `help`

---

## create

Create a new task under a project.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `projectKey` | string | Yes | Project this task belongs to (e.g., `"PROJ"`) |
| `title` | string | Yes | Short task title |
| `key` | string | No | Custom task key — auto-generated if omitted |
| `description` | string | No | Markdown description with acceptance criteria |
| `type` | string | No | `task` (default), `bug`, `story`, `epic`, or `spike` |
| `status` | string | No | `backlog` (default), `to_do`, `in_progress`, `in_review`, `verified`, `done` |
| `sprintId` | string | No | Link to a sprint at creation |
| `points` | number | No | Story points |
| `priority` | number | No | 1–5 |
| `assignee` | string | No | Agent handle |
| `reporter` | string | No | Agent handle |
| `metadata` | object | No | `{ tags?, links?, checklists? }` |

### Example

```text
pm_task {
  action: "create",
  projectKey: "MYAPI",
  title: "Add rate limiting to /auth endpoints",
  description: "Implement per-IP rate limiting on signup and login endpoints.",
  type: "task",
  status: "to_do",
  priority: 2,
  assignee: "sigrid"
}
```

---

## get

Fetch a task by key.

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `taskKey` | string | Yes |

---

## plan

Get the linked plan for a task (if one exists). Plans come from the [vmp planner](../planner/).

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `taskId` | string | Conditional | Task ULID. Required if `taskKey` is omitted. |
| `taskKey` | string | Conditional | Alternative lookup. Required if `taskId` is omitted. |

---

## get_prompt

Build the task-specific system prompt that agents receive when launched against this task. Includes description, acceptance criteria, linked requirements, and context.

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `taskKey` | string | Yes |

This is useful for agents that want to see what an executor would receive before launching.

---

## update

Update task fields. Pass only the fields you want to change.

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `taskKey` | string | Yes |
| `description` | string | No |
| `assignee` | string | No |
| `reporter` | string | No |
| `points` | number \| null | No |
| `priority` | number \| null | No |
| `metadata` | object | No |

Use `change_status` to change status. Use [`pm_sprint.link_task`](../sprints/#link_task) to change sprint membership.

---

## delete

Delete a task permanently.

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `taskKey` | string | Yes |

---

## search

Search tasks within a project.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `projectKey` | string | Yes | Scope to a specific project |
| `query` | string | No | Search text |
| `status` | string | No | Filter by status |
| `sprintId` | string | No | Filter by sprint |
| `limit` | number | No | Result cap |

### Example

```text
pm_task {
  action: "search",
  projectKey: "MYAPI",
  status: "in_progress",
  limit: 20
}
```

---

## change_status

Transition a task through the status lifecycle: `backlog → to_do → in_progress → in_review → verified → done`.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `taskKey` | string | Yes | |
| `to` | string | Yes | Target status |
| `reason` | string | No | Reason for the change |

### Example

```text
pm_task {
  action: "change_status",
  taskKey: "MYAPI-42",
  to: "in_review",
  reason: "Implementation complete, ready for code review"
}
```

---

## checklist_toggle

Toggle an individual checklist item on a task.

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `taskKey` | string | Yes |
| `checklistId` | string | Yes |
| `itemId` | string | Yes |
| `checked` | boolean | Yes |

---

## checklist_lookup

Look up checklist names, items, or templates.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `mode` | string | No | `names` (default), `items`, or `template` |
| `query` | string | No | Search query |
| `checklistName` | string | Conditional | Required for `template` mode |
| `limit` | number | No | Result cap |

### Example

```text
pm_task {
  action: "checklist_lookup",
  mode: "template",
  checklistName: "code-review"
}
```

---

## event_list

Fetch the audit trail of events for a task — status changes, assignee changes, comments, session launches, and more.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `taskKey` | string | Yes | |
| `limit` | number | No | Default 25, max 100 |

---

## comment_create / comment_list / comment_delete

Manage task and task-review comments. Comments can be scoped to a review or assignment for threaded discussion.

### comment_create

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `taskKey` | string | Yes | |
| `body` | string | Yes | |
| `reviewId` | string | No | Scope to a specific review |
| `assignmentId` | string | No | Scope to a reviewer assignment |
| `parentCommentId` | string | No | For threaded replies |
| `actorHandle` | string | No | Who is commenting |

### comment_list

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `taskKey` | string | Yes | |
| `reviewId` | string | No | Filter by review |
| `assignmentId` | string | No | Filter by assignment |

### comment_delete

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `taskKey` | string | Yes | |
| `commentId` | string | Yes | |
| `actorHandle` | string | No | Who is deleting |

Deleting a comment also deletes its replies.

---

## help

```text
pm_task { action: "help" }
```

## Related

- [pm_session](../sessions/) — launch agent sessions against tasks
- [pm_review](../reviews/) — start reviews on completed tasks
- [pm_sprint](../sprints/) — link tasks to sprints