@unbrained/pm-cli 2026.5.14 → 2026.5.24

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

@@ -1,81 +1,12 @@
-import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import type { GlobalOptions } from "../../../../src/sdk/index.js";
 
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
 
-interface TemplatesSdkModule {
-  CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS: Array<{ target: string }>;
-  EXIT_CODE: {
-    USAGE: number;
-    NOT_FOUND: number;
-    GENERIC_FAILURE: number;
-  };
-  PmCliError: new (message: string, exitCode?: number) => Error;
-  getSettingsPath: (pmRoot: string) => string;
-  nowIso: () => string;
-  pathExists: (targetPath: string) => Promise<boolean>;
-  readFileIfExists: (targetPath: string) => Promise<string | null>;
-  resolvePmRoot: (cwd: string, overridePath?: string) => string;
-  writeFileAtomic: (targetPath: string, contents: string) => Promise<void>;
-}
-
-const sdk = await loadTemplatesSdkModule();
-const {
-  CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS,
-  EXIT_CODE,
-  PmCliError,
-  getSettingsPath,
-  nowIso,
-  pathExists,
-  readFileIfExists,
-  resolvePmRoot,
-  writeFileAtomic,
-} = sdk;
-
-async function loadTemplatesSdkModule(): Promise<TemplatesSdkModule> {
-  const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
-  if (typeof envRoot !== "string" || envRoot.trim().length === 0) {
-    throw new Error(
-      `builtin-templates requires ${PM_PACKAGE_ROOT_ENV} to locate core SDK runtime exports.`,
-    );
-  }
-  const modulePath = path.join(path.resolve(envRoot.trim()), "dist", "sdk", "index.js");
-  try {
-    const loaded = (await import(pathToFileURL(modulePath).href)) as Partial<TemplatesSdkModule>;
-    if (
-      typeof loaded.resolvePmRoot === "function" &&
-      typeof loaded.pathExists === "function" &&
-      typeof loaded.PmCliError === "function" &&
-      Array.isArray(loaded.CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS)
-    ) {
-      return loaded as TemplatesSdkModule;
-    }
-  } catch {
-    // Fall through to deterministic failure message below.
-  }
-  throw new Error(
-    `builtin-templates failed to load SDK runtime exports from ${modulePath}.`,
-  );
-}
-
-const TEMPLATE_DIRECTORY_NAME = "templates";
-const TEMPLATE_FILE_EXTENSION = ".json";
-const TEMPLATE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
-const TEMPLATE_OPTION_REPEATABLE_KEYS = CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS.map((entry) => entry.target);
-const TEMPLATE_OPTION_REPEATABLE_KEY_SET = new Set<string>(TEMPLATE_OPTION_REPEATABLE_KEYS);
-
 type TemplateOptionValue = string | string[];
 export type CreateTemplateOptions = Record<string, TemplateOptionValue>;
 
