@unbrained/pm-cli 2026.9.26 → 2026.9.27

package/docs/generated/REFUSAL_CLOSURE_CENSUS.md

@@ -4,14 +4,14 @@ Tracker: `pm-f05lsg`.
 
 Every catalog code is listed. An `uncovered` row is an explicit closure obligation, never an omission or implied approval.
 
-- Catalog error codes: 378
+- Catalog error codes: 385
 - Executable error codes: 19
 - Executable-code ratchet floor: 18
 - Required executable canonical codes: `bulk_ids_input_empty`, `bulk_ids_input_missing_path`, `bulk_ids_input_unreadable`, `invalid_argument_value`, `manifest_unknown_key`, `missing_lifecycle_target`, `missing_required_argument`, `no_version_bounds_declared`, `projection_options_mutually_exclusive`, `tracker_not_initialized`, `tracker_root_missing`, `tracker_root_not_directory`, `tracker_root_unreadable`, `unknown_context_intent`, `unknown_field_projection`, `unknown_option`, `unknown_subcommand`
-- Uncovered error codes: 359
-- Coverage fraction: 0.050265
+- Uncovered error codes: 366
+- Coverage fraction: 0.049351
 - Closed-domain probes: 19
-- Grammar probes: 113
+- Grammar probes: 117
 
 | Error code | Canonical code | Disposition | Evidence kinds | Probe count |
 | --- | --- | --- | --- | --- |
@@ -96,6 +96,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `extension_mutation_guard_invalid_denial` | `extension_mutation_guard_invalid_denial` | uncovered | none | 0 |
 | `extension_mutation_guard_timed_out` | `extension_mutation_guard_timed_out` | uncovered | none | 0 |
 | `extension_update_health_partial_coverage` | `extension_update_health_partial_coverage` | uncovered | none | 0 |
+| `extensions_unreadable` | `extensions_unreadable` | uncovered | none | 0 |
 | `field_duplicate` | `field_duplicate` | uncovered | none | 0 |
 | `field_invalid` | `field_invalid` | uncovered | none | 0 |
 | `field_mcp_input_collision` | `field_mcp_input_collision` | uncovered | none | 0 |
@@ -189,8 +190,12 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `locks_stale_count` | `locks_stale_count` | uncovered | none | 0 |
 | `locks_unreadable` | `locks_unreadable` | uncovered | none | 0 |
 | `malformed_plan_step_evidence` | `malformed_plan_step_evidence` | uncovered | none | 0 |
+| `managed_state_invalid` | `managed_state_invalid` | uncovered | none | 0 |
+| `managed_state_unreadable` | `managed_state_unreadable` | uncovered | none | 0 |
 | `manifest_capabilities_absent` | `manifest_capabilities_absent` | uncovered | none | 0 |
+| `manifest_invalid` | `manifest_invalid` | uncovered | none | 0 |
 | `manifest_unknown_key` | `manifest_unknown_key` | executable | owned_state | 1 |
+| `manifest_unreadable` | `manifest_unreadable` | uncovered | none | 0 |
 | `mcp_annotation_file_unavailable` | `mcp_annotation_file_unavailable` | uncovered | none | 0 |
 | `mcp_stdin_unavailable` | `mcp_stdin_unavailable` | uncovered | none | 0 |
 | `mcp_task_not_found_or_not_authorized` | `mcp_task_not_found_or_not_authorized` | uncovered | none | 0 |
@@ -216,7 +221,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `missing_parameter_alias` | `missing_parameter_alias` | uncovered | none | 0 |
 | `missing_positive_execution_receipt` | `missing_positive_execution_receipt` | uncovered | none | 0 |
 | `missing_probe` | `missing_probe` | uncovered | none | 0 |
-| `missing_required_argument` | `missing_required_argument` | executable | grammar | 75 |
+| `missing_required_argument` | `missing_required_argument` | executable | grammar | 77 |
 | `missing_required_option` | `missing_required_option` | uncovered | none | 0 |
 | `missing_suggested_retry` | `missing_suggested_retry` | uncovered | none | 0 |
 | `missing_suggested_retry_args` | `missing_suggested_retry_args` | uncovered | none | 0 |
@@ -274,10 +279,12 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `retry_failed` | `retry_failed` | uncovered | none | 0 |
 | `schema_migration_input_required` | `schema_migration_input_required` | uncovered | none | 0 |
 | `semantic_spelling_collision` | `semantic_spelling_collision` | uncovered | none | 0 |
+| `settings_invalid` | `settings_invalid` | uncovered | none | 0 |
 | `settings_read_fs_error` | `settings_read_fs_error` | uncovered | none | 0 |
 | `settings_read_invalid_json` | `settings_read_invalid_json` | uncovered | none | 0 |
 | `settings_read_invalid_schema` | `settings_read_invalid_schema` | uncovered | none | 0 |
 | `settings_read_merge_failed` | `settings_read_merge_failed` | uncovered | none | 0 |
