@unbrained/pm-cli 2026.9.26 → 2026.9.28

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.

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

@@ -1,6 +1,4 @@
 interface:
   display_name: "pm Release"
-  short_description: "Run pm release workflows with linked evidence"
-  icon_small: "./assets/pm-cli-small.svg"
-  icon_large: "./assets/pm-cli-small.svg"
-  default_prompt: "Use native pm tools to prepare, gate, publish-check, and document this pm-cli release."
+  short_description: "Verify release gates and artifacts"
+  default_prompt: "Use pm to prepare, gate, and verify this release with distinct source and published evidence."

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

@@ -0,0 +1,39 @@
+---
+name: pm-workflow
+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
+
+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.
+
+## Orient
+
+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.
+
+## Work and hand off
+
+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.
+
+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.
+
+## Host adapters
+
+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.
+
+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-codex/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."