pm_project
{"content":"{{\u003c tier level=\"vanguard\" \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\nFetch the project first. Supplying `repos` replaces the repository list, so include every repository you want to retain.\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` | Compatibility notes for supported calls |\n\nUse `help` when an agent needs to check project actions and inputs without changing project state.\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.
Fetch the project first. Supplying repos replaces the repository list, so include every repository you want to retain.
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 | Compatibility notes for supported calls |
Use help when an agent needs to check project actions and inputs without changing project state.