@unbrained/pm-cli 2026.5.14 → 2026.5.18

package/docs/QUICKSTART.md

@@ -9,7 +9,7 @@ Use this page to get from a clean repository to a tracked, verified item.
 - Claim before implementation.
 - Link changed files, docs, and tests to the item.
 - Close only after evidence is recorded.
-- Use `pm guide quickstart` or `pm guide workflows` when you need local docs routing.
+- Use `pm install guide-shell --project` before `pm guide quickstart` or `pm guide workflows` when you need local docs routing.
 
 Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 
@@ -34,9 +34,10 @@ For one-off use:
 npx @unbrained/pm-cli --help
 ```
 
-Optional first-party packages are installable on demand:
+Optional first-party packages are installable during init or on demand:
 
 ```bash
+pm init --defaults --with-packages
 pm package catalog --project
 pm install '*' --project
 pm install all --project
@@ -48,9 +49,14 @@ pm package doctor --project --detail summary
 ```bash
 pm init
 pm health --check-only
+pm init --agent-guidance status
+pm init --agent-guidance add
 ```
 
 `pm init` creates `.agents/pm/` with settings, item folders, history, locks, search cache directories, and project extension storage.
+When AGENTS/CLAUDE guidance is missing, default `pm init` uses `--agent-guidance ask`: it prompts only in TTY, never blocks non-interactive runs, and records declined prompts.
+Use `pm init --agent-guidance add` to write the compact workflow block later, or `pm init --agent-guidance status` to inspect guidance state without changing files.
+Use `pm init --defaults --with-packages` when agents should get bundled commands such as calendar, templates, advanced search, and governance helpers in one non-interactive setup step.
 
 ## Create Your First Item
 
@@ -94,9 +100,9 @@ Do not create a duplicate item until `context`, `search`, and list commands show
 ## Link Work Artifacts
 
 ```bash
-pm files <item-id> --add path=src/core/lock/lock.ts,scope=project,note="implementation"
-pm docs <item-id> --add path=docs/ARCHITECTURE.md,scope=project,note="design context"
-pm test <item-id> --add command="node scripts/run-tests.mjs test -- tests/unit/lock.spec.ts",scope=project,timeout_seconds=240
+pm files <item-id> --add path=src/core/lock/lock.ts,note="implementation"
+pm docs <item-id> --add path=docs/ARCHITECTURE.md,note="design context"
+pm test <item-id> --add command="node scripts/run-tests.mjs test -- tests/unit/lock.spec.ts",timeout_seconds=240
 ```
 
 Use `node scripts/run-tests.mjs ...` for linked tests so tracker data is sandboxed.

package/docs/README.md

@@ -2,11 +2,12 @@
 
 This directory is the public documentation home for `pm-cli`. It is organized for progressive disclosure: read the smallest page that answers the current question, then follow links only when more detail is needed.
 
-## CLI Guide Router
+## Optional CLI Guide Router
 
-`pm guide` exposes the same documentation routes from inside the CLI:
+`pm guide` is provided by the optional `guide-shell` package. Install it when local in-CLI documentation routing is useful:
 
 ```bash
+pm install guide-shell --project
 pm guide
 pm guide quickstart
 pm guide commands --depth standard
@@ -23,7 +24,7 @@ pm guide release --json
 | Maintainer | [Contributing](../CONTRIBUTING.md) | [Testing](TESTING.md), [Releasing](RELEASING.md), [Architecture](ARCHITECTURE.md) |
 | Package author | [Packages and Extensions](EXTENSIONS.md) | [SDK](SDK.md), [starter extension](examples/starter-extension/README.md) |
 | Codex user | [Codex Plugin](CODEX_PLUGIN.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md) |
-| Machine client | `pm guide commands` | [Command Reference](COMMANDS.md#machine-contracts), then `pm contracts --json` |
+| Machine client | `pm contracts --json` | [Command Reference](COMMANDS.md#machine-contracts), optionally `pm install guide-shell --project && pm guide commands` |
 
 ## Documentation Map
 
@@ -41,8 +42,8 @@ pm guide release --json
 
 ## Guide Topic Map
 
-| `pm guide` topic | Primary docs |
-|------------------|--------------|
+| Optional `pm guide` topic | Primary docs |
+|-----------------------------|--------------|
 | `quickstart` | [Quickstart](QUICKSTART.md), [Command Reference](COMMANDS.md) |
 | `commands` | [Command Reference](COMMANDS.md), [Configuration](CONFIGURATION.md) |
 | `workflows` | [Agent Guide](AGENT_GUIDE.md), [Testing](TESTING.md) |
@@ -79,7 +80,7 @@ This documentation structure is tracked through:
 When changing docs, link files back to the active item:
 
 ```bash
