@unbrained/pm-cli 2026.5.11 → 2026.5.14

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

@@ -1,73 +0,0 @@
----
-name: pm-developer
-description: Runs the pm-cli developer execution loop (orient, claim, implement, verify, close) with linked files/tests/docs evidence. Use when coding, debugging, refactoring, or shipping repository changes tracked in pm items.
-license: MIT
-compatibility: Works in terminal-based coding agents with bash, Node.js, and pnpm.
-metadata:
-  owner: unbrained
-  domain: pm-cli
-  scope: developer-workflow
----
-
-# pm Developer Skill
-
-Use this skill for implementation work that changes code, docs, tests, or release gates.
-
-## Quick Start
-
-```bash
-pm context --limit 10
-pm search "<task keywords>" --limit 10
-pm list-open --limit 20
-pm claim <ID>
-pm update <ID> --status in_progress
-pm guide workflows
-```
-
-## Canonical Workflow
-
-1. **Orient**: pick an existing item when possible.
-2. **Claim**: claim before substantial edits.
-3. **Link context**: attach changed files/tests/docs while implementing.
-4. **Verify**: run linked tests plus local quality gates.
-5. **Close with evidence**: append what changed and what passed.
-6. **Release claim**: release when paused, handed off, or closed.
-
-## Workflow Prompts
-
-Use one prompt template, then execute only the minimum required commands.
-
-### Prompt: Implement Scoped Change
-
-`Implement the requested change on <ID>. Keep edits scoped, link files/tests/docs, run targeted verification, and record closure evidence before releasing claim.`
-
-### Prompt: Debug Regression
-
-`Investigate failing behavior for <ID>. Reproduce first, add or update regression tests, patch root cause, and append evidence with exact command outputs.`
-
-### Prompt: Documentation + Code Sync
-
-`Update implementation and docs together for <ID>. Ensure docs route through pm guide topics and verify command examples still match pm contracts output.`
-
-## Required Evidence Commands
-
-```bash
-pm files <ID> --add path=<path>,scope=project,note="<reason>"
-pm test <ID> --add command="node scripts/run-tests.mjs test -- <target>",scope=project,timeout_seconds=240
-pm docs <ID> --add path=<doc>,scope=project,note="<reason>"
-pm comments <ID> "Evidence: <what changed + tests run>"
-```
-
-## Verification Defaults
-
-```bash
-pnpm build
-node scripts/run-tests.mjs test -- <targets>
-node scripts/run-tests.mjs coverage
-pm validate --check-resolution --check-history-drift
-```
-
-## Progressive Disclosure References
-
-- [Developer command playbook](references/COMMAND_PLAYBOOK.md)
-- [Prompt templates and examples](references/PROMPTS.md)

package/.agents/skills/pm-developer/references/COMMAND_PLAYBOOK.md

@@ -1,48 +0,0 @@
-# Developer Command Playbook
-
-## Session Bootstrap (Maintainer Run)
-
-```bash
-npm install -g .
-pm --version
-node -v
-pnpm -v
-pnpm build
-```
-
-## Item Lifecycle
-
-```bash
-pm context --limit 10
-pm search "<keywords>" --limit 10
-pm list-open --limit 20
-pm claim <ID>
-pm update <ID> --status in_progress --description "..."
-pm append <ID> --body "Implementation notes"
-```
-
-## Evidence Linking
-
-```bash
-pm files <ID> --add path=src/<file>.ts,scope=project,note="implementation"
-pm docs <ID> --add path=docs/<doc>.md,scope=project,note="public docs update"
-pm test <ID> --add command="node scripts/run-tests.mjs test -- tests/unit/<file>.spec.ts",scope=project,timeout_seconds=240
-```
-
-## Close Workflow
-
-```bash
-pm test <ID> --run --progress
-node scripts/run-tests.mjs coverage
-pm comments <ID> "Evidence: linked tests passed; coverage remained green."
-pm close <ID> "Acceptance criteria met with verification evidence." --validate-close warn
-pm release <ID>
-```
-
-## Local Docs Routing
-
-```bash
-pm guide workflows
-pm guide commands --depth standard
-pm guide release --json
-```

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

@@ -1,17 +0,0 @@
-# Prompt Templates
-
-## Implement Feature
-
-`Implement <feature> on <ID>. Reuse existing architecture, link all changed files/tests/docs, run targeted + coverage checks, and append evidence before close.`
-
-## Fix Bug
-
-`Fix <bug> on <ID>. Add a regression test, keep the patch minimal, run focused tests first, then full gate commands if scope expands.`
-
-## Refactor
-
-`Refactor <area> on <ID> without behavior changes. Preserve API contracts, update docs where command behavior is clarified, and validate with existing regression suite.`
-
-## Release Readiness Sweep
-
-`Perform release readiness checks for <ID>. Run build, coverage, static quality, secret scan, and release gates. Document all results in a closure comment.`

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

