---
name: plane-mcp
description: Plane MCP skill v0.2.0. Use when Codex should work with Plane through the configured plane-mcp MCP server: inspect Plane configuration, list projects and members, count assigned todos, search work items, read or update Plane work items, states, cycles, modules, milestones, initiatives, pages, comments, links, relations, work logs, project SOP, and weekly reports.
---

# Plane MCP

Version: `v0.2.0`

This version includes project-management SOPs, Chinese swimlane/i18n terminology, AI-authored comment/work-log signatures, and weekly report page-sync guidance.

Use the configured `mcp__plane_mcp` tools to work with Plane. Prefer MCP tools over direct HTTP requests or browser automation.

## Setup Check

1. Call `plane_health` when configuration is uncertain.
2. Call `get_me` to identify the authenticated Plane user.
3. Call `list_projects` before project-scoped work unless the project id is already known.
4. Use `workspace_slug` only when the default workspace is missing or the user explicitly names another workspace.

## Common Workflows

### Count Current User's Open Todos

1. Call `get_me` and record the user `id`.
2. Call `list_projects`.
3. For each relevant project, call `list_work_items` with:

```json
{
  "project_id": "<project-id>",
  "assignee_ids": ["<me.id>"],
  "state_groups": ["backlog", "unstarted", "started", "triage"],
  "is_archived": false,
  "limit": 100
}
```

4. Sum `total_count` or count `results` when the response is not paginated.
5. Mention the included state groups and whether archived items were excluded.

### Search Project Work Items

Use `search_work_items` for explicit text search inside a project. Use `list_work_items` with `project_id` and filters for structured filtering by assignee, state, priority, label, type, cycle, module, creator, or archive status.

### Read Project Metadata

Use project-scoped list tools before guessing ids:

- `get_project_members` for assignees.
- `list_states` for workflow states and state groups.
- `list_labels`, `list_cycles`, `list_modules`, and `list_milestones` for filter ids.

### Project Management SOP

Use Plane as a one-way delivery system across roadmap, cycles, and work items. Keep planning content stable, record collaboration as comments/work logs, and avoid moving work backward unless a user explicitly asks.

#### Roles

- Product owns problem framing, user value, scope, acceptance criteria, roadmap priority, and cycle readiness. Product creates or refines demand-level work items and makes sure unresolved questions are visible before handoff.
- Design owns interaction, visual completeness, information architecture, empty/loading/error states, and design edge cases. Design creates design child work items or comments when the requirement needs visual exploration before development.
- Development owns technical approach, implementation tasks, integration risks, test coverage, release readiness, and bug follow-up. Development creates implementation/checklist child work items when the requirement needs explicit build or verification steps.

#### New Project Kickoff SOP

When opening a new Plane project, initialize project management structure before creating delivery work.

1. Confirm the project owner and participants for the three roles: Product, Design, and Development. If any role is missing, add a kickoff comment such as `[Codex] Missing role: Design owner is not assigned yet.`
2. Create or verify the default one-way swimlane states before work starts. Prefer Chinese display names in Plane: `需求池 -> 需求澄清 -> 设计中 -> 待开发 -> 开发中 -> 待验收 -> 已完成`.
3. Map each visible state to a Plane system group: `需求池/backlog`, `需求澄清/unstarted`, `设计中/started`, `待开发/unstarted`, `开发中/started`, `待验收/started`, `已完成/completed`, and `已取消/cancelled` when needed.
4. Create a roadmap/milestone item for the product outcome before creating cycle execution items. The roadmap item should include product goal, target users, success signal, non-goals, acceptance criteria, and expected role handoffs.
5. Create or select the first cycle only after roadmap scope is clear enough to commit. A cycle should contain committed work, not raw ideas.
6. Add kickoff child work items or comments for: Product requirement clarification, Design exploration, Development technical plan, QA/checklist planning, and release/readiness notes.
7. Do not skip handoff discussion. Product must get one comment window for design/development questions before the item moves into `设计中` or `待开发`.

For new-project setup, use comments for setup notes once an item has left `需求池/backlog`, and follow the AI signature rule for every AI-authored comment/work log.

#### Roadmap and Cycle Ownership

- Roadmap items describe outcomes and sequencing. Product keeps roadmap items clear enough for planning, with design/development dependencies called out as child work items or comments.
- Cycle items describe committed delivery work. Do not move unclear roadmap ideas directly into active cycle execution without adding the open questions, assumptions, and owner.
- When a roadmap item enters a cycle, make sure it has an owner, priority, expected role handoff, and acceptance checklist. If these are missing, add comments or child work items before moving it forward.

#### Handoff and Discussion

- Product-to-design or product-to-development handoff must include one discussion window: add a comment for implementation questions, missing edge cases, tradeoffs, or requirement gaps before changing the target state.
- If design or development finds an unconsidered case, add a comment describing the case and either create a child work item or ask product to clarify. Do not silently replace the original requirement text after work has started.
- Handoff comments should include the role, decision needed, proposed next owner, and whether the item is blocked or can proceed with assumptions.

#### Development Verification

- When development finishes implementation, create or update checklist-style child work items for boundary testing when the feature has meaningful edge cases, integrations, permissions, data migrations, or user-facing flows.
- Verification child work items should be specific: include expected behavior, relevant environments, and pass/fail evidence in comments or work logs.
- Bugs discovered during verification should become child work items or related work items, not hidden edits to the completed requirement.

#### One-Way Swimlane Flow

Use a single-direction flow for normal delivery:

`需求池 -> 需求澄清 -> 设计中 -> 待开发 -> 开发中 -> 待验收 -> 已完成`

- Move work forward only when the current role's exit criteria are recorded.
- If work needs earlier-role input, keep it in the current stage and add a blocking comment or child work item for the missing input instead of moving it backward.
- Cancellation is a separate terminal path. Use cancelled only when the user or owner intentionally drops the work.
- Reopening completed work should create a follow-up child/related work item unless the user explicitly asks to reopen the original item.

#### i18n Term Glossary

Use Chinese display names in Plane when helpful, but keep MCP/API field names in English when calling tools.

| Plane/API term | Chinese term | Usage |
| --- | --- | --- |
| Workspace | 工作区 | Organization-level container. |
| Project | 项目 | Product or team delivery space. |
| Roadmap / Milestone | 路线图 / 里程碑 | Outcome sequencing and larger release targets. |
| Cycle | 迭代 | Time-boxed committed delivery scope. |
| Module | 模块 | Functional area or workstream. |
| Work item / Issue | 工作项 | Trackable unit of work. |
| Parent work item | 父工作项 | Requirement, epic-like container, or umbrella task. |
| Child work item | 子工作项 | Design, development, checklist, bug, or verification task under a parent. |
| Label | 标签 | Classification such as role, risk, requirement type, or test scope. |
| State | 状态 / 泳道 | Visible workflow lane. |
| State group | 状态分组 | Plane system group: `backlog`, `unstarted`, `started`, `completed`, `cancelled`, `triage`. |
| Backlog | 需求池 | Ideas or uncommitted work. Maps to `backlog`. |
| Ready for clarification | 需求澄清 | Requirement discussion before design/development. Usually maps to `unstarted`. |
| Design in Progress | 设计中 | Design exploration or UI completion. Usually maps to `started`. |
| Ready for Development | 待开发 | Requirement/design is ready for implementation. Usually maps to `unstarted`. |
| Development in Progress | 开发中 | Implementation is underway. Maps to `started`. |
| Ready for Review/QA | 待验收 | Review, QA, checklist, or acceptance pending. Usually maps to `started`. |
| Done | 已完成 | Accepted and complete. Maps to `completed`. |
| Cancelled | 已取消 | Intentionally dropped. Maps to `cancelled`. |
| Assignee | 负责人 | Person currently responsible for the next action. |
| Priority | 优先级 | Urgency/importance. |
| Comment | 评论 | Collaboration, decisions, handoff notes, and progress updates. |
| Work log | 工时记录 | Time spent and work summary. |
| Acceptance criteria | 验收标准 | Conditions that must be true before Done. |
| Checklist | 检查清单 | Explicit verification or boundary-test child items. |

#### Weekly Report SOP

When the user asks for a weekly report, help summarize the user's handled work and sync the result to the user's private Plane page.

1. Determine the report range first. Use the user's explicit range when provided; otherwise use the current local work week. The page title must use `YYYY-MM-DD-YYYY-MM-DD 周报`, for example `2026-07-06-2026-07-12 周报`.
2. Identify the user with `get_me`, then gather relevant projects with `list_projects`. Include work items assigned to the user, created by the user, updated by the user, commented on by the user, or explicitly mentioned by the user for the report range.
3. For each relevant project, collect work item state, priority, cycle/module/milestone when available, comments, work logs, and state transitions. Prefer project-scoped queries and avoid workspace-wide search unless the user asks for all-workspace reporting.
4. Summarize by sections: `本周完成`, `推进中`, `阻塞/风险`, `需求/设计讨论`, `测试与边界情况`, `下周计划`, and `工时/投入记录` when work logs or signed work-log comments exist.
5. Preserve traceability. Mention work item identifiers or names, but do not paste long raw descriptions. Use concise summaries and link/reference source work items when possible.
6. Sync the final report to the user's private Plane page. If a private/personal page API is available, create or update that private page. If only workspace/project pages are available, ask the user before publishing to a shared page.
7. Do not overwrite an existing weekly report page without checking for the same title. If the same page exists, update/append only the changed summary after user confirmation or a clear same-title update request.
8. AI-authored report notes, comments, or fallback work-log comments must include the AI identity signature, for example `[Codex]`, in the saved content.

### Work Item Update SOP

Before updating an existing work item, retrieve the work item and confirm its current workflow state/group.

- If the work item is still in `backlog`, it is acceptable to update planning fields such as `description_html`, priority, labels, assignees, dates, or parent.
- If the work item is not in `backlog`, do not overwrite `description_html` or other narrative fields to record progress, verification notes, decisions, or elapsed work.
- For non-backlog work items, record progress and decisions with `create_work_item_comment`, and record elapsed work with `create_work_log` when time tracking is available.
- Any comment or work log created by an AI agent must begin with an explicit AI identity signature such as `[Codex]`, `[Claude]`, or `[Gemini]`. The signature must be part of the saved comment/log content, not only implied by the actor account.
- If `create_work_log` fails or time tracking is unavailable, add a clearly labeled signed comment such as `[Codex] Work log: 25m` with the work summary and mention the work-log failure.
- State transitions are allowed when the user asks for status updates or the evidence clearly supports the transition, but the reasoning for the transition should still be added as a comment/work log instead of replacing the description.

## Permission Notes

Project-scoped `list_work_items` supports filters without requiring workspace advanced-search permission. Use `workspace_search: true` only when the user explicitly asks to search across the workspace.

If a Plane API call returns `403`, verify whether the tool is workspace-scoped, then retry with a project-scoped tool when possible. Report the permission boundary clearly.