@unbrained/pm-cli 2026.5.6 → 2026.5.10

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

@@ -0,0 +1,118 @@
+---
+name: pm-planner
+description: Plan and organize pm CLI work — triage requests, break epics into tasks, prioritize the backlog, and keep the tracker clean. Use when decomposing features, planning sprints, or organizing incoming requests.
+---
+
+# pm Planner
+
+Use this skill when decomposing features, organizing backlogs, triaging incoming work, or planning multi-item projects.
+
+## Planning Loop
+
+1. **Survey** — `pm_context` then `pm_list` with no filter to see the full active backlog.
+2. **Deduplicate** — `pm_search` before every create to avoid duplicate items.
+3. **Decompose** — break large items into Epic → Feature → Task hierarchy.
+4. **Prioritize** — use `pm_update` to set priority (`0`=critical … `4`=minimal).
+5. **Link parents** — always set `parent` on child items via `pm_update`.
+6. **Sync TUI** — call `TaskCreate` for any item you claim during this session (see Hybrid TUI Sync).
+7. **Validate** — `pm_validate` after batch creates to check consistency.
+
+## Hybrid TUI Sync
+
+pm is the **persistent store**. Claude Code's task panel is the **live session view**.
+
+When you claim a planning item or start active decomposition work:
+```
+TaskCreate:
+  subject: "[pm-xxxx] Plan: <epic/feature title>"
+  description: "Planning pm-xxxx — decomposing into child items"
+  activeForm: "Planning pm-xxxx"
+```
+Save the `taskId`. Call `TaskUpdate(in_progress)` when active.
+Call `TaskUpdate(completed)` when the planning item is closed.
+
+## MCP Call Patterns
+
+### Survey the Backlog
+```json
+{ "tool": "pm_context", "args": { "options": { "depth": "standard", "limit": "20" } } }
+{ "tool": "pm_list", "args": { "options": { "limit": "50" } } }
+```
+
+### Deduplicate Before Creating
+```json
+{ "tool": "pm_search", "args": { "query": "feature keywords", "options": { "limit": "10" } } }
+```
+
+### Create Epic → Feature → Task Hierarchy
+```json
+{
+  "tool": "pm_create",
+  "args": {
+    "author": "claude-code-agent",
+    "options": {
+      "title": "Epic: Authentication system overhaul",
+      "type": "Epic",
+      "status": "open",
+      "priority": "1",
+      "description": "High-level initiative description.",
+      "createMode": "progressive"
+    }
+  }
+}
+```
+Then for each child feature/task, set `parent: "pm-xxxx"` via `pm_update`.
+
+### Prioritize the Backlog
+```json
+{ "tool": "pm_list", "args": { "options": { "status": "open", "limit": "30" } } }
+{ "tool": "pm_update", "args": { "id": "pm-xxxx", "author": "claude-code-agent", "options": { "priority": "0" } } }
+```
+
+### Link Parent
+```json
+{ "tool": "pm_update", "args": { "id": "pm-child", "author": "claude-code-agent", "options": { "parent": "pm-epic" } } }
+```
+
+### Run Dedupe Audit After Batch Work
+```json
+{ "tool": "pm_run", "args": { "action": "dedupe-audit", "options": { "mode": "parent_scope", "limit": "20" } } }
+```
+
+### Validate After Batch Creates
+```json
+{ "tool": "pm_validate", "args": { "options": { "checkResolution": true } } }
+```
+
+## Item Type Guide
+
+| Type | When to use |
+|------|------------|
+| `Epic` | Large initiative spanning multiple features (weeks/months) |
+| `Feature` | Distinct capability under an epic (days) |
+| `Task` | Atomic unit of implementation work (hours) |
+| `Bug` | Defect with reproduce steps |
+| `Story` | User-facing narrative unit |
+
+## Priority Reference
+
+- `0` = critical — blocking release or other work
+- `1` = high — important, should be done soon
+- `2` = normal — standard priority (default)
+- `3` = low — nice to have
+- `4` = minimal — defer unless time allows
+
+## Acceptance Criteria Best Practice
+
+Write AC as numbered, testable assertions:
+1. Given [precondition], when [action], then [result].
+2. All existing tests pass.
+3. Coverage gate maintained.
+
+Set via `pm_create` with `acceptanceCriteria` field or `pm_update` with `options.acceptanceCriteria`.
+
+## Safety
+
+- Never pass `path` during real repository tracking.
+- Always `pm_search` before `pm_create` — avoid duplicates.
+- Run `pm_validate` after batch changes.

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

