@unbrained/pm-cli 2026.5.6 → 2026.5.10

package/.agents/skills/pm-user/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: pm-user
+description: Guides user- and operator-facing pm-cli workflows for planning, triage, prioritization, and task lifecycle management with minimal token usage. Use when routing requests into pm items without implementing code changes.
+license: MIT
+compatibility: Works in terminal-based agent harnesses that execute pm CLI commands.
+metadata:
+  owner: unbrained
+  domain: pm-cli
+  scope: operator-workflow
+---
+
+# pm User Skill
+
+Use this skill for planning and coordination work where the main output is clean tracker state.
+
+## Quick Start
+
+```bash
+pm guide quickstart
+pm context --limit 10
+pm search "<request keywords>" --limit 10
+pm list-open --limit 20
+pm list-in-progress --limit 20
+```
+
+## Primary Use Cases
+
+- Intake a new request and decide whether an item already exists.
+- Create parent lineage (`Epic` -> `Feature` -> `Task`) for net-new scope.
+- Prioritize and schedule work with deterministic metadata.
+- Maintain clear ownership and handoff notes.
+
+## Workflow Prompts
+
+### Prompt: New Request Triage
+
+`Triage this request using pm only. Reuse an existing item if relevant; otherwise create canonical parent lineage and a scoped child item with duplicate-check evidence.`
+
+### Prompt: Prioritization Sweep
+
+`Review open and in-progress items, normalize priority/status metadata, and leave append-only notes explaining why any prioritization changed.`
+
+### Prompt: Handoff Preparation
+
+`Prepare handoff for <ID>: summarize state in comments, ensure linked files/tests/docs are complete, and release claim when ready.`
+
+## Deterministic Metadata Commands
+
+```bash
+pm update <ID> --description "..." --ac "..." --estimate 60
+pm update <ID> --deadline +2d --priority 1 --status open
+pm comments <ID> "Decision log: <why this status/priority>"
+pm notes <ID> --add "Context for next owner."
+```
+
+## Progressive Disclosure References
+
+- [Triage and planning workflows](references/WORKFLOWS.md)
+- [Operator prompt templates](references/PROMPTS.md)

package/.agents/skills/pm-user/references/PROMPTS.md

@@ -0,0 +1,17 @@
+# Operator Prompt Templates
+
+## Triage
+
+`Find the canonical pm item for this request. Show duplicate-check commands, then either reuse and update the item or create parent lineage + child item with explicit rationale.`
+
+## Schedule
+
+`Apply deterministic scheduling metadata (status, priority, estimate, deadline) to <ID> and leave a comment explaining the prioritization decision.`
+
+## Handoff
+
+`Prepare <ID> for handoff: append current state, blockers, and next actions; release the claim when handoff is complete.`
+
+## Closure Readiness
+
+`Validate whether <ID> is close-ready by checking acceptance criteria, linked files/tests/docs, and latest verification evidence.`

package/.agents/skills/pm-user/references/WORKFLOWS.md

@@ -0,0 +1,35 @@
+# User and Operator Workflows
+
+## Intake Workflow
+
+1. Query current context:
+
+```bash
+pm context --limit 10
+pm search "<keywords>" --limit 10
+pm list-open --limit 20
+pm list-in-progress --limit 20
+```
+
+2. If existing item matches, reuse and update it.
+3. If no match exists, create parent lineage then child item.
+4. Add duplicate-check evidence in comments at creation time.
+
+## Claim and Ownership Workflow
+
+```bash
+pm claim <ID>
+pm update <ID> --status in_progress --message "Start work"
+pm comments <ID> "Owner update: <state>"
+pm release <ID>
+```
+
+## Audit-Friendly Collaboration
+
+For non-owner append-only collaboration:
+
+```bash
+pm comments <ID> --add "audit comment" --allow-audit-comment
+pm notes <ID> --add "audit note" --allow-audit-comment
+pm update <ID> --dep "id=<id>,kind=related,author=<author>,created_at=now" --allow-audit-dep-update
+```

package/.claude-plugin/marketplace.json