-pm docs <item-id> --add path=docs/README.md,scope=project,note="documentation index"
+pm docs <item-id> --add path=docs/README.md,note="documentation index"
 pm comments <item-id> "Docs updated; links and build verified."
 ```
 

package/docs/RELEASING.md

@@ -1,7 +1,7 @@
 # Releasing `@unbrained/pm-cli`
 
 This page is for maintainers cutting npm and GitHub releases. It assumes release work is tracked with `pm`.
-For local progressive-disclosure routing, use `pm guide release`.
+For local progressive-disclosure routing, install `guide-shell` with `pm install guide-shell --project`, then use `pm guide release`.
 
 ## Agent Quick Context
 
@@ -10,7 +10,7 @@ For local progressive-disclosure routing, use `pm guide release`.
 - Publishing is owned by the tag-driven GitHub Actions release workflow.
 - Do not run manual `npm publish`.
 - Run local parity gates before pushing release tags.
-- Use `pm guide release --json` for machine-readable release docs routing.
+- Use `pm guide release --json` for machine-readable release docs routing after `guide-shell` is installed.
 
 Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 

package/docs/TESTING.md

@@ -36,7 +36,7 @@ Use focused runs while iterating, then run coverage before closure when risk or
 Add tests to the item that owns the work:
 
 ```bash
-pm test <item-id> --add command="node scripts/run-tests.mjs test -- tests/unit/output.spec.ts",scope=project,timeout_seconds=240
+pm test <item-id> --add command="node scripts/run-tests.mjs test -- tests/unit/output.spec.ts",timeout_seconds=240
 pm test <item-id> --run --progress
 ```
 
@@ -76,7 +76,7 @@ Linked tests can include assertion metadata:
 
 ```bash
 pm test <item-id> --add \
-  command="pm list-open --json",scope=project,timeout_seconds=120,assert_json_field_gte=count:0
+  command="pm list-open --json",timeout_seconds=120,assert_json_field_gte=count:0
 ```
 
 Common assertion keys include:

package/marketplace.json

@@ -7,10 +7,10 @@
   },
   "plugins": [
     {
-      "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, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "1.3.0",
-      "source": "./plugins/pm-cli-claude",
+      "version": "1.4.0",
+      "source": "./plugins/pm-claude",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.5.14",
+  "version": "2026.5.18",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",
@@ -49,12 +49,14 @@
     ".claude-plugin/**",
     "plugins/**",
     "packages/pm-*/**",
+    "scripts/finalize-build.mjs",
     "scripts/install.sh",
     "scripts/install.ps1",
+    "scripts/prepare-build-cache.mjs",
     "marketplace.json"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "node scripts/prepare-build-cache.mjs && tsc -p tsconfig.json && node scripts/finalize-build.mjs",
     "typecheck": "tsc --noEmit -p tsconfig.json && tsc -p tsconfig.packages.json",
     "start": "node dist/cli.js",
     "dev": "tsx src/cli.ts",

package/packages/pm-beads/package.json

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

package/packages/pm-calendar/README.md

@@ -1,6 +1,6 @@
 # pm Calendar Package
 
-`@unbrained/pm-package-calendar` provides agenda and calendar views as an installable pm package.
+`@unbrained/pm-calendar` provides agenda and calendar views as an installable pm package.
 
 ```bash
 pm install calendar

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

@@ -46,7 +46,7 @@ export function activate(api) {
   api.registerCommand(calendarCommand("cal"));
   api.registerService("output_format", (context) => {
     const rendered = renderCalendarPackageOutput(context);
-    return rendered ?? context.payload;
+    return rendered ?? null;
   });
 }
 

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

@@ -52,7 +52,7 @@ export function activate(api: ExtensionApi): void {
   api.registerCommand(calendarCommand("cal"));
   api.registerService("output_format", (context) => {
     const rendered = renderCalendarPackageOutput(context as ServiceOverrideContext);
-    return rendered ?? context.payload;
+    return rendered ?? null;
   });
 }
 

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

@@ -51,10 +51,6 @@ function isCalendarResult(value) {
   );
 }
 
