@unbrained/pm-cli 2026.5.6 → 2026.5.11

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.

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,120 @@
+#!/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. Uses native pm modules when available (repo checkout
+ * or dist/); falls back to npx @unbrained/pm-cli without requiring the CLI to
+ * be installed globally. Exits silently if pm is not set up.
+ */
+import { access } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { execSync } from "node:child_process";
+
+const workspace = process.cwd();
+const pmSettingsPath = join(workspace, ".agents", "pm", "settings.json");
+
+if (!existsSync(pmSettingsPath)) {
+  process.exit(0);
+}
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+async function pathExists(target) {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function findNativeModule() {
+  let cursor = here;
+  for (let depth = 0; depth < 10; depth += 1) {
+    const candidate = join(cursor, "dist", "pi", "native.js");
+    if (await pathExists(candidate)) {
+      return candidate;
+    }
+    const parent = dirname(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+  return null;
+}
+
+function formatSummary(ctx) {
+  const { summary } = ctx;
+  if (!summary) return null;
+
+  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) return null;
+
+  const topItems = [...(ctx.high_level ?? []), ...(ctx.low_level ?? [])].slice(0, 3);
+  const itemLines = topItems
+    .map((item) => `  • [${item.id}] ${item.title} (${item.status})`)
+    .join("\n");
+
+  return (
+    `pm tracker: ${parts.join(", ")}\n` +
+    (itemLines ? `${itemLines}\n` : "") +
+    `Use pm_context tool or /pm-status for full details.\n`
+  );
+}
+
+async function tryNativeContext() {
+  const nativePath = await findNativeModule();
+  if (!nativePath) return null;
+
+  try {
+    const { runNativePmAction } = await import(pathToFileURL(nativePath).href);
+    const result = await runNativePmAction({
+      action: "context",
+      cwd: workspace,
+      json: true,
+      options: { limit: "5" },
+    });
+    const text = Array.isArray(result?.content)
+      ? result.content.find((p) => p?.type === "text")?.text ?? ""
+      : typeof result === "string"
+        ? result
+        : JSON.stringify(result);
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function tryNpxContext() {
+  try {
+    const raw = execSync(
+      "npx -y --package=@unbrained/pm-cli@latest pm context --limit 5 --json",
+      {
+        cwd: workspace,
+        encoding: "utf-8",
+        timeout: 15000,
+        stdio: ["ignore", "pipe", "ignore"],
+      },
+    );
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+try {
+  const ctx = (await tryNativeContext()) ?? tryNpxContext();
+  if (!ctx) process.exit(0);
+
+  const message = formatSummary(ctx);
+  if (message) process.stdout.write(message);
+} catch {
+  // Any failure: 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`.