| name | project-manager |
| description | Use this skill when the user says "project manager", "pm", "where are we", "what's in progress", "what should I work on next", "project status", "open issues", "what's next", "track this work", "review this issue", "improve this issue", "what are our conventions", "create a project", "plan this project", "project health", or asks about Linear issues, GitHub issues, GitHub PRs, or any issue tracking for the current project. Also use proactively when the user describes work that doesn't appear to be tracked, when starting new work on main/master, when branch naming suggests untracked work, or when the user has a spec they're about to file as a Linear initiative or GitHub project. Routes to focused pm-* skills (status, issues, templates, review, improve, conventions, branches, report, spec, handoff, setup, projects) based on the task. For autonomous multi-step work, delegate to the `pm-agent` sub-agent. |
| version | 0.44.4 |
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:
- Ask what they're working on
- Search Linear for a matching issue, or suggest creating one via
pm-issues
- 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 issue?"
On a properly named feature branch
The branch contains a Linear ID (e.g., feat/ENG-42-auth-middleware):
- Confirm the active issue: "Working on ENG-42"
- No further prompting needed — the session-end hook will track progress automatically
Project-level routing
Project skills operate on a project (a Linear Project / GitHub Milestone), not an individual issue. Phrasing discriminator: "project" vs "issue" (and ID shape — ENG-42 is an issue; project IDs are slug or workspace name).
| Task | Skill to use |
|---|
| Create / update / closeout a project | pm-projects |
| Resolve / list / register a project-type template | pm-project-templates |
| Review a project against its type template | pm-project-review |
| Enrich a project with context, related work, references | pm-project-improve |
| Decompose a project into milestones + draft constituent issues | pm-project-plan |
| Project health / "is this project on track" | pm-report --profile project-health |
| Ambiguous ("review this", "improve this") | Ask — issue or project? Do not guess |
