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

The `pm_project` tool manages projects — the top-level containers that group tasks, sprints, and agent work. Projects have a unique `key`, a `taskKeyPrefix` for generating task identifiers, and `metadata` for status and owners.

## Actions

`create`, `get`, `list`, `update`, `delete`, `comment_create`, `help`

---

## create

Create a new project.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `key` | string | Yes | Unique project key (e.g., `"my-api"`). Used in all downstream references. |
| `name` | string | Yes | Human-readable project name. |
| `taskKeyPrefix` | string | Yes | Alphanumeric + hyphens. Task keys generated as `<prefix>-<number>`. |
| `description` | string | No | Project description. |
| `metadata` | object | No | `{ status, owners[] }` where each owner is `{ handle or agentId, role? }`. |
| `repos` | array | No | Array of `{ rootPath, repoUrl?, isPrimary? }` — linked repositories. |

### Example

```text
pm_project {
  action: "create",
  key: "my-api",
  name: "My API Service",
  taskKeyPrefix: "MYAPI",
  description: "REST API for customer-facing services.",
  metadata: {
    status: "in_progress",
    owners: [{ handle: "@alice", role: "owner" }]
  }
}
```

---

## get

Fetch a project by its key. Returns the full project record including repos and comments.

### Parameters

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

### Example

```text
pm_project { action: "get", key: "my-api" }
```

---

## list

List projects, optionally filtered by status.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `status` | string | No | `planned`, `in_progress`, `paused`, `done`, or `archived` |
| `limit` | number | No | 1–200 |

### Example

```text
pm_project { action: "list", status: "in_progress", limit: 20 }
```

---

## update

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

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `key` | string | Yes |
| `name` | string | No |
| `description` | string | No |
| `taskKeyPrefix` | string | No |
| `metadata` | object | No |
| `repos` | array | No |

---

## delete

Delete a project and all associated data (tasks, sprints, reviews). **Destructive — no undo.**

### Parameters

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

---

## comment_create

Add a comment to a project.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `key` | string | Yes | Project key |
| `actor` | string | Yes | Who is commenting (handle or system actor) |
| `body` | string | Yes | Comment content |
| `tags` | string[] | No | Freeform tags |
| `references` | array | No | Array of `{ uri or url, label? }` |

### Example

```text
pm_project {
  action: "comment_create",
  key: "my-api",
  actor: "@alice",
  body: "Promoting to In Progress — sprint kickoff today.",
  tags: ["status-change"]
}
```

---

## help

Returns the canonical action reference directly from the MCP server.

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

## Related

- [pm_task](../tasks/) — tasks belong to projects
- [pm_sprint](../sprints/) — sprints are scoped to a project