+| `settings_unreadable` | `settings_unreadable` | uncovered | none | 0 |
 | `stale_budget` | `stale_budget` | uncovered | none | 0 |
 | `stale_destination` | `stale_destination` | uncovered | none | 0 |
 | `stale_observed_signature` | `stale_observed_signature` | uncovered | none | 0 |
@@ -318,13 +325,13 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `unknown_field` | `unknown_field` | uncovered | none | 0 |
 | `unknown_field_projection` | `unknown_field_projection` | executable | closed_domain | 10 |
 | `unknown_item_type` | `unknown_item_type` | uncovered | none | 0 |
-| `unknown_lifecycle_action` | `unknown_subcommand` | executable | grammar, owned_state | 12 |
+| `unknown_lifecycle_action` | `unknown_subcommand` | executable | grammar, owned_state | 14 |
 | `unknown_noun` | `unknown_noun` | uncovered | none | 0 |
 | `unknown_option` | `unknown_option` | executable | owned_state | 1 |
 | `unknown_plan_template` | `unknown_plan_template` | uncovered | none | 0 |
 | `unknown_provenance_dimension` | `unknown_provenance_dimension` | uncovered | none | 0 |
 | `unknown_status` | `unknown_status` | uncovered | none | 0 |
-| `unknown_subcommand` | `unknown_subcommand` | executable | grammar, owned_state | 12 |
+| `unknown_subcommand` | `unknown_subcommand` | executable | grammar, owned_state | 14 |
 | `unsafe_init_recovery` | `unsafe_init_recovery` | uncovered | none | 0 |
 | `unsupported_update_option` | `unsupported_update_option` | uncovered | none | 0 |
 | `validate_command_references_stale_pm_ids` | `validate_command_references_stale_pm_ids` | uncovered | none | 0 |

package/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.9.26"
+    "version": "2026.9.27"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.9.26",
+      "version": "2026.9.27",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.9.26",
+  "version": "2026.9.27",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -123,7 +123,7 @@
     "lint:complexity:baseline": "eslint . --suppress-rule complexity --suppress-rule sonarjs/cognitive-complexity",
     "lint:duplicates": "jscpd --config .jscpd.json && jscpd --config .jscpd.source.json && jscpd --config .jscpd.tables.json",
     "lint:codefactor": "pnpm quality:static",
-    "quality:static": "pnpm quality:docstrings && pnpm quality:exports && pnpm lint:eslint && pnpm lint:duplicates && node scripts/check-workflow-permissions.mjs && node scripts/check-dependency-cooldown.mjs && node scripts/gen-plugin-mcp-wrappers.mjs --check && pnpm build && node scripts/contracts-snapshot.mjs --check && node scripts/generate-agent-capability-surfaces.mjs --check && node scripts/generate-error-code-catalog.mjs --check && node scripts/release/repository-assurance.mjs repository-static-quality --trigger ci --json && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/surface-replication-gate.mjs && node scripts/release/command-grammar-gate.mjs && node scripts/release/flag-invocation-parity.mjs && node scripts/release/flag-lexicon-gate.mjs && node scripts/release/refusal-closure-gate.mjs && node scripts/release/agent-task-token-gate.mjs && pnpm quality:mcp-deprecations && node dist/cli.js assurance run tracker-context-quality --trigger ci --dry-run --json --output-budget unbounded && node scripts/release/gate-registry.mjs && node scripts/sdk-surface-snapshot.mjs --check && node scripts/bench/sdk-entrypoint-costs.mjs --check && node scripts/bench/cli-transport-floor.mjs --check && node dist/cli.js assurance run graph-composition --trigger ci --dry-run --json --output-budget unbounded && node dist/cli.js assurance run record-integrity --trigger ci --dry-run --json --output-budget unbounded && pnpm quality:mutation -- --prebuilt",
+    "quality:static": "pnpm quality:docstrings && pnpm quality:exports && pnpm lint:eslint && pnpm lint:duplicates && node scripts/check-workflow-permissions.mjs && node scripts/check-dependency-cooldown.mjs && node scripts/gen-plugin-mcp-wrappers.mjs --check && node scripts/gen-agent-plugin-skills.mjs --check && pnpm build && node scripts/contracts-snapshot.mjs --check && node scripts/generate-agent-capability-surfaces.mjs --check && node scripts/generate-error-code-catalog.mjs --check && node scripts/release/repository-assurance.mjs repository-static-quality --trigger ci --json && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/surface-replication-gate.mjs && node scripts/release/command-grammar-gate.mjs && node scripts/release/flag-invocation-parity.mjs && node scripts/release/flag-lexicon-gate.mjs && node scripts/release/refusal-closure-gate.mjs && node scripts/release/agent-task-token-gate.mjs && pnpm quality:mcp-deprecations && node dist/cli.js assurance run tracker-context-quality --trigger ci --dry-run --json --output-budget unbounded && node scripts/release/gate-registry.mjs && node scripts/sdk-surface-snapshot.mjs --check && node scripts/bench/sdk-entrypoint-costs.mjs --check && node scripts/bench/cli-transport-floor.mjs --check && node dist/cli.js assurance run graph-composition --trigger ci --dry-run --json --output-budget unbounded && node dist/cli.js assurance run record-integrity --trigger ci --dry-run --json --output-budget unbounded && pnpm quality:mutation -- --prebuilt",
     "quality:exports": "knip --no-config-hints && node scripts/run-tests.mjs test -- tests/unit/scripts/release/dead-exports.spec.ts",
     "quality:command-grammar": "pnpm build && node scripts/release/command-grammar-gate.mjs && node scripts/release/flag-invocation-parity.mjs && node scripts/release/flag-lexicon-gate.mjs",
     "quality:recovery-closure": "pnpm build && node scripts/release/refusal-closure-gate.mjs",

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.9.26",
+  "version": "2026.9.27",
   "private": true,
   "type": "module",
   "description": "First-party pm package for importing Beads JSONL records.",

