@unbrained/pm-cli 2026.9.26 → 2026.9.28

package/plugins/pm-claude/README.md

@@ -7,12 +7,16 @@ Native pm CLI integration for Claude Code. Use pm project management tools direc
 | Component | What it provides |
 |-----------|----------------|
 | **32 MCP tools** | Full pm surface: discover, next, context, search, events, list, get, create, atomic mutate, copy, focus, update, claim, release, close, comments, files, docs, notes, learnings, deps, graph, test, validate, health, contracts, plan, append, schema, config, profile + `pm_run` for everything else |
-| **5 skills** | `pm-workflow`, `pm-developer`, `pm-release`, `pm-audit`, `pm-planner` — auto-loaded as Claude Code skills |
-| **14 slash commands** | Full lifecycle coverage — status, start, close, triage, audit, search, new, list, calendar, developer, planner, release, workflow, init |
+| **14 skills and slash invocations** | Full lifecycle coverage — status, start, close, triage, audit, search, new, list, calendar, developer, planner, release, workflow, init |
 | **4 subagents** | `pm-coordinator` (batch/multi-item), `pm-triage-agent` (duplicate-safe item creation), `pm-verification-agent` (evidence + close readiness), and `pm-delivery-chain` (orchestrated delivery) |
 | **Hybrid TUI tracking** | pm items sync to Claude Code's task panel — pm is the persistent store, the task panel is the live session view |
 | **Session hook** | Injects active pm item summary at session start using the same pinned pm-cli runtime as the MCP server |
 
+Five core workflow skills are generated from the shared portable source in
+`templates/agent-skills/`. Both plugin packages carry identical workflow
+guidance; the Claude task panel mapping is conditional on its tools.
+The other nine skills provide Claude-specific, directly invocable workflows.
+
 ## Installation
 
 ### Option A: Plugin marketplace — canonical install (recommended)
@@ -29,7 +33,7 @@ claude plugin marketplace add /path/to/pm-cli
 # claude plugin marketplace add unbraind/pm-cli
 ```
 
-This installs all 32 MCP tools, 5 skills, 14 slash commands, 4 subagents, hybrid TUI tracking, and the session hook in one step. (`pm-claude` is the plugin name; `pm` is the marketplace name from `marketplace.json`.)
+This installs all 32 MCP tools, 14 skills available through `/pm-*`, 4 subagents, hybrid TUI tracking, and the session hook in one step. (`pm-claude` is the plugin name; `pm` is the marketplace name from `.claude-plugin/marketplace.json`.)
 
 ### Option B: Global MCP server via Claude Code CLI (MCP tools only)
 
@@ -37,7 +41,7 @@ This installs all 32 MCP tools, 5 skills, 14 slash commands, 4 subagents, hybrid
 claude mcp add --transport stdio pm-mcp -- npx -y --package=@unbrained/pm-cli@latest pm-mcp
 ```
 
-This gives you the 32 MCP tools but not the skills, slash commands, or session hook.
+This gives you the 32 MCP tools but not the skills or session hook.
 
 ### Option C: Direct `.mcp.json` (project-scoped MCP only)
 
@@ -87,7 +91,7 @@ When you `/pm-start-task` or `/pm-developer`:
 
 This means you get full history in pm (survives restarts, visible in `pm list`) and live visual feedback in the Claude Code session.
 
-## Slash Commands
+## Skill Invocations
 
 | Command | What it does |
 |---------|-------------|
@@ -106,7 +110,7 @@ This means you get full history in pm (survives restarts, visible in `pm list`)
 | `/pm-workflow [id or description]` | General pm workflow loop with TUI tracking |
 | `/pm-init [project name]` | Initialize pm in the current project |
 
-## Skills
+## Core Skills
 
 | Skill | When Claude uses it |
 |-------|-------------------|
@@ -177,7 +181,7 @@ Spawn pm-triage-agent to set up the pm item for: add OAuth2 login support
 
 ## Hybrid TUI Sync Pattern
 