@@ -0,0 +1,83 @@
+---
+name: pm-release
+description: Run pm-cli release-readiness workflows — validation, coverage gates, changelog, GitHub checks — using native MCP tools with linked evidence. Use when preparing releases, publishing, or verifying post-release state.
+---
+
+# pm Release
+
+Use for release preparation, publication, and post-release verification.
+
+## Release Loop
+
+1. **Find or create** the release pm item (after duplicate check with `pm_search`).
+2. **Claim** it — then call `TaskCreate` to show the release in Claude Code's task panel.
+3. **Run local gates** before tagging:
+   - `pnpm build` — clean build
+   - `node scripts/run-tests.mjs coverage` — full coverage gate
+   - `pm_validate` with all checks
+   - `pm_health` for tracker status
+4. **Tag and push** — let CI run.
+5. **Verify GitHub checks** — `gh run list --limit 5` after push.
+6. **Record evidence** with `pm_comments`.
+7. **Close and release** the pm item, then `TaskUpdate(completed)`.
+
+## Hybrid TUI Sync
+
+### After claiming the release item
+```
+TaskCreate:
+  subject: "[pm-xxxx] Release: <version>"
+  description: "Release gate tracking for pm-xxxx"
+  activeForm: "Running release gates"
+```
+Save the `taskId`. Then `TaskUpdate(in_progress)`.
+
+### After pm_close + pm_release
+```
+TaskUpdate: { taskId: <saved>, status: "completed" }
+```
+
+## MCP Calls
+
+### Pre-Release Validation
+```json
+{ "tool": "pm_validate", "args": { "options": { "checkResolution": true, "checkHistoryDrift": true, "checkFiles": true } } }
+{ "tool": "pm_health", "args": {} }
+{ "tool": "pm_context", "args": { "options": { "depth": "standard" } } }
+```
+
+### Link Release Artifacts
+```json
+{ "tool": "pm_docs", "args": { "id": "pm-xxxx", "author": "claude-code-agent", "options": { "add": ["path=CHANGELOG.md,scope=project,note=release-notes"] } } }
+{ "tool": "pm_files", "args": { "id": "pm-xxxx", "author": "claude-code-agent", "options": { "add": ["path=package.json,scope=project,note=version"] } } }
+```
+
+### Record Evidence
+```json
+{
+  "tool": "pm_comments",
+  "args": {
+    "id": "pm-xxxx",
+    "author": "claude-code-agent",
+    "options": {
+      "add": "Release evidence: build ok. Tests pass. 100% coverage. pm validate ok. GitHub CI green. npm publish ok."
+    }
+  }
+}
+```
+
+## Gate Script Reference
+
+```bash
+pnpm build                                   # TypeScript build
+node scripts/run-tests.mjs coverage          # Full test + coverage
+node scripts/release/run-gates.mjs           # All release gates
+gh run list --limit 5                        # GitHub CI status
+gh run view <run-id>                         # Detailed run status
+```
+
+## Safety
+
+- Never set `path` for real repository tracking — only for sandbox tests.
+- Run coverage gate before any `npm publish` or version tag.
+- Confirm GitHub CI green before closing the release item.

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