-function isCalendarCommand(command) {
-  return command === "calendar" || command === "cal";
-}
-
 function readPayloadFormat(payload) {
   if (typeof payload === "object" && payload !== null) {
     const format = payload.format;
@@ -72,6 +68,26 @@ function readPayloadResult(payload) {
   return payload;
 }
 
+function readPayloadCommandOptions(payload) {
+  if (typeof payload === "object" && payload !== null) {
+    const commandOptions = payload.command_options;
+    if (typeof commandOptions === "object" && commandOptions !== null) {
+      return commandOptions;
+    }
+  }
+  return {};
+}
+
+function readPayloadGlobalOptions(payload) {
+  if (typeof payload === "object" && payload !== null) {
+    const global = payload.global;
+    if (typeof global === "object" && global !== null) {
+      return global;
+    }
+  }
+  return {};
+}
+
 export async function runCalendarPackage(options, global) {
   const loaded = await ensureCalendarCoreModule();
   return loaded.runCalendar(options, global);
@@ -79,11 +95,14 @@ export async function runCalendarPackage(options, global) {
 
 export function renderCalendarPackageOutput(context) {
   const result = readPayloadResult(context.payload);
-  if (!calendarCore || !isCalendarCommand(context.command) || !isCalendarResult(result)) {
+  if (!calendarCore || !isCalendarResult(result)) {
     return null;
   }
-  const options = context.options ?? {};
-  const global = context.global ?? {};
+  const options =
+    context.options && Object.keys(context.options).length > 0
+      ? context.options
+      : readPayloadCommandOptions(context.payload);
+  const global = context.global ?? readPayloadGlobalOptions(context.payload);
   const outputFormat = calendarCore.resolveCalendarOutputFormat(options, global);
   if (outputFormat === "markdown") {
     return `${calendarCore.renderCalendarMarkdown(result)}\n`;

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

@@ -60,10 +60,6 @@ function isCalendarResult(value: unknown): value is CalendarResult {
   );
 }
 
-function isCalendarCommand(command: unknown): boolean {
-  return command === "calendar" || command === "cal";
-}
-
 function readPayloadFormat(payload: unknown): "toon" | "json" {
   if (typeof payload === "object" && payload !== null) {
     const format = (payload as { format?: unknown }).format;
@@ -81,6 +77,26 @@ function readPayloadResult(payload: unknown): unknown {
   return payload;
 }
 
+function readPayloadCommandOptions(payload: unknown): CalendarOptions {
+  if (typeof payload === "object" && payload !== null) {
+    const commandOptions = (payload as { command_options?: unknown }).command_options;
+    if (typeof commandOptions === "object" && commandOptions !== null) {
+      return commandOptions as CalendarOptions;
+    }
+  }
+  return {};
+}
+
+function readPayloadGlobalOptions(payload: unknown): GlobalOptions {
+  if (typeof payload === "object" && payload !== null) {
+    const global = (payload as { global?: unknown }).global;
+    if (typeof global === "object" && global !== null) {
+      return global as GlobalOptions;
+    }
+  }
+  return {};
+}
+
 export async function runCalendarPackage(options: CalendarOptions, global: GlobalOptions): Promise<CalendarResult> {
   const loaded = await ensureCalendarCoreModule();
   return loaded.runCalendar(options, global);
@@ -88,11 +104,14 @@ export async function runCalendarPackage(options: CalendarOptions, global: Globa
 
 export function renderCalendarPackageOutput(context: ServiceOverrideContext): string | null {
   const result = readPayloadResult(context.payload);
-  if (!calendarCore || !isCalendarCommand(context.command) || !isCalendarResult(result)) {
+  if (!calendarCore || !isCalendarResult(result)) {
     return null;
   }
-  const options = (context.options ?? {}) as CalendarOptions;
-  const global = (context.global ?? {}) as GlobalOptions;
+  const options =
+    context.options && Object.keys(context.options).length > 0
+      ? (context.options as CalendarOptions)
+      : readPayloadCommandOptions(context.payload);
+  const global = context.global ?? readPayloadGlobalOptions(context.payload);
   const outputFormat = calendarCore.resolveCalendarOutputFormat(options, global);
   if (outputFormat === "markdown") {
     return `${calendarCore.renderCalendarMarkdown(result)}\n`;

package/packages/pm-calendar/package.json

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

package/packages/pm-governance-audit/package.json

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

package/packages/pm-guide-shell/extensions/guide-shell/index.js

@@ -66,7 +66,7 @@ export function activate(api) {
   api.registerCommand(completionTagsCommand());
   api.registerService("output_format", (context) => {
     const rendered = renderGuideShellPackageOutput(context);
-    return rendered ?? context.payload;
+    return rendered ?? null;
   });
 }
 

package/packages/pm-guide-shell/extensions/guide-shell/index.ts

@@ -71,7 +71,7 @@ export function activate(api: ExtensionApi): void {
   api.registerCommand(completionTagsCommand());
   api.registerService("output_format", (context) => {
     const rendered = renderGuideShellPackageOutput(context as ServiceOverrideContext);
-    return rendered ?? context.payload;
+    return rendered ?? null;
   });
 }
 

package/packages/pm-guide-shell/package.json

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

package/packages/pm-linked-test-adapters/package.json

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

package/packages/pm-search-advanced/extensions/search-advanced/index.ts

@@ -6,7 +6,7 @@ export const manifest = {
   version: "0.1.0",
   entry: "./index.js",
   priority: 0,
-  capabilities: ["commands"],
+  capabilities: ["commands", "schema"],
 };
 
 const searchAdvancedFlags = [

package/packages/pm-search-advanced/package.json

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

package/packages/pm-templates/README.md

@@ -1,6 +1,6 @@
 # pm Templates Package
 
-`@unbrained/pm-package-templates` provides reusable `pm create` templates as an installable pm package.
+`@unbrained/pm-templates` provides reusable `pm create` templates as an installable pm package.
 
 Install it with:
 

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"