@unbrained/pm-cli 2026.5.14 → 2026.5.24

package/docs/CLAUDE_CODE_PLUGIN.md

@@ -8,9 +8,9 @@ Native pm integration for Claude Code via the Model Context Protocol (MCP). Clau
 pm-cli/ (repo root)
 ├── .claude-plugin/
 │   └── marketplace.json     # Root marketplace catalog — read by /plugin marketplace add
-├── plugins/pm-cli-claude/
+├── plugins/pm-claude/
 │   ├── .claude-plugin/
-│   │   └── plugin.json      # Claude Code plugin manifest (name: "pm-cli")
+│   │   └── plugin.json      # Claude Code plugin manifest (name: "pm-claude")
 │   ├── .mcp.json            # MCP server config using ${CLAUDE_PLUGIN_ROOT}
 │   ├── skills/
 │   │   ├── pm-workflow/     # Auto-invoked: orient → claim → implement → close
@@ -64,7 +64,7 @@ The server exposes 18 native tools that call pm library functions directly:
 | `pm_validate` | `pm validate` | `options.checkResolution`, `options.checkFiles` |
 | `pm_health` | `pm health` | `options.checkOnly` |
 | `pm_contracts` | `pm contracts` | `options.command`, `options.json` |
-| `pm_guide` | `pm guide` | `options.topic`, `options.depth` |
+| `pm_plan` | `pm plan` | `options.subcommand`, `id`, `stepRef` |
 | `pm_run` | any pm action | `action` (required), `id`, `query`, `reason`, `options.*` |
 
 All tools accept `cwd` (workspace directory), `path` (pm data root override), and `author` (mutation author).
@@ -77,15 +77,15 @@ Add the pm-cli GitHub repo as a marketplace source, then install:
 
 ```
 /plugin marketplace add unbraind/pm-cli
-/plugin install pm-cli@pm-cli
+/plugin install pm-claude@pm
 ```
 