@@ -0,0 +1,148 @@
+---
+name: pm-workflow
+description: Use pm CLI natively in Claude Code through MCP tools for planning, tracking, mutation, validation, and reporting. Use this skill whenever work should be tracked through pm — before implementing, during implementation, and at close.
+---
+
+# pm Workflow
+
+Use this skill for all pm-tracked work. Prefer native MCP tools over shell `pm` commands.
+
+## Tool Preference
+
+**Always use native MCP tools before falling back to Bash `pm` commands:**
+
+| Purpose | Tool |
+|---------|------|
+| Orient / read state | `pm_context`, `pm_search`, `pm_list`, `pm_get` |
+| Create / update | `pm_create`, `pm_update`, `pm_claim`, `pm_release`, `pm_close` |
+| Evidence | `pm_comments`, `pm_files`, `pm_docs`, `pm_test` |
+| Verify | `pm_validate`, `pm_health`, `pm_contracts` |
+| Everything else | `pm_run` with an explicit `action` |
+
+## Required Workflow Loop
+
+1. **Orient** — run `pm_context`, `pm_search`, and `pm_list` before creating new work.
+2. **Reuse** — claim an existing item when one matches instead of creating a duplicate.
+3. **Claim** — call `pm_claim` with `author: "claude-code-agent"` before substantial edits.
+4. **Sync TUI** — after claiming, call `TaskCreate` to mirror the item in Claude Code's task panel (see Hybrid TUI Sync below).
+5. **Link evidence** — call `pm_files`, `pm_docs`, `pm_test` as work progresses.
+6. **Add comments** — `pm_comments` for progress notes and verification results.
+7. **Verify** — run `pm_validate` and project tests before closing.
+8. **Close** — `pm_close` with reason, then `pm_release`, then `TaskUpdate(completed)`.
+
+## Hybrid TUI Sync
+
+pm is the **persistent store** (cross-session). Claude Code's task panel is the **live session view**.
+
+### When claiming or creating an item
+
+Call `TaskCreate` immediately after `pm_claim` (or after `pm_create` if starting fresh):
+
+```
+TaskCreate:
+  subject: "[pm-xxxx] <item title>"
+  description: "Tracking pm item pm-xxxx. AC: <acceptance_criteria if set>"
+  activeForm: "Implementing pm-xxxx"
+```
+
+Save the returned `taskId` — you'll need it for `TaskUpdate` calls later in this session.
+
+### When setting in_progress
+
+Call `TaskUpdate` with `status: "in_progress"` using the `taskId` from above.
+
+### When closing
+
+Call `pm_close` then `pm_release`, then immediately call:
+```
+TaskUpdate:
+  taskId: <saved taskId>
+  status: "completed"
+```
+
+### Blocked items
+
+If a pm item becomes blocked, call `TaskUpdate` with `status: "in_progress"` and add "(BLOCKED)" to the subject so it's visible in the panel.
+
+## Tool Call Shape
+
+Most tools accept `cwd`, `author`, and `options`:
+
+```json
+{
+  "cwd": "/path/to/repo",
+  "author": "claude-code-agent",
+  "options": { "limit": "10" }
+}
+```
+
+`pm_run` requires an `action` field:
+
+```json
+{
+  "action": "calendar",
+  "options": { "view": "week", "format": "markdown" }
+}
+```
+
+## Common Patterns
+
+**Get active work snapshot:**
+```json
+{ "tool": "pm_context", "args": { "options": { "limit": "10" } } }
+```
+
+**Search for existing work:**
+```json
+{ "tool": "pm_search", "args": { "query": "your keywords", "options": { "limit": "10" } } }
+```
+
+**Create a new item:**
+```json
+{
+  "tool": "pm_create",
+  "args": {
+    "author": "claude-code-agent",
+    "options": {
+      "title": "Item title",
+      "description": "What this item tracks.",
+      "type": "Task",
+      "status": "open",
+      "priority": "1",
+      "createMode": "progressive"
+    }
+  }
+}
+```
+
+**Link changed files:**
+```json
+{
+  "tool": "pm_files",
+  "args": {
+    "id": "pm-xxxx",
+    "author": "claude-code-agent",
+    "options": { "add": ["path=src/file.ts,scope=project,note=implementation"] }
+  }
+}
+```
+
+**Close with evidence:**
+```json
+{
+  "tool": "pm_close",
+  "args": {
+    "id": "pm-xxxx",
+    "reason": "All acceptance criteria met. Tests pass.",
+    "author": "claude-code-agent"
+  }
+}
+```
+
+## Priority Reference
+
+- `0` = critical, `1` = high, `2` = normal, `3` = low, `4` = minimal
+
+## Safety
+
+Do not pass `path` during real repository tracking. Only pass `path` for sandbox/test runs.

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

@@ -0,0 +1,45 @@
+{
+  "name": "pm-cli-codex",
+  "version": "1.0.0",
+  "description": "Native Codex integration for pm-cli with bundled MCP tools, skills, commands, and agent workflows.",
+  "author": {
+    "name": "unbrained",
+    "url": "https://github.com/unbraind/pm-cli"
+  },
+  "homepage": "https://github.com/unbraind/pm-cli/tree/main/plugins/pm-cli-codex",
+  "repository": "https://github.com/unbraind/pm-cli",
+  "license": "MIT",
+  "keywords": [
+    "pm-cli",
+    "codex",
+    "mcp",
+    "project-management",
+    "agents",
+    "tasks",
+    "workflows"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "pm CLI",
+    "shortDescription": "Native pm tracker tools and agent workflows",
+    "longDescription": "Use pm CLI from Codex through native MCP tools instead of shelling out to the pm command. The plugin bundles tracker operations, skills, command prompts, and subagent workflow guidance for planning, execution, validation, release, and audit work.",
+    "developerName": "unbrained",
+    "category": "Coding",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/unbraind/pm-cli",
+    "privacyPolicyURL": "https://github.com/unbraind/pm-cli/blob/main/SECURITY.md",
+    "termsOfServiceURL": "https://github.com/unbraind/pm-cli/blob/main/LICENSE",
+    "defaultPrompt": [
+      "Use pm CLI to orient, claim, track, verify, and close this repository task"
+    ],
+    "composerIcon": "./assets/pm-cli-small.svg",
+    "logo": "./assets/pm-cli-small.svg",
+    "screenshots": [],
+    "brandColor": "#2563EB"
+  }
+}