@@ -0,0 +1,38 @@
+{
+  "name": "pm-cli",
+  "owner": {
+    "name": "unbrained",
+    "url": "https://github.com/unbraind/pm-cli"
+  },
+  "metadata": {
+    "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "pm-cli",
+      "source": "./plugins/pm-cli-claude",
+      "description": "Native pm CLI integration for Claude Code — 18 MCP tools, workflow skills, slash commands, session context injection, and a coordination subagent for git-based project management without leaving Claude Code.",
+      "version": "1.0.0",
+      "author": {
+        "name": "unbrained",
+        "url": "https://github.com/unbraind/pm-cli"
+      },
+      "homepage": "https://github.com/unbraind/pm-cli",
+      "repository": "https://github.com/unbraind/pm-cli",
+      "license": "MIT",
+      "keywords": [
+        "pm-cli",
+        "project-management",
+        "mcp",
+        "tasks",
+        "agents",
+        "workflows",
+        "git-native",
+        "task-tracker",
+        "ai"
+      ],
+      "category": "productivity"
+    }
+  ]
+}

package/.pi/README.md

@@ -0,0 +1,26 @@
+# pm CLI Pi Package
+
+This directory is the installable Pi package payload for `@unbrained/pm-cli`.
+
+Install from npm after publish:
+
+```bash
+pi install npm:@unbrained/pm-cli
+```
+
+For local development from a checkout:
+
+```bash
+pnpm build
+pi install -l .
+# or one-shot
+pi -e .
+```
+
+Resources exposed by `package.json`:
+
+- `.pi/extensions/pm-cli/index.js` — native Pi extension registering the `pm` tool and slash commands.
+- `.pi/skills/*` — Pi skills for native pm workflows and release validation.
+- `.pi/prompts/*` — prompt templates for pm-tracked work.
+
+The extension imports the built package from `dist/`, so run `pnpm build` before local install or before publishing.

package/.pi/extensions/pm-cli/index.js

