pm_project
{"content":"{{\u003c badge content=\"Vanguard\" color=\"blue\" class=\"tier-badge\" \u003e}}\n\nThe `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.\n\n## Actions\n\n`create`, `get`, `list`, `update`, `delete`, `comment_create`, `help`\n\n---\n\n## create\n\nCreate a new project.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `key` | string | Yes | Unique project key (e.g., `\"my-api\"`). Used in all downstream references. |\n| `name` | string | Yes | Human-readable project name. |\n| `taskKeyPrefix` | string | Yes | Alphanumeric + hyphens. Task keys generated as `\u003cprefix\u003e-\u003cnumber\u003e`. |\n| `description` | string | No | Project description. |\n| `metadata` | object | No | `{ status, owners[] }` where each owner is `{ handle or agentId, role? }`. |\n| `repos` | array | No | Array of `{ rootPath, repoUrl?, isPrimary? }` — linked repositories. |\n\n### Example\n\n```text\npm_project {\n action: \"create\",\n key: \"my-api\",\n name: \"My API Service\",\n taskKeyPrefix: \"MYAPI\",\n description: \"REST API for customer-facing services.\",\n metadata: {\n status: \"in_progress\",\n owners: [{ handle: \"@alice\", role: \"owner\" }]\n }\n}\n```\n\n---\n\n## get\n\nFetch a project by its key. Returns the full project record including repos and comments.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `key` | string | Yes |\n\n### Example\n\n```text\npm_project { action: \"get\", key: \"my-api\" }\n```\n\n---\n\n## list\n\nList projects, optionally filtered by status.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `status` | string | No | `planned`, `in_progress`, `paused`, `done`, or `archived` |\n| `limit` | number | No | 1–200 |\n\n### Example\n\n```text\npm_project { action: \"list\", status: \"in_progress\", limit: 20 }\n```\n\n---\n\n## update\n\nUpdate project fields. Pass only the fields you want to change.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `key` | string | Yes |\n| `name` | string | No |\n| `description` | string | No |\n| `taskKeyPrefix` | string | No |\n| `metadata` | object | No |\n| `repos` | array | No |\n\n---\n\n## delete\n\nDelete a project and all associated data (tasks, sprints, reviews). **Destructive — no undo.**\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `key` | string | Yes |\n\n---\n\n## comment_create\n\nAdd a comment to a project.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `key` | string | Yes | Project key |\n| `actor` | string | Yes | Who is commenting (handle or system actor) |\n| `body` | string | Yes | Comment content |\n| `tags` | string[] | No | Freeform tags |\n| `references` | array | No | Array of `{ uri or url, label? }` |\n\n### Example\n\n```text\npm_project {\n action: \"comment_create\",\n key: \"my-api\",\n actor: \"@alice\",\n body: \"Promoting to In Progress — sprint kickoff today.\",\n tags: [\"status-change\"]\n}\n```\n\n---\n\n## help\n\nReturns the canonical action reference directly from the MCP server.\n\n```text\npm_project { action: \"help\" }\n```\n\nThe help payload is a read-only contract for project-aware automation:\n\n| Field | Contents |\n|-------|----------|\n| `actions` | Every accepted `pm_project` action: `create`, `get`, `list`, `update`, `delete`, `comment_create`, and `help` |\n| `whenToUse` | Action-by-action guidance for creating projects, fetching before mutation, listing lifecycle states, deleting intentionally, and adding project comments |\n| `examples` | Representative calls such as fetching a project, listing active projects, and attaching a coordination note |\n| `cautions` | Guardrails for fetch-before-update, sprint membership boundaries, and destructive project deletes |\n| `compatibility` | Notes that the help payload is additive and accepted input schemas, action names, and MCP error behavior are unchanged |\n\nUse `help` when an agent needs the project tool contract without mutating project state. The structured payload is compatibility-preserving: it gives newer clients richer guidance while keeping existing `pm_project` calls and result shapes stable.\n\n## Related\n\n- [pm_task](../tasks/) — tasks belong to projects\n- [pm_sprint](../sprints/) — sprints are scoped to a project","description":"Manage projects, repositories, and project-level comments via MCP.","title":"pm_project"}
Vanguard
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
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
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
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
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.
pm_project { action: "help" }The help payload is a read-only contract for project-aware automation:
| Field | Contents |
|---|---|
actions | Every accepted pm_project action: create, get, list, update, delete, comment_create, and help |
whenToUse | Action-by-action guidance for creating projects, fetching before mutation, listing lifecycle states, deleting intentionally, and adding project comments |
examples | Representative calls such as fetching a project, listing active projects, and attaching a coordination note |
cautions | Guardrails for fetch-before-update, sprint membership boundaries, and destructive project deletes |
compatibility | Notes that the help payload is additive and accepted input schemas, action names, and MCP error behavior are unchanged |
Use help when an agent needs the project tool contract without mutating project state. The structured payload is compatibility-preserving: it gives newer clients richer guidance while keeping existing pm_project calls and result shapes stable.