package/plugins/pm-cli-codex/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "pm-cli-native": {
+      "command": "node",
+      "args": [
+        "./scripts/pm-mcp-server.mjs"
+      ],
+      "env": {
+        "PM_AUTHOR": "codex-agent"
+      },
+      "note": "Native pm-cli MCP server. It imports pm command modules directly and does not spawn the pm CLI for tool calls."
+    }
+  }
+}

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

@@ -0,0 +1,30 @@
+# pm CLI Codex Plugin
+
+This plugin packages pm-cli for Codex with:
+
+- a native stdio MCP server (`pm-cli-native`) backed by pm command modules, not shell `pm` invocations
+- skills for developer, user, extension, SDK, release, and audit workflows
+- command prompts for common planning and verification loops
+- repo marketplace metadata for one-step local installation in Codex
+
+## Install
+
+From this repository:
+
+```bash
+codex plugin marketplace add .
+```
+
+Restart Codex, then install **pm CLI** from the repo marketplace. The bundled MCP server starts through `plugins/pm-cli-codex/scripts/pm-mcp-server.mjs`.
+
+For a published package install, keep `@unbrained/pm-cli` available through npm. The launcher uses the local repo build when present and falls back to `npx -y @unbrained/pm-cli@latest pm-mcp` when the plugin is cached outside the repository.
+
+## Native Tools
+
+Prefer the narrow tools when they match the task: `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`, and `pm_guide`.
+
+Use `pm_run` for the remaining pm surface. Supported actions include `init`, `calendar`, `activity`, `aggregate`, `dedupe-audit`, `normalize`, `reindex`, `extension`, `history`, `stats`, `append`, `notes`, `learnings`, `test-all`, `comments-audit`, `gc`, templates, and test-runs controls.
+
+## Safety
+
+Do not pass `path` for real repository tracking. For tests, pass a sandbox `cwd` or `path`, and keep `PM_GLOBAL_PATH` isolated when running commands that execute linked tests.

package/plugins/pm-cli-codex/assets/pm-cli-small.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="pm CLI">
+  <rect width="64" height="64" rx="14" fill="#2563EB"/>
+  <path d="M15 41V18h15c5 0 9 4 9 9s-4 9-9 9h-7v5h-8Zm8-12h6c1.7 0 3-1.3 3-3s-1.3-3-3-3h-6v6Zm20 12V18h6v23h-6Z" fill="#FFFFFF"/>
+</svg>

package/plugins/pm-cli-codex/commands/pm-audit.md

@@ -0,0 +1,8 @@
+# Audit a pm repository
+
+Use native pm tools to inspect project state:
+
+1. `pm_context` with deeper options for hierarchy, blockers, files, and tests.
+2. `pm_run` with `action=contracts`, `health`, `validate`, `aggregate`, and `dedupe-audit`.
+3. Convert findings into tracked pm items.
+4. Link evidence through `pm_files`, `pm_docs`, `pm_test`, and `pm_comments`.

package/plugins/pm-cli-codex/commands/pm-close-task.md

@@ -0,0 +1,9 @@
+# Close a pm-tracked task
+
+Use native pm tools to:
+
+1. Run linked or relevant tests.
+2. Link any changed files/docs/tests that are missing from the item.
+3. Add evidence with `pm_comments`.
+4. Run `pm_validate` or `pm_health` when relevant.
+5. Close with `pm_close` and release with `pm_release`.

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