@@ -0,0 +1,147 @@
+import { PM_TOOL_ACTIONS } from "../../../dist/sdk/cli-contracts.js";
+import { runNativePmAction } from "../../../dist/pi/native.js";
+
+const PM_PI_TOOL_PARAMETERS_SCHEMA = {
+  type: "object",
+  additionalProperties: true,
+  required: ["action"],
+  description: "Parameters for the native pm Pi tool. Extra properties are forwarded to the selected pm action.",
+  properties: {
+    action: {
+      type: "string",
+      description: "pm action to execute, for example context, search, get, create, update, files, docs, test, validate, or close-task.",
+    },
+    id: { type: "string", description: "pm item id for item-scoped actions." },
+    text: { type: "string", description: "Text payload for comment-like actions or close reasons." },
+    title: { type: "string", description: "Title for create actions." },
+    description: { type: "string", description: "Description for create/update actions." },
+    query: { type: "string", description: "Search query text." },
+    limit: { type: "string", description: "Result limit. Numeric strings are accepted." },
+    author: { type: "string", description: "Explicit pm author for mutations." },
+    path: { type: "string", description: "pm data path override or linked file path, depending on action." },
+    scope: { type: "string", description: "Link scope such as project." },
+    command: { type: "string", description: "Linked test command or shell completion target, depending on action." },
+    options: {
+      type: "object",
+      additionalProperties: true,
+      description: "Advanced command options object forwarded to the selected pm action.",
+    },
+  },
+};
+
+function contentText(result) {
+  if (typeof result === "string") return result;
+  return JSON.stringify(result, null, 2);
+}
+
+function errorDetails(error) {
+  return {
+    message: error instanceof Error ? error.message : String(error),
+    code: typeof error?.exitCode === "number" ? error.exitCode : 1,
+  };
+}
+
+export function createPmToolDefinition() {
+  return {
+    name: "pm",
+    label: "pm",
+    description:
+      "Use pm natively from Pi without shelling out to the pm CLI. Supports pm project context, search, lifecycle mutations, links, tests, validation, extension management, templates, calendar, and audit workflows.",
+    promptSnippet: "Run native pm project-management operations without bash or the pm CLI.",
+    promptGuidelines: [
+      "Use the pm tool instead of bash pm commands for project-management operations when this tool is available.",
+      "Use pm action=context/list-open/list-in-progress/search before creating new work items.",
+      "For mutations, set author explicitly and link changed files/tests/docs through pm actions before closing work.",
+    ],
+    parameters: PM_PI_TOOL_PARAMETERS_SCHEMA,
+    async execute(_toolCallId, params, _signal, onUpdate, ctx) {
+      onUpdate?.({ content: [{ type: "text", text: `Running native pm action: ${params.action}` }] });
+      try {
+        const result = await runNativePmAction({ cwd: ctx?.cwd, ...params });
+        return {
+          content: [{ type: "text", text: contentText(result) }],
+          details: { ok: true, action: params.action, result, native: true },
+        };
+      } catch (error) {
+        const details = errorDetails(error);
+        throw new Error(`pm ${params.action ?? "action"} failed: ${details.message}`);
+      }
+    },
+  };
+}
+
+export function registerPmCommands(pi) {
+  pi.registerCommand("pm-context", {
+    description: "Show pm context snapshot using the native pm integration",
+    handler: async (args, ctx) => {
+      const limit = args?.trim() || "10";
+      const result = await runNativePmAction({ cwd: ctx.cwd, action: "context", limit, json: false });
+      ctx.ui.notify(contentText(result), "info");
+    },
+  });
+
+  pi.registerCommand("pm-start", {
+    description: "Start/claim a pm item: /pm-start <id>",
+    handler: async (args, ctx) => {
+      const id = args?.trim();
+      if (!id) return ctx.ui.notify("Usage: /pm-start <id>", "error");
+      const result = await runNativePmAction({ cwd: ctx.cwd, action: "start-task", id, author: "pi-agent" });
+      ctx.ui.notify(contentText(result), "success");
+    },
+  });
+
+  pi.registerCommand("pm-close", {
+    description: "Close and release a pm item: /pm-close <id> <reason>",
+    handler: async (args, ctx) => {
+      const [id, ...reasonParts] = (args ?? "").trim().split(/\s+/);
+      const reason = reasonParts.join(" ");
+      if (!id || !reason) return ctx.ui.notify("Usage: /pm-close <id> <reason>", "error");
+      const result = await runNativePmAction({ cwd: ctx.cwd, action: "close-task", id, text: reason, author: "pi-agent", validateClose: "warn" });
+      ctx.ui.notify(contentText(result), "success");
+    },
+  });
+
+  pi.registerCommand("pm-actions", {
+    description: "List native pm tool actions",
+    handler: async (_args, ctx) => {
+      ctx.ui.notify(PM_TOOL_ACTIONS.join(", "), "info");
+    },
+  });
+}
+
+function patchPmToolParametersInProviderPayload(payload) {
+  if (!payload || typeof payload !== "object" || !Array.isArray(payload.tools)) {
+    return undefined;
+  }
+  let changed = false;
+  const tools = payload.tools.map((tool) => {
+    if (!tool || typeof tool !== "object") {
+      return tool;
+    }
+    if (tool.name === "pm") {
+      const parameters = tool.parameters;
+      if (!parameters || parameters.type !== "object") {
+        changed = true;
+        return { ...tool, parameters: PM_PI_TOOL_PARAMETERS_SCHEMA };
+      }
+    }
+    if (tool.function?.name === "pm") {
+      const parameters = tool.function.parameters;
+      if (!parameters || parameters.type !== "object") {
+        changed = true;
+        return { ...tool, function: { ...tool.function, parameters: PM_PI_TOOL_PARAMETERS_SCHEMA } };
+      }
+    }
+    return tool;
+  });
+  return changed ? { ...payload, tools } : undefined;
+}
+
+export default function pmCliPiExtension(pi) {
+  pi.registerTool(createPmToolDefinition());
+  pi.on("before_provider_request", (event) => patchPmToolParametersInProviderPayload(event.payload));
+  registerPmCommands(pi);
+  pi.on("session_start", async (_event, ctx) => {
+    ctx.ui.setStatus?.("pm", "pm native");
+  });
+}

package/.pi/prompts/pm-workflow.md

@@ -0,0 +1,5 @@
+---
+description: Start a pm-tracked implementation workflow using the native pm Pi tool.
+---
+
+Use the native `pm` tool to orient, find an existing relevant item, claim it, link evidence, verify, and close/release only after acceptance criteria are met. Do not run `pm` via bash when the native tool is available.

