@unbrained/pm-cli 2026.5.6 → 2026.5.10

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

@@ -0,0 +1,51 @@
+---
+description: Plan and organize pm work — triage requests, break epics into tasks, prioritize the backlog, and keep the tracker clean. Accepts an optional scope description as argument.
+---
+
+Run the pm planning loop using native MCP tools. Argument: `$ARGUMENTS` (optional: feature/epic description to decompose, or empty to survey and prioritize the backlog).
+
+1. **Survey the backlog**:
+   ```json
+   { "tool": "pm_context", "args": { "options": { "depth": "standard", "limit": "20" } } }
+   { "tool": "pm_list", "args": { "options": { "limit": "50" } } }
+   ```
+
+2. **If `$ARGUMENTS` describes new scope** — triage it:
+   - `pm_search` with the most distinctive keywords to check for duplicates.
+   - If no match, proceed to create. If match found, show it and ask: duplicate or related?
+
+3. **Decompose** (if creating new scope):
+   - Create Epic (if the scope spans multiple features)
+   - Create child Features/Tasks with `parent` links
+   - Use `pm_create` with `createMode: "progressive"` for each
+
+4. **Sync to Claude Code task panel** for any item you claim this session:
+   ```
+   TaskCreate:
+     subject: "[pm-xxxx] Plan: <title>"
+     description: "Planning scope for pm-xxxx"
+     activeForm: "Planning pm-xxxx"
+   ```
+   Call `TaskUpdate(in_progress)`. Save taskId.
+
+5. **Prioritize** — review open items and update priorities with `pm_update`:
+   - `0` = critical, `1` = high, `2` = normal, `3` = low, `4` = minimal
+
+6. **Link parents** for all child items:
+   ```json
+   { "tool": "pm_update", "args": { "id": "pm-child", "author": "claude-code-agent", "options": { "parent": "pm-epic" } } }
+   ```
+
+7. **Validate** after batch creates:
+   ```json
+   { "tool": "pm_validate", "args": { "options": { "checkResolution": true } } }
+   ```
+
+8. **Dedupe check**:
+   ```json
+   { "tool": "pm_run", "args": { "action": "dedupe-audit", "options": { "mode": "parent_scope", "limit": "20" } } }
+   ```
+
+9. If you claimed a planning item: `pm_close` it, `pm_release`, then `TaskUpdate(completed)`.
+
+10. **Report** — list all created/updated items with their IDs, types, priorities, and parent links.

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

@@ -0,0 +1,41 @@
+---
+description: Run pm release-readiness — validation, coverage gate, changelog check, GitHub CI verification — with live TUI tracking. Accepts an optional version or release item ID as argument.
+---
+
+Run the full pm release workflow using native MCP tools. Argument: `$ARGUMENTS` (optional: version like `v1.2.3`, or pm item ID for an existing release item).
+
+1. **Find or create the release item**:
+   - `pm_search` with query "release" to find existing release items.
+   - If `$ARGUMENTS` is a pm ID: `pm_get` it directly.
+   - If no match: `pm_create` with `type: "Chore"`, `title: "Release <version>"`, `priority: "0"`.
+2. **Claim** with `pm_claim` and `author: "claude-code-agent"`.
+3. **Sync to Claude Code task panel**:
+   ```
+   TaskCreate:
+     subject: "[pm-xxxx] Release: <version>"
+     description: "Release gate tracking — pm-xxxx"
+     activeForm: "Running release gates"
+   ```
+   Call `TaskUpdate(in_progress)`. Save the taskId.
+4. **Link release artifacts**:
+   - `pm_docs` — link `CHANGELOG.md`
+   - `pm_files` — link `package.json`
+5. **Run gates** (all must pass before tagging):
+   - `pnpm build`
+   - `node scripts/run-tests.mjs coverage`
+   - `pm_validate` with `checkResolution: true, checkHistoryDrift: true, checkFiles: true`
+   - `pm_health`
+   - `node scripts/release/run-gates.mjs` (if present)
+6. **Record gate results** with `pm_comments`:
+   ```
+   "Release evidence: build ok. N tests pass. 100% coverage. pm validate ok. pm health ok."
+   ```
+7. **Tag and push** (if all gates pass):
+   ```bash
+   git tag v<version> && git push origin v<version>
+   ```
+8. **Verify CI** — `gh run list --limit 5` and confirm all checks are green.
+9. **Post-CI evidence** — add a final `pm_comments` with CI run URL.
+10. **Close** — `pm_close` with reason, `pm_release`, then `TaskUpdate(completed)`.
+
+Do not tag if any gate fails. Report the failing gate and what's needed to fix it.

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

