pm-projects

What this skill does

# 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**:
   ```bash
   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:
   ```bash
   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:
```bash
# 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`.