@unbrained/pm-cli 2026.9.25 → 2026.9.27

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

@@ -1,170 +1,39 @@
 ---
 name: pm-workflow
-description: Use pm CLI natively in Claude Code through MCP tools for planning, tracking, mutation, validation, and reporting. Use this skill whenever work should be tracked through pm — before implementing, during implementation, and at close.
+description: Use when starting, resuming, or handing off work in a repository managed by pm. Orient from live context, reuse existing items, and leave evidence for the next agent.
+license: MIT
 ---
 
 # pm Workflow
 
-Use this skill for all pm-tracked work. Prefer native MCP tools over shell `pm` commands.
+Project management is context management. Read the live tracker before describing
+work as open, blocked, or done. Use the bundled pm MCP tools when available;
+use the pm CLI with the same contracts when they are not.
 
-## Tool Preference
+## Orient
 
-**Always use native MCP tools before falling back to Bash `pm` commands:**
+1. Read pm_context with a bounded limit, then pm_list for open and in-progress work.
+2. Search all statuses before creating an item. Inspect the candidate's full
+   metadata, comments, notes, learnings, dependencies, and history.
+3. Follow omission receipts and cursors before making a completeness claim.
+4. Cross-check release, CI, package, or infrastructure claims against the live
+   system that owns them.
 
-| Purpose | Tool |
-|---------|------|
-| Orient / read state | `pm_context`, `pm_search`, `pm_list`, `pm_get` |
-| Create / update | `pm_create`, `pm_update`, `pm_claim`, `pm_release`, `pm_close` |
-| Evidence | `pm_comments`, `pm_notes`, `pm_learnings`, `pm_files`, `pm_docs`, `pm_test` |
-| Verify | `pm_validate`, `pm_health`, `pm_contracts` |
-| Everything else | `pm_run` with an explicit `action` |
+## Work and hand off
 
-## Required Workflow Loop
+Claim only an item being actively edited. Link files, docs, tests, and typed
+relationships that express a real dependency or outcome. Record concise
+evidence, then close with resolution, expected, and actual results when the
+acceptance criteria are met. Release the claim when stopping.
 
-1. **Orient** — run `pm_context`, `pm_search`, and `pm_list` before creating new work.
-2. **Reuse** — claim an existing item when one matches instead of creating a duplicate.
-3. **Claim** — call `pm_claim` before substantial edits.
-4. **Sync TUI** — after claiming, call `TaskCreate` to mirror the item in Claude Code's task panel (see Hybrid TUI Sync below).
-5. **Link evidence** — call `pm_files`, `pm_docs`, `pm_test` as work progresses.
-6. **Add comments** — `pm_comments` for progress notes and verification results.
-7. **Verify** — run `pm_validate` and project tests before closing.
-8. **Close** — `pm_close` with reason, then `pm_release`, then `TaskUpdate(completed)`.
+For handoff, report the item IDs, exact current status, last verified result,
+remaining work, and the next read command. Do not copy the entire tracker.
 
-## Hybrid TUI Sync
+## Host adapters
 
-pm is the **persistent store** (cross-session). Claude Code's task panel is the **live session view**.
+In Claude Code, mirror a claimed item in the task panel when TaskCreate and
+TaskUpdate are available. Keep pm as the durable source of truth. In Codex,
+use the native MCP tools and the same claim, evidence, close, and release loop.
 