@@ -0,0 +1,21 @@
+---
+description: Search pm items by keywords, tags, status, or type — returns ranked results with context. Pass the search query as argument.
+---
+
+Search pm items using native MCP tools. Query: `$ARGUMENTS`
+
+1. **Parse the query** — extract key terms from `$ARGUMENTS`. If empty, ask the user what to search for.
+2. **Run primary search** — call `pm_search` with the query:
+   ```json
+   { "tool": "pm_search", "args": { "query": "$ARGUMENTS", "options": { "limit": "15" } } }
+   ```
+3. **If query includes a status filter** (e.g. "open bugs", "blocked", "in progress") — also call `pm_list` with the matching status filter:
+   ```json
+   { "tool": "pm_list", "args": { "options": { "status": "blocked", "limit": "20" } } }
+   ```
+4. **Present results** — show each matching item as:
+   - `[pm-xxxx]` **Title** (status, type, priority)
+   - One line of description if relevant
+5. **Offer to start, update, or triage** — after showing results, ask if the user wants to claim an item or create a new one if nothing matches.
+
+Keep results concise — title + status + type per line. Group by status if there are many results.

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

@@ -0,0 +1,27 @@
+---
+description: Start a pm-tracked task — orient, find or create the right item, claim it, sync to TUI, and link initial scope. Accepts an optional item ID or keywords as argument.
+---
+
+Use native pm MCP tools to start a tracked task. Argument: `$ARGUMENTS` (item ID like `pm-xxxx`, or keywords to search, or empty to use context).
+
+1. **Orient** — call `pm_context` with `options: { limit: "10" }`.
+2. **Find the item**:
+   - If `$ARGUMENTS` looks like an ID (starts with `pm-`): call `pm_get` with that ID.
+   - If `$ARGUMENTS` has keywords: call `pm_search` with those keywords.
+   - If empty: call `pm_list` to show open items and ask the user which to start.
+3. **Claim** the selected item with `pm_claim` and `author: "claude-code-agent"`.
+4. **Update status** with `pm_update` to `status: "in_progress"`.
+5. **Sync to Claude Code task panel** — call `TaskCreate`:
+   ```
+   TaskCreate:
+     subject: "[pm-xxxx] <item title>"
+     description: "Tracking pm item pm-xxxx. AC: <acceptance_criteria if set>"
+     activeForm: "Implementing pm-xxxx"
+   ```
+   Then call `TaskUpdate` with `status: "in_progress"` using the returned taskId.
+6. **Add a start comment** with `pm_comments`: `"Starting work. Scope: <brief description of planned approach>."`
+7. **Report** the claimed item's title, ID, and acceptance criteria.
+
+If no matching item exists and the user wants to create one, collect title + description + type then call `pm_create` — then proceed from step 3.
+
+The Claude Code task panel will now show the item with a spinner. Use `/pm-close-task pm-xxxx` when done to close both pm and the panel entry.

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

@@ -0,0 +1,15 @@
+---
+description: Show a compact pm project status snapshot — active items, blocked work, and upcoming deadlines.
+---
+
+Use native pm MCP tools to show project status:
+
+1. Call `pm_context` with `options: { limit: "10", depth: "standard" }` to get the active work snapshot.
+2. Call `pm_run` with `action: "calendar"` and `options: { view: "week", format: "markdown", include: "deadlines,reminders" }` to show upcoming events.
+3. Present a compact summary:
+   - Count items by status (in_progress / open / blocked)
+   - List the top 3 active items with title, assignee, and deadline
+   - Note any overdue or blocked items
+   - Show the next 3 calendar events if any
+
+Keep the response concise — under 300 words unless there are many items. Do not show closed or canceled items.

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