-This clones the repo, reads `.claude-plugin/marketplace.json` at the root, installs the plugin from `./plugins/pm-cli-claude/`, and configures the MCP server, 5 skills, 9 slash commands, and the session hook automatically.
+This clones the repo, reads `.claude-plugin/marketplace.json` at the root, installs the plugin from `./plugins/pm-claude/`, and configures the MCP server, 5 skills, 9 slash commands, and the session hook automatically.
 
 ### 2. Global MCP 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
 ```
 
 Gives you the 18 MCP tools without skills or slash commands.
@@ -97,9 +97,9 @@ Add to the project's `.mcp.json`:
 ```json
 {
   "mcpServers": {
-    "pm-cli-native": {
+    "pm-mcp": {
       "command": "node",
-      "args": ["./plugins/pm-cli-claude/scripts/pm-mcp-server.mjs"],
+      "args": ["./plugins/pm-claude/scripts/pm-mcp-server.mjs"],
       "env": { "PM_AUTHOR": "claude-code-agent" }
     }
   }
@@ -110,7 +110,7 @@ The repo root `.mcp.json` uses this approach — activates automatically when Cl
 
 ## MCP Server Launcher
 
-`plugins/pm-cli-claude/scripts/pm-mcp-server.mjs` resolves the server in order:
+`plugins/pm-claude/scripts/pm-mcp-server.mjs` resolves the server in order:
 
 1. `PM_CLI_MCP_SERVER` env var (explicit override)
 2. `dist/mcp/server.js` walking up from the launcher (repo checkout)
@@ -188,7 +188,7 @@ For migration details and automation expectations, see:
 
 ```bash
 claude plugin validate .claude-plugin/marketplace.json
-claude plugin validate plugins/pm-cli-claude/.claude-plugin/plugin.json
+claude plugin validate plugins/pm-claude/.claude-plugin/plugin.json
 ```
 
 ### Manual verification

package/docs/CODEX_PLUGIN.md

@@ -1,6 +1,6 @@
 # Codex Plugin
 
-pm-cli ships a repo-local Codex plugin at [`plugins/pm-cli-codex`](../plugins/pm-cli-codex/README.md).
+pm-cli ships a repo-local Codex plugin at [`plugins/pm-codex`](../plugins/pm-codex/README.md).
 
 ## Install From This Repo
 
@@ -12,7 +12,7 @@ Restart Codex and install **pm CLI** from the `pm CLI Local` marketplace.
 
 ## What It Provides
 
-- `pm-cli-native` MCP server for structured pm operations without invoking the `pm` shell command
+- `pm-mcp` MCP server for structured pm operations without invoking the `pm` shell command
 - narrow tools for common loops: context, search, list, get, create, update, claim, release, close, comments, files, docs, tests, validate, health, contracts, and guide
 - `pm_run` for the rest of the pm surface, including calendar, activity, aggregate, dedupe-audit, normalize, reindex, extensions, templates, history, stats, gc, and test-runs controls
 - skills for native tracking, audits, and release workflows

package/docs/COMMANDS.md

@@ -6,6 +6,7 @@ This is a task-oriented command guide. For exact flags, use runtime help because
 pm <command> --help
 pm <command> --help --json
 pm contracts --command <command> --flags-only --json
+pm install guide-shell --project
 pm guide commands --depth standard
 ```
 
@@ -13,7 +14,7 @@ pm guide commands --depth standard
 
 - Prefer `pm context`, `pm search`, and narrow list commands before mutation.
 - Prefer TOON for reading and `--json` for strict parsing.
-- Use `pm guide <topic>` for local docs routing before opening deeper pages.
+- Use `pm install guide-shell --project` before `pm guide <topic>` when local docs routing is needed.
 - Use `pm contracts` for machine clients.
 - Every mutation writes history.
 
@@ -26,27 +27,36 @@ Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 | Bootstrap | `init`, `config`, `health` | create and inspect tracker setup |
 | Triage | `context`, `search`, `list*`, `aggregate`, `dedupe-audit` | find work and audit decomposition |
 | Lifecycle | `create`, `claim`, `update`, `append`, `close`, `release`, `delete`, `start-task`, `pause-task`, `close-task` | mutate item state |
+| Planning | `plan create`, `plan add-step`, `plan update-step`, `plan complete-step`, `plan link`, `plan approve`, `plan materialize` | agent-optimized living plans with ordered steps, evidence, decisions, validation, and materialization |
 | Logs | `comments`, `notes`, `learnings`, `comments-audit` | record progress and durable context |
 | Links | `files`, `docs`, `test`, `deps` | connect items to artifacts, tests, and relationships |
 | Verification | `test`, `test-all`, `test-runs`, `validate`, `gc` | run linked tests and repository checks |
-| History | `history`, `activity`, `restore`, `stats` | inspect and recover item state |
+| History | `history`, `history-redact`, `history-repair`, `activity`, `restore`, `stats` | inspect, redact, re-anchor, and recover item state |
+| Schema | `schema add-type` | register config-driven custom item types into `.agents/pm/schema/types.json` |
 | Calendar | `calendar`, `cal` | project deadlines, reminders, and events |
 | Packages | `install`, `upgrade`, `package`, `packages`, `extension`, package/extension command groups | install, upgrade, manage, and run package-backed extension commands |
-| Machines | `guide`, `contracts`, `completion`, `help` | local docs routing plus command contracts and shell helpers |
+| Machines | `contracts`, `help`, optional `guide`/`completion` | command contracts plus optional guide-shell docs routing and shell helpers |
 
 ## Bootstrap
 
 ```bash
 pm init
+pm init --defaults --with-packages
+pm init --agent-guidance status
+pm init --agent-guidance add
 pm config project list
-pm health --check-only
+pm health --check-only --summary --json
 ```
 
-`pm init` creates `.agents/pm`. `pm health --check-only` inspects without refreshing optional search artifacts.
+`pm init` creates `.agents/pm`. `pm health --check-only --summary --json` gives the smallest machine-readable health gate without refreshing optional search artifacts.
+`pm init --agent-guidance ask` is the default behavior: prompt in TTY only when AGENTS/CLAUDE guidance is missing and no decline is recorded.
+Use `--agent-guidance add` to write guidance, `--agent-guidance skip` to persist a decline without writing, and `--agent-guidance status` to inspect guidance state.
+Use `--with-packages` for one-step agent setup when bundled package commands should be active immediately.
 
 ## Packages
 
 ```bash
+pm package                     # bare command defaults to --explore (list installed)
 pm install '*' --project
 pm package catalog --project
 pm install npm:@scope/pm-package --project
@@ -56,7 +66,7 @@ pm upgrade --packages-only
 pm upgrade --cli-only --repair
 ```
 
-`pm install` and `pm package` are the preferred package-first workflow. `pm install '*'`, shell-expanded `pm install *`, and `pm install all` install bundled first-party packages. `pm extension` remains as a compatibility command for direct extension lifecycle operations.
+`pm install` and `pm package` are the preferred package-first workflow. `pm package` and `pm extension` bare invocations default to `--explore` so agents can list installed packages without remembering an action flag. `pm install '*'`, shell-expanded `pm install *`, and `pm install all` install bundled first-party packages. `pm extension` remains as a compatibility command for direct extension lifecycle operations.
 When package-owned commands are unavailable, usage guidance includes an install-ready retry (for example `pm install calendar`, `pm install search-advanced`, `pm install governance-audit`, or `pm install guide-shell`).
 
 ## Triage
@@ -74,7 +84,18 @@ Use `context` first for a compact active-work snapshot. Use `search` when the re
 
 ## Create and Update
 
-Minimal progressive create:
+Shortest agent-friendly create (positional title + defaults to `Task` type):
+
+```bash
+pm create "Document command contracts"
+pm create "Fix login bug" --type Issue --priority high
+```
+
+`pm create` defaults `--type` to `settings.governance.create_default_type` (falling back to `Task`).
+Pass `--create-mode strict` to require an explicit `--type` flag for governance-controlled flows.
+Priority accepts either `0..4` or the equivalent names `critical`, `high`, `medium`, `low`, and `minimal`.
+
+Minimal progressive create with explicit fields:
 
 ```bash
 pm create \
@@ -104,11 +125,23 @@ Update existing work:
 
 ```bash
 pm update <id> --status in_progress --message "Start implementation"
-pm update <id> --deadline +1d --estimate 120
+pm update <id> --priority medium --deadline +1d --estimate 120
 pm update <id> --parent <parent-id>
 pm append <id> --body "Detailed implementation notes."
 ```
 
+## Templates
+
+After `pm install templates --project`, `pm templates` lists both saved templates and built-in starters:
+
+```bash
+pm templates
+pm templates show bug
+pm create --template bug --title "Fix search regression"
+```
+
+Built-ins are `bug`, `feature`, `spike`, and `chore`. A saved template with the same name overrides the built-in.
+
 Use `pm close <id> "<reason>"` instead of `pm update --status closed`.
 
 ## Lifecycle Aliases
@@ -146,9 +179,9 @@ Use comments for progress and evidence, notes for implementation context, and le
 ## Linked Artifacts
 
 ```bash
-pm files <id> --add path=src/cli/main.ts,scope=project,note="command wiring"
+pm files <id> --add path=src/cli/main.ts,note="command wiring"
 pm files <id> --add-glob "src/cli/**/*.ts"
-pm docs <id> --add path=docs/COMMANDS.md,scope=project,note="public command docs"
+pm docs <id> --add path=docs/COMMANDS.md,note="public command docs"
 pm deps <id> --format tree
 ```
 
@@ -157,7 +190,7 @@ Linked files and docs keep reviews reproducible. `deps` is read-only and project
 ## Linked Tests
 
 ```bash
-pm test <id> --add command="node scripts/run-tests.mjs test -- tests/unit/output.spec.ts",scope=project,timeout_seconds=240
+pm test <id> --add command="node scripts/run-tests.mjs test -- tests/unit/output.spec.ts",timeout_seconds=240
 pm test <id> --run --progress
 pm test-all --status in_progress --progress
 ```
@@ -200,12 +233,84 @@ Use dry-run modes before broad lifecycle or cleanup changes.
 
 ```bash
 pm history <id> --limit 20
-pm history <id> --diff --verify
+pm history <id> --full --diff --verify
+pm history-redact <id> --literal "[redacted_path_prefix]/private" --replacement "[redacted_path]"
+pm history-redact <id> --regex "/192\\.168\\.[0-9.]+/g" --dry-run
+pm history-repair <id> --dry-run
+pm history-repair <id> --message "re-anchor legacy drift"
 pm activity --id <id> --limit 50
+pm activity --full --id <id> --limit 50
 pm restore <id> <timestamp-or-version>
 ```
 
 History is append-only. Restore appends a new restore event instead of rewriting old history.
+`history-redact` rewrites matching history payloads deterministically, recomputes hash chains, and appends an auditable `history_redact` marker entry when changes are applied.
+`history-repair` re-anchors a drifted history chain when `pm health`/`pm validate --check-history-drift` report stale hashes: it replays the stream, recomputes every before/after hash, repairs legacy patch ops that no longer strictly apply, reconciles the latest hash with the on-disk item, and appends an auditable `history_repair` marker. It never modifies item content and is a safe no-op on a clean stream.
+
+## Custom Item Types
+
+`pm schema add-type` registers a config-driven custom item type so agents can use `pm create <Type> "..."` for project-specific work categories without editing settings by hand. The definition is merged into the runtime type registry from `.agents/pm/schema/types.json` (shape: `{ "definitions": [ItemTypeDefinition...] }`).
+
+```bash
+pm schema add-type Spike --description "Time-boxed investigation" --default-status open
+pm schema add-type Spike --alias spike --alias research --folder spikes
+pm create Spike "Investigate retry backoff"
+```
+
+- The command is an idempotent UPSERT keyed on the type name (case-insensitive); re-running it merges aliases and overrides supplied fields while preserving everything else.
+- Built-in types (Chore, Decision, Epic, Event, Feature, Issue, Meeting, Milestone, Plan, Reminder, Task) are reserved and cannot be redefined.
+- Flags: `--description <text>`, `--default-status <status>`, `--folder <dir>`, `--alias <name>` (repeatable), plus `--author`/`--force` governance flags. Add `--json` for the machine envelope.
+- When `pm create`/`pm update` reject an unknown type, the error now points back here: `To register a custom type, run: pm schema add-type "X" (writes .agents/pm/schema/types.json).`
+
+## Plan Workflow
+
+`pm plan` is the agent-optimized planning loop built on the first-class `Plan` item type. Plans persist ordered steps, evidence, decisions, discoveries, validation, and resume context. Each mutation appends a history entry; full hash-chain replay is preserved.
+
+```bash
+pm plan create --title "Refactor lock retry" --scope "Improve retry semantics" --harness claude-code --parent pm-epic1 --related pm-rel1,pm-rel2 --claim
+pm plan add-step <plan-id> --step-title "Read lock.ts" --step-body "Inspect retry path" --depends-on pm-task1
+pm plan update-step <plan-id> plan-step-001 --step-status in_progress --step-evidence "started reading lock.ts"
+pm plan complete-step <plan-id> plan-step-001 --step-evidence "lock.ts read; retry path captured"
+pm plan block-step <plan-id> plan-step-003 --step-blocked-reason "waiting on pm-task9 approval"
+pm plan link <plan-id> plan-step-002 --link pm-rel3 --link-kind discovered_from --link-note "found related util"
+pm plan decision <plan-id> --decision-text "Use exponential backoff" --decision-rationale "Avoid thundering herd"
+pm plan discovery <plan-id> --discovery-text "Found existing util in src/util/retry.ts"
+pm plan validation <plan-id> --validation-text "Coverage stays at 100%" --validation-command "node scripts/run-tests.mjs coverage"
+pm plan resume <plan-id> --resume-context "step 2 pending; tests still failing on retry path"
+pm plan approve <plan-id> --message "ready to execute"
+pm plan materialize <plan-id> --steps plan-step-002,plan-step-003 --materialize-type Task --materialize-parent pm-epic1
+pm plan show <plan-id> --depth brief
+pm plan show <plan-id> --depth standard
+pm plan show <plan-id> --depth deep
+pm plan show <plan-id> --fields id,title,steps_summary
+```
+
+Subcommand cheatsheet:
+
+| Subcommand | Purpose |
+|------------|---------|
+| `create` | Create a Plan item with scope, harness, parent, related, blocked-by, and optional auto-claim |
+| `show` | Progressive-disclosure read (brief / standard / deep) with current step + next-action hints |
+| `add-step` | Append a step with title/body/owner/status/dependencies/files/tests/docs |
+| `update-step` | Patch one step (title, body, status, evidence, owner, blocked reason) |
+| `complete-step` | Shortcut for setting a step to `completed` with evidence |
+| `block-step` | Shortcut for setting a step to `blocked` with required `--step-blocked-reason` |
+| `reorder-step` | Move a step to a new 1-based order |
+| `remove-step` | Drop a step and renumber remaining steps |
+| `link` / `unlink` | Add or remove `linked_items` on a step (with optional `--promote-to-item-dep`) |
+| `decision` | Append a decision log entry (decision/rationale/evidence) |
+| `discovery` | Append a discovery log entry |
+| `validation` | Append a validation check (text/command/expected) |
+| `resume` | Replace the resume-context summary for stateless agents |
+| `approve` | Move `plan_mode` to `approved` (default) or any other mode via `--mode` |
+| `materialize` | Create real pm items (default `Task`) from selected steps with bidirectional links |
+
+Invariants:
+
+- Exactly one step is `in_progress` per Plan; pass `--allow-multiple-active` for explicit parallel branches.
+- Blocking a step requires `--step-blocked-reason` (or an already-recorded reason).
+- `materialize` adds `discovered_from` + `parent` to each new item and an `implements` link back on the source step plus a `child` dependency on the Plan.
+- Search keyword corpus includes plan_scope, step titles/bodies, decisions, discoveries, validation, and step linked items.
 
 ## Machine Contracts
 

package/docs/CONFIGURATION.md

@@ -48,7 +48,8 @@ Precedence:
 | `validation.sprint_release_format` | `warn` or `strict_error` |
 | `validation.parent_reference` | `warn` or `strict_error` |
 | `item_types.definitions[]` | custom item types and type options |
-| `search.*` | search mode, scoring, providers, and vector settings |
+| `governance.create_default_type` | default `--type` used by the `pm create "title"` positional shortcut (defaults to `Task`) |
+| `search.*` | search mode, scoring, providers, embedding timeout, and vector settings |
 
 ## Environment Variables
 
@@ -103,7 +104,7 @@ Use standalone checks when validating a repository:
 ```bash
 pm validate --check-resolution --check-history-drift
 pm validate --check-files --scan-mode tracked-all
-pm health --check-only
+pm health --check-only --summary --json
 ```
 
 ## Search Configuration
@@ -116,6 +117,8 @@ pm search "release docs" --mode keyword --limit 10
 
 Semantic and hybrid search can use built-in OpenAI-compatible or Ollama providers plus vector stores such as Qdrant or LanceDB. If local Ollama is available and semantic settings are unset, `pm` can resolve local defaults automatically.
 
+For local Ollama or slower embedding providers, tune `search.embedding_batch_size`, `search.embedding_timeout_ms`, and `search.scanner_max_batch_retries` in project config before assuming semantic search is broken. Keyword search remains the fast baseline while semantic indexing catches up.
+
 Useful commands:
 
 ```bash