@unbrained/pm-cli 2026.5.6 → 2026.5.10

package/.agents/pm/extensions/.managed-extensions.json

@@ -17,7 +17,7 @@
       "source": {
         "kind": "local",
         "input": "builtin-beads-import",
-        "location": "/home/steve/GITHUB_RELEASE/pm-cli/.agents/pm/extensions/beads"
+        "location": ".agents/pm/extensions/beads"
       }
     },
     {
@@ -35,7 +35,7 @@
       "source": {
         "kind": "local",
         "input": "builtin-todos-import-export",
-        "location": "/home/steve/GITHUB_RELEASE/pm-cli/.agents/pm/extensions/todos"
+        "location": ".agents/pm/extensions/todos"
       }
     }
   ]

package/.agents/pm/extensions/beads/runtime.js

@@ -361,7 +361,7 @@ function ensureInitHasRun(pmRoot) {
 }
 function emptyDocument() {
     return {
-        front_matter: {},
+        metadata: {},
         body: "",
     };
 }
@@ -520,7 +520,7 @@ export async function runBeadsImport(options, global) {
             finalBody += (finalBody ? "\n\n" : "") + "## External Reference\n" + externalRef;
         }
         const afterDocument = canonicalDocument({
-            front_matter: frontMatter,
+            metadata: frontMatter,
             body: finalBody,
         });
         const existing = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
@@ -529,12 +529,12 @@ export async function runBeadsImport(options, global) {
             skipped += 1;
             continue;
         }