-interface StoredCreateTemplateDocument {
-  name: string;
-  created_at: string;
-  updated_at: string;
-  options: CreateTemplateOptions;
-}
-
 export interface TemplatesSaveResult {
   name: string;
   created_at: string;
@@ -87,128 +18,60 @@ export interface TemplatesSaveResult {
 export interface TemplatesListResult {
   templates: string[];
   count: number;
+  builtin_templates: string[];
+  user_templates: string[];
 }
 
 export interface TemplatesShowResult {
   name: string;
+  source: "builtin" | "user";
   created_at: string;
   updated_at: string;
   path: string;
   options: CreateTemplateOptions;
 }
 
-function normalizeTemplateName(rawName: string): string {
-  const name = rawName.trim();
-  if (!TEMPLATE_NAME_PATTERN.test(name)) {
-    throw new PmCliError(
-      `Invalid template name "${rawName}". Expected 1-64 characters matching [A-Za-z0-9][A-Za-z0-9._-]*.`,
-      EXIT_CODE.USAGE,
-    );
-  }
-  return name;
-}
-
-function templatesDirectory(pmRoot: string): string {
-  return path.join(pmRoot, TEMPLATE_DIRECTORY_NAME);
-}
-
-function templatePath(pmRoot: string, normalizedName: string): string {
-  return path.join(templatesDirectory(pmRoot), `${normalizedName}${TEMPLATE_FILE_EXTENSION}`);
-}
-
-async function ensureTrackerInitialized(pmRoot: string): Promise<void> {
-  if (!(await pathExists(getSettingsPath(pmRoot)))) {
-    throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-  }
-}
-
-function sortTemplateOptions(options: CreateTemplateOptions): CreateTemplateOptions {
-  return Object.fromEntries(
-    Object.entries(options).sort(([left], [right]) => left.localeCompare(right)),
-  ) as CreateTemplateOptions;
+interface TemplatesSdkModule {
+  loadCreateTemplateOptions: (pmRoot: string, rawTemplateName: string) => Promise<CreateTemplateOptions>;
+  runTemplatesList: (global: GlobalOptions) => Promise<TemplatesListResult>;
+  runTemplatesSave: (
+    rawTemplateName: string,
+    options: Record<string, unknown>,
+    global: GlobalOptions,
+  ) => Promise<TemplatesSaveResult>;
+  runTemplatesShow: (rawTemplateName: string, global: GlobalOptions) => Promise<TemplatesShowResult>;
 }
 
-function extractTemplateOptions(rawOptions: Record<string, unknown>): CreateTemplateOptions {
-  const next: CreateTemplateOptions = {};
-  for (const [key, value] of Object.entries(rawOptions)) {
-    if (value === undefined) {
-      continue;
-    }
-    if (TEMPLATE_OPTION_REPEATABLE_KEY_SET.has(key)) {
-      if (typeof value === "string") {
-        next[key] = [value];
-        continue;
-      }
-      if (!Array.isArray(value)) {
-        continue;
-      }
-      const values = value.filter((entry): entry is string => typeof entry === "string");
-      if (values.length > 0) {
-        next[key] = values;
-      }
-      continue;
-    }
-    if (typeof value === "string") {
-      next[key] = value;
-      continue;
-    }
-    if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) {
-      next[key] = [...value];
-    }
-  }
-  return sortTemplateOptions(next);
-}
+const sdk = await loadTemplatesSdkModule();
 
-function parseStoredTemplateOptions(rawOptions: unknown, templateName: string): CreateTemplateOptions {
-  if (typeof rawOptions !== "object" || rawOptions === null || Array.isArray(rawOptions)) {
-    throw new PmCliError(`Template "${templateName}" has invalid options payload.`, EXIT_CODE.GENERIC_FAILURE);
-  }
-  const normalized: CreateTemplateOptions = {};
-  for (const [key, value] of Object.entries(rawOptions as Record<string, unknown>)) {
-    const normalizedKey = key.trim();
-    if (normalizedKey.length === 0) {
-      throw new PmCliError(`Template "${templateName}" contains an empty option key.`, EXIT_CODE.GENERIC_FAILURE);
-    }
-    if (typeof value === "string") {
-      normalized[normalizedKey] = value;
-      continue;
-    }
-    if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) {
-      normalized[normalizedKey] = [...value];
-      continue;
-    }
-    throw new PmCliError(`Template "${templateName}" contains invalid value for option "${normalizedKey}".`, EXIT_CODE.GENERIC_FAILURE);
+async function loadTemplatesSdkModule(): Promise<TemplatesSdkModule> {
+  const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
+  if (typeof envRoot !== "string" || envRoot.trim().length === 0) {
+    throw new Error(
+      `builtin-templates requires ${PM_PACKAGE_ROOT_ENV} to locate core SDK runtime exports.`,
+    );
   }
-  return sortTemplateOptions(normalized);
-}
-
-function parseStoredTemplateDocument(raw: string, normalizedName: string): StoredCreateTemplateDocument {
-  let parsed: unknown;
+  const modulePath = path.join(path.resolve(envRoot.trim()), "dist", "sdk", "index.js");
   try {
-    parsed = JSON.parse(raw) as unknown;
+    const loaded = (await import(pathToFileURL(modulePath).href)) as Partial<TemplatesSdkModule>;
+    if (
+      typeof loaded.loadCreateTemplateOptions === "function" &&
+      typeof loaded.runTemplatesList === "function" &&
+      typeof loaded.runTemplatesSave === "function" &&
+      typeof loaded.runTemplatesShow === "function"
+    ) {
+      return loaded as TemplatesSdkModule;
+    }
   } catch {
-    throw new PmCliError(`Template "${normalizedName}" contains invalid JSON.`, EXIT_CODE.GENERIC_FAILURE);
-  }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    throw new PmCliError(`Template "${normalizedName}" has invalid document shape.`, EXIT_CODE.GENERIC_FAILURE);
+    // Fall through to deterministic failure message below.
   }
-  const record = parsed as Record<string, unknown>;
-  const options = parseStoredTemplateOptions(record.options, normalizedName);
-  const now = nowIso();
-  return {
-    name: typeof record.name === "string" && record.name.trim().length > 0 ? record.name.trim() : normalizedName,
-    created_at: typeof record.created_at === "string" ? record.created_at : now,
-    updated_at: typeof record.updated_at === "string" ? record.updated_at : now,
-    options,
-  };
+  throw new Error(
+    `builtin-templates failed to load template runtime exports from ${modulePath}.`,
+  );
 }
 
-async function readStoredTemplateDocument(pmRoot: string, normalizedName: string): Promise<StoredCreateTemplateDocument> {
-  const raw = await readFileIfExists(templatePath(pmRoot, normalizedName));
-  if (raw === null) {
-    throw new PmCliError(`Template "${normalizedName}" not found`, EXIT_CODE.NOT_FOUND);
-  }
-  return parseStoredTemplateDocument(raw, normalizedName);
+export async function loadCreateTemplateOptions(pmRoot: string, rawTemplateName: string): Promise<CreateTemplateOptions> {
+  return sdk.loadCreateTemplateOptions(pmRoot, rawTemplateName);
 }
 
 export async function runTemplatesSave(
@@ -216,68 +79,13 @@ export async function runTemplatesSave(
   options: Record<string, unknown>,
   global: GlobalOptions,
 ): Promise<TemplatesSaveResult> {
-  const pmRoot = resolvePmRoot(process.cwd(), global.path);
-  await ensureTrackerInitialized(pmRoot);
-  const normalizedName = normalizeTemplateName(rawTemplateName);
-  const nextOptions = extractTemplateOptions(options);
-  if (Object.keys(nextOptions).length === 0) {
-    throw new PmCliError("templates save requires at least one create option flag", EXIT_CODE.USAGE);
-  }
-
-  const now = nowIso();
-  const storedPath = templatePath(pmRoot, normalizedName);
-  let createdAt = now;
-  if (await pathExists(storedPath)) {
-    const existing = await readStoredTemplateDocument(pmRoot, normalizedName);
-    createdAt = existing.created_at;
-  }
-
-  const document: StoredCreateTemplateDocument = {
-    name: normalizedName,
-    created_at: createdAt,
-    updated_at: now,
-    options: nextOptions,
-  };
-  await fs.mkdir(templatesDirectory(pmRoot), { recursive: true });
-  await writeFileAtomic(storedPath, `${JSON.stringify(document, null, 2)}\n`);
-  return {
-    name: document.name,
-    created_at: document.created_at,
-    updated_at: document.updated_at,
-    path: storedPath,
-    options: document.options,
-  };
+  return sdk.runTemplatesSave(rawTemplateName, options, global);
 }
 
 export async function runTemplatesList(global: GlobalOptions): Promise<TemplatesListResult> {
-  const pmRoot = resolvePmRoot(process.cwd(), global.path);
-  await ensureTrackerInitialized(pmRoot);
-  const dirPath = templatesDirectory(pmRoot);
-  if (!(await pathExists(dirPath))) {
-    return { templates: [], count: 0 };
-  }
-  const entries = await fs.readdir(dirPath);
-  const templates = entries
-    .filter((entry) => entry.toLowerCase().endsWith(TEMPLATE_FILE_EXTENSION))
-    .map((entry) => entry.slice(0, -TEMPLATE_FILE_EXTENSION.length))
-    .filter((entry) => TEMPLATE_NAME_PATTERN.test(entry))
-    .sort((left, right) => left.localeCompare(right));
-  return {
-    templates,
-    count: templates.length,
-  };
+  return sdk.runTemplatesList(global);
 }
 
 export async function runTemplatesShow(rawTemplateName: string, global: GlobalOptions): Promise<TemplatesShowResult> {
-  const pmRoot = resolvePmRoot(process.cwd(), global.path);
-  await ensureTrackerInitialized(pmRoot);
-  const normalizedName = normalizeTemplateName(rawTemplateName);
-  const stored = await readStoredTemplateDocument(pmRoot, normalizedName);
-  return {
-    name: stored.name,
-    created_at: stored.created_at,
-    updated_at: stored.updated_at,
-    path: templatePath(pmRoot, normalizedName),
-    options: stored.options,
-  };
+  return sdk.runTemplatesShow(rawTemplateName, global);
 }

package/packages/pm-templates/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@unbrained/pm-package-templates",
+  "name": "@unbrained/pm-templates",
   "version": "0.1.0",
   "private": true,
   "type": "module",

package/packages/pm-todos/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@unbrained/pm-package-todos",
+  "name": "@unbrained/pm-todos",
   "version": "0.1.0",
   "private": true,
   "type": "module",

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}/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": [

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-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.