@unbrained/pm-cli 2026.5.6 → 2026.5.11

package/docs/MIGRATION_CLI_SIMPLIFICATION.md

@@ -0,0 +1,64 @@
+# CLI Simplification Migration (Conservative Full-Surface Pass)
+
+This note documents behavioral and output-shape changes introduced in the conservative CLI simplification pass.
+
+## What Changed
+
+### 1) Command invocation normalization before Commander parse
+
+`pm` now normalizes invocation tokens before Commander parses them:
+
+- long-flag shape normalization (`--foo_bar` / camel variants -> canonical kebab flags)
+- high-confidence typo normalization for long flags
+- `key=value` / `key:value` promotion into canonical `--flag value` tokens when unambiguous
+- legacy `pm extension <action>` shorthand normalization to explicit action flags
+
+Normalization runs across command families and preserves a normalization trace for diagnostics and recovery.
+
+### 2) Setup-agnostic PM root discovery
+
+`resolvePmRoot()` precedence is now:
+
+1. explicit `--path`
+2. `PM_PATH`
+3. upward discovery of initialized `.agents/pm` roots (must contain `settings.json`)
+4. local default (`<cwd>/.agents/pm`)
+
+If you need the old local-only behavior from nested directories, pass an explicit path (`--path .agents/pm`).
+
+### 3) Structured recovery bundles in CLI error output
+
+Error payloads now include optional `recovery` metadata in text and JSON guidance surfaces:
+
+- `attempted_command`
+- `normalized_args`
+- `provided_fields`
+- `missing`
+- `suggested_retry`
+
+Automation should read this bundle for deterministic retries instead of rebuilding retries from free-form error text.
+
+### 4) Legacy `none`/`null` compatibility in create/update
+
+For deterministic compatibility:
+
+- scalar `none` / `null` values on unset-capable fields are reinterpreted as `--unset <field>`
+- repeatable `none` / `null` values are reinterpreted as their matching `--clear-*` action
+- mixed legacy clear token + concrete repeatable payloads remain rejected (ambiguous input)
+
+## Migration Guidance for Automation
+
+- **Prefer contracts first**: keep using `pm contracts --json` and command-scoped flag contracts.
+- **Consume `recovery` directly**: treat `recovery.suggested_retry` as first-choice replay command.
+- **Do not hardcode old error envelopes**: parsers should tolerate additional fields (`recovery`) and richer guidance text.
+- **Avoid relying on local cwd-only root resolution**: pass `--path` explicitly when wrappers need fixed data roots.
+- **Update none/null assumptions**: if your tests expected hard failures for pure `none`/`null` clear intents, update them to expect deterministic clear/unset behavior.
+
+## Verification Checklist
+
+- `tests/unit/bootstrap-args.spec.ts`
+- `tests/unit/store-paths.spec.ts`
+- `tests/integration/help-runtime.spec.ts`
+- `tests/unit/create-command.spec.ts`
+- `tests/unit/update-command.spec.ts`
+

package/docs/PI_PACKAGE.md

