pm-project-plan

What this skill does

# 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:

   ```bash
   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.