package/packages/pm-calendar/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-calendar",
-  "version": "2026.9.26",
+  "version": "2026.9.27",
   "private": true,
   "type": "module",
   "description": "First-party pm package for calendar and agenda views.",

package/packages/pm-command-kit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-command-kit",
-  "version": "2026.9.26",
+  "version": "2026.9.27",
   "private": true,
   "type": "module",
   "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",

package/packages/pm-digital-twin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-digital-twin",
-  "version": "2026.9.26",
+  "version": "2026.9.27",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a temporal production-facility digital twin built entirely on public pm SDK and extension primitives.",

package/packages/pm-governance-audit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-governance-audit",
-  "version": "2026.9.26",
+  "version": "2026.9.27",
   "private": true,
   "type": "module",
   "description": "First-party pm package for governance audit and normalization workflows.",

package/packages/pm-guide-shell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-guide-shell",
-  "version": "2026.9.26",
+  "version": "2026.9.27",
   "private": true,
   "type": "module",
   "description": "First-party pm package for guide and shell completion workflows.",

package/packages/pm-kanban/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-kanban",
-  "version": "2026.9.26",
+  "version": "2026.9.27",
   "private": true,
   "type": "module",
   "description": "First-party pm archetype package: a complete Kanban continuous-flow profile built on public SDK primitives.",

package/packages/pm-lifecycle-hooks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-lifecycle-hooks",
-  "version": "2026.9.26",
+  "version": "2026.9.27",
   "private": true,
   "type": "module",
   "description": "First-party pm package demonstrating safe lifecycle hook registration.",

package/packages/pm-linked-test-adapters/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-linked-test-adapters",
-  "version": "2026.9.26",
+  "version": "2026.9.27",
   "private": true,
   "type": "module",
   "description": "First-party pm package for optional linked-test run management adapters and reporters.",

package/packages/pm-search-advanced/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-search-advanced",
-  "version": "2026.9.26",
+  "version": "2026.9.27",
   "private": true,
   "type": "module",
   "description": "First-party pm package for semantic, hybrid, and reindex search workflows.",

package/packages/pm-templates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-templates",
-  "version": "2026.9.26",
+  "version": "2026.9.27",
   "private": true,
   "type": "module",
   "description": "First-party pm package for reusable create templates.",

package/packages/pm-todos/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-todos",
-  "version": "2026.9.26",
+  "version": "2026.9.27",
   "private": true,
   "type": "module",
   "description": "First-party pm package for Todo markdown import and export.",

package/packages/pm-vcs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-vcs-sdk-exemplar",
-  "version": "2026.9.26",
+  "version": "2026.9.27",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a VCS-style changeset workflow built entirely on public pm SDK and extension primitives.",

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

@@ -1,7 +1,7 @@
 {
   "name": "pm-claude",
   "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents (coordinator, delivery-chain, triage, verification), hybrid TUI task tracking (pm as persistent store + Claude Code task panel as live view), session context injection, and full git-based project management without leaving Claude Code.",
-  "version": "2026.9.26",
+  "version": "2026.9.27",
   "author": {
     "name": "unbrained",
     "url": "https://github.com/unbraind/pm-cli"

package/plugins/pm-claude/README.md

@@ -13,6 +13,10 @@ Native pm CLI integration for Claude Code. Use pm project management tools direc
 | **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 |
 
+The five 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.
+
 ## Installation
 
 ### Option A: Plugin marketplace — canonical install (recommended)
@@ -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.27",
   "dependencies": {
-    "@unbrained/pm-cli": "2026.9.26"
+    "@unbrained/pm-cli": "2026.9.27"
   }
 }

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/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."