pm-project-plan

name	pm-project-plan
description	Decompose a project (a Linear Project / GitHub Milestone) into milestones and draft its constituent issues. Bridges the project tier to the issue tier — each drafted issue is filed THROUGH pm-issues (so issue templates, type/exec-mode labels, and the pm-issue.js create-gate all still apply). Linear creates native milestones via linear milestone create; GitHub records phases as a checklist in the milestone description (documented degradation — no sub-milestones). Operates on a project, not an individual issue. Trigger phrases — "plan this project", "break down the project", "decompose the project into issues", "what issues does this project need", "/pm-project-plan".
version	0.44.4

PM Project Plan

The bridge from project tier to issue tier. Proposes a milestone breakdown for a project, then drafts each constituent issue and files it through pm-issues.

Usage

/pm-project-plan <project> [--milestone <name>]

• <project> (project slug/name/id, required) — the project (Linear Project / GitHub Milestone) to decompose into milestones and constituent issues. May be omitted when .claude/pm/project.json has linear_project_name set (the create-gate falls back to the config value).
• --milestone <name> (optional) — link drafted issues to a milestone other than the project's default; passed through to the pm-issue.js create create-gate.

Operates on a PROJECT (not an individual issue). Each drafted child issue is filed THROUGH pm-issues (pm-issue.js create), so issue templates, type/exec-mode labels, and the create-gate still apply.

Flow

1. Load the project (cache-first, falls back to a live read via the adapter).

2. Read the description's ## Milestones section as the seed for the breakdown. If it's empty or aspirational, propose a breakdown based on the type template's expected shape.

3. Confirm the milestone list with the user — count, ordering, target dates. Allow edit.

4. Create the milestones:

   • Linear: linear milestone create --project <id> --name "<m>" --target-date <date> --json per milestone (adapter: createMilestone).
   • GitHub: a checklist in the project description's ## Milestones section is the substitute (degradation — Milestones have no sub-milestones). The plan skill rewrites the description with the checklist via updateGithubMilestone.

5. For each milestone, propose constituent issues. Draft each issue with the right issue template, type tag, and labels — drawn from the project's template + context.

6. Hand each draft to pm-issues create — that skill applies its own templates, type/exec-mode labels, and pm-issue.js create-gate. Filed issues link to the project and milestone via the create-verb's --project and --milestone flags (NTH-541), so the documented chain stays inside the gate:

   node "$CLAUDE_PLUGIN_ROOT/hooks/bin/pm-issue.js" create \
     --tag <tag> --title "<t>" --draft-file "$DRAFT" \
     --exec-mode <hitl|afk> --priority <1-4> \
     --project "<project_name>" \
     --milestone "<milestone_name>"
   

   When the project's .claude/pm/project.json already has linear_project_name set, --project may be omitted — the create-gate falls back to the config value. When linking to a milestone that isn't the project's default, pass --milestone explicitly. On GitHub, --milestone <name> passes through to gh issue create.

7. Update the cache — re-sync issues to capture the new links.

GitHub degradation

GitHub Milestones cannot contain sub-milestones. The plan skill records phases as a markdown checklist in the milestone description (within the ## Milestones section), and child issues are linked to the GitHub milestone (the only tracker tier below it). Reports treat the checklist phases as the equivalent of Linear native milestones for the project-health profile.

Conventions

Honors ## Project titles and any ## Issue titles conventions when drafting issue titles.

Related

• pm-issues — drafts are filed through this skill, never bypassing.
• pm-projects — the upstream (create produces the shell; plan decomposes).
• pm-report --profile project-health — consumes milestone completion to label projects.
• pm-project-templates — provides the type's expected milestone shape.