-### When claiming or creating an item
-
-Call `TaskCreate` immediately after `pm_claim` (or after `pm_create` if starting fresh):
-
-```
-TaskCreate:
-  subject: "[pm-xxxx] <item title>"
-  description: "Tracking pm item pm-xxxx. AC: <acceptance_criteria if set>"
-  activeForm: "Implementing pm-xxxx"
-```
-
-Save the returned `taskId` — you'll need it for `TaskUpdate` calls later in this session.
-
-### When setting in_progress
-
-Call `TaskUpdate` with `status: "in_progress"` using the `taskId` from above.
-
-### When closing
-
-Call `pm_close` then `pm_release`, then immediately call:
-```
-TaskUpdate:
-  taskId: <saved taskId>
-  status: "completed"
-```
-
-### Blocked items
-
-If a pm item becomes blocked, call `TaskUpdate` with `status: "in_progress"` and add "(BLOCKED)" to the subject so it's visible in the panel.
-
-## Tool Call Shape
-
-Most tools accept `cwd`, `author`, and `options`:
-
-```json
-{
-  "cwd": "/path/to/repo",
-  "options": { "limit": "10" }
-}
-```
-
-`pm_run` requires an `action` field:
-
-```json
-{
-  "action": "calendar",
-  "options": { "view": "week", "format": "markdown" }
-}
-```
-
-## Common Patterns
-
-**Get active work snapshot:**
-```json
-{ "tool": "pm_context", "args": { "options": { "limit": "10" } } }
-```
-
-**Search for existing work:**
-```json
-{ "tool": "pm_search", "args": { "query": "your keywords", "options": { "limit": "10" } } }
-```
-
-**Create a new item:**
-```json
-{
-  "tool": "pm_create",
-  "args": {
-    "options": {
-      "title": "Item title",
-      "description": "What this item tracks.",
-      "type": "Task",
-      "status": "open",
-      "priority": "1",
-      "createMode": "progressive"
-    }
-  }
-}
-```
-
-**Link changed files:**
-```json
-{
-  "tool": "pm_files",
-  "args": {
-    "id": "pm-xxxx",
-    "options": { "add": ["path=src/file.ts,scope=project,note=implementation"] }
-  }
-}
-```
-
-**Close with evidence:**
-```json
-{
-  "tool": "pm_close",
-  "args": {
-    "id": "pm-xxxx",
-    "reason": "All acceptance criteria met. Tests pass."
-  }
-}
-```
-
-## Priority Reference
-
-- `0` = critical, `1` = high, `2` = normal, `3` = low, `4` = minimal
-
-## Safety
-
-Do not pass `path` during real repository tracking. Only pass `path` for sandbox/test runs.
-
-## 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.
+Use pm_contracts for exact active flags and pm_run for actions without a narrow
+tool. Never set a static author; let the host identity be detected.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "pm Workflow"
+  short_description: "Orient and hand off tracked project work"
+  default_prompt: "Use pm to read live context, select existing work, and leave a concise evidence-backed handoff."

package/plugins/pm-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pm-codex",
-  "version": "2026.9.25",
+  "version": "2026.9.27",
   "description": "Native Codex integration for pm-cli with bundled MCP tools, skills, commands, and agent workflows.",
   "author": {
     "name": "unbrained",

package/plugins/pm-codex/README.md

@@ -3,10 +3,18 @@
 This plugin packages pm-cli for Codex with:
 
 - a native stdio MCP server (`pm-mcp`) backed by pm command modules, not shell `pm` invocations
-- skills for developer, user, extension, SDK, release, and audit workflows
+- five portable skills for orientation, implementation, planning, review, and release
 - command prompts for common planning and verification loops
 - repo marketplace metadata for one-step local installation in Codex
 
+The root `plugin.json` and typed `mcp.json` are the portable package entrypoints.
+The `.codex-plugin/plugin.json` and `.mcp.json` files support existing hosts.
+Both MCP configurations start the same pinned launcher. The five shared skills are generated with the Claude package from
+`templates/agent-skills/`. The older `pm-native` and `pm-auditor` entrypoints
+are generated compatibility skills that route to `pm-workflow`, `pm-planner`,
+and `pm-audit`. `node scripts/gen-agent-plugin-skills.mjs --check` guards all
+published copies against drift.
+
 ## Install
 
 From this repository:
@@ -24,7 +32,7 @@ The launcher uses the local repo build when present. In a copied plugin cache it
 Prefer the narrow tools when they match the task: `pm_context`, `pm_search`, `pm_list`, `pm_get`, `pm_create`, `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_test`, `pm_validate`, `pm_health`, `pm_contracts`, `pm_schema`, `pm_config`, and `pm_plan`.
 
 
-`pm_plan` exposes Codex-style ExecPlans as a first-class `Plan` item type with ordered steps, evidence, decisions, discoveries, validation, and materialization. See the `pm-native` skill for the full Plan workflow recipe.
+`pm_plan` exposes Codex-style ExecPlans as a first-class `Plan` item type with ordered steps, evidence, decisions, discoveries, validation, and materialization. See the `pm-planner` skill for the planning workflow.
 For `init` automation, pass `options.agentGuidance` (`ask|add|skip|status`) when you need deterministic AGENTS/CLAUDE guidance behavior in non-interactive runs.
 
 ## Safety

package/plugins/pm-codex/mcp.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "pm-mcp": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["./scripts/pm-mcp-server.mjs"],
+      "cwd": "./"
+    }
+  }
+}

package/plugins/pm-codex/package.json

@@ -2,8 +2,8 @@
   "name": "pm-codex-runtime",
   "private": true,
   "type": "module",
-  "version": "2026.9.25",
+  "version": "2026.9.27",
   "dependencies": {
-    "@unbrained/pm-cli": "2026.9.25"
+    "@unbrained/pm-cli": "2026.9.27"
   }
 }