package/.pi/skills/pm-native/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: pm-native
+description: Native pm integration for Pi. Use when planning, claiming, updating, linking files/tests/docs, validating, or closing pm CLI work through the Pi pm tool instead of shelling out to the pm CLI.
+license: MIT
+compatibility: Pi coding-agent with the @unbrained/pm-cli Pi package installed.
+metadata:
+  owner: unbrained
+  domain: pm-cli
+  scope: pi-native
+---
+
+# pm Native for Pi
+
+Use the `pm` tool for project-management operations. Do not run `pm ...` through bash when the native tool is available.
+
+## Required Loop
+
+1. Orient before creating work:
+   - `pm` action `context` with `limit: 10`
+   - `pm` action `search` with relevant keywords
+   - `pm` action `list-open` and `list-in-progress`
+2. Claim work with action `claim` or `start-task`.
+3. Mutate with explicit `author`.
+4. Link evidence:
+   - action `files` with `add`
+   - action `docs` with `add`
+   - action `test` with sandbox-safe commands
+5. Verify with action `test`, `validate`, and project test commands when appropriate.
+6. Close with action `close-task` or `close`, then release if needed.
+
+## Common Tool Calls
+
+- Context: `{ "action": "context", "limit": 10 }`
+- Search: `{ "action": "search", "query": "pi native extension", "limit": 10 }`
+- Claim: `{ "action": "claim", "id": "pm-1234", "author": "pi-agent" }`
+- Link file: `{ "action": "files", "id": "pm-1234", "add": ["path=src/file.ts,scope=project,note=implementation"], "author": "pi-agent" }`
+- Add comment: `{ "action": "comments", "id": "pm-1234", "add": ["Evidence: build and tests passed"], "author": "pi-agent" }`
+- Close: `{ "action": "close-task", "id": "pm-1234", "text": "All acceptance criteria met", "author": "pi-agent", "validateClose": "warn" }`
+
+Use `pm guide` topics through action `guide` for deeper command docs.

package/.pi/skills/pm-release/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: pm-release
+description: Release-readiness workflow for pm projects in Pi. Use when running final validation, coverage, package checks, GitHub checks, and closure evidence through the native pm integration.
+license: MIT
+compatibility: Pi coding-agent with the @unbrained/pm-cli Pi package installed.
+metadata:
+  owner: unbrained
+  domain: pm-cli
+  scope: release
+---
+
+# pm Release Workflow for Pi
+
+Use the native `pm` tool for tracker state and linked evidence. Use shell only for non-pm project build/test commands.
+
+## Release Checklist
+
+1. `pm` action `context` with `depth: "standard"`.
+2. Run linked tests with `pm` action `test` and `run: true` for active work items.
+3. Run validation with `pm` action `validate`, usually `checkResolution: true`, `checkHistoryDrift: true`, and relevant file checks.
+4. Run package install/discovery smoke for Pi packages:
+   - local: `pi install -l .` or `pi -e .`
+   - npm after publish: `pi install npm:@unbrained/pm-cli`
+5. Use `gh` only to inspect GitHub checks after pushing.
+6. Add a `comments` evidence entry with exact command summaries.
+7. Close/release the pm item with `close-task` once acceptance criteria are met.
+
+## Evidence Format
+
+Record:
+- Changed package resources (`pi.extensions`, `pi.skills`, `pi.prompts`)
+- Native pm tool smoke result
+- Build/test/coverage result
+- Pi install smoke result
+- GitHub checks status

package/AGENTS.md

@@ -7,7 +7,7 @@ This document defines how coding agents must use `pm` for planning, execution, a
 - Use `pm` as the system of record for project work.
 - Prefer deterministic, script-friendly command usage (`--json` when strict parsing is needed).
 - Default to TOON output when human + model readability and low token use are desired (calendar command is the intentional exception and defaults to markdown unless overridden).
-- Treat TOON as the canonical item-document format in this repo; `front_matter` is an internal model key, while TOON item metadata is stored as top-level object fields.
+- Treat TOON as the canonical item-document format in this repo; item metadata is modeled as `metadata` internally and stored as top-level object fields in TOON.
 - Never make destructive item changes outside `pm` mutations.
 - Every mutation must produce a history entry.
 

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2026.5.10] - 2026-05-10
+
+### Changed
+- Added top-level `ok` fields to `pm test --run --json` and `pm test-all --json` so agents can gate linked-test execution without parsing every result row.
+- Capped and truncated semantic reindex embedding payloads for local Ollama providers, with adaptive timeout splitting, to avoid full-corpus reindex failures on large item bodies.
+
 ## [2026.5.6] - 2026-05-06
 
 ### Changed

package/PRD.md