@@ -0,0 +1,35 @@
+---
+description: Triage a new request through pm — check for duplicates, create canonical parent lineage if needed, and produce a scoped child item with acceptance criteria. Pass the request description as argument.
+---
+
+Use native pm MCP tools to triage a request into pm tracking. Request: `$ARGUMENTS`
+
+1. **Duplicate check** — `pm_search` with the most distinctive keywords from the request. Check first 10 results.
+2. **Context** — `pm_context` to understand current workload and priorities.
+3. **Decision**:
+   - If a matching item exists: show it and ask if this is a duplicate or a related new item.
+   - If no match: proceed to create.
+4. **Parent lineage** — for net-new scope, check if there's an Epic or Feature parent. Create parent items if needed before the child.
+5. **Create the item**:
+   ```json
+   {
+     "tool": "pm_create",
+     "args": {
+       "author": "claude-code-agent",
+       "options": {
+         "title": "Concise, action-oriented title",
+         "description": "What and why, one paragraph.",
+         "type": "Task",
+         "status": "open",
+         "priority": "1",
+         "tags": "relevant,tags",
+         "acceptanceCriteria": "Specific, testable criteria.",
+         "createMode": "progressive"
+       }
+     }
+   }
+   ```
+6. **Link parent** if one exists: `pm_update` with `options: { parent: "pm-xxxx" }`.
+7. **Report** the created item ID, title, and acceptance criteria.
+
+Keep the item scoped — one work unit per item. Break large requests into Epic → Feature → Task hierarchy.

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

@@ -0,0 +1,49 @@
+---
+description: Run the pm workflow loop — orient, claim, track, and close a pm item — with full hybrid TUI display. Accepts an optional item ID or description as argument.
+---
+
+Run the pm workflow loop using native MCP tools. Argument: `$ARGUMENTS` (item ID, keywords, or description of new work).
+
+This is the general-purpose pm workflow command. For specialized loops use:
+- `/pm-developer` — implementation/coding work
+- `/pm-release` — release gates and publishing
+- `/pm-planner` — backlog planning and decomposition
+- `/pm-audit` — tracker health audit
+
+**Steps:**
+
+1. **Orient**:
+   ```json
+   { "tool": "pm_context", "args": { "options": { "limit": "10" } } }
+   ```
+
+2. **Find or create the item** from `$ARGUMENTS`:
+   - pm ID → `pm_get`
+   - Keywords → `pm_search` then pick the best match
+   - Description of new work → `pm_search` first, then `pm_create` if no duplicate
+
+3. **Claim** with `pm_claim` + `author: "claude-code-agent"`, then `pm_update` to `in_progress`.
+
+4. **Sync to Claude Code task panel**:
+   ```
+   TaskCreate:
+     subject: "[pm-xxxx] <item title>"
+     description: "Tracking pm-xxxx"
+     activeForm: "Working on pm-xxxx"
+   ```
+   Call `TaskUpdate(in_progress)`. Save taskId for this session.
+
+5. **Do the work** — link evidence as you go:
+   - Changed files: `pm_files`
+   - Updated docs: `pm_docs`
+   - Test commands: `pm_test`
+   - Progress notes: `pm_comments`
+
+6. **Verify** — `pm_validate` before closing.
+
+7. **Close**:
+   - `pm_close` with reason addressing acceptance criteria
+   - `pm_release`
+   - `TaskUpdate(completed)` using saved taskId
+
+Report the item ID, title, and final status at the end.

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

