# Modules

> Plane modules — feature and workstream grouping that cuts across sprints. Use when the user wants to group related work items by feature area, track progress of a larger feature over multiple sprints, create or manage modules, or ask about workstream progress. Modules complement cycles (time-boxed) by organizing work around outcomes (scope-boxed).

- Skill: `agents-store/modules` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add agents-store/modules`
- Raw SKILL.md: https://api.skillmd.com/api/skills/agents-store/modules/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: agents-store (https://skillmd.com/u/agents-store)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/agents-store/modules

---


# 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

Resolve real tool names via the `connector-bootstrap` skill. Match by action suffix.

## Available Actions

| Action | Purpose |
|--------|---------|
| `list_modules` | List active modules in a project |
| `list_archived_modules` | List archived (completed) modules |
| `create_module` | Create a new module |
| `retrieve_module` | Get a module by UUID |
| `update_module` | Update module details (name, lead, target date) |
| `delete_module` | Delete a module |
| `archive_module` / `unarchive_module` | Archive lifecycle |
| `list_module_work_items` | Get work items in a module |
| `add_work_items_to_module` | Add items (bulk) |
| `remove_work_item_from_module` | Remove an item |

## 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. list_projects              → pick project_id
3. get_project_members        → pick lead (UUID)
4. create_module({
     project_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" | "in-progress" | "paused" | "completed" | "cancelled"
   })
```

## Adding Work Items to a Module

```
add_work_items_to_module({
  project_id,
  module_id,
  issue_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.

## Module Progress Reporting

```
1. list_module_work_items({ project_id, module_id })
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: list_work_item_relations per 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:

```
archive_module({ project_id, module_id })
```

**Caveat:** many Plane deployments reject `archive_module` on **active** modules (HTTP 400). Set `status: "completed"` or `"cancelled"` via `update_module` first, then archive. To remove an active module entirely, use `delete_module` directly.

**Caveat:** `update_module` on many deployments returns a response object with mostly `null` fields even when the update succeeded. Do not rely on the response — refetch via `retrieve_module` 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.