@@ -0,0 +1,141 @@
+# Pi Native Package & Claude Code Plugin
+
+pm-cli ships both an official Pi package and a Claude Code plugin so AI coding agents can use pm through native integrations instead of shelling out to the `pm` CLI.
+
+## Claude Code Plugin
+
+The Claude Code plugin (`plugins/pm-cli-claude/`) provides full native pm integration for Claude Code without any CLI dependency.
+
+### Install
+
+```
+/plugin install pm-cli@pm
+```
+
+Both `pm` and `pm-cli` marketplace IDs work:
+
+```
+/plugin install pm-cli@pm      # canonical
+/plugin install pm-cli@pm-cli  # legacy alias
+```
+
+To add the marketplace first (local checkout):
+
+```bash
+claude plugin marketplace add /path/to/pm-cli
+```
+
+After npm publish, the marketplace will be available via GitHub:
+
+```bash
+claude plugin marketplace add unbraind/pm-cli
+```
+
+### Plugin Components
+
+| Component | Path | What it provides |
+|-----------|------|-----------------|
+| MCP server | `scripts/pm-mcp-server.mjs` | 18 native MCP tools |
+| Skills | `skills/` | 5 workflow skills auto-loaded in Claude Code |
+| Commands | `commands/` | 14 slash commands |
+| Agents | `agents/` | 3 subagents + 1 delivery chain |
+| Hooks | `hooks/` | Session-start context injection |
+
+### MCP Tools (18)
+
+Narrow 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`
+
+General tool: `pm_run` (with explicit `action` for everything else)
+
+### Subagents (4)
+
+| Agent | Description |
+|-------|-------------|
+| `pm-coordinator` | Multi-item batch coordination |
+| `pm-triage-agent` | Duplicate-safe item creation with lineage |
+| `pm-verification-agent` | Evidence collection and close readiness |
+| `pm-delivery-chain` | Full triage → implement → verify orchestration |
+
+### Session Hook
+
+The session-start hook runs natively:
+1. Walks up from plugin root to find `dist/pi/native.js` in a repo checkout
+2. Falls back to `npx @unbrained/pm-cli` if no local dist
+3. No `pm` CLI global install required in either path
+
+---
+
+## Pi Native Package
+
+The Pi package at `.pi/` exposes pm through Pi's native extension API.
+
+### Install
+
+After the package is published:
+
+```bash
+pi install npm:@unbrained/pm-cli
+```
+
+From a local checkout:
+
+```bash
+pnpm build
+pi install -l .
+# or try without writing settings
+pi --no-extensions -e .
+```
+
+`pnpm build` is required for local checkouts because the Pi extension imports the compiled native integration from `dist/pi/native.js`.
+
+### Package Resources
+
+The root `package.json` declares the Pi manifest:
+
+- `pi.extensions`: `.pi/extensions/pm-cli/index.js`
+- `pi.skills`: `.pi/skills`
+- `pi.prompts`: `.pi/prompts`
+
+The extension registers:
+
+- native `pm` tool using pm command modules directly, not the `pm` shell command
+- custom TUI rendering for pm tool calls/results (context, list/search, item details, history/activity)
+- `/pm-context`, `/pm-board`, `/pm-item`, `/pm-history`, `/pm-start`, `/pm-close`, `/pm-actions`, and `/pm-workflows` helper commands
+- `@pm-...` item autocomplete layered on top of Pi's editor completion
+- footer status and a small below-editor widget (`pm native ready`) in interactive mode
+
+### Native Tool Usage
+
+Use the Pi `pm` tool with an `action` field. Examples:
+
+```json
+{ "action": "context", "limit": 10 }
+{ "action": "search", "query": "pi extension", "limit": 10 }
+{ "action": "start-task", "id": "pm-1234", "author": "pi-agent" }
+{ "action": "files", "id": "pm-1234", "add": ["path=src/file.ts,scope=project,note=implementation"], "author": "pi-agent" }
+{ "action": "close-task", "id": "pm-1234", "text": "Verified and complete", "author": "pi-agent", "validateClose": "warn" }
+```
+
+For real project tracking, leave `path` unset. For tests, set `path` to a sandbox pm root and isolate `PM_GLOBAL_PATH`.
+
+### Pi TUI Commands
+
+```text
+/pm-board [limit]        # context dashboard with active items
+/pm-item <pm-id>         # item details and recent comments
+/pm-history <pm-id>      # item history panel
+/pm-actions              # installed native action list
+/pm-workflows            # suggested native pm workflows
+```
+
+### Pi Skills and Subagents
+
+- Skills: `pm-native`, `pm-release`
+- Prompt template: `/pm-workflow`
+- Subagent files: `.pi/agents/pm-triage-agent.md`, `.pi/agents/pm-verification-agent.md`, `.pi/chains/pm-native-delivery.chain.md`
+
+---
+
+## Supported Surface
+
+Both integrations cover the core pm action set: init/config/extensions, item creation and lifecycle, list/search/context/calendar/activity, files/docs/deps/tests, validation/health/gc/contracts, templates, test-runs, guide workflows, bundled beads/todos import/export, and lifecycle shortcuts (`start-task`, `pause-task`, `close-task`).

package/docs/QUICKSTART.md

@@ -9,6 +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.
 
 Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 

package/docs/README.md

@@ -2,6 +2,18 @@
 
 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
+
+`pm guide` exposes the same documentation routes from inside the CLI:
+
+```bash
+pm guide
+pm guide quickstart
+pm guide commands --depth standard
+pm guide sdk --depth deep --format markdown
+pm guide release --json
+```
+
 ## Read Path
 
 | Reader | First page | Then read |
@@ -10,7 +22,9 @@ This directory is the public documentation home for `pm-cli`. It is organized fo
 | Coding agent | [Agent Guide](AGENT_GUIDE.md) | [Configuration](CONFIGURATION.md), then command help |
 | Maintainer | [Contributing](../CONTRIBUTING.md) | [Testing](TESTING.md), [Releasing](RELEASING.md), [Architecture](ARCHITECTURE.md) |
 | Extension author | [Extensions](EXTENSIONS.md) | [SDK](SDK.md), [starter extension](examples/starter-extension/README.md) |
-| Machine client | [Command Reference](COMMANDS.md#machine-contracts) | `pm contracts --json` |
+| Pi user | [Pi Package](PI_PACKAGE.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.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` |
 
 ## Documentation Map
 
