@unbrained/pm-cli 2026.5.10 → 2026.5.12

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,12 @@
  * 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 the published pm CLI through npx without
+ * requiring a global install. Exits silently if pm is not set up.
  */
-import { execSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { execSync } from "node:child_process";
 
 const workspace = process.cwd();
 const pmSettingsPath = join(workspace, ".agents", "pm", "settings.json");
@@ -16,40 +17,53 @@ 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);
+function formatSummary(ctx) {
   const { summary } = ctx;
-  if (!summary) {
-    process.exit(0);
-  }
+  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`
   );
+}
+
+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 = 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);
 }

package/.agents/pm/extensions/.managed-extensions.json

@@ -1,42 +0,0 @@
-{
-  "version": 1,
-  "updated_at": "2026-04-25T17:01:49.273Z",
-  "entries": [
-    {
-      "name": "builtin-beads-import",
-      "directory": "beads",
-      "scope": "project",
-      "manifest_version": "0.1.0",
-      "manifest_entry": "./index.js",
-      "capabilities": [
-        "commands",
-        "schema"
-      ],
-      "installed_at": "2026-04-25T17:01:49.268Z",
-      "updated_at": "2026-04-25T17:01:49.268Z",
-      "source": {
-        "kind": "local",
-        "input": "builtin-beads-import",
-        "location": ".agents/pm/extensions/beads"
-      }
-    },
-    {
-      "name": "builtin-todos-import-export",
-      "directory": "todos",
-      "scope": "project",
-      "manifest_version": "0.1.0",
-      "manifest_entry": "./index.js",
-      "capabilities": [
-        "commands",
-        "schema"
-      ],
-      "installed_at": "2026-04-25T17:01:49.268Z",
-      "updated_at": "2026-04-25T17:01:49.268Z",
-      "source": {
-        "kind": "local",
-        "input": "builtin-todos-import-export",
-        "location": ".agents/pm/extensions/todos"
-      }
-    }
-  ]
-}

package/.agents/skills/HARNESS_COMPATIBILITY.md

@@ -1,45 +0,0 @@
-# Harness Compatibility
-
-This repository supports the following harnesses through shared docs and `.agents/skills` workflows only (no harness-specific runtime code):
-
-- Pi coding agent
-- OpenClaw
-- Claude Code
-- Codex CLI
-- OpenCode
-- Amp
-- Droid
-- Hermes
-- Gemini CLI
-
-## Progressive-Disclosure Route
-
-Use the same low-token route in every harness:
-
-1. `pm guide` (topic index)
-2. `pm guide <topic>` (focused route)
-3. `pm guide <topic> --depth standard|deep` (details only when needed)
-4. `pm contracts --command <command> --flags-only --json` (strict machine flags)
-
-## Harness Mapping
-
-| Harness | Preferred prompt/doc entrypoint | Skill route |
-|---------|----------------------------------|-------------|
-| Pi coding agent | `AGENTS.md` + `pm guide workflows` | `.agents/skills/pm-developer/SKILL.md` |
-| OpenClaw | repository docs + `pm guide` | `.agents/skills/pm-user/SKILL.md` |
-| Claude Code | repository docs + `pm guide skills` | `.agents/skills/pm-developer/SKILL.md` |
-| Codex CLI | repository docs + `pm guide commands` | `.agents/skills/pm-developer/SKILL.md` |
-| OpenCode | repository docs + `pm guide quickstart` | `.agents/skills/pm-user/SKILL.md` |
-| Amp | repository docs + `pm guide workflows` | `.agents/skills/pm-user/SKILL.md` |
-| Droid | repository docs + `pm guide extensions` | `.agents/skills/pm-extensions/SKILL.md` |
-| Hermes | repository docs + `pm guide sdk` | `.agents/skills/pm-sdk/SKILL.md` |
-| Gemini CLI | repository docs + `pm guide commands` | `.agents/skills/pm-user/SKILL.md` |
-
-## Verification
-
-Before release, run:
-
-```bash
-pm guide skills --depth standard
-node scripts/release/docs-skills-gate.mjs
-```

package/.agents/skills/README.md

@@ -1,21 +0,0 @@
-# pm Agent Skills
-
-This directory contains `agentskills.io`-style skills for `pm` workflows.
-
-Start with:
-
-```bash
-pm guide skills
-pm guide harnesses --depth standard
-```
-
-Skill bundles:
-
-- `pm-developer` - implementation loop for coding agents.
-- `pm-user` - operator workflow for planning and task routing.
-- `pm-extensions` - extension lifecycle, diagnostics, and release-safe updates.
-- `pm-sdk` - SDK and integration workflows.
-
-Compatibility routing:
-
-- [Harness compatibility matrix](HARNESS_COMPATIBILITY.md)

package/.agents/skills/pm-developer/SKILL.md

@@ -1,73 +0,0 @@
----
-name: pm-developer
-description: Runs the pm-cli developer execution loop (orient, claim, implement, verify, close) with linked files/tests/docs evidence. Use when coding, debugging, refactoring, or shipping repository changes tracked in pm items.
-license: MIT
-compatibility: Works in terminal-based coding agents with bash, Node.js, and pnpm.
-metadata:
-  owner: unbrained
-  domain: pm-cli
-  scope: developer-workflow
----
-
-# pm Developer Skill
-
-Use this skill for implementation work that changes code, docs, tests, or release gates.
-
-## Quick Start
-
-```bash
-pm context --limit 10
-pm search "<task keywords>" --limit 10
-pm list-open --limit 20
-pm claim <ID>
-pm update <ID> --status in_progress
-pm guide workflows
-```
-
-## Canonical Workflow
-
-1. **Orient**: pick an existing item when possible.
-2. **Claim**: claim before substantial edits.
-3. **Link context**: attach changed files/tests/docs while implementing.
-4. **Verify**: run linked tests plus local quality gates.
-5. **Close with evidence**: append what changed and what passed.
-6. **Release claim**: release when paused, handed off, or closed.
-
-## Workflow Prompts
-
-Use one prompt template, then execute only the minimum required commands.
-
-### Prompt: Implement Scoped Change
-
-`Implement the requested change on <ID>. Keep edits scoped, link files/tests/docs, run targeted verification, and record closure evidence before releasing claim.`
-
-### Prompt: Debug Regression
-
-`Investigate failing behavior for <ID>. Reproduce first, add or update regression tests, patch root cause, and append evidence with exact command outputs.`
-
-### Prompt: Documentation + Code Sync
-
-`Update implementation and docs together for <ID>. Ensure docs route through pm guide topics and verify command examples still match pm contracts output.`
-
-## Required Evidence Commands
-
-```bash
-pm files <ID> --add path=<path>,scope=project,note="<reason>"
-pm test <ID> --add command="node scripts/run-tests.mjs test -- <target>",scope=project,timeout_seconds=240
-pm docs <ID> --add path=<doc>,scope=project,note="<reason>"
-pm comments <ID> "Evidence: <what changed + tests run>"
-```
-
-## Verification Defaults
-
-```bash
-pnpm build
-node scripts/run-tests.mjs test -- <targets>
-node scripts/run-tests.mjs coverage
-pm validate --check-resolution --check-history-drift
-```
-
-## Progressive Disclosure References
-
-- [Developer command playbook](references/COMMAND_PLAYBOOK.md)
-- [Prompt templates and examples](references/PROMPTS.md)

package/.agents/skills/pm-developer/references/COMMAND_PLAYBOOK.md

@@ -1,48 +0,0 @@
-# Developer Command Playbook
-
-## Session Bootstrap (Maintainer Run)
-
-```bash
-npm install -g .
-pm --version
-node -v
-pnpm -v
-pnpm build
-```
-
-## Item Lifecycle
-
-```bash
-pm context --limit 10
-pm search "<keywords>" --limit 10
-pm list-open --limit 20
-pm claim <ID>
-pm update <ID> --status in_progress --description "..."
-pm append <ID> --body "Implementation notes"
-```
-
-## Evidence Linking
-
-```bash
-pm files <ID> --add path=src/<file>.ts,scope=project,note="implementation"
-pm docs <ID> --add path=docs/<doc>.md,scope=project,note="public docs update"
-pm test <ID> --add command="node scripts/run-tests.mjs test -- tests/unit/<file>.spec.ts",scope=project,timeout_seconds=240
-```
-
-## Close Workflow
-
-```bash
-pm test <ID> --run --progress
-node scripts/run-tests.mjs coverage
-pm comments <ID> "Evidence: linked tests passed; coverage remained green."
-pm close <ID> "Acceptance criteria met with verification evidence." --validate-close warn
-pm release <ID>
-```
-
-## Local Docs Routing
-
-```bash
-pm guide workflows
-pm guide commands --depth standard
-pm guide release --json
-```

package/.agents/skills/pm-developer/references/PROMPTS.md

@@ -1,17 +0,0 @@
-# Prompt Templates
-
-## Implement Feature
-
-`Implement <feature> on <ID>. Reuse existing architecture, link all changed files/tests/docs, run targeted + coverage checks, and append evidence before close.`
-
-## Fix Bug
-
-`Fix <bug> on <ID>. Add a regression test, keep the patch minimal, run focused tests first, then full gate commands if scope expands.`
-
-## Refactor
-
-`Refactor <area> on <ID> without behavior changes. Preserve API contracts, update docs where command behavior is clarified, and validate with existing regression suite.`
-
-## Release Readiness Sweep
-
-`Perform release readiness checks for <ID>. Run build, coverage, static quality, secret scan, and release gates. Document all results in a closure comment.`

package/.agents/skills/pm-extensions/SKILL.md

@@ -1,57 +0,0 @@
----
-name: pm-extensions
-description: Manages pm-cli extension lifecycle operations (explore, install, activate, diagnose, and release-safe validation). Use when building, integrating, or troubleshooting pm extensions and extension-provided commands.
-license: MIT
-compatibility: Requires pm extension commands and local project/global extension directories.
-metadata:
-  owner: unbrained
-  domain: pm-cli
-  scope: extension-workflow
----
-
-# pm Extensions Skill
-
-Use this skill when the request touches extension install, activation, command registration, diagnostics, or extension governance.
-
-## Quick Start
-
-```bash
-pm guide extensions
-pm extension explore --project
-pm extension manage --detail summary
-pm extension doctor --detail deep
-```
-
-## Lifecycle Workflow
-
-1. **Inspect state first** (`explore`, `manage`, `doctor`).
-2. **Apply lifecycle mutation** (`install`, `adopt`, `activate`, `deactivate`, `uninstall`).
-3. **Verify command/action exposure** with `pm contracts`.
-4. **Record evidence** in linked `pm` items.
-
-## Workflow Prompts
-
-### Prompt: Diagnose Extension Failure
-
-`Diagnose extension activation issues using pm extension explore/manage/doctor before making lifecycle changes. Report root cause and minimal remediation commands.`
-
-### Prompt: Install and Validate Extension
-
-`Install <extension> in project scope, validate with doctor diagnostics, and confirm command/action availability using pm contracts runtime output.`
-
-### Prompt: Safe Deactivation
-
-`Deactivate or uninstall <extension> with rollback-safe sequencing and explicit evidence of which commands/actions are removed.`
-
-## Contract Verification
-
-```bash
-pm contracts --command extension --flags-only
-pm contracts --runtime-only --availability-only
-pm contracts --command <extension-command> --flags-only
-```
-
-## Progressive Disclosure References
-
-- [Extension lifecycle recipes](references/LIFECYCLE.md)
-- [Troubleshooting playbook](references/TROUBLESHOOTING.md)