@@ -73,7 +73,7 @@ Existing trackers either rely on hosted backends, store state in non-diff-friend
 
 From `todos.ts`:
 
-- Item file format = JSON front-matter at file start, blank line, then markdown body.
+- Legacy import format = JSON front-matter at file start, blank line, then markdown body.
 - ID normalization accepts optional `#` and optional prefix.
 - Claim/release is represented in-record (`assignee`).
 - Locking model:
@@ -246,16 +246,16 @@ Constraints:
 
 ## 7) Item File Format
 
-Each item is one document at `<type-folder>/<id>.toon` (default) or `<type-folder>/<id>.md` (JSON+Markdown alternative).
+Each item is one TOON document at `<type-folder>/<id>.toon`. Legacy `<type-folder>/<id>.md` files are read only for migration.
 
 Format:
 
-1. TOON root-object metadata keys (default) or JSON object metadata block (markdown format).
-2. Optional `body` field / markdown body.
+1. TOON root-object metadata keys.
+2. Optional `body` field.
 
 ### 7.1 Canonical item-metadata schema
 
-`front_matter` remains the internal field name in TypeScript (`ItemDocument.front_matter`), but TOON documents store the same metadata as top-level keys.
+`metadata` is the internal TypeScript field name (`ItemDocument.metadata`), and TOON documents store the same metadata as top-level keys.
 
 Required fields:
 
@@ -500,7 +500,7 @@ Canonical patch document shape:
 
 ```json
 {
-  "front_matter": { "...": "..." },
+  "metadata": { "...": "..." },
   "body": "markdown text"
 }
 ```
@@ -517,7 +517,7 @@ Canonical patch document shape:
 
 1. Resolve item or matching history stream for ID and load full history.
 2. Replay patches from initial create through target version/timestamp.
-3. Rebuild exact canonical document (`front_matter` + `body`).
+3. Rebuild exact canonical document (`metadata` + `body`).
 4. Write item atomically.
 5. Append a `restore` history event with patch from pre-restore state to restored state.
 
@@ -717,7 +717,7 @@ Help and error UX note:
 - `pm restore <ID> <TIMESTAMP|VERSION>`
 - `pm config <project|global> set definition-of-done --criterion <text>`
 - `pm config <project|global> get definition-of-done`
-- `pm config <project|global> set item-format --format toon|json_markdown`
+- `pm config <project|global> set item-format --format toon`
 - `pm config <project|global> get item-format`
 - `pm config <project|global> set history-missing-stream-policy --policy auto_create|strict_error`
 - `pm config <project|global> get history-missing-stream-policy`
@@ -970,7 +970,7 @@ Contract compatibility policy keeps command names/flags/aliases stable while all
 | `pm calendar` / `pm cal` | `--view agenda|day|week|month`, `--date`, `--from`/`--to` (agenda), `--past`, `--full-period` (day/week/month only), list-like filters (`type`, `tag`, `priority`, `status`, `assignee`, `sprint`, `release`, `limit`), source controls (`--include`), and recurrence bounds (`--recurrence-lookahead-days`, `--recurrence-lookback-days`, `--occurrence-limit`) | `{ view, output_default, now, anchor, range, filters, summary, events, days }` where `range` includes period metadata (`period_start`, `period_end`, `full_period`), `summary` includes deterministic aggregate breakdown fields (`by_kind`, `by_type`, `by_status`, `recurring_events`), and markdown output includes rich event detail tokens by default |
 | `pm context` / `pm ctx` | `--date`, `--from`/`--to`, `--past`, list-like filters (`type`, `tag`, `priority`, `assignee`, `sprint`, `release`, `limit`), `--format` | `{ output_default, now, window, filters, summary, high_level, low_level, blocked_fallback, agenda }` (defaults to TOON unless `--format` or `--json` override) |
 | `pm beads import [--file <path\|->] [--preserve-source-ids]` | optional Beads JSONL source path (`.beads/issues.jsonl` auto-discovered first, then `issues.jsonl`; implicit `sync_base.jsonl` fallback is refused as unsafe; `--file -` requires piped stdin and fails fast on interactive TTY stdin) | `{ ok, source, imported, skipped, ids, warnings }` |