@@ -0,0 +1,17 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.mjs\"",
+            "timeout": 8,
+            "async": true
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/pm-cli-claude/hooks/session-start.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * pm-cli Claude Code session-start hook.
+ *
+ * Injects a brief pm context summary into the session when pm is initialized
+ * in the current workspace. Exits silently if pm is not set up.
+ */
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const workspace = process.cwd();
+const pmSettingsPath = join(workspace, ".agents", "pm", "settings.json");
+
+if (!existsSync(pmSettingsPath)) {
+  process.exit(0);
+}
+
+try {
+  const raw = execSync("pm context --limit 5 --json", {
+    cwd: workspace,
+    encoding: "utf-8",
+    timeout: 5000,
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+
+  const ctx = JSON.parse(raw);
+  const { summary } = ctx;
+  if (!summary) {
+    process.exit(0);
+  }
+
+  const parts = [];
+  if (summary.in_progress > 0) parts.push(`${summary.in_progress} in_progress`);
+  if (summary.open > 0) parts.push(`${summary.open} open`);
+  if (summary.blocked > 0) parts.push(`${summary.blocked} BLOCKED`);
+
+  if (parts.length === 0) {
+    process.exit(0);
+  }
+
+  const topItems = [...(ctx.high_level ?? []), ...(ctx.low_level ?? [])].slice(0, 3);
+  const itemLines = topItems
+    .map((item) => `  • [${item.id}] ${item.title} (${item.status})`)
+    .join("\n");
+
+  process.stdout.write(
+    `pm tracker: ${parts.join(", ")}\n` +
+      (itemLines ? `${itemLines}\n` : "") +
+      `Use pm_context tool or /pm-status for full details.\n`,
+  );
+} catch {
+  // pm unavailable, not initialized, or timed out — exit silently
+  process.exit(0);
+}

package/plugins/pm-cli-claude/scripts/pm-mcp-server.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * pm-cli native MCP server launcher for Claude Code.
+ *
+ * Resolution order:
+ * 1. PM_CLI_MCP_SERVER env var (explicit path)
+ * 2. dist/mcp/server.js walking up from this file (repo checkout)
+ * 3. npx -y @unbrained/pm-cli@latest pm-mcp (installed via npm)
+ */
+import { spawn } from "node:child_process";
+import { access } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+async function exists(target) {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function findRepoServer() {
+  let cursor = here;
+  for (let depth = 0; depth < 10; depth += 1) {
+    const candidate = path.join(cursor, "dist", "mcp", "server.js");
+    if (await exists(candidate)) {
+      return candidate;
+    }
+    const parent = path.dirname(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+  return null;
+}
+
+const explicitServer = process.env.PM_CLI_MCP_SERVER;
+if (explicitServer && (await exists(explicitServer))) {
+  await import(pathToFileURL(explicitServer).href);
+} else {
+  const repoServer = await findRepoServer();
+  if (repoServer) {
+    await import(pathToFileURL(repoServer).href);
+  } else {
+    const child = spawn("npx", ["-y", "--package=@unbrained/pm-cli@latest", "pm-mcp"], {
+      stdio: "inherit",
+      env: process.env,
+    });
+    child.on("exit", (code, signal) => {
+      if (signal) {
+        process.kill(process.pid, signal);
+        return;
+      }
+      process.exit(code ?? 1);
+    });
+  }
+}

package/plugins/pm-cli-claude/skills/pm-audit/SKILL.md

@@ -0,0 +1,88 @@
+---
+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.
+---
+
+# pm Audit
+
+Use for comprehensive repository audits, consistency reviews, and health diagnostics.
+
+## Audit Flow
+
+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.
+7. **Dedupe review** — `pm_run` with `action: "dedupe-audit"`.
+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": "dedupe-audit", "options": { "mode": "parent_scope", "limit": "20" } } }
+{ "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" } } }
+{ "tool": "pm_run", "args": { "action": "comments-audit", "options": { "limit": "20" } } }
+```
+
+### 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",
+    "author": "claude-code-agent",
+    "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`.

package/plugins/pm-cli-claude/skills/pm-developer/SKILL.md

@@ -0,0 +1,116 @@
+---
+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.
+---
+
+# 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", "author": "claude-code-agent" } }
+{ "tool": "pm_update", "args": { "id": "pm-xxxx", "author": "claude-code-agent", "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", "author": "claude-code-agent", "options": { "add": ["path=src/file.ts,scope=project,note=implementation"] } } }
+{ "tool": "pm_docs", "args": { "id": "pm-xxxx", "author": "claude-code-agent", "options": { "add": ["path=docs/GUIDE.md,scope=project,note=updated"] } } }
+{ "tool": "pm_test", "args": { "id": "pm-xxxx", "author": "claude-code-agent", "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", "author": "claude-code-agent", "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.", "author": "claude-code-agent" } }
+{ "tool": "pm_release", "args": { "id": "pm-xxxx", "author": "claude-code-agent" } }
+```
+
+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": {
+    "author": "claude-code-agent",
+    "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.