-All skills and commands implement this pattern for every claimed item:
+Claude commands can mirror claimed items with this pattern:
 
 ```
 1. pm_claim → [pm stores claim]

package/plugins/pm-claude/package.json

@@ -2,8 +2,8 @@
   "name": "pm-claude-runtime",
   "private": true,
   "type": "module",
-  "version": "2026.9.26",
+  "version": "2026.9.28",
   "dependencies": {
-    "@unbrained/pm-cli": "2026.9.26"
+    "@unbrained/pm-cli": "2026.9.28"
   }
 }

package/plugins/pm-claude/skills/pm-audit/SKILL.md

@@ -1,110 +1,21 @@
 ---
 name: pm-audit
-description: Audit pm-cli repositories with native pm MCP tools — health checks, validation, duplicate detection, aggregation, privacy review, and workflow health. Use when performing broad repository audits, release readiness checks, or agent-workflow health reviews.
+description: Use when asked to inspect pm tracker health, duplicate work, graph quality, privacy, or release readiness. Report verified findings and reuse existing lineage.
+license: MIT
 ---
 
-# pm Audit
+# pm Review
 
-Use for comprehensive repository audits, consistency reviews, and health diagnostics.
+Read the requested scope and the full live records behind any status claim.
+Use pm_health, pm_validate, pm_search, pm_graph, and pm_contracts as needed.
+Use pm_run for duplicate checks when no narrow tool covers them. Check omission
+receipts and follow cursors before reporting totals.
 
-## Audit Flow
+Classify each finding by its observable impact. Search all statuses before
+filing it and link it to its source with a meaningful typed relationship.
+Record exact commands and results on the canonical item. Keep credentials,
+private operational data, and raw meeting content out of public records.
 
-1. **Context snapshot** — `pm_context` with `depth: "standard"`.
-2. **Search for existing audits** — `pm_search` to avoid duplicate tracking.
-3. **Create or claim audit item** — then call `TaskCreate` to show in Claude Code's task panel.
-4. **Health check** — `pm_health` for tracker diagnostics.
-5. **Validation suite** — `pm_validate` with all checks enabled.
-6. **Aggregate** — `pm_run` with `action: "aggregate"` for governance view.
-8. **Calendar** — `pm_run` with `action: "calendar"` for deadline view.
-9. **Convert findings** — create pm items for each actionable finding.
-10. **Evidence** — `pm_comments` with verification summaries.
-11. **Close audit item** then `TaskUpdate(completed)`.
-
-## Hybrid TUI Sync
-
-After creating/claiming the audit tracking item:
-```
-TaskCreate:
-  subject: "[pm-xxxx] Audit: pm tracker health"
-  description: "Tracking full audit run — pm-xxxx"
-  activeForm: "Running pm audit"
-```
-Save the `taskId`. Call `TaskUpdate(in_progress)`.
-When closing: `TaskUpdate(completed)`.
-
-For each **finding item** created during the audit, also create a matching `TaskCreate` if you plan to work on it this session.
-
-## MCP Calls
-
-### Full Audit Suite
-```json
-{ "tool": "pm_context", "args": { "options": { "depth": "standard", "limit": "20" } } }
-{ "tool": "pm_health", "args": {} }
-{ "tool": "pm_validate", "args": { "options": { "checkResolution": true, "checkHistoryDrift": true, "checkFiles": true, "scanMode": "tracked-all" } } }
-{ "tool": "pm_run", "args": { "action": "aggregate", "options": { "groupBy": "status,type" } } }
-{ "tool": "pm_run", "args": { "action": "calendar", "options": { "view": "week", "format": "markdown", "include": "deadlines,reminders" } } }
-{ "tool": "pm_run", "args": { "action": "stats" } }
-```
-
-### Activity Review
-```json
-{ "tool": "pm_run", "args": { "action": "activity", "options": { "limit": "50" } } }
-```
-
-### Contracts and Schema Check
-```json
-{ "tool": "pm_contracts", "args": {} }
-```
-
-## Finding Classification
-
-| Severity | Action |
-|----------|--------|
-| Blocker | Create pm item with priority 0, status open |
-| Warning | Create pm item with priority 1 |
-| Info | Append to existing audit item comments |
-| No issue | Log as evidence in audit comments |
-
-## Evidence Format
-
-```json
-{
-  "tool": "pm_comments",
-  "args": {
-    "id": "pm-xxxx",
-    "options": {
-      "add": "Audit evidence: health=ok, validate=ok (2 warnings), dedupe=5 candidates, items=681, tests=1087 passing."
-    }
-  }
-}
-```
-
-## Privacy
-
-Keep sensitive operational data (telemetry credentials, user PII, internal endpoints) out of public docs and tracked comments. Use `pm notes` for sensitive context instead of `pm comments`.
-
-## Progressive Disclosure and Token Discipline
-
-Load the smallest thing that answers the question. Costs are measured.
-
-| Need | Call | Cost |
-|------|------|------|
-| Pick or resume work | `pm_next`, or `pm_context` with `limit: 10` | ~2.1-2.5k tok |
-| Exact flags for one command | `pm_contracts` with `command: "<name>", flagsOnly: true` | ~1-3.4k tok |
-| The whole command surface with per-command ceilings | `pm_contracts` with `summary: true` | ~2.6k tok |
-| An unfamiliar capability family | `pm_run` with `action: "guide", topic: "<topic>", depth: "brief"` | ~0.6-1k tok |
-
-Guide topics are declared at runtime: `pm guide` prints the current index and
-`pm guide <topic> --depth brief` expands one topic. Do not copy the list.
-
-Never load `docs/COMMANDS.md` (~29k tok) or `docs/SDK.md` (~45k tok) whole.
-
-Bound every read in this order: projection (`outputInclude`), then row limit
-(`outputLimit` or `limit`), then `outputBudget`, then `outputCursor` to resume.
-Read the `omission_receipt` before treating a result as complete — a
-budget-truncated read is a claim about the part it withheld, and a truncated
-list must never be summarized as if it were the whole population.
-
-Author identity is detected automatically. Never pass `author` and never set
-`PM_AUTHOR`; the harness, model, effort, role, and topic are probed and recorded
-on every history entry.
+An inspection does not imply permission to rewrite history or fabricate
+relationships. When asked to fix findings, claim only the work being changed
+and follow the pm-developer skill.

package/plugins/pm-claude/skills/pm-audit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "pm Review"
+  short_description: "Inspect tracker health and readiness"
+  default_prompt: "Review live pm health, quality, and release evidence; report verified findings."

package/plugins/pm-claude/{commands/pm-calendar.md → skills/pm-calendar/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+name: pm-calendar
 description: Show the pm calendar — upcoming deadlines, reminders, and scheduled events. Optionally pass a view like "week", "month", or a date range.
 ---
 

package/plugins/pm-claude/{commands/pm-close-task.md → skills/pm-close-task/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+name: pm-close-task
 description: Close a pm-tracked task with evidence — verify tests pass, link changed files, add closing comment, close and release in pm, then mark the Claude Code task panel entry as completed. Accepts an optional item ID as argument.
 ---
 

package/plugins/pm-claude/skills/pm-developer/SKILL.md

@@ -1,149 +1,26 @@
 ---
 name: pm-developer
-description: Run the pm-cli developer execution loop — orient, claim, implement, link evidence, verify, and close — with native MCP tools. Use when coding, debugging, refactoring, or shipping changes tracked in pm items.
+description: Use when implementing, debugging, refactoring, or shipping code, tests, or docs tracked by pm. Keep SDK behavior and verification linked to the active item.
+license: MIT
 ---
 
 # pm Developer
 
-Use this skill for implementation work that changes code, docs, tests, or release artifacts.
-
-## Canonical Execution Loop
-
-1. **Orient** — `pm_context` then `pm_search` for relevant existing items.
-2. **Decide** — reuse an existing item when one matches; create only when needed.
-3. **Claim** — `pm_claim` before any substantial edits.
-4. **Sync TUI** — call `TaskCreate` to mirror the pm item in Claude Code's task panel (see Hybrid TUI Sync).
-5. **Implement** — make the changes, link files/docs/tests as you go.
-6. **Verify** — run linked tests plus local quality gates.
-7. **Evidence** — `pm_comments` with what changed and what passed.
-8. **Close** — `pm_close` then `pm_release` then `TaskUpdate(completed)`.
-
-## Hybrid TUI Sync
-
-pm is the **persistent store**. Claude Code's task panel is the **live session view**.
-
-### After pm_claim (or pm_create when starting fresh)
-
-```
-TaskCreate:
-  subject: "[pm-xxxx] <item title>"
-  description: "Tracking pm item pm-xxxx. AC: <acceptance_criteria>"
-  activeForm: "Implementing pm-xxxx"
-```
-
-Save the returned `taskId`. Then:
-
-```
-TaskUpdate: { taskId: <saved>, status: "in_progress" }
-```
-
-### After pm_close + pm_release
-
-```
-TaskUpdate: { taskId: <saved>, status: "completed" }
-```
-
-## Step-by-Step MCP Calls
-
-### 1. Orient
-
-```json
-{ "tool": "pm_context", "args": { "options": { "limit": "10" } } }
-{ "tool": "pm_search", "args": { "query": "task keywords", "options": { "limit": "10" } } }
-```
-
-### 2. Claim
-
-```json
-{ "tool": "pm_claim", "args": { "id": "pm-xxxx" } }
-{ "tool": "pm_update", "args": { "id": "pm-xxxx", "options": { "status": "in_progress" } } }
-```
-
-Then immediately: `TaskCreate` → `TaskUpdate(in_progress)` as shown above.
-
-### 3. Link Evidence (during implementation)
-
-```json
-{ "tool": "pm_files", "args": { "id": "pm-xxxx", "options": { "add": ["path=src/file.ts,scope=project,note=implementation"] } } }
-{ "tool": "pm_docs", "args": { "id": "pm-xxxx", "options": { "add": ["path=docs/GUIDE.md,scope=project,note=updated"] } } }
-{ "tool": "pm_test", "args": { "id": "pm-xxxx", "options": { "add": ["command=node scripts/run-tests.mjs test -- tests/unit/foo.spec.ts,scope=project,timeout_seconds=240"] } } }
-```
-
-### 4. Validate
-
-```json
-{ "tool": "pm_validate", "args": { "options": { "checkResolution": true, "checkHistoryDrift": true } } }
-```
-
-### 5. Add Evidence Comment
-
-```json
-{ "tool": "pm_comments", "args": { "id": "pm-xxxx", "options": { "add": "Evidence: changed src/foo.ts. All tests pass. pm validate ok." } } }
-```
-
-### 6. Close
-
-```json
-{ "tool": "pm_close", "args": { "id": "pm-xxxx", "reason": "Implementation complete. Acceptance criteria met." } }
-{ "tool": "pm_release", "args": { "id": "pm-xxxx" } }
-```
-
-Then: `TaskUpdate: { taskId: <saved>, status: "completed" }`
-
-## Verification Defaults
-
-Run these before closing any implementation item:
-
-- `pnpm build` (or project build command)
-- `node scripts/run-tests.mjs test -- <target>` (targeted test)
-- `node scripts/run-tests.mjs coverage` (coverage gate)
-- `pm_validate` with `checkResolution: true`
-
-## Create When Needed
-
-When no existing item matches:
-
-```json
-{
-  "tool": "pm_create",
-  "args": {
-    "options": {
-      "title": "Fix: concise description of the problem",
-      "description": "Root cause and approach.",
-      "type": "Task",
-      "status": "open",
-      "priority": "1",
-      "tags": "relevant,tags",
-      "createMode": "progressive"
-    }
-  }
-}
-```
-
-Then call `TaskCreate` + `TaskUpdate(in_progress)` after claiming.
-
-## Progressive Disclosure and Token Discipline
-
-Load the smallest thing that answers the question. Costs are measured.
-
-| Need | Call | Cost |
-|------|------|------|
-| Pick or resume work | `pm_next`, or `pm_context` with `limit: 10` | ~2.1-2.5k tok |
-| Exact flags for one command | `pm_contracts` with `command: "<name>", flagsOnly: true` | ~1-3.4k tok |
-| The whole command surface with per-command ceilings | `pm_contracts` with `summary: true` | ~2.6k tok |
-| An unfamiliar capability family | `pm_run` with `action: "guide", topic: "<topic>", depth: "brief"` | ~0.6-1k tok |
-
-Guide topics are declared at runtime: `pm guide` prints the current index and
-`pm guide <topic> --depth brief` expands one topic. Do not copy the list.
-
-Never load `docs/COMMANDS.md` (~29k tok) or `docs/SDK.md` (~45k tok) whole.
-
-Bound every read in this order: projection (`outputInclude`), then row limit
-(`outputLimit` or `limit`), then `outputBudget`, then `outputCursor` to resume.
-Read the `omission_receipt` before treating a result as complete — a
-budget-truncated read is a claim about the part it withheld, and a truncated
-list must never be summarized as if it were the whole population.
-
-Author identity is detected automatically. Never pass `author` and never set
-`PM_AUTHOR`; the harness, model, effort, role, and topic are probed and recorded
-on every history entry.
+Orient with pm-workflow before editing. Claim the canonical item and keep its
+scope aligned with the change.
+
+1. Read the complete source owner and relevant tests before editing. For a
+   regression, identify the observable contract and the change that would
+   make its test fail.
+2. Put domain behavior in the public pm SDK. Keep CLI and MCP adapters thin,
+   with transport-specific tests only where those boundaries add risk.
+3. Link changed files, docs, and isolated runnable tests through pm_files,
+   pm_docs, and pm_test.
+4. Run the focused test, build, full coverage, static quality, and installed
+   consumer checks required by the affected contract. Keep tracker test roots
+   separate from the real repository.
+5. Record exact results in pm_comments. Close with structured resolution,
+   expected, and actual fields only when the criteria are actually met.
+
+Prefer pm_contracts for flags and the SDK public surface for integration APIs.
+An unknown review provider or missing check is not approval.

package/plugins/pm-claude/skills/pm-developer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "pm Developer"
+  short_description: "Deliver code with linked pm evidence"
+  default_prompt: "Use pm to claim, implement, verify, document, and close this repository change."

package/plugins/pm-claude/{commands/pm-init.md → skills/pm-init/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+name: pm-init
 description: Initialize pm in the current project — creates the .agents/pm/ tracker directory, sets up default settings, and shows a quick-start summary. Accepts an optional project name as argument.
 ---
 
@@ -46,7 +47,7 @@ Initialize pm project tracking using native MCP tools. Argument: `$ARGUMENTS` (o
    - pm initialized at `.agents/pm/`
    - guidance mode defaults to `ask` (TTY prompt only); use `agentGuidance=add|skip|status` in `pm_run` options for deterministic behavior
    - Available slash commands: `/pm-status`, `/pm-new`, `/pm-start-task`, `/pm-close-task`, `/pm-list`, `/pm-search`, `/pm-triage`, `/pm-calendar`, `/pm-developer`, `/pm-planner`, `/pm-release`, `/pm-audit`, `/pm-workflow`
-   - All 30 MCP tools available: `pm_next`, `pm_context`, `pm_search`, `pm_list`, `pm_get`, `pm_create`, `pm_mutate`, `pm_copy`, `pm_focus`, `pm_update`, `pm_append`, `pm_claim`, `pm_release`, `pm_close`, `pm_comments`, `pm_files`, `pm_docs`, `pm_notes`, `pm_learnings`, `pm_deps`, `pm_graph`, `pm_test`, `pm_validate`, `pm_health`, `pm_contracts`, `pm_schema`, `pm_config`, `pm_profile`, `pm_plan`, `pm_run`
+   - Use `pm_discover` to inspect the current MCP tool catalog and `pm_contracts` for exact command flags. The catalog is currently 32 tools.
    - Next: use `/pm-new <title>` to create your first item, or `/pm-status` to see the tracker state
 
 If initialization fails, report the error and suggest running `pm init` manually in the terminal.

package/plugins/pm-claude/{commands/pm-list.md → skills/pm-list/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+name: pm-list
 description: List pm items with optional status or type filter. Pass a filter like "open", "in_progress", "blocked", "bugs", or leave empty for active items.
 ---
 
@@ -23,7 +24,7 @@ List pm items using native MCP tools. Filter: `$ARGUMENTS`
      }
    }
    ```