@@ -1,57 +0,0 @@
----
-name: pm-extensions
-description: Manages pm-cli extension lifecycle operations (explore, install, activate, diagnose, and release-safe validation). Use when building, integrating, or troubleshooting pm extensions and extension-provided commands.
-license: MIT
-compatibility: Requires pm extension commands and local project/global extension directories.
-metadata:
-  owner: unbrained
-  domain: pm-cli
-  scope: extension-workflow
----
-
-# pm Extensions Skill
-
-Use this skill when the request touches extension install, activation, command registration, diagnostics, or extension governance.
-
-## Quick Start
-
-```bash
-pm guide extensions
-pm extension explore --project
-pm extension manage --detail summary
-pm extension doctor --detail deep
-```
-
-## Lifecycle Workflow
-
-1. **Inspect state first** (`explore`, `manage`, `doctor`).
-2. **Apply lifecycle mutation** (`install`, `adopt`, `activate`, `deactivate`, `uninstall`).
-3. **Verify command/action exposure** with `pm contracts`.
-4. **Record evidence** in linked `pm` items.
-
-## Workflow Prompts
-
-### Prompt: Diagnose Extension Failure
-
-`Diagnose extension activation issues using pm extension explore/manage/doctor before making lifecycle changes. Report root cause and minimal remediation commands.`
-
-### Prompt: Install and Validate Extension
-
-`Install <extension> in project scope, validate with doctor diagnostics, and confirm command/action availability using pm contracts runtime output.`
-
-### Prompt: Safe Deactivation
-
-`Deactivate or uninstall <extension> with rollback-safe sequencing and explicit evidence of which commands/actions are removed.`
-
-## Contract Verification
-
-```bash
-pm contracts --command extension --flags-only
-pm contracts --runtime-only --availability-only
-pm contracts --command <extension-command> --flags-only
-```
-
-## Progressive Disclosure References
-
-- [Extension lifecycle recipes](references/LIFECYCLE.md)
-- [Troubleshooting playbook](references/TROUBLESHOOTING.md)

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,35 +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, custom TUI renderers, autocomplete, status/widget UI, and slash commands.
-- `.pi/skills/*` — Pi skills for native pm workflows and release validation.
-- `.pi/prompts/*` — prompt templates for pm-tracked work.
-- `.pi/agents/*` and `.pi/chains/*` — optional pi-subagents setup for pm triage and verification workflows in repositories that use subagents.
-
-The extension imports the built package from `dist/`, so run `pnpm build` before local install or before publishing.
-
-Interactive commands:
-
-- `/pm-board [limit]` — dashboard panel for active pm context.
-- `/pm-item <id>` and `/pm-history <id>` — item details/history panels.
-- `/pm-actions` and `/pm-workflows` — native action list and workflow reminders.
-
-The `pm` tool should be preferred over shelling out to `pm`; it calls pm command modules directly in-process.

package/.pi/agents/pm-triage-agent.md

@@ -1,19 +0,0 @@
----
-name: pm-triage-agent
-description: Native pm triage agent for Pi. Use to inspect context, search for duplicates, select or create tracker lineage, and hand off an implementation-ready pm item without shelling out to the pm CLI.
-tools: pm,read,grep,find,ls
-skills: pm-native,pm-user
----
-
-# pm Triage Agent
-
-Use the native `pm` tool only for pm operations.
-
-Workflow:
-1. Run `pm` action `context` with `limit: 10`.
-2. Run `pm` action `search` with the user's key terms.
-3. Run `pm` actions `list-open` and `list-in-progress`.
-4. If an item exists, recommend reusing it and claim/start only when asked.
-5. If no item exists, identify parent lineage and propose a create payload with duplicate-check evidence.
-
-Output a concise handoff with item id, rationale, recommended next action, and exact native `pm` tool calls.

package/.pi/agents/pm-verification-agent.md

@@ -1,21 +0,0 @@
----
-name: pm-verification-agent
-description: Native pm verification agent for Pi. Use to inspect linked files/tests/docs, run sandbox-safe linked tests through pm, validate close readiness, and produce closure evidence.
-tools: pm,bash,read,grep,find,ls
-skills: pm-native,pm-release
----
-
-# pm Verification Agent
-
-Use the native `pm` tool for pm mutations and linked-test orchestration.
-Use bash only for non-pm project commands such as `pnpm build` or `gh run list`.
-
-Workflow:
-1. Read the target item with `pm` action `get`.
-2. Check linked files/docs/tests and acceptance criteria.
-3. Run `pm` action `test` with `run: true` or equivalent linked-test options when available.
-4. Run targeted project validation requested by the parent.
-5. Add a `pm` comment summarizing evidence.
-6. Recommend close/release only if verification is clean.
-
-Output failures with exact commands, item id, and next remediation step.

package/.pi/chains/pm-native-delivery.chain.md

@@ -1,11 +0,0 @@
----
-name: pm-native-delivery
-description: Triage, implement, and verify a pm-tracked change using native pm operations in Pi.
-steps:
-  - agent: pm-triage-agent
-    task: "Triage the requested work and identify the canonical pm item for: {task}"
-  - agent: worker
-    task: "Implement the approved scope from the triage handoff. Use native pm for tracker operations, link changed files/tests/docs, and keep edits scoped. Original request: {task}\n\nTriage handoff:\n{previous}"
-  - agent: pm-verification-agent
-    task: "Verify the implementation and produce pm closure evidence. Original request: {task}\n\nImplementation handoff:\n{previous}"
----