@unbrained/pm-cli 2026.5.6 → 2026.5.11

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

@@ -0,0 +1,225 @@
+# 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, no `pm` CLI required.
+
+## 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 |
+| **3 subagents** | `pm-coordinator` (batch/multi-item), `pm-triage-agent` (duplicate-safe item creation), `pm-verification-agent` (evidence + close readiness), and a `pm-delivery-chain` orchestrator |
+| **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 (uses native modules, no CLI required) |
+
+## Installation
+
+### Option A: Plugin marketplace — canonical install (recommended)
+
+```
+/plugin install pm-cli@pm
+```
+
+First time: add the marketplace if it's not configured yet:
+
+```bash
+claude plugin marketplace add /path/to/pm-cli
+# or after npm publish:
+# claude plugin marketplace add unbraind/pm-cli
+```
+
+This installs all 18 MCP tools, 5 skills, 14 slash commands, 3 subagents, hybrid TUI tracking, and the session hook in one step.
+
+### Option B: Legacy marketplace alias (also works)
+
+```
+/plugin install pm-cli@pm-cli
+```
+
+Both `pm` and `pm-cli` marketplace IDs resolve to the same plugin.
+
+### Option C: 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 D: Direct `.mcp.json` (project-scoped MCP only)
+
+Add to your project's `.mcp.json`:
+
+```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
+
+Triage this request: add dark mode toggle to settings screen
+→ Claude spawns pm-triage-agent, checks duplicates, creates pm item with AC, hands off to /pm-developer
+```
+
+## 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 |
+
+## Subagents
+
+| Agent | Role |
+|-------|------|
+| `pm-coordinator` | Multi-item and batch coordination — batch updates, audit workflows, release gate sequences |
+| `pm-triage-agent` | Duplicate-safe item creation — orient, search, establish lineage, produce implementation-ready item |
+| `pm-verification-agent` | Closure evidence — read item, check AC, run tests, validate, produce structured close recommendation |
+| `pm-delivery-chain` | End-to-end orchestrator — runs triage → implement → verify as a single tracked loop |
+
+Use subagents via Claude Code's built-in `Agent` tool:
+```
+Spawn pm-triage-agent to set up the pm item for: add OAuth2 login support
+```
+
+## 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]
+```
+
+## Session Context Injection
+
+At session start, the hook runs natively (no `pm` CLI required):
+- Walks up directories to find `dist/pi/native.js` in the repo checkout
+- Falls back to `npx @unbrained/pm-cli` if no local dist is found
+- Injects a compact summary of in-progress/open/blocked items
+
+Example output:
+```
+pm tracker: 2 in_progress, 1 open
+  • [pm-abc1] Add OAuth2 login (in_progress)
+  • [pm-abc2] Fix test flakiness (in_progress)
+  • [pm-abc3] Update docs (open)
+Use pm_context tool or /pm-status for full details.
+```
+
+## 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 resolved automatically via local dist (in repo) or `npx @unbrained/pm-cli` (no global install needed)
+- Project initialized with `pm init` (or use `/pm-init`)
+
+## Links
+
+- [pm CLI docs](https://github.com/unbraind/pm-cli/tree/main/docs)
+- [Architecture guide](https://github.com/unbraind/pm-cli/blob/main/docs/ARCHITECTURE.md)
+- [Extension guide](https://github.com/unbraind/pm-cli/blob/main/docs/EXTENSIONS.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/agents/pm-delivery-chain.md

@@ -0,0 +1,88 @@
+---
+name: pm-delivery-chain
+description: Subagent that orchestrates the full pm delivery workflow — triage to establish or reuse a pm item, implement the scoped work, and verify before close. Use when you want a fully tracked, end-to-end delivery loop with pm integration.
+---
+
+# pm Delivery Chain
+
+You are a pm CLI delivery orchestration subagent. You coordinate triage, implementation, and verification into a single tracked delivery loop using native pm MCP tools.
+
+## Your Role
+
+Run the full three-phase delivery loop for a work request:
+1. **Triage** — establish the canonical pm item (reuse or create)
+2. **Implement** — execute the scoped work with evidence linking
+3. **Verify** — confirm acceptance criteria before closing
+
+## Phase 1: Triage
+
+Follow the pm triage workflow to produce an implementation-ready pm item:
+
+1. `pm_context` for orientation
+2. `pm_search` for duplicate detection
+3. `pm_list` to see active backlog
+4. Reuse an existing item if one matches, otherwise `pm_create` with full acceptance criteria
+5. Link parent if applicable via `pm_update`
+
+Output: pm item ID + acceptance criteria for Phase 2.
+
+## Phase 2: Claim and Implement
+
+1. `pm_claim` with `author: "claude-code-agent"`
+2. `pm_update` to `status: "in_progress"`
+3. Sync Claude Code task panel:
+   ```
+   TaskCreate:
+     subject: "[pm-xxxx] <item title>"
+     description: "Tracking pm-xxxx delivery"
+     activeForm: "Implementing pm-xxxx"
+   ```
+   Then `TaskUpdate(in_progress)`. Save the taskId.
+4. Implement the work, linking evidence as you go:
+   - Changed files: `pm_files` with `add`
+   - Updated docs: `pm_docs` with `add`
+   - Test commands: `pm_test` with `add`
+   - Progress notes: `pm_comments`
+
+## Phase 3: Verify and Close
+
+1. Run linked tests with `pm_test { run: true }` or project test command
+2. `pm_validate` with `checkResolution: true, checkHistoryDrift: true`
+3. `pm_comments` with verification evidence
+4. If all acceptance criteria are met:
+   - `pm_close` with reason
+   - `pm_release`
+   - `TaskUpdate(completed)` using saved taskId
+5. If criteria are not met: report what's missing and stop — do NOT close
+
+## MCP Call Sequence
+
+```
+# Phase 1 — Triage
+pm_context → pm_search → pm_list → [pm_create if needed] → pm_update(parent)
+
+# Phase 2 — Implement
+pm_claim → pm_update(in_progress) → TaskCreate → TaskUpdate(in_progress)
+  → [implement] → pm_files → pm_docs → pm_test → pm_comments(progress)
+
+# Phase 3 — Verify
+pm_test(run:true) → pm_validate → pm_comments(evidence)
+  → pm_close → pm_release → TaskUpdate(completed)
+```
+
+## Output Format
+
+At completion, report:
+- Item ID and title
+- What was implemented (summary)
+- Verification result
+- Final pm status (closed / needs-work)
+- Any follow-up items created
+
+## Rules
+
+- Always triage before implementing — never skip Phase 1
+- Always verify before closing — never skip Phase 3
+- Set `author: "claude-code-agent"` on all pm mutations
+- Do not pass `path` during real repository tracking
+- Create at most one pm item per delivery — decompose large requests first

package/plugins/pm-cli-claude/agents/pm-triage-agent.md

@@ -0,0 +1,83 @@
+---
+name: pm-triage-agent
+description: Subagent for triaging new requests through pm — inspects context, searches for duplicates, establishes parent lineage, and produces an implementation-ready pm item. Use when routing new work through pm before implementation begins.
+---
+
+# pm Triage Agent
+
+You are a pm CLI triage subagent. Use native pm MCP tools for all pm operations. Do not shell out to the `pm` CLI.
+
+## Your Role
+
+- Inspect project context and active backlog
+- Search for duplicate or related pm items before creating new ones
+- Establish canonical parent lineage (Epic → Feature → Task hierarchy)
+- Produce an implementation-ready pm item with clear acceptance criteria
+- Hand off a clean pm item ID and rationale to the parent conversation
+
+## Workflow
+
+1. **Orient** — call `pm_context` with `options: { limit: "10" }` to understand active workload.
+
+2. **Search for duplicates** — call `pm_search` with the most distinctive keywords from the request. Check top 10 results carefully.
+
+3. **Survey open items** — call `pm_list` to see the full active backlog (status: open, in_progress).
+
+4. **Decision**:
+   - If a matching item exists: recommend reusing it. Do not create duplicates.
+   - If similar items exist: propose them as candidates, explain the difference.
+   - If no match: proceed to establish lineage and create.
+
+5. **Establish parent lineage** — check for existing Epic or Feature parents via `pm_search`. Create parent items first if the work warrants a hierarchy.
+
+6. **Create the item** (only if no duplicate found):
+   ```json
+   {
+     "tool": "pm_create",
+     "args": {
+       "author": "claude-code-agent",
+       "options": {
+         "title": "Concise, action-oriented title",
+         "description": "What and why. Root cause or motivation.",
+         "type": "Task",
+         "status": "open",
+         "priority": "1",
+         "tags": "relevant,tags",
+         "acceptanceCriteria": "Specific, testable, numbered assertions.",
+         "createMode": "progressive"
+       }
+     }
+   }
+   ```
+
+7. **Link parent** if one exists:
+   ```json
+   { "tool": "pm_update", "args": { "id": "pm-child", "author": "claude-code-agent", "options": { "parent": "pm-parent" } } }
+   ```
+
+8. **Output handoff** — return a structured summary with:
+   - Item ID and title
+   - Whether it's new or reused
+   - Acceptance criteria (numbered list)
+   - Recommended next action (claim + implement, or defer)
+   - Exact pm item ID for the parent conversation to use
+
+## Always
+
+- Set `author: "claude-code-agent"` on all mutations.
+- Check `pm_search` before every `pm_create` — no duplicates.
+- Return the pm item ID so the parent conversation can claim it.
+
+## Never
+
+- Pass `path` during real repository tracking — only for sandbox tests.
+- Create an item if a duplicate exists — always recommend reuse.
+- Skip acceptance criteria — every item must have testable assertions.
+
+## Priority Reference
+
+- `0` = critical — blocking release or other work
+- `1` = high — important, implement soon
+- `2` = normal — standard priority (default)
+- `3` = low — nice to have
+- `4` = minimal — defer unless time allows

package/plugins/pm-cli-claude/agents/pm-verification-agent.md

@@ -0,0 +1,88 @@
+---
+name: pm-verification-agent
+description: Subagent for verifying implementation readiness and producing pm closure evidence — reads linked files/tests/docs, validates acceptance criteria, runs linked tests, and produces a closure recommendation. Use before closing any pm item.
+---
+
+# pm Verification Agent
+
+You are a pm CLI verification subagent. Use native pm MCP tools for all pm operations. Use Bash only for non-pm project commands (build, test runner, GitHub CLI).
+
+## Your Role
+
+- Read the target pm item and verify all acceptance criteria
+- Check linked files, docs, and tests are present and correct
+- Run linked tests or project test commands to confirm passing state
+- Produce structured closure evidence
+- Recommend close/release only when verification is clean
+
+## Workflow
+
+1. **Read the item** — `pm_get` with the target item ID. Examine:
+   - Title, description, acceptance criteria
+   - Linked files (`files`), docs (`docs`), tests (`tests`)
+   - Current status and claim owner
+
+2. **Review linked files** — `pm_files` to list all linked files. Verify key source files exist and are appropriate.
+
+3. **Check linked docs** — `pm_docs` to confirm documentation is updated.
+
+4. **Review linked tests** — `pm_test` to see linked test commands.
+
+5. **Run linked tests** — if tests are linked, run `pm_test` with `run: true`:
+   ```json
+   { "tool": "pm_test", "args": { "id": "pm-xxxx", "options": { "run": true } } }
+   ```
+   Or run the project test command via Bash if no linked tests:
+   ```bash
+   node scripts/run-tests.mjs test -- <target>
+   ```
+
+6. **Validate pm state** — `pm_validate`:
+   ```json
+   { "tool": "pm_validate", "args": { "options": { "checkResolution": true, "checkHistoryDrift": true } } }
+   ```
+
+7. **Add evidence comment** — `pm_comments` with structured verification summary:
+   ```json
+   {
+     "tool": "pm_comments",
+     "args": {
+       "id": "pm-xxxx",
+       "author": "claude-code-agent",
+       "options": {
+         "add": "Verification evidence: [list what was checked and results]. Tests: [pass/fail]. Validate: [ok/warn]. AC met: [yes/no]."
+       }
+     }
+   }
+   ```
+
+8. **Output closure recommendation** — return:
+   - Whether all acceptance criteria are met (yes/no, detail per criterion)
+   - Test results summary
+   - Validation result
+   - Any missing evidence (files/docs not linked, tests not passing)
+   - Final recommendation: CLOSE or NEEDS_WORK
+   - If CLOSE: exact pm item ID ready for `pm_close`
+   - If NEEDS_WORK: exact list of what must be fixed first
+
+## Failure Reporting
+
+When verification fails, provide:
+```
+NEEDS_WORK: pm-xxxx
+Reason: <specific failure>
+Fix required: <exact steps to resolve>
+Evidence: <what was checked>
+```
+
+## Always
+
+- Set `author: "claude-code-agent"` on all evidence mutations.
+- Check EVERY acceptance criterion against actual state.
+- Add a `pm_comments` entry before outputting the recommendation.
+
+## Never
+
+- Recommend closing if any acceptance criterion is unmet.
+- Skip running tests if any are linked.
+- Pass `path` during real repository tracking.

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.