@unbrained/pm-cli 2026.5.12 → 2026.5.18

package/packages/pm-todos/extensions/todos/index.js

@@ -1,141 +1,130 @@
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
 const CURRENT_EXTENSION_ROOT = path.dirname(fileURLToPath(import.meta.url));
-
 export const manifest = {
-  name: "builtin-todos-import-export",
-  version: "0.1.0",
-  entry: "./index.js",
-  priority: 0,
-  capabilities: ["commands", "schema"],
+    name: "builtin-todos-import-export",
+    version: "0.1.0",
+    entry: "./index.js",
+    priority: 0,
+    capabilities: ["commands", "schema"],
 };
-
 function asOptionalString(value) {
-  return typeof value === "string" ? value : undefined;
+    return typeof value === "string" ? value : undefined;
 }
-
 function toImportOptions(options) {
-  return {
-    folder: asOptionalString(options.folder),
-    author: asOptionalString(options.author),
-    message: asOptionalString(options.message),
-  };
+    return {
+        folder: asOptionalString(options.folder),
+        author: asOptionalString(options.author),
+        message: asOptionalString(options.message),
+    };
 }
-
 function toExportOptions(options) {
-  return {
-    folder: asOptionalString(options.folder),
-  };
+    return {
+        folder: asOptionalString(options.folder),
+    };
 }
-
 function resolvePackageRootCandidates() {
-  const candidates = [];
-  const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
-  if (typeof envRoot === "string" && envRoot.trim().length > 0) {
-    candidates.push(path.resolve(envRoot.trim()));
-  }
-  const argvEntry = typeof process.argv[1] === "string" ? process.argv[1].trim() : "";
-  if (argvEntry.length > 0) {
-    const resolvedEntry = path.resolve(argvEntry);
-    const entryDir = path.dirname(resolvedEntry);
-    candidates.push(path.resolve(entryDir, ".."));
-    candidates.push(path.resolve(entryDir, "../.."));
-    candidates.push(path.resolve(entryDir, "../../.."));
-  }
-  return [...new Set(candidates)];
+    const candidates = [];
+    const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
+    if (typeof envRoot === "string" && envRoot.trim().length > 0) {
+        candidates.push(path.resolve(envRoot.trim()));
+    }
+    const argvEntry = typeof process.argv[1] === "string" ? process.argv[1].trim() : "";
+    if (argvEntry.length > 0) {
+        const resolvedEntry = path.resolve(argvEntry);
+        const entryDir = path.dirname(resolvedEntry);
+        candidates.push(path.resolve(entryDir, ".."));
+        candidates.push(path.resolve(entryDir, "../.."));
+        candidates.push(path.resolve(entryDir, "../../.."));
+    }
+    return [...new Set(candidates)];
 }
