@unbrained/pm-cli 2026.5.12 → 2026.5.18

package/plugins/{pm-cli-codex → pm-codex}/.mcp.json

@@ -1,6 +1,6 @@
 {
   "mcpServers": {
-    "pm-cli-native": {
+    "pm-mcp": {
       "command": "node",
       "args": [
         "./scripts/pm-mcp-server.mjs"

package/plugins/{pm-cli-codex → pm-codex}/README.md

@@ -2,7 +2,7 @@
 
 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
+- a native stdio MCP server (`pm-mcp`) 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
@@ -15,15 +15,18 @@ From this repository:
 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`.
+Restart Codex, then install **pm CLI** from the repo marketplace. The bundled MCP server starts through `plugins/pm-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`.
+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_plan`.
 
-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.
+Use `pm_run` for the remaining pm surface. Supported actions include `init`, `calendar`, `activity`, `aggregate`, `dedupe-audit`, `normalize`, `reindex`, `extension`, `history`, `history-redact`, `plan`, `stats`, `append`, `notes`, `learnings`, `test-all`, `comments-audit`, `gc`, templates, and test-runs controls.
+
+`pm_plan` exposes Codex-style ExecPlans as a first-class `Plan` item type with ordered steps, evidence, decisions, discoveries, validation, and materialization. See the `pm-native` skill for the full Plan workflow recipe.
+For `init` automation, pass `options.agentGuidance` (`ask|add|skip|status`) when you need deterministic AGENTS/CLAUDE guidance behavior in non-interactive runs.
 
 ## Safety
 

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

@@ -33,11 +33,13 @@ async function findRepoServer() {
 
 const explicitServer = process.env.PM_CLI_MCP_SERVER;
 if (explicitServer && await exists(explicitServer)) {
-  await import(pathToFileURL(explicitServer).href);
+  const server = await import(pathToFileURL(explicitServer).href);
+  server.startMcpServer();
 } else {
   const repoServer = await findRepoServer();
   if (repoServer) {
-    await import(pathToFileURL(repoServer).href);
+    const server = await import(pathToFileURL(repoServer).href);
+    server.startMcpServer();
   } else {
     const child = spawn("npx", ["-y", "@unbrained/pm-cli@latest", "pm-mcp"], {
       stdio: "inherit",

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

@@ -0,0 +1,81 @@
+---
+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"
+  }
+}
+```
+
+## Plan workflow (`pm_plan`)
+
+Codex-style living ExecPlans are first-class via the `Plan` item type and the `pm_plan` MCP tool. Plans persist ordered steps, evidence, decisions, discoveries, validation, and resume context so a future stateless agent can pick up the work.
+
+Use `pm_plan` for plan-then-execute workflows; use `pm_create` with type Task/Feature/Epic for already-decomposed backlog work.
+
+```json
+{ "tool": "pm_plan", "args": { "options": { "subcommand": "create", "title": "Refactor lock retry", "scope": "Improve retry semantics under load", "harness": "codex", "parent": "pm-epic1", "claim": true } } }
+{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "add-step", "stepTitle": "Read lock.ts", "dependsOn": "pm-task1" } } }
+{ "tool": "pm_plan", "args": { "id": "pm-plan1", "stepRef": "plan-step-001", "options": { "subcommand": "update-step", "stepStatus": "in_progress", "stepEvidence": "started reading lock.ts" } } }
+{ "tool": "pm_plan", "args": { "id": "pm-plan1", "stepRef": "plan-step-001", "options": { "subcommand": "complete-step", "stepEvidence": "lock.ts read; retry path captured" } } }
+{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "decision", "decisionText": "Use exponential backoff", "decisionRationale": "Avoid thundering herd" } } }
+{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "approve" } } }
+{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "materialize", "steps": "plan-step-002", "materializeType": "Task", "materializeParent": "pm-epic1" } } }
+{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "resume", "resumeContext": "step 2 pending, deps verified" } } }
+{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "show", "depth": "deep" } } }
+```
+
+Invariants:
+
+- One step `in_progress` at a time by default; pass `allowMultipleActive: true` for explicit parallel branches.
+- Use `subcommand: block-step` with `stepBlockedReason` when discovery flips a step.
+- Use `subcommand: materialize` once steps are concrete enough to become Tasks.

package/scripts/finalize-build.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+import { chmod, stat } from "node:fs/promises";
+import path from "node:path";
+
+const repoRoot = process.cwd();
+const executableOutputs = [
+  path.join(repoRoot, "dist", "cli.js"),
+  path.join(repoRoot, "dist", "mcp", "server.js"),
+];
+
+async function outputExists(filePath) {
+  try {
+    await stat(filePath);
+    return true;
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+
+for (const outputPath of executableOutputs) {
+  if (await outputExists(outputPath)) {
+    await chmod(outputPath, 0o755);
+  }
+}

package/scripts/prepare-build-cache.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+import { rm, stat } from "node:fs/promises";
+import path from "node:path";
+
+const repoRoot = process.cwd();
+const buildInfoPath = path.join(repoRoot, ".cache", "tsbuildinfo", "pm-cli.tsbuildinfo");
+const requiredOutputs = [
+  path.join(repoRoot, "dist", "cli.js"),
+  path.join(repoRoot, "dist", "sdk", "index.js"),
+];
+
+async function exists(filePath) {
+  try {
+    await stat(filePath);
+    return true;
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+
+const missingOutput = [];
+for (const outputPath of requiredOutputs) {
+  if (!(await exists(outputPath))) {
+    missingOutput.push(path.relative(repoRoot, outputPath));
+  }
+}
+
+if (missingOutput.length > 0 && (await exists(buildInfoPath))) {
+  await rm(buildInfoPath, { force: true });
+  console.warn(
+    `Removed stale TypeScript build cache because required build output is missing: ${missingOutput.join(", ")}`,
+  );
+}

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

@@ -1,57 +0,0 @@
----
-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"
-  }
-}
-```