pm-projects

name	pm-projects
description	Create, update, and close out a project (a Linear Project / GitHub Milestone) — the project-tier CRUD bundle. Mirrors pm-issues one tier up. Use when the user says "create a project", "new Linear project", "file a project", "update the project target date", "close out the project", "wrap up the project", "archive the project", "/pm-projects". This operates on a project (a Linear Project or a GitHub Milestone), NOT on an individual issue — issue CRUD lives in pm-issues. Routes child issue filing through pm-issues so all issue-tier discipline (templates, labels, the pm-issue.js create-gate) still applies.
version	0.44.4

PM Projects

CRUD-and-lifecycle for tracker projects. Three verbs: create, update, closeout.

Usage

/pm-projects create|update|closeout  [<project>] [flags…]

• create (verb) — scaffold a new project (Linear Project / GitHub Milestone) from a type template; runs the create-gate.
• update (verb) — patch metadata (name, target date, lead, status) on an existing project.
• closeout (verb) — verify children closed, capture retro, orchestrate the handoff brief, set terminal state.
• <project> (project slug/name or id; update/closeout) — which project to operate on; resolved to a Linear project id / GitHub milestone number.
• --type <type> (create) — project template type; prompted if omitted.
• --provider <linear|github> (create/validate gate, required) — tracker the create-gate writes against.
• --id <project_id> (update, Linear) — target Linear project id for the GraphQL patch.
• --slug <workspace_slug> (create, cache) — workspace slug used to reconcile the new project into local cache.

Operates on a PROJECT (a Linear Project / GitHub Milestone), not an individual issue — issue CRUD lives in pm-issues. Child-issue filing routes through pm-issues (via pm-project-plan), so all issue-tier discipline (templates, labels, the pm-issue.js create-gate) still applies.

Create

1. Resolve the project type — explicit --type or ask. Load the type's template body from pm-project-templates.
2. Scaffold the description from the template body. Required sections from the manifest must be substantive at submission time.
3. Resolve teams via the shared team resolver (hooks/lib/team-resolver.js):
   • Explicit team(s) in request → use them.
   • Otherwise → always-multi-select picker across the workspace (primary team pre-checked).
   • User declines / non-interactive → fall back to project.json linear_team_key.
4. Resolve lead — explicit value, @me, or skip on GitHub (Milestones have no lead).
5. Resolve target date — explicit, or ask.
6. Run the create-gate:

   echo '<json-draft>' | node "$CLAUDE_PLUGIN_ROOT/skills/pm-projects/scripts/pm-project.js" create --provider <linear|github>
   

   Validates: type marker present, all required sections substantive, at least one team. Refuses on MISSING_TYPE / MISSING_SECTIONS / NO_TEAMS with the specific gap surfaced.
7. On success, the project lands in the tracker. To pull it into the local cache, run:

   node "$CLAUDE_PLUGIN_ROOT/hooks/bin/pm-cache.js" portfolio-sync --workspace <workspace_slug> --mode delta
   

   This refreshes the whole workspace cache and picks up the new project alongside everything else. There is no single-project sync verb in this release — portfolio-sync is the canonical entry point for project cache updates.

Two-step milestones (default): create produces the project shell only. Milestones come later via pm-project-plan. (One-step scaffolding is not implemented in this release.)

Update

Patch metadata via:

# Linear: use the pm-project.js script (GraphQL transport)
echo '<json-patch>' | node "$CLAUDE_PLUGIN_ROOT/skills/pm-projects/scripts/pm-project.js" update --id <project_id> --provider linear
# GitHub:
gh api -X PATCH /repos/<o>/<r>/milestones/<num> -f ...

Adapter wrappers: updateProject (Linear GraphQL) and updateGithubMilestone (GitHub). Conventions consulted via pm-conventions before writing user-facing copy. Cache refreshed after the write.

Closeout

1. Verify all child issues are closed/cancelled. Warn-and-confirm if any are still open — list them, require explicit confirmation. Never auto-close children.

2. Capture a retro: optional with prompt. Skip allowed; required not enforced.

3. Generate a completion summary (drawn from the original description's Goal + Success Metrics + the captured retro).

4. Orchestrate pm-handoff for the recipient-facing "project done / ready for release" brief. Four-block invariant unchanged.

5. Set the tracker's terminal state:

   • Linear: linear project update <id> --status completed
   • GitHub: gh api -X PATCH /repos/<o>/<r>/milestones/<num> -f state=closed

   True archival (Linear) via the linear api GraphQL escape hatch only if a user reports needing it; deferred from this release.

Conventions

Honors <repo>/.claude/pm/conventions.md — recognized headings consulted: ## Project titles, ## Project labels. Plugin defaults apply when absent.

Related

• pm-issues — issue-tier CRUD (also adopts the shared team resolver in this release).
• pm-project-templates — type registry consulted at create + closeout.
• pm-project-review — lints an existing project against its template.
• pm-handoff — orchestrated by closeout for the recipient-facing brief.
• pm-spec — refines a spec interactively, then hands settled values to pm-projects create.