-        const itemPath = getItemPath(pmRoot, type, id, settings.item_format, typeRegistry.type_to_folder);
+        const itemPath = getItemPath(pmRoot, type, id, "toon", typeRegistry.type_to_folder);
         const historyPath = getHistoryPath(pmRoot, id);
         try {
             const releaseLock = await acquireLock(pmRoot, id, settings.locks.ttl_seconds, author);
             try {
-                await writeFileAtomic(itemPath, serializeItemDocument(afterDocument, { format: settings.item_format }));
+                await writeFileAtomic(itemPath, serializeItemDocument(afterDocument, { format: "toon" }));
                 try {
                     const entry = createHistoryEntry({
                         nowIso: nowIso(),

package/.agents/pm/extensions/beads/runtime.ts

@@ -16,7 +16,7 @@ import { isTimestampLiteral, nowIso } from "../../../../src/core/shared/time.js"
 import { locateItem } from "../../../../src/core/store/item-store.js";
 import { getHistoryPath, getItemPath, getSettingsPath, resolvePmRoot } from "../../../../src/core/store/paths.js";
 import { readSettings } from "../../../../src/core/store/settings.js";
-import type { Dependency, ItemDocument, ItemFrontMatter, ItemStatus, ItemType, LogNote, LinkedFile, LinkedTest, LinkedDoc } from "../../../../src/types/index.js";
+import type { Dependency, ItemDocument, ItemMetadata, ItemStatus, ItemType, LogNote, LinkedFile, LinkedTest, LinkedDoc } from "../../../../src/types/index.js";
 import { DEPENDENCY_KIND_VALUES } from "../../../../src/types/index.js";
 
 const PRIMARY_AUTO_DISCOVERY_FILES = [
@@ -445,7 +445,7 @@ function ensureInitHasRun(pmRoot: string): Promise<void> {
 
 function emptyDocument(): ItemDocument {
   return {
-    front_matter: {} as ItemFrontMatter,
+    metadata: {} as ItemMetadata,
     body: "",
   };
 }
@@ -633,7 +633,7 @@ export async function runBeadsImport(options: BeadsImportOptions, global: Global
       finalBody += (finalBody ? "\n\n" : "") + "## External Reference\n" + externalRef;
     }
     const afterDocument = canonicalDocument({
-      front_matter: frontMatter,
+      metadata: frontMatter,
       body: finalBody,
     });
     const existing = await locateItem(pmRoot, id, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
@@ -642,13 +642,13 @@ export async function runBeadsImport(options: BeadsImportOptions, global: Global
       skipped += 1;
       continue;
     }
-    const itemPath = getItemPath(pmRoot, type, id, settings.item_format, typeRegistry.type_to_folder);
+    const itemPath = getItemPath(pmRoot, type, id, "toon", typeRegistry.type_to_folder);
 
     const historyPath = getHistoryPath(pmRoot, id);
     try {
       const releaseLock = await acquireLock(pmRoot, id, settings.locks.ttl_seconds, author);
       try {
-        await writeFileAtomic(itemPath, serializeItemDocument(afterDocument, { format: settings.item_format }));
+        await writeFileAtomic(itemPath, serializeItemDocument(afterDocument, { format: "toon" }));
         try {
           const entry = createHistoryEntry({
             nowIso: nowIso(),

package/.agents/pm/extensions/todos/runtime.js

@@ -187,7 +187,7 @@ function normalizeBody(body) {
 }
 function emptyDocument() {
     return {
-        front_matter: {},
+        metadata: {},
         body: "",
     };
 }
@@ -254,9 +254,9 @@ async function importTodoCandidate(candidate, runtime) {
     if (located) {
         return { warning: `todos_import_item_exists:${id}` };
     }
-    const itemPath = getItemPath(runtime.pmRoot, type, id, runtime.settings.item_format, runtime.typeToFolder);
+    const itemPath = getItemPath(runtime.pmRoot, type, id, "toon", runtime.typeToFolder);
     const afterDocument = canonicalDocument({
-        front_matter: normalizeFrontMatter({
+        metadata: normalizeFrontMatter({
             id,
             title,
             description: toNonEmptyString(candidate.frontMatter.description) ?? "",
@@ -316,7 +316,7 @@ async function importTodoCandidate(candidate, runtime) {
     try {
         const releaseLock = await acquireLock(runtime.pmRoot, id, runtime.settings.locks.ttl_seconds, runtime.author);
         try {
-            await writeFileAtomic(itemPath, serializeItemDocument(afterDocument, { format: runtime.settings.item_format }));
+            await writeFileAtomic(itemPath, serializeItemDocument(afterDocument, { format: "toon" }));
             try {
                 const historyEntry = createHistoryEntry({
                     nowIso: nowIso(),
@@ -442,18 +442,18 @@ export async function runTodosExport(options, global) {
         }
         try {
             const { document } = await readLocatedItem(located);
-            const todoFrontMatter = { ...document.front_matter };
+            const todoFrontMatter = { ...document.metadata };
             const frontMatter = JSON.stringify(todoFrontMatter, null, 2);
             const body = normalizeBody(document.body);
             const serialized = body.length > 0 ? `${frontMatter}\n\n${body}\n` : `${frontMatter}\n`;
-            const exportPath = path.join(destinationFolder, `${document.front_matter.id}.md`);
+            const exportPath = path.join(destinationFolder, `${document.metadata.id}.md`);
             await writeFileAtomic(exportPath, serialized);
             warnings.push(...(await runActiveOnWriteHooks({
                 path: exportPath,
                 scope: "project",
                 op: "todos:export",
             })));
-            ids.push(document.front_matter.id);
+            ids.push(document.metadata.id);
             exported += 1;
         }
         catch {

package/.agents/pm/extensions/todos/runtime.ts

@@ -18,7 +18,7 @@ import { listAllFrontMatter, locateItem, readLocatedItem } from "../../../../src
 import { getHistoryPath, getItemPath, getSettingsPath, resolvePmRoot } from "../../../../src/core/store/paths.js";
 import { readSettings } from "../../../../src/core/store/settings.js";
 import { CONFIDENCE_TEXT_VALUES, ISSUE_SEVERITY_VALUES, RISK_VALUES } from "../../../../src/types/index.js";
-import type { ItemDocument, ItemFrontMatter, ItemStatus, ItemType, PmSettings } from "../../../../src/types/index.js";
+import type { ItemDocument, ItemMetadata, ItemStatus, ItemType, PmSettings } from "../../../../src/types/index.js";
 
 const DEFAULT_TODOS_FOLDER = ".pi/todos";
 
@@ -133,7 +133,7 @@ function toPriority(value: unknown): PriorityValue {
   return 2;
 }
 
-function toConfidence(value: unknown): ItemFrontMatter["confidence"] | undefined {
+function toConfidence(value: unknown): ItemMetadata["confidence"] | undefined {
   if (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 100) {
     return value;
   }
@@ -258,7 +258,7 @@ function normalizeBody(body: string): string {
 
 function emptyDocument(): ItemDocument {
   return {
-    front_matter: {} as ItemFrontMatter,
+    metadata: {} as ItemMetadata,
     body: "",
   };
 }
@@ -336,10 +336,10 @@ async function importTodoCandidate(candidate: ParsedTodoCandidate, runtime: Todo
   if (located) {
     return { warning: `todos_import_item_exists:${id}` };
   }
-  const itemPath = getItemPath(runtime.pmRoot, type, id, runtime.settings.item_format, runtime.typeToFolder);
+  const itemPath = getItemPath(runtime.pmRoot, type, id, "toon", runtime.typeToFolder);
 
   const afterDocument = canonicalDocument({
-    front_matter: normalizeFrontMatter({
+    metadata: normalizeFrontMatter({
       id,
       title,
       description: toNonEmptyString(candidate.frontMatter.description) ?? "",
@@ -391,7 +391,7 @@ async function importTodoCandidate(candidate: ParsedTodoCandidate, runtime: Todo
       files: Array.isArray(candidate.frontMatter.files) ? (candidate.frontMatter.files as any[]) : undefined,
       docs: Array.isArray(candidate.frontMatter.docs) ? (candidate.frontMatter.docs as any[]) : undefined,
       tests: Array.isArray(candidate.frontMatter.tests) ? (candidate.frontMatter.tests as any[]) : undefined,
-    } as ItemFrontMatter),
+    } as ItemMetadata),
     body: candidate.body,
   });
 
@@ -400,7 +400,7 @@ async function importTodoCandidate(candidate: ParsedTodoCandidate, runtime: Todo
   try {
     const releaseLock = await acquireLock(runtime.pmRoot, id, runtime.settings.locks.ttl_seconds, runtime.author);
     try {
-      await writeFileAtomic(itemPath, serializeItemDocument(afterDocument, { format: runtime.settings.item_format }));
+      await writeFileAtomic(itemPath, serializeItemDocument(afterDocument, { format: "toon" }));
       try {
         const historyEntry = createHistoryEntry({
           nowIso: nowIso(),
@@ -538,11 +538,11 @@ export async function runTodosExport(options: TodosExportOptions, global: Global
 
     try {
       const { document } = await readLocatedItem(located);
-      const todoFrontMatter: Record<string, unknown> = { ...document.front_matter };
+      const todoFrontMatter: Record<string, unknown> = { ...document.metadata };
       const frontMatter = JSON.stringify(todoFrontMatter, null, 2);
       const body = normalizeBody(document.body);
       const serialized = body.length > 0 ? `${frontMatter}\n\n${body}\n` : `${frontMatter}\n`;
-      const exportPath = path.join(destinationFolder, `${document.front_matter.id}.md`);
+      const exportPath = path.join(destinationFolder, `${document.metadata.id}.md`);
       await writeFileAtomic(exportPath, serialized);
       warnings.push(
         ...(await runActiveOnWriteHooks({
@@ -551,7 +551,7 @@ export async function runTodosExport(options: TodosExportOptions, global: Global
           op: "todos:export",
         })),
       );
-      ids.push(document.front_matter.id);
+      ids.push(document.metadata.id);
       exported += 1;
     } catch {
       warnings.push(`todos_export_read_failed:${item.id}`);

package/.agents/skills/HARNESS_COMPATIBILITY.md

@@ -0,0 +1,45 @@
+# Harness Compatibility
+
+This repository supports the following harnesses through shared docs and `.agents/skills` workflows only (no harness-specific runtime code):
+
+- Pi coding agent
+- OpenClaw
+- Claude Code
+- Codex CLI
+- OpenCode
+- Amp
+- Droid
+- Hermes
+- Gemini CLI
+
+## Progressive-Disclosure Route
+
+Use the same low-token route in every harness:
+
+1. `pm guide` (topic index)
+2. `pm guide <topic>` (focused route)
+3. `pm guide <topic> --depth standard|deep` (details only when needed)
+4. `pm contracts --command <command> --flags-only --json` (strict machine flags)
+
+## Harness Mapping
+
+| Harness | Preferred prompt/doc entrypoint | Skill route |
+|---------|----------------------------------|-------------|
+| Pi coding agent | `AGENTS.md` + `pm guide workflows` | `.agents/skills/pm-developer/SKILL.md` |
+| OpenClaw | repository docs + `pm guide` | `.agents/skills/pm-user/SKILL.md` |
+| Claude Code | repository docs + `pm guide skills` | `.agents/skills/pm-developer/SKILL.md` |
+| Codex CLI | repository docs + `pm guide commands` | `.agents/skills/pm-developer/SKILL.md` |
+| OpenCode | repository docs + `pm guide quickstart` | `.agents/skills/pm-user/SKILL.md` |
+| Amp | repository docs + `pm guide workflows` | `.agents/skills/pm-user/SKILL.md` |
+| Droid | repository docs + `pm guide extensions` | `.agents/skills/pm-extensions/SKILL.md` |
+| Hermes | repository docs + `pm guide sdk` | `.agents/skills/pm-sdk/SKILL.md` |
+| Gemini CLI | repository docs + `pm guide commands` | `.agents/skills/pm-user/SKILL.md` |
+
+## Verification
+
+Before release, run:
+
+```bash
+pm guide skills --depth standard
+node scripts/release/docs-skills-gate.mjs
+```

package/.agents/skills/README.md

@@ -0,0 +1,21 @@
+# pm Agent Skills
+
+This directory contains `agentskills.io`-style skills for `pm` workflows.
+
+Start with:
+
+```bash
+pm guide skills
+pm guide harnesses --depth standard
+```
+
+Skill bundles:
+
+- `pm-developer` - implementation loop for coding agents.
+- `pm-user` - operator workflow for planning and task routing.
+- `pm-extensions` - extension lifecycle, diagnostics, and release-safe updates.
+- `pm-sdk` - SDK and integration workflows.
+
+Compatibility routing:
+
+- [Harness compatibility matrix](HARNESS_COMPATIBILITY.md)

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,13 @@
+# 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.`