@unbrained/pm-cli 2026.5.5 → 2026.5.10

package/docs/RELEASING.md

@@ -1,6 +1,7 @@
 # Releasing `@unbrained/pm-cli`
 
 This page is for maintainers cutting npm and GitHub releases. It assumes release work is tracked with `pm`.
+For local progressive-disclosure routing, use `pm guide release`.
 
 ## Agent Quick Context
 
@@ -9,6 +10,7 @@ This page is for maintainers cutting npm and GitHub releases. It assumes release
 - Publishing is owned by the tag-driven GitHub Actions release workflow.
 - Do not run manual `npm publish`.
 - Run local parity gates before pushing release tags.
+- Use `pm guide release --json` for machine-readable release docs routing.
 
 Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 
@@ -34,7 +36,7 @@ pnpm version:check
 ## One-Time Setup
 
 - Prefer npm Trusted Publishing for `.github/workflows/release.yml` so GitHub-hosted release jobs can publish with short-lived OIDC credentials. Keep `id-token: write`, `npm publish --access public --provenance`, and the package repository URL aligned with npm's Trusted Publisher configuration. If Trusted Publishing is not configured yet, add `NPM_TOKEN` as a GitHub Environment or repository secret as the fallback publisher credential.
-- Add `SENTRY_AUTH_TOKEN` as an optional GitHub Environment or repository secret when Sentry release creation and sourcemap upload should run. Add `SENTRY_PERSONAL_ADMIN_TOKEN` only when the automated Sentry issue-threshold gate needs broader issue-read access than the CI token. The release workflow skips Sentry upload cleanly when `SENTRY_AUTH_TOKEN` is absent; the auto-release workflow skips the external Sentry gate only when no Sentry token is configured and `--telemetry-mode off` is selected.
+- Add `SENTRY_AUTH_TOKEN` as an optional GitHub Environment or repository secret when Sentry release creation and sourcemap upload should run. Add `SENTRY_PERSONAL_ADMIN_TOKEN` only when the GitHub-hosted Sentry issue-threshold gate should read unresolved issues; CI-scoped release tokens may not have issue-read scope. The release workflow skips Sentry upload cleanly when `SENTRY_AUTH_TOKEN` is absent and skips the GitHub-hosted issue-threshold gate when `SENTRY_PERSONAL_ADMIN_TOKEN` is absent; local maintainers should still run the token-backed Sentry gate before release.
 - Keep any `release` environment compatible with free GitHub features. This repository is public, so environment secrets and tag/branch deployment rules are compatible with the free GitHub path; do not add paid-only release gates.
 - Ensure `GITHUB_TOKEN` has `contents: write` for GitHub Release creation.
 - Keep `package.json` repository, homepage, and bugs URLs aligned with `https://github.com/unbraind/pm-cli`.
@@ -52,6 +54,7 @@ Policy:
 - same-day follow-up release (`YYYY.M.D-N`) is manual-only via `allow_same_day_release=true`
 - release preparation must pass all quality and compatibility gates before commit+tag push
 - external Sentry checks run when a Sentry token is configured; local maintainers can make Sentry and private telemetry mandatory with `--telemetry-mode required`
+- after creating and pushing a new tag, auto-release dispatches `.github/workflows/release.yml` with that tag and waits for the publish workflow to finish, because GitHub does not start normal push/tag workflows from `GITHUB_TOKEN` pushes
 
 Pipeline entrypoint:
 
@@ -63,7 +66,7 @@ The pipeline performs:
 
 1. change detection + one-release-per-day guard
 2. version bump + changelog promotion from `[Unreleased]`
-3. strict gates (build, typecheck, coverage, static quality, compatibility, security, smoke checks, reliability gate)
+3. strict gates (build, typecheck, docs/skills freshness, coverage, static quality, compatibility, security, smoke checks, reliability gate)
 4. release note generation from changelog + pm evidence
 5. commit and tag creation (plus optional push)
 
@@ -84,7 +87,7 @@ Minimum coverage:
 - parent and dependency links
 - comments, notes, learnings, body, reminders, events
 - linked files, docs, and tests
