@unbrained/pm-cli 2026.5.10 → 2026.5.11

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

@@ -1,7 +1,7 @@
 {
   "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",
+  "description": "Native pm CLI integration for Claude Code — 18 MCP tools, 5 workflow skills, 14 slash commands, 3 subagents (coordinator, triage, verification), hybrid TUI task tracking (pm as persistent store + Claude Code task panel as live view), session context injection, and full git-based project management without leaving Claude Code.",
+  "version": "1.3.0",
   "author": {
     "name": "unbrained",
     "url": "https://github.com/unbraind/pm-cli"

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

@@ -1,6 +1,6 @@
 # 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.
+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
 
@@ -9,29 +9,37 @@ Native pm CLI integration for Claude Code. Use pm project management tools direc
 | **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 |
-| **pm-coordinator agent** | Subagent for coordinating multi-item and batch operations |
+| **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 (recommended)
+### Option A: Plugin marketplace — canonical install (recommended)
 
 ```
-/plugin install pm-cli@pm-cli
+/plugin install pm-cli@pm
 ```
 
-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):
+First time: add the marketplace if it's not configured yet:
 
 ```bash
 claude plugin marketplace add /path/to/pm-cli
-# or from GitHub:
+# or after npm publish:
 # claude plugin marketplace add unbraind/pm-cli
 ```
 
-### Option B: Global MCP server via Claude Code CLI (MCP tools only)
+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
@@ -39,9 +47,9 @@ claude mcp add --transport stdio pm-cli-native -- npx -y @unbrained/pm-cli pm-mc
 
 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)
+### Option D: Direct `.mcp.json` (project-scoped MCP only)
 
-Add to your project's `.mcp.json` for MCP tools in a single project:
+Add to your project's `.mcp.json`:
 
 ```json
 {
@@ -70,6 +78,9 @@ Start working on the authentication bug.
 
 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
@@ -116,6 +127,20 @@ This means you get full history in pm (survives restarts, visible in `pm list`)
 | `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)
@@ -163,6 +188,22 @@ All skills and commands implement this pattern for every claimed item:
    → [✔ 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.
@@ -173,12 +214,12 @@ All skills and commands implement this pattern for every claimed item:
 ## Requirements
 
 - Node.js ≥ 20
-- pm CLI available via npx (auto-resolved) or installed globally: `npm install -g @unbrained/pm-cli`
+- 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)
-- [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)
+- [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-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/hooks/session-start.mjs

@@ -3,11 +3,15 @@
  * 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.
+ * 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 { execSync } from "node:child_process";
+import { access } from "node:fs/promises";
 import { existsSync } from "node:fs";
-import { join } from "node:path";
+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");
@@ -16,40 +20,101 @@ 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 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) {
-    process.exit(0);
-  }
+  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");
 
-  process.stdout.write(
+  return (
     `pm tracker: ${parts.join(", ")}\n` +
-      (itemLines ? `${itemLines}\n` : "") +
-      `Use pm_context tool or /pm-status for full details.\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 {
-  // pm unavailable, not initialized, or timed out — exit silently
+  // Any failure: exit silently
   process.exit(0);
 }