-   For `all`, use `pm_list` with no status filter.
+   For `all`, use `pm_list` with `status: "all"` so closed and canceled items are included.
 
 3. **If filter is empty** (active items) — also call `pm_context` for a richer summary:
    ```json

package/plugins/pm-claude/{commands/pm-new.md → skills/pm-new/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+name: pm-new
 description: Quickly create a new pm item — duplicate-checks first, then creates with sensible defaults. Pass a title (or title + description) as argument.
 ---
 

package/plugins/pm-claude/skills/pm-planner/SKILL.md

@@ -1,173 +1,22 @@
 ---
 name: pm-planner
-description: Plan and organize pm CLI work — triage requests, break epics into tasks, prioritize the backlog, and keep the tracker clean. Use when decomposing features, planning sprints, or organizing incoming requests.
+description: Use when triaging requests, organizing a backlog, decomposing an epic, or making a durable pm plan. Search all statuses and build evidence-backed typed relationships.
+license: MIT
 ---
 
 # pm Planner
 
-Use this skill when decomposing features, organizing backlogs, triaging incoming work, or planning multi-item projects.
-
-## Planning Loop
-
-1. **Survey** — `pm_context` then `pm_list` with no filter to see the full active backlog.
-2. **Deduplicate** — `pm_search` before every create to avoid duplicate items.
-3. **Decompose** — break large items into Epic → Feature → Task hierarchy.
-4. **Prioritize** — use `pm_update` to set priority (`0`=critical … `4`=minimal).
-5. **Link parents** — always set `parent` on child items via `pm_update`.
-6. **Sync TUI** — call `TaskCreate` for any item you claim during this session (see Hybrid TUI Sync).
-7. **Validate** — `pm_validate` after batch creates to check consistency.
-
-## Hybrid TUI Sync
-
-pm is the **persistent store**. Claude Code's task panel is the **live session view**.
-
-When you claim a planning item or start active decomposition work:
-```
-TaskCreate:
-  subject: "[pm-xxxx] Plan: <epic/feature title>"
-  description: "Planning pm-xxxx — decomposing into child items"
-  activeForm: "Planning pm-xxxx"
-```
-Save the `taskId`. Call `TaskUpdate(in_progress)` when active.
-Call `TaskUpdate(completed)` when the planning item is closed.
-
-## MCP Call Patterns
-
-### Survey the Backlog
-```json
-{ "tool": "pm_context", "args": { "options": { "depth": "standard", "limit": "20" } } }
-{ "tool": "pm_list", "args": { "options": { "limit": "50" } } }
-```
-
-### Deduplicate Before Creating
-```json
-{ "tool": "pm_search", "args": { "query": "feature keywords", "options": { "limit": "10" } } }
-```
-
-### Create Epic → Feature → Task Hierarchy
-```json
-{
-  "tool": "pm_create",
-  "args": {
-    "options": {
-      "title": "Epic: Authentication system overhaul",
-      "type": "Epic",
-      "status": "open",
-      "priority": "1",
-      "description": "High-level initiative description.",
-      "createMode": "progressive"
-    }
-  }
-}
-```
-Then for each child feature/task, set `parent: "pm-xxxx"` via `pm_update`.
-
-### Prioritize the Backlog
-
-```json
-{ "tool": "pm_list", "args": { "options": { "status": "open", "limit": "30" } } }
-{ "tool": "pm_update", "args": { "id": "pm-xxxx", "options": { "priority": "0" } } }
-```
-
-### Link Parent
-
-```json
-{ "tool": "pm_update", "args": { "id": "pm-child", "options": { "parent": "pm-epic" } } }
-```
-
-### Run Dedupe Audit After Batch Work
-
-```json
-```
-
-### Validate After Batch Creates
-
-```json
-{ "tool": "pm_validate", "args": { "options": { "checkResolution": true } } }
-```
-
-## Item Type Guide
-
-| Type | When to use |
-|------|------------|
-| `Epic` | Large initiative spanning multiple features (weeks/months) |
-| `Feature` | Distinct capability under an epic (days) |
-| `Task` | Atomic unit of implementation work (hours) |
-| `Bug` | Defect with reproduce steps |
-| `Story` | User-facing narrative unit |
-
-## Priority Reference
-
-- `0` = critical — blocking release or other work
-- `1` = high — important, should be done soon
-- `2` = normal — standard priority (default)
-- `3` = low — nice to have
-- `4` = minimal — defer unless time allows
-
-## Acceptance Criteria Best Practice
-
-Write AC as numbered, testable assertions:
-1. Given [precondition], when [action], then [result].
-2. All existing tests pass.
-3. Coverage gate maintained.
-
-Set via `pm_create` with `acceptanceCriteria` field or `pm_update` with `options.acceptanceCriteria`.
-
-## Built-in Plan workflow (`pm_plan` / `pm plan`)
-
-For durable Codex-style ExecPlans, Claude-style Plan Mode, and Cursor-style editable checklists, pm exposes a first-class `Plan` item type plus a `pm plan` command family. Use [Command Reference: Plan Workflow](../../../../docs/COMMANDS.md#plan-workflow) as the canonical lifecycle recipe; this skill keeps only Claude-specific routing notes.
-
-### When to use `pm plan` vs. `pm_create` + tasks
-
-- `pm plan` — when you need a **living, resumable plan** with ordered steps, evidence, decisions, discoveries, validation, and the option to later materialize selected steps as real Tasks. Best for plan-then-execute workflows.
-- `pm_create` (Epic/Feature/Task) — when the work is already decomposed and you just need persistent backlog items.
-
-### Claude MCP routing
-
-Call the same lifecycle through the `pm_plan` MCP tool. Use `harness: "claude-code"` on creation, `subcommand: "show"` with `depth: "brief"` for low-token reads, and `subcommand: "resume"` after compaction or handoff.
-
-### Harness mapping cheatsheet
-
-| Harness signal | pm_plan equivalent |
-|----------------|--------------------|
-| Codex `update_plan` step status | `subcommand=update-step` with `stepStatus` |
-| Claude `TaskCreate` | `subcommand=add-step` |
-| Claude `TaskUpdate(in_progress)` | `subcommand=update-step` with `stepStatus=in_progress` |
-| Cursor edit a plan step | `subcommand=update-step` |
-| Resume after compaction | `subcommand=resume` with `resumeContext` then `subcommand=show --depth deep` |
-| Approve before edits | `subcommand=approve` |
-| Convert checklist into real items | `subcommand=materialize` |
-
-## Safety
-
-- Never pass `path` during real repository tracking.
-- Always `pm_search` before `pm_create`/`pm plan create` — avoid duplicates.
-- Run `pm_validate` after batch changes.
-- Set exactly one step `in_progress` per plan; pass `allowMultipleActive: true` only for explicit parallel branches.
-- Use `pm_plan` `subcommand=resume` after long-running sessions so the next agent can pick up with a deterministic context.
-
-## Progressive Disclosure and Token Discipline
-
-Load the smallest thing that answers the question. Costs are measured.
-
-| Need | Call | Cost |
-|------|------|------|
-| Pick or resume work | `pm_next`, or `pm_context` with `limit: 10` | ~2.1-2.5k tok |
-| Exact flags for one command | `pm_contracts` with `command: "<name>", flagsOnly: true` | ~1-3.4k tok |
-| The whole command surface with per-command ceilings | `pm_contracts` with `summary: true` | ~2.6k tok |
-| An unfamiliar capability family | `pm_run` with `action: "guide", topic: "<topic>", depth: "brief"` | ~0.6-1k tok |
-
-Guide topics are declared at runtime: `pm guide` prints the current index and
-`pm guide <topic> --depth brief` expands one topic. Do not copy the list.
-
-Never load `docs/COMMANDS.md` (~29k tok) or `docs/SDK.md` (~45k tok) whole.
-
-Bound every read in this order: projection (`outputInclude`), then row limit
-(`outputLimit` or `limit`), then `outputBudget`, then `outputCursor` to resume.
-Read the `omission_receipt` before treating a result as complete — a
-budget-truncated read is a claim about the part it withheld, and a truncated
-list must never be summarized as if it were the whole population.
-
-Author identity is detected automatically. Never pass `author` and never set
-`PM_AUTHOR`; the harness, model, effort, role, and topic are probed and recorded
-on every history entry.
+1. Read pm_context and the relevant parent or outcome milestone.
+2. Search all statuses and inspect nearest matches before creating anything.
+3. Use a Plan when ordered steps, decisions, discoveries, and handoff must
+   remain resumable. Use Epic, Feature, Task, Issue, and Decision items for
+   durable backlog work with different ownership.
+4. Give new work a parent, testable acceptance criteria, expected result, and
+   a create-time duplicate-check explanation.
+5. Add typed edges only when evidence supports their meaning. Use dependency
+   edges for ordering and verification edges for proof; do not invent graph
+   depth or fill the graph with related edges.
+6. Validate the resulting tracker and summarize the next actionable items.
+
+Use pm_plan for a living plan and pm_contracts to discover exact options.
+Keep one plan step in progress unless parallel work is explicitly intended.

package/plugins/pm-claude/skills/pm-planner/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "pm Planner"
+  short_description: "Plan and connect project work"
+  default_prompt: "Use pm to deduplicate this request, plan its work, and link it to the project outcome."