@unbrained/pm-cli 2026.5.10 → 2026.5.12

package/.agents/skills/pm-extensions/references/LIFECYCLE.md

@@ -1,40 +0,0 @@
-# Extension Lifecycle Recipes
-
-## Inspect Current State
-
-```bash
-pm extension explore --project
-pm extension manage --detail summary
-pm extension doctor --detail deep
-```
-
-## Install and Activate
-
-```bash
-pm extension install <target> --project
-pm extension activate <target> --project
-pm extension doctor --detail summary
-```
-
-## Adopt Existing Extensions
-
-```bash
-pm extension adopt <name> --project
-pm extension adopt-all --project
-pm extension manage --detail summary
-```
-
-## Deactivate / Uninstall
-
-```bash
-pm extension deactivate <target> --project
-pm extension uninstall <target> --project
-pm extension doctor --detail deep
-```
-
-## Contract Checks
-
-```bash
-pm contracts --runtime-only --availability-only
-pm contracts --command extension --flags-only
-```

package/.agents/skills/pm-extensions/references/TROUBLESHOOTING.md

@@ -1,25 +0,0 @@
-# Extension Troubleshooting
-
-## Common Diagnostic Sequence
-
-1. `pm extension explore --project`
-2. `pm extension manage --detail summary`
-3. `pm extension doctor --detail deep --trace`
-4. `pm contracts --runtime-only --availability-only`
-
-## Symptoms and Checks
-
-- **Command not visible**
-  - Confirm extension is managed and active.
-  - Confirm capability includes `commands`.
-  - Check `pm contracts` action availability.
-
-- **Schema mismatch**
-  - Confirm capability includes `schema`.
-  - Re-run doctor with `--detail deep --trace`.
-  - Validate runtime-only contracts output.
-
-- **Unexpected behavior after updates**
-  - Check registration precedence with manage/doctor.
-  - Run with `--no-extensions` to isolate core behavior.
-  - Re-activate extension after fixing manifest or entry path.

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

@@ -1,50 +0,0 @@
----
-name: pm-sdk
-description: Implements pm-cli integrations using @unbrained/pm-cli/sdk and runtime contracts. Use when authoring extensions, wrappers, or automation that must stay aligned with command/action schema changes.
-license: MIT
-compatibility: Requires Node.js and access to pm contracts output for runtime parity checks.
-metadata:
-  owner: unbrained
-  domain: pm-cli
-  scope: sdk-integration
----
-
-# pm SDK Skill
-
-Use this skill when integrating against `@unbrained/pm-cli/sdk` or validating external wrappers.
-
-## Quick Start
-
-```bash
-pm guide sdk
-pm contracts --schema-only
-pm contracts --runtime-only --availability-only
-pm contracts --command <command> --flags-only
-```
-
-## Integration Workflow
-
-1. Capture current runtime schema and command contracts.
-2. Map integration payload fields to contract keys.
-3. Implement with SDK exports (no internal `src/core/...` imports).
-4. Validate command/action availability in runtime-only mode.
-5. Add regression tests for schema-bound behavior.
-
-## Workflow Prompts
-
-### Prompt: Build New Integration
-
-`Implement <integration> using @unbrained/pm-cli/sdk and pm contracts output as the source of truth. Add tests that fail when required command/action fields drift.`
-
-### Prompt: Contract Drift Investigation
-
-`Compare integration assumptions with current pm contracts output, identify drift, and patch mapping logic and tests to restore parity.`
-
-### Prompt: Extension Authoring
-
-`Author extension registration using defineExtension and declared capabilities only, then verify activation and command availability with pm contracts.`
-
-## Progressive Disclosure References
-
-- [Integration checklist](references/INTEGRATION_CHECKLIST.md)
-- [SDK prompt templates](references/PROMPTS.md)

package/.agents/skills/pm-sdk/references/INTEGRATION_CHECKLIST.md

@@ -1,31 +0,0 @@
-# SDK Integration Checklist
-
-## Contract Capture
-
-```bash
-pm contracts --schema-only --json
-pm contracts --runtime-only --availability-only --json
-pm contracts --command <command> --flags-only --json
-```
-
-## Implementation Rules
-
-- Use `@unbrained/pm-cli/sdk` exports only.
-- Do not import internal runtime modules from `src/core/...`.
-- Keep action/flag mappings derived from `pm contracts` outputs.
-- Handle extension-unavailable states through availability metadata.
-
-## Validation
-
-```bash
-pnpm build
-node scripts/run-tests.mjs test -- <targeted sdk/integration tests>
-node scripts/run-tests.mjs coverage
-```
-
-## Release Readiness
-
-```bash
-node scripts/release/docs-skills-gate.mjs
-node scripts/release/run-gates.mjs --telemetry-mode best-effort
-```

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

@@ -1,13 +0,0 @@
-# SDK Prompt Templates
-
-## Runtime Contract Mapping
-
-`Map this integration request to pm contracts output first, then generate implementation steps keyed to command flags and action schema fields.`
-
-## Extension Capability Design
-
-`Design extension capabilities for <feature> using defineExtension. Include only needed capabilities and provide a verification command list for activation and contracts checks.`
-
-## Wrapper Parity Check
-
-`Audit wrapper action/command mapping parity against current pm contracts output and report any missing or stale fields with patch recommendations.`

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

@@ -1,59 +0,0 @@
----
-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

@@ -1,17 +0,0 @@
-# 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

@@ -1,35 +0,0 @@
-# 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/.pi/README.md

@@ -1,26 +0,0 @@
-# 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

@@ -1,147 +0,0 @@
-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

@@ -1,5 +0,0 @@
----
-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

@@ -1,40 +0,0 @@
----
-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

@@ -1,35 +0,0 @@
----
-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/dist/pi/native.d.ts

@@ -1,5 +0,0 @@
-import type { GlobalOptions } from "../core/shared/command-types.js";
-export type NativePmArgs = Record<string, unknown>;
-export declare function nativeGlobalOptions(args: NativePmArgs): GlobalOptions;
-export declare function nativeCommandOptions(args: NativePmArgs): Record<string, unknown>;
-export declare function runNativePmAction(args: NativePmArgs): Promise<unknown>;