-
 async function loadRuntimeModule() {
-  const attempted = [];
-  for (const packageRoot of resolvePackageRootCandidates()) {
-    const modulePaths = [
-      path.join(packageRoot, ".agents", "pm", "extensions", "todos", "runtime.js"),
-      path.join(packageRoot, "packages", "pm-todos", "extensions", "todos", "runtime.js"),
-    ];
-    for (const modulePath of modulePaths) {
-      attempted.push(modulePath);
-      try {
-        return await import(pathToFileURL(modulePath).href);
-      } catch {
-        // Try the next package-root candidate.
-      }
+    const attempted = [];
+    for (const packageRoot of resolvePackageRootCandidates()) {
+        const modulePaths = [
+            path.join(packageRoot, ".agents", "pm", "extensions", "todos", "runtime.js"),
+            path.join(packageRoot, "packages", "pm-todos", "extensions", "todos", "runtime.js"),
+        ];
+        for (const modulePath of modulePaths) {
+            attempted.push(modulePath);
+            try {
+                return await import(pathToFileURL(modulePath).href);
+            }
+            catch {
+                // Try the next package-root candidate.
+            }
+        }
+    }
+    const localRuntimePath = path.join(CURRENT_EXTENSION_ROOT, "runtime.js");
+    attempted.push(localRuntimePath);
+    try {
+        return await import(pathToFileURL(localRuntimePath).href);
     }
-  }
-
-  const localRuntimePath = path.join(CURRENT_EXTENSION_ROOT, "runtime.js");
-  attempted.push(localRuntimePath);
-  try {
-    return await import(pathToFileURL(localRuntimePath).href);
-  } catch {
-    // Fall through to the diagnostic below.
-  }
-
-  throw new Error(
-    "Unable to resolve packaged todos extension runtime module. " +
-      `Tried: ${attempted.join(", ")}. Ensure the installed extension includes runtime.js or PM_CLI_PACKAGE_ROOT points to an installed pm package root.`,
-  );
+    catch {
+        // Fall through to the diagnostic below.
+    }
+    throw new Error("Unable to resolve packaged todos extension runtime module. " +
+        `Tried: ${attempted.join(", ")}. Ensure the installed extension includes runtime.js or PM_CLI_PACKAGE_ROOT points to an installed pm package root.`);
 }
-
 async function runTodosImportFromRuntime(options, global) {
-  const runtime = await loadRuntimeModule();
-  if (typeof runtime.runTodosImport !== "function") {
-    throw new Error('Bundled todos runtime module is missing runTodosImport().');
-  }
-  return runtime.runTodosImport(options, global);
+    const runtime = await loadRuntimeModule();
+    if (typeof runtime.runTodosImport !== "function") {
+        throw new Error("Bundled todos runtime module is missing runTodosImport().");
+    }
+    return runtime.runTodosImport(options, global);
 }
-
 async function runTodosExportFromRuntime(options, global) {
-  const runtime = await loadRuntimeModule();
-  if (typeof runtime.runTodosExport !== "function") {
-    throw new Error('Bundled todos runtime module is missing runTodosExport().');
-  }
-  return runtime.runTodosExport(options, global);
+    const runtime = await loadRuntimeModule();
+    if (typeof runtime.runTodosExport !== "function") {
+        throw new Error("Bundled todos runtime module is missing runTodosExport().");
+    }
+    return runtime.runTodosExport(options, global);
 }
-
 export function activate(api) {
-  api.registerCommand({
-    name: "todos import",
-    description: "Import Todo markdown files into pm items.",
-    flags: [
-      {
-        long: "--folder",
-        value_name: "path",
-        value_type: "string",
-        description: "Source folder containing Todo markdown files.",
-      },
-      {
-        long: "--author",
-        value_name: "author",
-        value_type: "string",
-        description: "Override import mutation author.",
-      },
-      {
-        long: "--message",
-        value_name: "text",
-        value_type: "string",
-        description: "Override import history message.",
-      },
-    ],
-    run: async (context) => runTodosImportFromRuntime(toImportOptions(context.options), context.global),
-  });
-  api.registerCommand({
-    name: "todos export",
-    description: "Export pm items into Todo markdown files.",
-    flags: [
-      {
-        long: "--folder",
-        value_name: "path",
-        value_type: "string",
-        description: "Destination folder for exported Todo markdown files.",
-      },
-    ],
-    run: async (context) => runTodosExportFromRuntime(toExportOptions(context.options), context.global),
-  });
+    api.registerCommand({
+        name: "todos import",
+        action: "todos-import",
+        description: "Import Todo markdown files into pm items.",
+        flags: [
+            {
+                long: "--folder",
+                value_name: "path",
+                value_type: "string",
+                description: "Source folder containing Todo markdown files.",
+            },
+            {
+                long: "--author",
+                value_name: "author",
+                value_type: "string",
+                description: "Override import mutation author.",
+            },
+            {
+                long: "--message",
+                value_name: "text",
+                value_type: "string",
+                description: "Override import history message.",
+            },
+        ],
+        run: async (context) => runTodosImportFromRuntime(toImportOptions(context.options), context.global),
+    });
+    api.registerCommand({
+        name: "todos export",
+        action: "todos-export",
+        description: "Export pm items into Todo markdown files.",
+        flags: [
+            {
+                long: "--folder",
+                value_name: "path",
+                value_type: "string",
+                description: "Destination folder for exported Todo markdown files.",
+            },
+        ],
+        run: async (context) => runTodosExportFromRuntime(toExportOptions(context.options), context.global),
+    });
 }
-
 export default {
-  manifest,
-  activate,
+    manifest,
+    activate,
 };

package/packages/pm-todos/extensions/todos/index.ts

@@ -1,7 +1,6 @@
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import type { CommandDefinition, ExtensionApi } from "../../../../src/core/extensions/loader.js";
-import type { GlobalOptions } from "../../../../src/core/shared/command-types.js";
+import type { CommandDefinition, ExtensionApi, GlobalOptions } from "../../../../src/sdk/index.js";
 import type { TodosExportOptions, TodosExportResult, TodosImportOptions, TodosImportResult } from "./runtime.js";
 
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
@@ -105,6 +104,7 @@ async function runTodosExportFromRuntime(options: TodosExportOptions, global: Gl
 export function activate(api: ExtensionApi): void {
   api.registerCommand({
     name: "todos import",
+    action: "todos-import",
     description: "Import Todo markdown files into pm items.",
     flags: [
       {
@@ -130,6 +130,7 @@ export function activate(api: ExtensionApi): void {
   } satisfies CommandDefinition);
   api.registerCommand({
     name: "todos export",
+    action: "todos-export",
     description: "Export pm items into Todo markdown files.",
     flags: [
       {

package/packages/pm-todos/extensions/todos/runtime.js

@@ -1,21 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { getActiveExtensionRegistrations, runActiveOnReadHooks, runActiveOnWriteHooks } from "../../../../dist/core/extensions/index.js";
-import { pathExists, removeFileIfExists, writeFileAtomic } from "../../../../dist/core/fs/fs-utils.js";
-import { appendHistoryEntry, createHistoryEntry } from "../../../../dist/core/history/history.js";
-import { generateItemId, normalizeItemId } from "../../../../dist/core/item/id.js";
-import { canonicalDocument, normalizeFrontMatter, serializeItemDocument, splitFrontMatter } from "../../../../dist/core/item/item-format.js";
-import { normalizeStatusInput } from "../../../../dist/core/item/status.js";
-import { resolveItemTypeRegistry } from "../../../../dist/core/item/type-registry.js";
-import { parseTags } from "../../../../dist/core/item/parse.js";
-import { acquireLock } from "../../../../dist/core/lock/lock.js";
-import { EXIT_CODE } from "../../../../dist/core/shared/constants.js";
-import { PmCliError } from "../../../../dist/core/shared/errors.js";
-import { nowIso } from "../../../../dist/core/shared/time.js";
-import { listAllFrontMatter, locateItem, readLocatedItem } from "../../../../dist/core/store/item-store.js";
-import { getHistoryPath, getItemPath, getSettingsPath, resolvePmRoot } from "../../../../dist/core/store/paths.js";
-import { readSettings } from "../../../../dist/core/store/settings.js";
-import { CONFIDENCE_TEXT_VALUES, ISSUE_SEVERITY_VALUES, RISK_VALUES } from "../../../../dist/types/index.js";
+import { CONFIDENCE_TEXT_VALUES, EXIT_CODE, ISSUE_SEVERITY_VALUES, PmCliError, RISK_VALUES, acquireLock, appendHistoryEntry, canonicalDocument, createHistoryEntry, generateItemId, getActiveExtensionRegistrations, getHistoryPath, getItemPath, getSettingsPath, listAllFrontMatter, locateItem, normalizeFrontMatter, normalizeItemId, normalizeStatusInput, nowIso, parseTags, pathExists, readLocatedItem, readSettings, removeFileIfExists, resolveItemTypeRegistry, resolvePmRoot, runActiveOnReadHooks, runActiveOnWriteHooks, serializeItemDocument, splitFrontMatter, writeFileAtomic, } from "../../../../dist/sdk/index.js";
 const DEFAULT_TODOS_FOLDER = ".pm/todos";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -467,4 +452,4 @@ export async function runTodosExport(options, global) {
         ids,
         warnings,
     };
-}
+}

package/packages/pm-todos/extensions/todos/runtime.ts

@@ -1,24 +1,46 @@
 import fs from "node:fs/promises";
 import type { Dirent } from "node:fs";
 import path from "node:path";
-import { getActiveExtensionRegistrations, runActiveOnReadHooks, runActiveOnWriteHooks } from "../../../../src/core/extensions/index.js";
-import { pathExists, removeFileIfExists, writeFileAtomic } from "../../../../src/core/fs/fs-utils.js";
-import { appendHistoryEntry, createHistoryEntry } from "../../../../src/core/history/history.js";
-import { generateItemId, normalizeItemId } from "../../../../src/core/item/id.js";
-import { canonicalDocument, normalizeFrontMatter, serializeItemDocument, splitFrontMatter } from "../../../../src/core/item/item-format.js";
-import { normalizeStatusInput } from "../../../../src/core/item/status.js";
-import { resolveItemTypeRegistry } from "../../../../src/core/item/type-registry.js";
-import { parseTags } from "../../../../src/core/item/parse.js";
-import { acquireLock } from "../../../../src/core/lock/lock.js";
-import { EXIT_CODE } from "../../../../src/core/shared/constants.js";
-import type { GlobalOptions } from "../../../../src/core/shared/command-types.js";
-import { PmCliError } from "../../../../src/core/shared/errors.js";
-import { nowIso } from "../../../../src/core/shared/time.js";
-import { listAllFrontMatter, locateItem, readLocatedItem } from "../../../../src/core/store/item-store.js";
-import { getHistoryPath, getItemPath, getSettingsPath, resolvePmRoot } from "../../../../src/core/store/paths.js";
-import { readSettings } from "../../../../src/core/store/settings.js";
-import { CONFIDENCE_TEXT_VALUES, ISSUE_SEVERITY_VALUES, RISK_VALUES } from "../../../../src/types/index.js";
-import type { ItemDocument, ItemMetadata, ItemStatus, ItemType, PmSettings } from "../../../../src/types/index.js";
+import {
+  CONFIDENCE_TEXT_VALUES,
+  EXIT_CODE,
+  ISSUE_SEVERITY_VALUES,
+  PmCliError,
+  RISK_VALUES,
+  acquireLock,
+  appendHistoryEntry,
+  canonicalDocument,
+  createHistoryEntry,
+  generateItemId,
+  getActiveExtensionRegistrations,
+  getHistoryPath,
+  getItemPath,
+  getSettingsPath,
+  listAllFrontMatter,
+  locateItem,
+  normalizeFrontMatter,
+  normalizeItemId,
+  normalizeStatusInput,
+  nowIso,
+  parseTags,
+  pathExists,
+  readLocatedItem,
+  readSettings,
+  removeFileIfExists,
+  resolveItemTypeRegistry,
+  resolvePmRoot,
+  runActiveOnReadHooks,
+  runActiveOnWriteHooks,
+  serializeItemDocument,
+  splitFrontMatter,
+  writeFileAtomic,
+  type GlobalOptions,
+  type ItemDocument,
+  type ItemMetadata,
+  type ItemStatus,
+  type ItemType,
+  type PmSettings,
+} from "../../../../src/sdk/index.js";
 
 const DEFAULT_TODOS_FOLDER = ".pm/todos";
 

package/packages/pm-todos/package.json

@@ -1,17 +1,51 @@
 {
-  "name": "@unbrained/pm-package-todos",
+  "name": "@unbrained/pm-todos",
   "version": "0.1.0",
   "private": true,
   "type": "module",
   "description": "First-party pm package for Todo markdown import and export.",
+  "homepage": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-todos#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unbraind/pm-cli.git",
+    "directory": "packages/pm-todos"
+  },
+  "bugs": {
+    "url": "https://github.com/unbraind/pm-cli/issues"
+  },
   "keywords": [
     "pm-package",
     "project-management",
     "todos"
   ],
   "pm": {
+    "aliases": [
+      "todos"
+    ],
     "extensions": [
       "extensions/todos"
+    ],
+    "catalog": {
+      "display_name": "Todos Import/Export",
+      "category": "migration",
+      "summary": "Import and export Todo markdown tasks through pm package commands.",
+      "tags": [
+        "migration",
+        "todos",
+        "import",
+        "export"
+      ],
+      "links": {
+        "docs": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-todos#readme",
+        "repository": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-todos",
+        "report": "https://github.com/unbraind/pm-cli/issues"
+      }
+    },
+    "docs": [
+      "README.md"
+    ],
+    "examples": [
+      "README.md"
     ]
   }
 }

package/plugins/{pm-cli-claude → pm-claude}/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
-  "name": "pm-cli",
+  "name": "pm-claude",
   "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",
+  "version": "1.4.0",
   "author": {
     "name": "unbrained",
     "url": "https://github.com/unbraind/pm-cli"

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

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

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

@@ -6,7 +6,7 @@ Native pm CLI integration for Claude Code. Use pm project management tools direc
 
 | Component | What it provides |
 |-----------|----------------|
-| **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 |
+| **18 MCP tools** | Full pm surface: context, search, list, get, create, update, claim, release, close, comments, files, docs, test, validate, health, contracts, plan + `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 |
@@ -42,7 +42,7 @@ 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
+claude mcp add --transport stdio pm-mcp -- npx -y @unbrained/pm-cli pm-mcp
 ```
 
 This gives you the 18 MCP tools but not the skills, slash commands, or session hook.
@@ -54,7 +54,7 @@ Add to your project's `.mcp.json`:
 ```json
 {
   "mcpServers": {
-    "pm-cli-native": {
+    "pm-mcp": {
       "command": "npx",
       "args": ["-y", "@unbrained/pm-cli@latest", "pm-mcp"],
       "env": {
@@ -163,7 +163,7 @@ Spawn pm-triage-agent to set up the pm item for: add OAuth2 login support
 | `pm_validate` | Run validation checks |
 | `pm_health` | Run health diagnostics |
 | `pm_contracts` | Inspect command contracts |
-| `pm_guide` | Read guide topics |
+| `pm_plan` | Manage durable Plan workflows |
 
 ### General tool
 

package/plugins/{pm-cli-claude → pm-claude}/agents/pm-coordinator.md

@@ -29,7 +29,7 @@ For batch audits spanning many items, create one top-level `TaskCreate` for the
 
 ## Tools Available
 
-Use the `pm-cli-native` MCP server tools: `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`, and `pm_run` for all other operations.
+Use the `pm-mcp` MCP server tools: `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_plan`, and `pm_run` for all other operations.
 
 Also use Claude Code's built-in `TaskCreate` and `TaskUpdate` tools for TUI panel display.
 

package/plugins/{pm-cli-claude → pm-claude}/commands/pm-init.md

@@ -14,6 +14,14 @@ Initialize pm project tracking using native MCP tools. Argument: `$ARGUMENTS` (o
    ```json
    { "tool": "pm_run", "args": { "action": "init", "options": {} } }
    ```
+   If guidance state inspection is needed before writing AGENTS/CLAUDE sections, run:
+   ```json
+   { "tool": "pm_run", "args": { "action": "init", "options": { "agentGuidance": "status" } } }
+   ```
+   To explicitly add compact workflow guidance without waiting for interactive prompts, run:
+   ```json
+   { "tool": "pm_run", "args": { "action": "init", "options": { "agentGuidance": "add" } } }
+   ```
 
 3. **Verify initialization** — call `pm_health` again to confirm `ok: true`.
 
@@ -37,8 +45,9 @@ Initialize pm project tracking using native MCP tools. Argument: `$ARGUMENTS` (o
 
 5. **Show quick-start summary**:
    - pm initialized at `.agents/pm/`
+   - guidance mode defaults to `ask` (TTY prompt only); use `agentGuidance=add|skip|status` in `pm_run` options for deterministic behavior
    - 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`
+   - 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_plan`, `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 → pm-claude}/commands/pm-planner.md

@@ -49,3 +49,21 @@ Run the pm planning loop using native MCP tools. Argument: `$ARGUMENTS` (optiona
 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.
+
+## Living plan mode (`pm_plan`)
+
+If the user wants a Codex-style ExecPlan / Claude Plan Mode / Cursor plan-and-edit flow rather than a flat backlog, use the built-in `Plan` item type via the `pm_plan` MCP tool. It records ordered steps, evidence, decisions, discoveries, validation, and supports materializing steps into real Tasks/Features.
+
+```json
+{ "tool": "pm_plan", "args": { "options": { "subcommand": "create", "title": "Plan title", "scope": "What this plan changes", "harness": "claude-code", "parent": "pm-epic1", "claim": true } } }
+{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "add-step", "stepTitle": "Read affected files", "dependsOn": "pm-task1" } } }
+{ "tool": "pm_plan", "args": { "id": "pm-plan1", "stepRef": "plan-step-001", "options": { "subcommand": "complete-step", "stepEvidence": "files reviewed" } } }
+{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "approve" } } }
+{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "materialize", "steps": "plan-step-002,plan-step-003", "materializeType": "Task" } } }
+{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "show", "depth": "deep" } } }
+```
+
+Resume a plan after compaction:
+```json
+{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "resume", "resumeContext": "step 2 in progress; tests still failing on retry path" } } }
+```

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

@@ -39,11 +39,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", "--package=@unbrained/pm-cli@latest", "pm-mcp"], {
       stdio: "inherit",

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

@@ -111,8 +111,53 @@ Write AC as numbered, testable assertions:
 
 Set via `pm_create` with `acceptanceCriteria` field or `pm_update` with `options.acceptanceCriteria`.
 
+## Built-in Plan workflow (`pm_plan` / `pm plan`)
+
+For durable Codex-style ExecPlans, Claude-style Plan Mode, and Cursor-style editable checklists, pm exposes a first-class `Plan` item type plus a `pm plan` command family. Plans are stored as normal pm items under `.agents/pm/plans/`, get the full history hash chain, dependencies, search corpus, and lifecycle tooling.
+
+### When to use `pm plan` vs. `pm_create` + tasks
+
+- `pm plan` — when you need a **living, resumable plan** with ordered steps, evidence, decisions, discoveries, validation, and the option to later materialize selected steps as real Tasks. Best for plan-then-execute workflows.
+- `pm_create` (Epic/Feature/Task) — when the work is already decomposed and you just need persistent backlog items.
+
+### Lifecycle (call via `pm_plan` MCP tool)
+
+```json
+{ "tool": "pm_plan", "args": { "options": { "subcommand": "create", "title": "Refactor lock retry", "scope": "Improve retry semantics", "harness": "claude-code", "parent": "pm-epic1", "related": "pm-rel1,pm-rel2", "claim": true } } }
+{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "add-step", "stepTitle": "Read lock.ts", "stepBody": "Understand retry path", "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": "discovery", "discoveryText": "Found existing util in src/util/retry.ts" } } }
+{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "validation", "validationText": "Coverage gate stays at 100%", "validationCommand": "node scripts/run-tests.mjs coverage" } } }
+{ "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" } } }
+```
+
+### Progressive-disclosure reads
+
+```json
+{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "show", "depth": "brief" } } }
+{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "show", "depth": "standard" } } }
+{ "tool": "pm_plan", "args": { "id": "pm-plan1", "options": { "subcommand": "show", "depth": "deep" } } }
+```
+
+### Harness mapping cheatsheet
+
+| Harness signal | pm_plan equivalent |
+|----------------|--------------------|
+| Codex `update_plan` step status | `subcommand=update-step` with `stepStatus` |
+| Claude `TaskCreate` | `subcommand=add-step` |
+| Claude `TaskUpdate(in_progress)` | `subcommand=update-step` with `stepStatus=in_progress` |
+| Cursor edit a plan step | `subcommand=update-step` |
+| Resume after compaction | `subcommand=resume` with `resumeContext` then `subcommand=show --depth deep` |
+| Approve before edits | `subcommand=approve` |
+| Convert checklist into real items | `subcommand=materialize` |
+
 ## Safety
 
 - Never pass `path` during real repository tracking.
-- Always `pm_search` before `pm_create` — avoid duplicates.
+- Always `pm_search` before `pm_create`/`pm plan create` — avoid duplicates.
 - Run `pm_validate` after batch changes.
+- Set exactly one step `in_progress` per plan; pass `allowMultipleActive: true` only for explicit parallel branches.
+- Use `pm_plan` `subcommand=resume` after long-running sessions so the next agent can pick up with a deterministic context.

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

@@ -1,12 +1,12 @@
 {
-  "name": "pm-cli-codex",
-  "version": "1.0.0",
+  "name": "pm-codex",
+  "version": "1.1.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",
+  "homepage": "https://github.com/unbraind/pm-cli/tree/main/plugins/pm-codex",
   "repository": "https://github.com/unbraind/pm-cli",
   "license": "MIT",
   "keywords": [