Modules

Modules in Plane group work items by scope (feature, workstream, or outcome), in contrast to cycles which group by time (sprints). A single module can span multiple sprints and contain items owned by different people.

Tool Name Resolution

Plane MCP exposes one module tool and the operation goes into the action parameter: module(action=create, ...). This skill writes calls in that form. Resolve the real tool name (mcp__<server>__module) through the connector-bootstrap skill - never assume a server prefix.

Available Calls

Call	Purpose
module(action=list)	List active modules in a project (archived=true lists archived ones; paginated)
module(action=create)	Create a new module
module(action=retrieve)	Get a module by UUID
module(action=update)	Update module details (name, lead, target date, status)
module(action=delete)	Delete a module
module(action=archive) / module(action=unarchive)	Archive lifecycle
module(action=list_workitems)	Get work items in a module (pql filter, paginated)
module(action=manage_workitems)	Add (add_ids) or remove (remove_ids) items in bulk
workitem(action=count)	Module totals per state group: pql='module = "<module_id>"'

When to Use a Module vs a Cycle

Use a module when	Use a cycle when
Grouping work around a feature or outcome	Grouping work into a time-boxed sprint
Work spans multiple sprints	Work is committed for the next 1–2 weeks
Tracking a workstream (mobile, billing, onboarding)	Tracking team commitment
Reporting progress to stakeholders by feature	Reporting progress to the team by sprint

An item can live in both a module and a cycle simultaneously.

Creating a Module

1. connector-bootstrap        → resolve tools and instance
2. project(action=list)      → pick project_id
3. member(action=list_project, project_id=<id>) → pick lead (UUID)
4. module(action=create,
     project_id=<id>,
     name="Billing v2",
     description="Revamp billing: Stripe migration, invoices, proration",
     lead=<user_uuid>,
     members=[<uuid>, <uuid>],
     start_date="YYYY-MM-DD",
     target_date="YYYY-MM-DD",
     status="planned")    // backlog | planned | in-progress | paused | completed | cancelled

Adding Work Items to a Module

module(action=manage_workitems,
  project_id=<id>,
  module_id=<module_id>,
  add_ids=["<uuid>", "<uuid>", ...])

Items can come from any state — backlog, in-progress, or done. Adding a done item is valid; it counts toward module completion. manage_workitems returns nothing: read the result back with module(action=list_workitems). To take items out pass remove_ids=[...] instead (the items stay in the project).

Module Progress Reporting

1. workitem(action=count, project_id=<id>, pql='module = "<module_id>"', group_by=state__group)
   → item totals per state group in one call
   module(action=list_workitems, project_id=<id>, module_id=<module_id>, fields="id,name,point,estimate_point,state")
   → the items with points (follow next_cursor); pass pql='stateGroup = "completed"' for only the finished ones
2. Group items by state group: backlog | unstarted | started | completed | cancelled
3. Calculate:
   - total_items, total_points
   - completed_items, completed_points
   - completion_rate = completed_points / total_points
4. Surface blockers: workitem_relation(action=list) per open item, filter active blocked_by

Reporting table:

| Module | Status | Lead | Completion | Blocked | Target |
|--------|--------|------|-----------|---------|--------|
| Billing v2 | in-progress | @alice | 34/52 (65%) | 2 | Apr 30 |

Module Lifecycle

1. Planned — scope defined, lead assigned, items drafted
2. In Progress — first items moved to "started"
3. Paused — explicitly deprioritized; lead re-assigns team
4. Completed — all items Done or explicitly dropped
5. Cancelled — abandoned; archive after retrospective

Always archive completed/cancelled modules to keep the active list clean:

module(action=archive, project_id=<id>, module_id=<module_id>)

Caveat: unlike cycle(action=archive) (which ends a running cycle first), the module tool documents no such behavior, and some Plane deployments reject archiving an active module (HTTP 400). If that happens, set status="completed" or "cancelled" with module(action=update) first, then archive; module(action=unarchive) reverses it. To remove an active module entirely, use module(action=delete) directly, after confirmation.

Caveat: if an update response looks empty or has mostly null fields, do not rely on it — refetch with module(action=retrieve) to get the post-update state.

Best Practices

1. One lead per module — accountability is clearer.
2. Scope modules to 4–12 weeks of work. Smaller → use a cycle. Larger → use an epic or initiative.
3. Review module progress at each sprint review, not just at module end.
4. If a module stalls for 2 sprints, pause it explicitly — do not leave it "in progress".
5. Link the module's tracking page (see pages-publishing) in every work item description.