@@ -0,0 +1,9 @@
+# Start a pm-tracked task
+
+Use the pm CLI plugin native tools to:
+
+1. Run `pm_context`, `pm_search`, and `pm_list`.
+2. Reuse or create the right pm item.
+3. Claim it with `pm_claim`.
+4. Link the intended files/docs/tests before substantial edits.
+5. Add a `pm_comments` note describing the selected scope.

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

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+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 < 8; 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", "@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-codex/skills/pm-auditor/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: pm-auditor
+description: Audit pm-cli repositories with native pm MCP tools, preserving duplicate checks, privacy boundaries, linked evidence, and verification records.
+license: MIT
+---
+
+# pm Auditor
+
+Use for broad repository audits, release readiness checks, privacy reviews, and agent-workflow health checks.
+
+## Audit Flow
+
+1. Use `pm_context` with standard or deep options.
+2. Use `pm_search` for likely existing audit or release items.
+3. Use `pm_run` actions `health`, `validate`, `contracts`, `dedupe-audit`, `aggregate`, and `calendar` as needed.
+4. Convert each actionable finding into a pm item or append evidence to an existing item.
+5. Keep sensitive operational data out of public docs and tracked comments.
+
+## Evidence
+
+Record exact verification commands and summarized results through `pm_comments`, and link touched files through `pm_files`.

package/plugins/pm-cli-codex/skills/pm-auditor/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "pm Auditor"
+  short_description: "Audit pm health, contracts, privacy, and readiness"
+  icon_small: "./assets/pm-cli-small.svg"
+  icon_large: "./assets/pm-cli-small.svg"
+  default_prompt: "Audit this pm repository with native pm tools, dedupe findings, link evidence, and avoid leaking private data."

package/plugins/pm-cli-codex/skills/pm-native/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: pm-native
+description: Use pm-cli natively in Codex through bundled MCP tools for planning, tracking, mutation, validation, and reporting without invoking the pm shell command.
+license: MIT
+---
+
+# pm Native Workflow
+
+Use this skill whenever a Codex task should be tracked through pm.
+
+## Tool Preference
+
+Use MCP tools before shell commands:
+
+- Orient: `pm_context`, `pm_search`, `pm_list`, `pm_get`
+- Mutate: `pm_create`, `pm_update`, `pm_claim`, `pm_release`, `pm_close`
+- Evidence: `pm_comments`, `pm_files`, `pm_docs`, `pm_test`
+- Verify: `pm_validate`, `pm_health`, `pm_contracts`
+- Everything else: `pm_run` with an explicit `action`
+
+Do not pass `path` during real repository work. For tests, pass a sandbox `cwd` or `path`.
+
+## Required Loop
+
+1. Run `pm_context`, `pm_search`, and `pm_list` before creating work.
+2. Reuse an existing item when one matches.
+3. Claim the item with `pm_claim`.
+4. Link changed files/docs/tests as work proceeds.
+5. Add concise evidence with `pm_comments`.
+6. Run linked and project verification.
+7. Close with `pm_close` and release with `pm_release`.
+
+## Native Argument Shape
+
+Most tools accept:
+
+```json
+{
+  "cwd": "/repo/root",
+  "author": "codex-agent",
+  "options": {
+    "limit": "10"
+  }
+}
+```
+
+`pm_run` accepts an `action` plus `options`:
+
+```json
+{
+  "action": "calendar",
+  "options": {
+    "view": "week",
+    "format": "markdown"
+  }
+}
+```

package/plugins/pm-cli-codex/skills/pm-native/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "pm Native"
+  short_description: "Track Codex work through native pm MCP tools"
+  icon_small: "./assets/pm-cli-small.svg"
+  icon_large: "./assets/pm-cli-small.svg"
+  default_prompt: "Use native pm tools to orient, claim, implement, verify, and close this task without shelling out to pm."

package/plugins/pm-cli-codex/skills/pm-release/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: pm-release
+description: Run compatibility-gated pm-cli release workflows with native pm tools, linked evidence, and public-surface verification.
+license: MIT
+---
+
+# pm Release
+
+Use for release prep, compatibility gates, publication checks, and post-release verification.
+
+## Release Loop
+
+1. Find or create the release item after duplicate checks.
+2. Claim it and link release docs, changelog, compatibility scripts, and tests.
+3. Run sandboxed compatibility checks before changing release assets.
+4. Run full local gates before tagging or publishing.
+5. Verify public surfaces after publish and record results through `pm_comments`.
+
+Use `pm_run` for release-adjacent pm actions not exposed as narrow tools.

package/plugins/pm-cli-codex/skills/pm-release/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "pm Release"
+  short_description: "Run pm release workflows with linked evidence"
+  icon_small: "./assets/pm-cli-small.svg"
+  icon_large: "./assets/pm-cli-small.svg"
+  default_prompt: "Use native pm tools to prepare, gate, publish-check, and document this pm-cli release."