-| `pm todos import --folder <path?>` | optional todos markdown source folder (defaults to `.pi/todos`); preserves canonical optional `ItemFrontMatter` metadata when present and applies deterministic defaults for missing PM fields | `{ ok, folder, imported, skipped, ids, warnings }` |
+| `pm todos import --folder <path?>` | optional todos markdown source folder (defaults to `.pi/todos`); preserves canonical optional `ItemMetadata` fields when present and applies deterministic defaults for missing PM fields | `{ ok, folder, imported, skipped, ids, warnings }` |
 | `pm todos export --folder <path?>` | optional todos markdown destination folder (defaults to `.pi/todos`) | `{ ok, folder, exported, ids, warnings }` |
 | `pm create ...` | required `--title` + `--description` + `--type`; strict mode is default (`--create-mode strict`) and enforces type-governed required options; progressive mode (`--create-mode progressive`) supports staged omission of type-level required create fields/repeatables; optional `--template` reusable defaults | `{ item, changed_fields, warnings }` |
 | `pm templates save <NAME> ...` | template name + create-compatible option payload (subset of create flags, including repeatable entries) | `{ name, path, template, saved_at }` |
@@ -986,7 +986,7 @@ Contract compatibility policy keeps command names/flags/aliases stable while all
 | `pm start-task <ID>` | lifecycle alias command (`claim` + `update --status in_progress`) with optional `--author`, `--message`, `--force` | `{ id, action: "start_task", claim, update }` |
 | `pm pause-task <ID>` | lifecycle alias command (`update --status open` + `release`) with optional `--author`, `--message`, `--force` | `{ id, action: "pause_task", update, release }` |
 | `pm close-task <ID> <TEXT>` | lifecycle alias command (`close` + `release`) with optional `--author`, `--message`, `--validate-close`, `--force` | `{ id, action: "close_task", close, release }` |
-| `pm comments <ID> [TEXT] --add/--limit` | id + optional positional comment text shorthand + comment text/limit (`--add` accepts plain text, `text=<value>`, markdown `text: <value>`, or stdin token `-`; positional `TEXT` is shorthand for `--add <TEXT>`; ambiguous CSV-like key fragments such as `text=hello,scope:project` remain plain text unless `text` is explicit); optional mutation metadata flags `--author`/`--message`/`--force`; additive ownership-safe audit path `--allow-audit-comment` for non-owner append-only comments | `{ id, comments, count }` |
+| `pm comments <ID> [TEXT] --add/--stdin/--file/--limit` | id + optional positional comment text shorthand + comment text/limit (`--add` accepts plain text, `text=<value>`, markdown `text: <value>`, or stdin token `-`; `--stdin` reads multiline markdown from piped stdin; `--file <path>` reads multiline markdown from a file; positional `TEXT` is shorthand for `--add <TEXT>`; ambiguous CSV-like key fragments such as `text=hello,scope:project` remain plain text unless `text` is explicit); exactly one comment source must be provided per mutation invocation (`[TEXT]`, `--add`, `--stdin`, or `--file`); optional mutation metadata flags `--author`/`--message`/`--force`; additive ownership-safe audit path `--allow-audit-comment` for non-owner append-only comments | `{ id, comments, count }` |
 | `pm comments-audit` | optional governance filters (`--status`, `--type`, `--assignee`, `--assignee-filter`, `--parent`, `--tag`, `--sprint`, `--release`, `--priority`, `--limit-items`) plus latest/full-history export mode controls (`--latest`, `--full-history`; mutually exclusive, `--latest 0` allowed for summary-only rows) | `{ items, count, summary, filters, export, now, warnings? }` where `summary` includes additive totals/coverage/by-type metrics, `filters.full_history` and `export.mode` indicate latest vs full-history behavior, and `export.row_count` is deterministic (`0` in summary-only latest mode); in full-history mode, `rows[]` includes flat per-comment export entries for NDJSON-friendly downstream processing |
 | `pm notes <ID> [TEXT] --add/--limit` | id + optional positional note text shorthand + note text/limit (`--add` accepts plain text, `text=<value>`, markdown `text: <value>`, or stdin token `-`; positional `TEXT` is shorthand for `--add <TEXT>`; ambiguous CSV-like key fragments such as `text=hello,scope:project` remain plain text unless `text` is explicit); optional mutation metadata flags `--author`/`--message`/`--force`; additive ownership-safe audit path `--allow-audit-comment` for non-owner append-only notes | `{ id, notes, count }` |
 | `pm learnings <ID> [TEXT] --add/--limit` | id + optional positional learning text shorthand + learning text/limit (`--add` accepts plain text, `text=<value>`, markdown `text: <value>`, or stdin token `-`; positional `TEXT` is shorthand for `--add <TEXT>`; ambiguous CSV-like key fragments such as `text=hello,scope:project` remain plain text unless `text` is explicit); optional mutation metadata flags `--author`/`--message`/`--force`; additive ownership-safe audit path `--allow-audit-comment` for non-owner append-only learnings | `{ id, learnings, count }` |