package/plugins/pm-codex/plugin.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "pm-codex",
+  "version": "2026.9.27",
+  "description": "Repository-native project context workflows and a version-pinned pm MCP server for Codex.",
+  "author": {
+    "name": "unbrained",
+    "url": "https://github.com/unbraind/pm-cli"
+  },
+  "homepage": "https://github.com/unbraind/pm-cli/tree/main/plugins/pm-codex",
+  "repository": "https://github.com/unbraind/pm-cli",
+  "license": "MIT",
+  "keywords": [
+    "pm-cli",
+    "codex",
+    "mcp",
+    "project-management",
+    "agents"
+  ],
+  "extensions": {
+    "com.openai": {
+      "interface": {
+        "displayName": "pm CLI",
+        "shortDescription": "Track project context with pm",
+        "longDescription": "Orient, plan, implement, verify, and hand off work with repository-native pm records and a bundled MCP server.",
+        "developerName": "unbrained",
+        "category": "Coding",
+        "capabilities": [
+          "Interactive",
+          "Read",
+          "Write"
+        ],
+        "websiteURL": "https://github.com/unbraind/pm-cli",
+        "privacyPolicyURL": "https://github.com/unbraind/pm-cli/blob/main/SECURITY.md",
+        "termsOfServiceURL": "https://github.com/unbraind/pm-cli/blob/main/LICENSE",
+        "defaultPrompt": [
+          "Use pm to orient, track, verify, and hand off this repository task."
+        ],
+        "composerIcon": "./assets/pm-cli-small.svg",
+        "logo": "./assets/pm-cli-small.svg",
+        "brandColor": "#2563EB"
+      }
+    }
+  }
+}

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

@@ -0,0 +1,21 @@
+---
+name: pm-audit
+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 Review
+
+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.
+
+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.
+
+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-codex/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-codex/skills/pm-auditor/SKILL.md

@@ -1,46 +1,11 @@
 ---
 name: pm-auditor
-description: Audit pm-cli repositories with native pm MCP tools, preserving duplicate checks, privacy boundaries, linked evidence, and verification records.
+description: Use only when an existing Codex workflow explicitly invokes pm-auditor. This compatibility skill routes to the canonical pm-audit review skill.
 license: MIT
 ---
 
-# pm Auditor
+# pm Auditor Compatibility
 
-Use for broad repository audits, release readiness checks, privacy reviews, and agent-workflow health checks.
-
-## Audit Flow
-
-1. Use `pm_context` with standard or deep options.
-2. Use `pm_search` for likely existing audit or release items.
-4. Convert each actionable finding into a pm item or append evidence to an existing item.
-5. Keep sensitive operational data out of public docs and tracked comments.
-
-## Evidence
-
-Record exact verification commands and summarized results through `pm_comments`, and link touched files through `pm_files`.
-
-## 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.
+Use pm-audit for live tracker health, duplicate, graph, privacy, and release
+readiness reviews. Read full records and omission receipts before making a
+status claim. Reuse existing lineage for each verified finding.

package/plugins/pm-codex/skills/pm-auditor/agents/openai.yaml

@@ -1,6 +1,4 @@
 interface:
-  display_name: "pm Auditor"
-  short_description: "Audit pm health, contracts, privacy, and readiness"
-  icon_small: "./assets/pm-cli-small.svg"
-  icon_large: "./assets/pm-cli-small.svg"
-  default_prompt: "Audit this pm repository with native pm tools, dedupe findings, link evidence, and avoid leaking private data."
+  display_name: "pm Auditor Compatibility"
+  short_description: "Route older reviews to the current pm review skill"
+  default_prompt: "Review this tracker using the canonical pm-audit guidance."

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

@@ -0,0 +1,26 @@
+---
+name: pm-developer
+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
+
+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-codex/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-codex/skills/pm-native/SKILL.md

@@ -1,94 +1,14 @@
 ---
 name: pm-native
-description: Use pm-cli natively in Codex through bundled MCP tools for planning, tracking, mutation, validation, and reporting without invoking the pm shell command.
+description: Use only when an existing Codex workflow explicitly invokes pm-native. This compatibility skill routes to the canonical pm-workflow and pm-planner skills.
 license: MIT
 ---
 
-# pm Native Workflow
+# pm Native Compatibility
 
-Use this skill whenever a Codex task should be tracked through pm.
+Use pm-workflow for orientation, claim, evidence, and handoff. Use pm-planner
+for durable Plan steps. The native pm MCP server exposes the same public SDK
+contracts in both workflows.
 
