@unbrained/pm-cli 2026.5.6 → 2026.5.10

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.6",
+  "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.

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

@@ -0,0 +1,44 @@
+---
+description: Initialize pm in the current project — creates the .agents/pm/ tracker directory, sets up default settings, and shows a quick-start summary. Accepts an optional project name as argument.
+---
+
+Initialize pm project tracking using native MCP tools. Argument: `$ARGUMENTS` (optional project name).
+
+1. **Check if already initialized** — look for `.agents/pm/settings.json` in the current directory:
+   ```json
+   { "tool": "pm_health", "args": {} }
+   ```
+   If health returns `ok: true`, pm is already initialized — show the current status with `pm_context` and stop.
+
+2. **Run init** via `pm_run`:
+   ```json
+   { "tool": "pm_run", "args": { "action": "init", "options": {} } }
+   ```
+
+3. **Verify initialization** — call `pm_health` again to confirm `ok: true`.
+
+4. **Create a first item** (optional) — if `$ARGUMENTS` is a project name or description, offer to create an initial Epic:
+   ```json
+   {
+     "tool": "pm_create",
+     "args": {
+       "author": "claude-code-agent",
+       "options": {
+         "title": "<project name> — initial setup",
+         "type": "Epic",
+         "status": "open",
+         "priority": "1",
+         "description": "Top-level epic for tracking <project name> work.",
+         "createMode": "progressive"
+       }
+     }
+   }
+   ```
+
+5. **Show quick-start summary**:
+   - pm initialized at `.agents/pm/`
+   - Available slash commands: `/pm-status`, `/pm-new`, `/pm-start-task`, `/pm-close-task`, `/pm-list`, `/pm-search`, `/pm-triage`, `/pm-calendar`, `/pm-developer`, `/pm-planner`, `/pm-release`, `/pm-audit`, `/pm-workflow`
+   - All 18 MCP tools available: `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`, `pm_run`
+   - Next: use `/pm-new <title>` to create your first item, or `/pm-status` to see the tracker state
+
+If initialization fails, report the error and suggest running `pm init` manually in the terminal.

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

@@ -0,0 +1,39 @@
+---
+description: List pm items with optional status or type filter. Pass a filter like "open", "in_progress", "blocked", "bugs", or leave empty for active items.
+---
+
+List pm items using native MCP tools. Filter: `$ARGUMENTS`
+
+1. **Parse filter** from `$ARGUMENTS`:
+   - Status keywords: `open`, `in_progress`, `in-progress`, `blocked`, `draft`, `closed`, `canceled`, `all`
+   - Type keywords: `task`, `bug`, `feature`, `epic`, `story`
+   - Combined: e.g. "open bugs", "blocked features"
+   - Empty: show active items (excludes closed/canceled)
+
+2. **Call `pm_list`** with the parsed filter:
+   ```json
+   {
+     "tool": "pm_list",
+     "args": {
+       "options": {
+         "status": "<parsed status or omit>",
+         "type": "<parsed type or omit>",
+         "limit": "25"
+       }
+     }
+   }
+   ```
+   For `all`, use `pm_list` with no status filter.
+
+3. **If filter is empty** (active items) — also call `pm_context` for a richer summary:
+   ```json
+   { "tool": "pm_context", "args": { "options": { "limit": "10" } } }
+   ```
+
+4. **Present results** — format as a table or grouped list:
+   | ID | Title | Status | Type | Priority |
+   |----|-------|--------|------|----------|
+
+5. **Show counts** — summarize: "X open, Y in_progress, Z blocked" at the top.
+
+Keep the response under 400 words unless there are many items to show.

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

@@ -0,0 +1,36 @@
+---
+description: Quickly create a new pm item — duplicate-checks first, then creates with sensible defaults. Pass a title (or title + description) as argument.
+---
+
+Create a new pm item using native MCP tools. Input: `$ARGUMENTS`
+
+1. **Parse input** — treat `$ARGUMENTS` as the item title. If it contains a pipe (`|`) or newline, split into title | description.
+2. **Duplicate check** — call `pm_search` with the title keywords:
+   ```json
+   { "tool": "pm_search", "args": { "query": "$ARGUMENTS", "options": { "limit": "5" } } }
+   ```
+   If a close match exists, show it and ask: "Is this a duplicate, or is this a new separate item?"
+3. **Get context** — call `pm_context` to understand current workload before creating:
+   ```json
+   { "tool": "pm_context", "args": { "options": { "limit": "5" } } }
+   ```
+4. **Create** — if no duplicate and user confirms, call `pm_create`:
+   ```json
+   {
+     "tool": "pm_create",
+     "args": {
+       "author": "claude-code-agent",
+       "options": {
+         "title": "<from $ARGUMENTS>",
+         "description": "<inferred or from input>",
+         "type": "Task",
+         "status": "open",
+         "priority": "2",
+         "createMode": "progressive"
+       }
+     }
+   }
+   ```
+5. **Report** — show the created item ID, title, and ask if it should be claimed immediately.
+
+If `$ARGUMENTS` is empty, ask for the title interactively before creating.