@@ -1010,7 +1010,7 @@ Contract compatibility policy keeps command names/flags/aliases stable while all
 
 List command row projection:
 
-- Default `list*` rows contain `ItemFrontMatter` fields only.
+- Default `list*` rows contain `ItemMetadata` fields only.
 - `--compact` projects deterministic compact fields (`id`, `title`, `status`, `type`, `priority`, `parent`, `updated_at`).
 - `--fields <csv>` projects caller-selected list fields.
 - With `--include-body`, each row additionally includes `body` and `filters.include_body` is `true` (`null` when omitted in JSON; omitted in sparse TOON).
@@ -1027,8 +1027,8 @@ Examples:
 
 - `list*`:
   - `{ items, count, filters, now }`
-  - default rows: `ItemFrontMatter`
-  - with `--include-body`: `ItemFrontMatter + body`
+  - default rows: `ItemMetadata`
+  - with `--include-body`: `ItemMetadata + body`
 - `search`:
   - `{ query, mode, items, count, filters, now }`
 - `get`:
@@ -1369,7 +1369,7 @@ Behavior:
   - `title -> title`
   - `body -> body`
   - imported IDs, including hierarchical suffixes such as `pm-legacy.1.2`, are preserved verbatim when provided in todos front matter
-  - canonical PM front-matter fields round-trip when present, including planning/workflow metadata (`definition_of_ready`, `order`, `goal`, `objective`, `value`, `impact`, `outcome`, `why_now`, `reviewer`, `risk`, `confidence`, `sprint`, `release`, `blocked_by`, `blocked_reason`, `unblock_note`) and issue metadata (`reporter`, `severity`, `environment`, `repro_steps`, `resolution`, `expected_result`, `actual_result`, `affected_version`, `fixed_version`, `component`, `regression`, `customer_impact`)
+  - canonical PM metadata fields round-trip when present, including planning/workflow metadata (`definition_of_ready`, `order`, `goal`, `objective`, `value`, `impact`, `outcome`, `why_now`, `reviewer`, `risk`, `confidence`, `sprint`, `release`, `blocked_by`, `blocked_reason`, `unblock_note`) and issue metadata (`reporter`, `severity`, `environment`, `repro_steps`, `resolution`, `expected_result`, `actual_result`, `affected_version`, `fixed_version`, `component`, `regression`, `customer_impact`)
   - `confidence`, `risk`, and `severity` text aliases normalize deterministically (`med -> medium`)
 - Missing PM fields get deterministic defaults:
   - `description = ""`
@@ -1653,7 +1653,7 @@ Definition of Done:
 Checklist:
 
 - [x] Item schema model + validation
-- [x] Parser/serializer for markdown item files
+- [x] Parser/serializer for TOON item files plus legacy markdown migration reader
 - [x] ID generation + normalization
 - [x] Lock acquire/release with TTL and conflict handling
 - [x] Core commands: init/create/get/update/append/claim/release/close/delete complete
@@ -1750,6 +1750,6 @@ Definition of Done:
   - unknown values retained in import metadata notes if lossy mapping is required
 - Hierarchical IDs from imports are preserved verbatim; new IDs generated by core default to flat `prefix-token`.
 - TOON formatting follows deterministic encoding with stable object keys; internal serializer may use a thin compatibility layer to ensure strict consistency across Node versions.
-- For `create`, `before_hash` is computed from canonical empty document: `{ "front_matter": {}, "body": "" }`.
+- For `create`, `before_hash` is computed from the legacy-compatible canonical empty hash document: `{ "front_matter": {}, "body": "" }` (history patch payloads use `metadata` paths).
 - If create item write succeeds but history append fails, implementation MUST rollback the new item file before returning failure.
 - ID normalization helper behavior (`#` prefix, missing configured prefix, case-insensitive input) is required in core utilities even before all commands expose it.

package/README.md