-- json_markdown items with external YAML wrappers before JSON front matter
+- legacy markdown item files (including external YAML wrappers before JSON front matter) migrating cleanly to TOON
 - closed issue metadata and history drift checks
 - current-build write mutation and item-count preservation
 
@@ -117,6 +120,7 @@ git push origin v<version>
 `.github/workflows/release.yml` runs on `v*.*.*` tags and handles:
 
 - full-history checkout
+- manual `workflow_dispatch` by tag for automation handoff or recovery when a tag already exists
 - pnpm install with frozen lockfile
 - version policy and tag guard
 - secret scan
@@ -129,7 +133,7 @@ git push origin v<version>
 - npm pack dry run and npx tarball smoke test
 - generated release notes from changelog plus sanitized tracker metadata
 - artifact uploads
-- `npm publish --access public --provenance`
+- `npm publish --access public --provenance`, skipped on retry when the exact version is already present on npm
 - post-publish npm/npx/bunx verification
 - GitHub Release creation
 
@@ -157,5 +161,5 @@ Use the npm registry package for maintainer global updates. Do not use `npm inst
 
 - If local gates fail, fix and rerun before tagging.
 - If the tag workflow fails before npm publish, confirm no package was published before moving or replacing a tag.
-- If npm publish succeeds but GitHub Release creation fails, recreate only the GitHub Release after verifying the tag and package.
+- If npm publish succeeds but GitHub Release creation fails, rerun `.github/workflows/release.yml` with `workflow_dispatch` and `tag=v<version>`; the workflow skips duplicate npm publish, reruns public verification, and creates the GitHub Release for the existing tag.
 - Record failure evidence and remediation in the release `pm` item.

package/docs/SDK.md

@@ -7,6 +7,7 @@ The public SDK is exported from `@unbrained/pm-cli/sdk`. Use it for extension au
 - Primary import: `@unbrained/pm-cli/sdk`.
 - Runtime extension lifecycle is documented in [Extensions](EXTENSIONS.md).
 - Exact command/action contracts are available through `pm contracts`.
+- Local deep-dive routing is available through `pm guide sdk --depth deep`.
 
 Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 
@@ -144,8 +145,8 @@ export default defineExtension({
       name: "example-search",
       async query(context) {
         return context.documents
-          .filter((doc) => doc.front_matter.title?.toLowerCase().includes(context.query.toLowerCase()))
-          .map((doc) => ({ id: doc.front_matter.id, score: 0.5, matched_fields: ["title"] }));
+          .filter((doc) => doc.metadata.title?.toLowerCase().includes(context.query.toLowerCase()))
+          .map((doc) => ({ id: doc.metadata.id, score: 0.5, matched_fields: ["title"] }));
       },
     });
   },

package/marketplace.json

@@ -0,0 +1,34 @@
+{
+  "name": "pm-cli",
+  "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
+  "owner": {
+    "name": "unbrained",
+    "url": "https://github.com/unbraind/pm-cli"
+  },
+  "plugins": [
+    {
+      "name": "pm-cli",
+      "description": "Native pm CLI integration for Claude Code — 18 MCP tools, 5 workflow skills, 14 slash commands, hybrid TUI task tracking, session context injection, and a coordination subagent for git-based project management without leaving Claude Code.",
+      "version": "1.2.0",
+      "source": "./plugins/pm-cli-claude",
+      "author": {
+        "name": "unbrained",
+        "url": "https://github.com/unbraind/pm-cli"
+      },
+      "homepage": "https://github.com/unbraind/pm-cli",
+      "repository": "https://github.com/unbraind/pm-cli",
+      "license": "MIT",
+      "keywords": [
+        "pm-cli",
+        "project-management",
+        "mcp",
+        "tasks",
+        "agents",
+        "workflows",
+        "git-native",
+        "task-tracker",
+        "ai"
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.5.5",
+  "version": "2026.5.10",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",
@@ -13,7 +13,8 @@
     "url": "https://github.com/unbraind/pm-cli/issues"
   },
   "bin": {
-    "pm": "dist/cli.js"
+    "pm": "dist/cli.js",
+    "pm-mcp": "dist/mcp/server.js"
   },
   "types": "dist/sdk/index.d.ts",
   "exports": {
@@ -45,9 +46,14 @@
     "AGENTS.md",
     "PRD.md",
     "docs/**",
+    ".claude-plugin/**",
+    "plugins/**",
+    ".pi/**",
+    ".agents/skills/**",
     ".agents/pm/extensions/**",
     "scripts/install.sh",
-    "scripts/install.ps1"
+    "scripts/install.ps1",
+    "marketplace.json"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -57,6 +63,9 @@
     "test": "node scripts/run-tests.mjs test",
     "test:coverage": "node scripts/run-tests.mjs coverage",
     "quality:static": "node scripts/release/static-quality-gate.mjs",
+    "quality:docs-skills": "node scripts/release/docs-skills-gate.mjs",
+    "smoke:codex-plugin": "node scripts/smoke-codex-plugin-mcp.mjs",
+    "smoke:claude-plugin": "node scripts/smoke-claude-plugin.mjs",
     "version:check": "node scripts/release-version.mjs check",
     "version:next": "node scripts/release-version.mjs next",
     "release:notes": "node scripts/generate-release-notes.mjs",
@@ -79,15 +88,40 @@
     "git-native",
     "typescript",
     "task-tracker",
-    "coding-agents"
+    "coding-agents",
+    "pi-package",
+    "pi-extension"
   ],
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
+  "pi": {
+    "extensions": [
+      "./.pi/extensions/pm-cli/index.js"
+    ],
+    "skills": [
+      "./.pi/skills"
+    ],
+    "prompts": [
+      "./.pi/prompts"
+    ]
+  },
   "engines": {
     "node": ">=20"
   },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "@sentry/node": "^10.51.0",
     "@toon-format/toon": "^2.1.0",

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

@@ -0,0 +1,23 @@
+{
+  "name": "pm-cli",
+  "description": "Native pm CLI integration for Claude Code — 18 MCP tools, 5 workflow skills, 14 slash commands, hybrid TUI task tracking (pm as persistent store + Claude Code task panel as live view), session context injection, and a coordination subagent for git-based project management without leaving Claude Code.",
+  "version": "1.2.0",
+  "author": {
+    "name": "unbrained",
+    "url": "https://github.com/unbraind/pm-cli"
+  },
+  "homepage": "https://github.com/unbraind/pm-cli",
+  "repository": "https://github.com/unbraind/pm-cli",
+  "license": "MIT",
+  "keywords": [
+    "pm-cli",
+    "project-management",
+    "mcp",
+    "tasks",
+    "agents",
+    "workflows",
+    "git-native",
+    "task-tracker",
+    "ai"
+  ]
+}

package/plugins/pm-cli-claude/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "pm-cli-native": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/pm-mcp-server.mjs"],
+      "env": {
+        "PM_AUTHOR": "claude-code-agent"
+      },
+      "note": "Native pm-cli MCP server. Imports pm command modules directly — no pm shell invocation needed."
+    }
+  }
+}

package/plugins/pm-cli-claude/README.md

@@ -0,0 +1,184 @@
+# pm CLI — Claude Code Plugin
+
+Native pm CLI integration for Claude Code. Use pm project management tools directly through Claude Code's MCP protocol — no shell invocations, no context switching.
+
+## What's Included
+
+| Component | What it provides |
+|-----------|----------------|
+| **18 MCP tools** | Full pm surface: context, search, list, get, create, update, claim, release, close, comments, files, docs, test, validate, health, contracts, guide + `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 |
+| **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 when pm is initialized |
+| **pm-coordinator agent** | Subagent for coordinating multi-item and batch operations |
+
+## Installation
+
+### Option A: Plugin marketplace (recommended)
+
+```
+/plugin install pm-cli@pm-cli
+```
+
+This installs the plugin including all MCP tools, skills, slash commands, hybrid TUI tracking, and the session hook in one step.
+
+To add the marketplace first (if not already configured):
+
+```bash
+claude plugin marketplace add /path/to/pm-cli
+# or from GitHub:
+# claude plugin marketplace add unbraind/pm-cli
+```
+
+### Option B: Global MCP server via Claude Code CLI (MCP tools only)
+
+```bash
+claude mcp add --transport stdio pm-cli-native -- npx -y @unbrained/pm-cli pm-mcp
+```
+
+This gives you the 18 MCP tools but not the skills, slash commands, or session hook.
+
+### Option C: Direct `.mcp.json` (project-scoped MCP only)
+
+Add to your project's `.mcp.json` for MCP tools in a single project:
+
+```json
+{
+  "mcpServers": {
+    "pm-cli-native": {
+      "command": "npx",
+      "args": ["-y", "@unbrained/pm-cli@latest", "pm-mcp"],
+      "env": {
+        "PM_AUTHOR": "claude-code-agent"
+      }
+    }
+  }
+}
+```
+
+## Quick Start
+
+After installation, restart Claude Code. All tools are available immediately:
+
+```
+Can you show me the current pm project status?
+→ Claude uses pm_context + pm_run(calendar) automatically
+
+Start working on the authentication bug.
+→ Claude searches pm, finds or creates an item, claims it, syncs to task panel
+
+Close pm-xxxx — the fix is complete.
+→ Claude runs /pm-close-task pm-xxxx with evidence linking, closes pm item, marks task panel entry completed
+```
+
+## Hybrid TUI Task Tracking
+
+pm items automatically sync to Claude Code's task panel during active sessions:
+
+- **pm** = persistent cross-session store (git-native, tracked in `.agents/pm/`)
+- **Claude Code task panel** = live session view with spinners and status
+
+When you `/pm-start-task` or `/pm-developer`:
+1. The pm item is claimed (`pm_claim`)
+2. A matching entry appears in Claude Code's task panel with a spinner (`TaskCreate`)
+3. Work progresses; evidence is linked in pm
+4. On `/pm-close-task`, pm is closed AND the task panel entry shows ✔ completed
+
+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
+
+| Command | What it does |
+|---------|-------------|
+| `/pm-status` | Quick status snapshot — active items + calendar |
+| `/pm-start-task [id or keywords]` | Find, claim, and start a pm item (with TUI sync) |
+| `/pm-close-task [id]` | Verify, evidence, close, and release an item (marks TUI completed) |
+| `/pm-triage <request>` | Triage a new request into pm tracking |
+| `/pm-audit` | Full repository audit with findings (TUI tracked) |
+| `/pm-search <query>` | Search pm items by keywords, tags, or status |
+| `/pm-new <title>` | Quick-create a new pm item (with duplicate check) |
+| `/pm-list [filter]` | List active or filtered pm items |
+| `/pm-calendar [view]` | Show upcoming deadlines and calendar events |
+| `/pm-developer [id or keywords]` | Full developer loop — claim, implement, verify, close |
+| `/pm-planner [scope]` | Plan and decompose work — survey, create hierarchy, prioritize |
+| `/pm-release [version or id]` | Release gates — build, tests, coverage, CI, publish |
+| `/pm-workflow [id or description]` | General pm workflow loop with TUI tracking |
+| `/pm-init [project name]` | Initialize pm in the current project |
+
+## Skills
+
+| Skill | When Claude uses it |
+|-------|-------------------|
+| `pm-workflow` | Any pm-tracked work — orient, claim, implement, close |
+| `pm-developer` | Implementation tasks — code, tests, docs changes |
+| `pm-release` | Release preparation — gates, tagging, publish |
+| `pm-audit` | Repository health audits — validate, dedupe, aggregate |
+| `pm-planner` | Planning — decompose epics, prioritize backlog, triage |
+
+## MCP Tools Reference
+
+### Narrow tools (prefer these)
+
+| Tool | Purpose |
+|------|---------|
+| `pm_context` | Active work snapshot |
+| `pm_search` | Keyword/semantic/hybrid search |
+| `pm_list` | Filtered item list |
+| `pm_get` | Single item detail |
+| `pm_create` | Create new item |
+| `pm_update` | Update metadata |
+| `pm_claim` | Claim for active work |
+| `pm_release` | Release claim |
+| `pm_close` | Close with reason |
+| `pm_comments` | List or add comments |
+| `pm_files` | Link/unlink files |
+| `pm_docs` | Link/unlink docs |
+| `pm_test` | Link or run tests |
+| `pm_validate` | Run validation checks |
+| `pm_health` | Run health diagnostics |
+| `pm_contracts` | Inspect command contracts |
+| `pm_guide` | Read guide topics |
+
+### General tool
+
+| Tool | Purpose |
+|------|---------|
+| `pm_run` | Any pm action not covered above — pass `action` field |
+
+**`pm_run` actions:** `init`, `calendar`, `activity`, `aggregate`, `dedupe-audit`, `normalize`, `reindex`, `extension`, `history`, `stats`, `append`, `notes`, `learnings`, `test-all`, `comments-audit`, `gc`, `templates-list`, `templates-save`, `templates-show`, `test-runs-list`, `test-runs-status`, `test-runs-logs`, `test-runs-stop`, `test-runs-resume`, `config`, `completion`
+
+## Hybrid TUI Sync Pattern
+
+All skills and commands implement this pattern for every claimed item:
+
+```
+1. pm_claim → [pm stores claim]
+2. TaskCreate { subject: "[pm-xxxx] title", activeForm: "Working on pm-xxxx" }
+   → [spinner appears in Claude Code task panel]
+3. TaskUpdate { status: "in_progress" }
+4. ... do work, link evidence in pm ...
+5. pm_close → pm_release → [pm stores closure]
+6. TaskUpdate { status: "completed" }
+   → [✔ appears in Claude Code task panel]
+```
+
+## Safety
+
+- Never pass `path` during real repository tracking — only use it for sandbox/test runs.
+- Set `author: "claude-code-agent"` on all mutations.
+- Run `pm_validate` before closing items.
+- For tests, pass a sandbox `cwd` and set `PM_GLOBAL_PATH` to an isolated path.
+
+## Requirements
+
+- Node.js ≥ 20
+- pm CLI available via npx (auto-resolved) or installed globally: `npm install -g @unbrained/pm-cli`
+- Project initialized with `pm init` (or use `/pm-init`)
+
+## Links
+
+- [pm CLI docs](https://github.com/unbraind/pm-cli/tree/main/docs)
+- [Command reference](https://github.com/unbraind/pm-cli/blob/main/docs/COMMANDS.md)
+- [Architecture guide](https://github.com/unbraind/pm-cli/blob/main/docs/ARCHITECTURE.md)
+- [CHANGELOG](https://github.com/unbraind/pm-cli/blob/main/CHANGELOG.md)

package/plugins/pm-cli-claude/agents/pm-coordinator.md

@@ -0,0 +1,48 @@
+---
+name: pm-coordinator
+description: Subagent for coordinating multi-item pm CLI work. Use when orchestrating across multiple pm items, running batch updates, or performing broad audit/migration tasks that should be isolated from the main conversation context.
+---
+
+# pm Coordinator
+
+You are a pm CLI coordination subagent. You have access to all pm native MCP tools and should use them to coordinate project management tasks.
+
+## Your Role
+
+- Coordinate across multiple pm items in a single focused session
+- Run batch operations (update-many, validate, aggregate) without polluting the main context
+- Perform audit workflows and return structured findings
+- Execute release gate sequences and report results
+- Mirror active items to Claude Code's task panel using the Hybrid TUI Sync pattern
+
+## Hybrid TUI Sync
+
+pm is the **persistent store**. Claude Code's task panel is the **live session view**.
+
+For each pm item you actively claim or work on:
+1. Call `TaskCreate` with `subject: "[pm-xxxx] <title>"` and `activeForm: "Working on pm-xxxx"`.
+2. Save the returned `taskId`.
+3. Call `TaskUpdate(in_progress)` once work begins.
+4. Call `TaskUpdate(completed)` after `pm_close` + `pm_release`.
+
+For batch audits spanning many items, create one top-level `TaskCreate` for the coordination session itself, and update it at the end.
+
+## Tools Available
+
+Use the `pm-cli-native` MCP server tools: `pm_context`, `pm_search`, `pm_list`, `pm_get`, `pm_create`, `pm_update`, `pm_claim`, `pm_release`, `pm_close`, `pm_comments`, `pm_files`, `pm_docs`, `pm_test`, `pm_validate`, `pm_health`, `pm_contracts`, `pm_guide`, and `pm_run` for all other operations.
+
+Also use Claude Code's built-in `TaskCreate` and `TaskUpdate` tools for TUI panel display.
+
+## Always
+
+1. Call `pm_context` first for orientation.
+2. Call `pm_search` before creating new items to avoid duplicates.
+3. Set `author: "claude-code-agent"` on all mutations.
+4. Mirror claimed items to Claude Code's task panel with `TaskCreate`.
+5. Return a structured summary of what you did and what pm items were affected.
+
+## Never
+
+- Pass `path` during real repository tracking.
+- Close items without verifying acceptance criteria.
+- Create duplicate items without checking `pm_search` first.

package/plugins/pm-cli-claude/commands/pm-audit.md

@@ -0,0 +1,39 @@
+---
+description: Run a comprehensive pm repository audit — health, validation, duplicates, aggregate counts, calendar, and activity. Produces a structured finding report with tracked pm items for actionable issues.
+---
+
+Use native pm MCP tools to audit the repository's pm tracker state.
+
+1. **Check for existing audit items** — `pm_search` with query "audit" to avoid duplicate tracking.
+2. **Create an audit tracking item** if none exists (or reuse a recent one):
+   ```json
+   { "tool": "pm_create", "args": { "author": "claude-code-agent", "options": { "title": "pm tracker audit", "type": "Task", "status": "open", "priority": "1", "createMode": "progressive" } } }
+   ```
+3. **Claim** the audit item.
+4. **Sync to Claude Code task panel**:
+   ```
+   TaskCreate:
+     subject: "[pm-xxxx] Audit: pm tracker health"
+     description: "Full pm audit run — pm-xxxx"
+     activeForm: "Running pm audit"
+   ```
+   Call `TaskUpdate(in_progress)`. Save the taskId.
+5. **Run the audit suite** in order:
+   - `pm_health` — tracker diagnostics
+   - `pm_validate` with `checkResolution: true, checkHistoryDrift: true, checkFiles: true, scanMode: "tracked-all"`
+   - `pm_run` with `action: "aggregate", options: { groupBy: "status,type" }` — count breakdown
+   - `pm_run` with `action: "dedupe-audit", options: { mode: "parent_scope", limit: "20" }` — duplicates
+   - `pm_run` with `action: "stats"` — storage metrics
+   - `pm_run` with `action: "calendar", options: { view: "week", include: "deadlines,reminders" }` — upcoming
+6. **Classify findings** — create child pm items for any blocker or warning findings.
+7. **Record evidence** with `pm_comments`: summary of all checks and findings.
+8. **Close audit item** with `pm_close`, then `pm_release`, then `TaskUpdate(completed)`.
+9. **Report** a structured audit summary:
+   - Health status
+   - Validation results (pass/warn/fail per check)
+   - Item counts by status
+   - Duplicate candidates found
+   - Overdue or upcoming deadlines
+   - Any created finding items
+
+Format the output as a markdown table for the validation results.

package/plugins/pm-cli-claude/commands/pm-calendar.md

@@ -0,0 +1,41 @@
+---
+description: Show the pm calendar — upcoming deadlines, reminders, and scheduled events. Optionally pass a view like "week", "month", or a date range.
+---
+
+Show the pm project calendar using native MCP tools. View: `$ARGUMENTS`
+
+1. **Parse view** from `$ARGUMENTS`:
+   - `week` (default) — current and next 7 days
+   - `month` — current month
+   - `today` — just today's events
+   - Empty — defaults to `week`
+
+2. **Call `pm_run` with calendar action**:
+   ```json
+   {
+     "tool": "pm_run",
+     "args": {
+       "action": "calendar",
+       "options": {
+         "view": "<parsed view, default: week>",
+         "format": "markdown",
+         "include": "deadlines,reminders,scheduled"
+       }
+     }
+   }
+   ```
+
+3. **Also call `pm_context`** for active work context alongside the calendar:
+   ```json
+   { "tool": "pm_context", "args": { "options": { "limit": "5" } } }
+   ```
+
+4. **Present the calendar** — show:
+   - A header: "📅 pm Calendar — [view] — [date range]"
+   - Calendar events grouped by date
+   - A brief summary of overdue items at the top if any
+   - Active in-progress work below the calendar
+
+5. **Flag overdue** — if any deadlines are past today, highlight them prominently.
+
+Keep the response concise — use a table or compact list for calendar entries.

package/plugins/pm-cli-claude/commands/pm-close-task.md

@@ -0,0 +1,20 @@
+---
+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.
+---
+
+Use native pm MCP tools to close a tracked task with evidence. Argument: `$ARGUMENTS` (item ID like `pm-xxxx`, or empty to show in-progress items).
+
+1. **Find the item**:
+   - If `$ARGUMENTS` is an ID: call `pm_get` with that ID and confirm it's the right item.
+   - If empty: call `pm_list` filtered to in_progress and ask the user which to close.
+2. **Review acceptance criteria** from the item's `acceptance_criteria` field.
+3. **Verify** — run linked tests with `pm_test` (with `run: true`) if any are linked.
+4. **Validate** — call `pm_validate` with `options: { checkResolution: true }`.
+5. **Link any missing files** with `pm_files` for changed source files.
+6. **Add closing evidence** with `pm_comments`: a brief summary of what changed and what was verified.
+7. **Close** with `pm_close` and a clear reason that addresses the acceptance criteria.
+8. **Release** with `pm_release`.
+9. **Sync TUI** — if a `TaskCreate` was called for this item during this session, call `TaskUpdate` with `status: "completed"` using the saved taskId. If no taskId is known, note the closure in the response.
+10. **Report** confirmation with the item ID and closing reason.
+
+Do not close if acceptance criteria are not met — instead report what's missing.

package/plugins/pm-cli-claude/commands/pm-developer.md

@@ -0,0 +1,38 @@
+---
+description: Run the pm-cli developer execution loop — orient, claim, implement, link evidence, verify, and close — with native MCP tools and live TUI tracking. Accepts an optional item ID or keywords as argument.
+---
+
+Run the full pm developer loop using native MCP tools. Argument: `$ARGUMENTS` (item ID like `pm-xxxx`, keywords, or empty to orient from context).
+
+1. **Orient**:
+   ```json
+   { "tool": "pm_context", "args": { "options": { "limit": "10" } } }
+   { "tool": "pm_search", "args": { "query": "$ARGUMENTS", "options": { "limit": "10" } } }
+   ```
+2. **Find or create the item**:
+   - If `$ARGUMENTS` is a pm ID: `pm_get` it directly.
+   - If keywords: pick the best match from search or ask the user.
+   - If no match: `pm_create` with progressive mode.
+3. **Claim** with `pm_claim` and `author: "claude-code-agent"`, then set `status: "in_progress"` with `pm_update`.
+4. **Sync to Claude Code task panel**:
+   ```
+   TaskCreate:
+     subject: "[pm-xxxx] <item title>"
+     description: "Developer loop — pm-xxxx. AC: <acceptance_criteria>"
+     activeForm: "Implementing pm-xxxx"
+   ```
+   Call `TaskUpdate(in_progress)`. Save the taskId for the session.
+5. **Implement** — make the changes. Link evidence as you go:
+   - `pm_files` for changed source files
+   - `pm_docs` for updated documentation
+   - `pm_test` for test commands
+6. **Verify**:
+   - Run the project build and tests
+   - `pm_validate` with `checkResolution: true`
+7. **Record evidence** with `pm_comments`: what changed, what was tested, results.
+8. **Close**:
+   - `pm_close` with reason
+   - `pm_release`
+   - `TaskUpdate(completed)` using the saved taskId
+
+If `$ARGUMENTS` is empty, call `pm_list` to show active items and ask which to work on.