-## Tool Preference
-
-Use MCP tools before shell commands:
-
-- Orient: `pm_context`, `pm_search`, `pm_list`, `pm_get`
-- Mutate: `pm_create`, `pm_update`, `pm_claim`, `pm_release`, `pm_close`
-- Evidence: `pm_comments`, `pm_notes`, `pm_learnings`, `pm_files`, `pm_docs`, `pm_test`
-- Verify: `pm_validate`, `pm_health`, `pm_contracts`
-- Everything else: `pm_run` with an explicit `action`
-
-Do not pass `path` during real repository work. For tests, pass a sandbox `cwd` or `path`.
-
-## Required Loop
-
-1. Run `pm_context`, `pm_search`, and `pm_list` before creating work.
-2. Reuse an existing item when one matches.
-3. Claim the item with `pm_claim`.
-4. Link changed files/docs/tests as work proceeds.
-5. Add concise evidence with `pm_comments`.
-6. Run linked and project verification.
-7. Close with `pm_close` and release with `pm_release`.
-
-## Native Argument Shape
-
-Most tools accept:
-
-```json
-{
-  "cwd": "/repo/root",
-  "options": {
-    "limit": "10"
-  }
-}
-```
-
-`pm_run` accepts an `action` plus `options`:
-
-```json
-{
-  "action": "calendar",
-  "options": {
-    "view": "week",
-    "format": "markdown"
-  }
-}
-```
-
-## Plan workflow (`pm_plan`)
-
-Codex-style living ExecPlans are first-class via the `Plan` item type and the `pm_plan` MCP tool. Use [Command Reference: Plan Workflow](../../../../docs/COMMANDS.md#plan-workflow) as the canonical lifecycle recipe; this skill keeps only Codex-specific routing notes.
-
-Use `pm_plan` for plan-then-execute workflows; use `pm_create` with type Task/Feature/Epic for already-decomposed backlog work.
-
-Invariants:
-
-- One step `in_progress` at a time by default; pass `allowMultipleActive: true` for explicit parallel branches.
-- Use `subcommand: block-step` with `stepBlockedReason` when discovery flips a step.
-- Use `subcommand: materialize` once steps are concrete enough to become Tasks.
-
-## 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.
+Read live pm_context and pm_search before creating or mutating items. Claim
+only active work, preserve linked evidence, and release the claim when done.

package/plugins/pm-codex/skills/pm-native/agents/openai.yaml

@@ -1,6 +1,4 @@
 interface:
-  display_name: "pm Native"
-  short_description: "Track Codex work through native pm MCP tools"
-  icon_small: "./assets/pm-cli-small.svg"
-  icon_large: "./assets/pm-cli-small.svg"
-  default_prompt: "Use native pm tools to orient, claim, implement, verify, and close this task without shelling out to pm."
+  display_name: "pm Native Compatibility"
+  short_description: "Route older Codex workflows to current pm skills"
+  default_prompt: "Continue this older pm-native workflow with the canonical pm-workflow and pm-planner guidance."

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

@@ -0,0 +1,22 @@
+---
+name: pm-planner
+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
+
+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-codex/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."

package/plugins/pm-codex/skills/pm-release/SKILL.md

@@ -1,45 +1,24 @@
 ---
 name: pm-release
-description: Run compatibility-gated pm-cli release workflows with native pm tools, linked evidence, and public-surface verification.
+description: Use when preparing a pm release, reviewing its gates, publishing, or verifying the released artifact. Keep source, reviewed head, main, tag, registry, and telemetry evidence distinct.
 license: MIT
 ---
 
 # pm Release
 
-Use for release prep, compatibility gates, publication checks, and post-release verification.
-
-## Release Loop
-
-1. Find or create the release item after duplicate checks.
-2. Claim it and link release docs, changelog, compatibility scripts, and tests.
-3. Run sandboxed compatibility checks before changing release assets.
-4. Run full local gates before tagging or publishing.
-5. Verify public surfaces after publish and record results through `pm_comments`.
-
-Use `pm_run` for release-adjacent pm actions not exposed as narrow tools.
-
-## 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.
+Inspect the release item and current release position before mutation. Search
+for an existing release or incident lineage and reuse it.
+
+1. Link the changed files, changelog, compatibility evidence, and release
+   tests to the item that owns them.
+2. Run the build, full coverage, static quality, security, docs, package,
+   version, and hosted analysis gates required by the repository.
+3. Verify the exact reviewed PR head and resolve actionable feedback before
+   merging. A silent or quota-limited provider is unavailable evidence.
+4. After publishing, verify the main commit, tag, GitHub Release, npm
+   package, installed npm and Bun consumers, Sentry, and telemetry separately.
+5. Record immutable close evidence and release the claim.
+
+Use the repository release pipeline and pm_contracts rather than a remembered
+flag spelling. Never assume a successful API request proves a scheduled
+release or physical telemetry delivery.