@@ -17,11 +17,22 @@
 | Settings, storage, search, and output | [Configuration](docs/CONFIGURATION.md) |
 | Safe test execution and linked tests | [Testing](docs/TESTING.md) |
 | Extension authoring | [Extensions](docs/EXTENSIONS.md) and [SDK](docs/SDK.md) |
+| Pi native package | [Pi Package](docs/PI_PACKAGE.md) |
+| Codex native integration | [Codex Plugin](docs/CODEX_PLUGIN.md) |
 | Maintainer release process (daily auto-release + local parity) | [Releasing](docs/RELEASING.md) |
 | Contributor internals | [Architecture](docs/ARCHITECTURE.md) |
 
 Full documentation starts at [docs/README.md](docs/README.md).
 
+Use local in-CLI routing when an agent should stay inside terminal context:
+
+```bash
+pm guide
+pm guide quickstart
+pm guide commands --depth standard
+pm guide skills --depth deep --format markdown
+```
+
 ## Install
 
 `pm-cli` requires Node.js 20 or newer.
@@ -40,6 +51,14 @@ Project-local invocation also works:
 npx @unbrained/pm-cli --help
 ```
 
+For Pi, install the native package integration after publish:
+
+```bash
+pi install npm:@unbrained/pm-cli
+```
+
+This registers a native `pm` tool, Pi skills, and prompt templates without requiring Pi to run the `pm` shell command.
+
 ## 60 Second Example
 
 ```bash
@@ -78,6 +97,8 @@ pm list-in-progress --limit 20
 
 If no relevant item exists, create a parent lineage before child work, claim the child item, link changed files/docs/tests, and leave evidence comments before closing. The full workflow is in the [Agent Guide](docs/AGENT_GUIDE.md).
 
+For token-aware local routing, use `pm guide workflows` and then drill into related topics (`commands`, `skills`, `release`) only when needed.
+
 ## Release Automation
 
 - Daily release preparation runs in `.github/workflows/auto-release.yml`.
@@ -94,6 +115,7 @@ If no relevant item exists, create a parent lineage before child work, claim the
 - Built-in types include `Epic`, `Feature`, `Task`, `Chore`, `Issue`, `Decision`, `Event`, `Reminder`, `Milestone`, and `Meeting`.
 - Output defaults to sparse TOON. Use `--json` for strict parsing.
 - `pm contracts` is the machine-readable command and schema contract surface for agents.
+- `pm guide` is the local progressive-disclosure docs and skills index for agents.
 
 ## Tracker References
 
@@ -105,10 +127,6 @@ This documentation refresh is tracked through `pm`:
 
 Docs should link to relevant `pm` items, and `pm` items should link back to changed docs through `pm docs`.
 
-## Privacy Boundary
-
-Private production operations material is local-only, gitignored, and intentionally not linked from public documentation or packaged release files. Keep public docs focused on user-facing CLI behavior and safe contribution workflows.
-
 ## License
 
 [MIT](LICENSE)

package/dist/cli/commands/claim.js

@@ -28,11 +28,11 @@ export async function runClaim(id, force, global, options = {}) {
         message: options.message,
         force,
         mutate(document) {
-            previousAssignee = document.front_matter.assignee ?? null;
-            if (statusIsTerminal(document.front_matter.status, statusRegistry) && !force) {
-                throw new PmCliError(`Cannot claim terminal item ${document.front_matter.id} without --force`, EXIT_CODE.CONFLICT);
+            previousAssignee = document.metadata.assignee ?? null;
+            if (statusIsTerminal(document.metadata.status, statusRegistry) && !force) {
+                throw new PmCliError(`Cannot claim terminal item ${document.metadata.id} without --force`, EXIT_CODE.CONFLICT);
             }
-            document.front_matter.assignee = author;
+            document.metadata.assignee = author;
             return { changedFields: ["assignee"] };
         },
     });
@@ -63,11 +63,11 @@ export async function runRelease(id, force, global, options = {}) {
             force,
             bypassAssigneeConflict: Boolean(options.allowAuditRelease),
             mutate(document) {
-                previousAssignee = document.front_matter.assignee ?? null;
+                previousAssignee = document.metadata.assignee ?? null;
                 if (!previousAssignee) {
                     return { changedFields: [] };
                 }
-                delete document.front_matter.assignee;
+                delete document.metadata.assignee;
                 return { changedFields: ["assignee"] };
             },
         });