@@ -22,9 +36,24 @@ This directory is the public documentation home for `pm-cli`. It is organized fo
 - [Architecture](ARCHITECTURE.md) - contributor internals: storage, mutation flow, search, extensions, and command contracts.
 - [Extensions](EXTENSIONS.md) - runtime extension lifecycle and API reference.
 - [SDK](SDK.md) - public import surfaces and typed authoring examples.
+- [Pi Package](PI_PACKAGE.md) - official Pi package install, native tool, skills, prompts, and workflows.
+- [Codex Plugin](CODEX_PLUGIN.md) - native MCP plugin install, tools, skills, and safety notes.
 - [Releasing](RELEASING.md) - maintainer release checklist and failure handling.
 - [starter extension](examples/starter-extension/README.md) - compact extension scaffold reference.
 
+## Guide Topic Map
+
+| `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) |
+| `sdk` | [SDK](SDK.md), [Architecture](ARCHITECTURE.md) |
+| `extensions` | [Extensions](EXTENSIONS.md), [starter extension](examples/starter-extension/README.md) |
+| `skills` | [Agent Guide](AGENT_GUIDE.md) plus `.agents/skills/*` |
+| `harnesses` | [Agent Guide](AGENT_GUIDE.md) plus `.agents/skills/HARNESS_COMPATIBILITY.md` |
+| `release` | [Releasing](RELEASING.md), [CHANGELOG](../CHANGELOG.md) |
+
 Community files:
 
 - [Contributing](../CONTRIBUTING.md)

package/docs/RELEASING.md

@@ -1,6 +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`.
 
 ## Agent Quick Context
 
@@ -9,6 +10,7 @@ This page is for maintainers cutting npm and GitHub releases. It assumes 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.
 
 Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
 
@@ -64,7 +66,7 @@ The pipeline performs:
 
 1. change detection + one-release-per-day guard
 2. version bump + changelog promotion from `[Unreleased]`
-3. strict gates (build, typecheck, coverage, static quality, compatibility, security, smoke checks, reliability gate)
+3. strict gates (build, typecheck, docs/skills freshness, coverage, static quality, compatibility, security, smoke checks, reliability gate)
 4. release note generation from changelog + pm evidence
 5. commit and tag creation (plus optional push)
 
@@ -85,7 +87,7 @@ Minimum coverage:
 - parent and dependency links
 - comments, notes, learnings, body, reminders, events
 - linked files, docs, and tests
-- json_markdown items with external YAML wrappers before JSON front matter
+- legacy markdown item files (including external YAML wrappers before JSON front matter) migrating cleanly to TOON
 - closed issue metadata and history drift checks
 - current-build write mutation and item-count preservation