project-manager

What this skill does

# Project Manager

## Scope Grammar (v0.21.0+)

Every PM skill that reads issues accepts `--scope <expression>`. The default is workspace-wide (the active project's workspace). Forms:

| Form | Resolves to |
|---|---|
| `repo:org/foo` | The teams + project_id for the matching profile in `projects` (back-compat) |
| `team:ENG` | All issues with `team_key == ENG` |
| `team:ENG+subteams` | `ENG ∪ children(ENG) ∪ children(children(ENG))` — transitive |
| `project:CHK` | All issues with `project_slug == CHK` |
| `project:CHK+deps` | CHK + transitive `depends_on` + transitive `depended_on_by` |
| `project:CHK+deps:upstream` | CHK + transitive `depends_on` only |
| `project:CHK+deps:downstream` | CHK + transitive `depended_on_by` only |
| `workspace:<slug>` | Whole workspace |
| `workspace:X,team:Y+subteams` | Intersection |
| `all` | All issues across all known workspaces |

Comma joins narrow (intersection). The scope graph (workspaces, teams, project relations) is populated by `/pm-setup --portfolio`. The resolver lives in `hooks/lib/scope-resolver.js`; the verbs that consume it are `scope-briefing`, `timeframe-report`, and (Phase 5b) `roadmap`.

Central routing skill for project management workflows. Delegates to focused skills based on the task.

## Skill Routing

| Task | Skill to use |
|------|-------------|
| Session briefing, what's in progress, what's next | `pm-status` |
| Register a project, paste Linear API key, configure conventions | `pm-setup` |
| Create, update, or close an issue | `pm-issues` |
| Resolve / list / register a tag-keyed issue template | `pm-templates` |
| Review an existing issue against its template + conventions | `pm-review` |
| Enrich an issue with repo context, related issues, research, Q&A | `pm-improve` |
| Triage a raw/untriaged issue (classify + review + enrich + label) | `pm-triage` |
| Place a workable issue (status, project/milestone, parent, assignee, workstream) | `pm-organize` |
| Dispatch triage + organize over an issue or backlog (returns one report) | `pm-intake` agent |
| Sync / show / edit the team roster (members + skills) | `pm-team` |
| Estimate a member's skills from their issue history (writes team.md) | `pm-proficiency` |
| Load, show, edit, or validate project conventions | `pm-conventions` |
| Create a branch or write a PR description | `pm-branches` |
| Changing direction mid-feature, pivoting | `pm-pivot` |
| Generate a daily or weekly status report (PDF/HTML) | `pm-report` |
| "what's stuck" / "what's blocked" / "what's dragging" | `pm-report --profile stuck` |
| "what shipped" / "what got done today/this week" | `pm-report --profile movement` |
| "velocity" / "are we on track" / "throughput" | `pm-report --profile throughput` |
| "what's next to pick up" / "ready" | `pm-report --profile next-up` |
| "standup" / "status report" | `pm-report --profile exec` |
| "review prs" / "open prs" / "what prs need attention" | `pm-report --profile prs` |
| "ready to merge" | `pm-report --profile prs` |
| "waiting on me to review" | `pm-report --profile prs` |
| "waiting on me" (ambiguous) | ask: "PRs waiting on you, or issues?" |
| Turn a spec into an interactive HTML playground (refine before filing as Linear initiative or GitHub project) | `pm-spec` |
| Hand off work to a teammate or to the next lifecycle stage (recipient-facing brief, routed through Linear/GitHub/markdown/chat) | `pm-handoff` |
| Save / render / rerun reusable CLI command sequences (e.g., the daily Linear pull) | `pm-scripts` |
| **Autonomous, multi-step PM work** (file + review + enrich in one go) | `pm-agent` sub-agent |
| Report a bug / unexpected result / idea about the PM plugin itself to the maintainers | `pm-feedback` |

## Project config layout (v0.20.0+)

**All PM config lives in `<repo>/.claude/pm/` — one place.** Runtime state (cache, reports) stays in user-home because it's not config.

```
<repo>/.claude/pm/
├── project.json          # checked in — slug, displayName, issue_tracker, linear_*, spec_source, feedback_channel, handoff_channels
├── project.local.json    # gitignored — gh_user (+ any per-machine override)
├── conventions.md        # checked in — house style
└── templates/            # checked in — tag registry + body templates
    ├── _manifest.json
    └── <tag>.md

~/.claude/project-manager/    # NOT config — runtime state only
├── cache/<slug>/             # issue cache, context, snapshots
└── reports/<slug>/           # generated reports
```

The session-start hook reads `project.json` + `project.local.json` (merged, local-wins) and injects the active project context. Downstream skills (pm-issues, pm-branches, pm-handoff, pm-review, pm-improve) consult the in-repo config without any extra setup.

If `project.json` is missing → the project isn't registered; route to `/pm-setup`.
If `project.local.json` is missing → fine, the merge just uses shared values. The hook nudges the operator if multi-account `gh auth` is detected.

## Conventions awareness

If `<repo>/.claude/pm/conventions.md` exists, **load it before delegating to any state-changing skill** (pm-issues, pm-branches, pm-handoff, pm-review --apply, pm-improve --apply). The conventions override the plugin's baked-in defaults; pass the file's content to the downstream skill as ambient context so it can apply the rules.

If the file doesn't exist, the plugin runs with built-in defaults. That's a valid configuration.

To inspect: `/pm-conventions show`. To initialize: `/pm-conventions init` (or accept the prompt during `/pm-setup`).

## Project Context

The `pm-session-start` hook has already injected the active project context into this session. Refer to the **Active Project** section at the top of the system context for:
- Repo name and GitHub user
- Linear team key
- Current branch

## Linear Execution Mode (GraphQL via LINEAR_API_KEY)

As of v0.32, Linear I/O goes through the plugin's authored GraphQL wrappers — the `schpet/linear-cli` dependency is retired. Never call `linear issue create/update`, `linear api`, or raw GraphQL mutations directly.

- **Reads / sync:** `node "$CLAUDE_PLUGIN_ROOT/hooks/bin/pm-cache.js" <verb> --provider linear …` (full-sync, delta-sync, briefing, scope-briefing, etc.). Transport is direct fetch against `api.linear.app/graphql`.
- **Writes:** always route through `node "$CLAUDE_PLUGIN_ROOT/hooks/bin/pm-issue.js"` (create / update / relate) and the `pm-projects` create script. These wrappers resolve label / project / assignee names to UUIDs, enforce the create-gate, and avoid Linear's replace-semantics label-drop. Bypassing them reintroduces the bug class v0.32 fixed.
- **Auth:** `LINEAR_API_KEY` — from the environment, or `.claude/pm/project.local.json` (`linear_api_key`). Run `/pm-setup` to configure. No CLI install, no `linear auth login`, no `.linear.toml`.

## Proactive Issue Suggestion

When the user describes work they're about to do, check whether it maps to an open Linear issue. If not, proactively suggest:

> "I don't see a Linear issue for this. Want me to create one?"

Then use the `pm-issues` skill to draft it with the appropriate template.

## Proactive Work Tracking

At session start, evaluate the current branch and suggest appropriate actions:

### On main/master
The user is about to work without a feature branch. Before any code changes:
1. Ask what they're working on
2. Search Linear for a matching issue, or suggest creating one via `pm-issues`
3. Once an issue exists, suggest creating a branch via `pm-branches` (e.g., `feat/ENG-42-description`)

> "You're on main. Let's identify or create a Linear issue first, then set up a branch."

### On a feature branch without a Linear ID
The branch name doesn't contain a Linear issue ID (e.g., `feat/add-auth` instead of `feat/ENG-42-add-auth`):
- Ask if this work relates to an existing Linear issue
- If yes, note the association for session tracking
- If no, suggest creating one via `pm-issues`

> "This branch doesn't have a Linear ID. Is it related to an existing