@unbrained/pm-cli 2026.8.25 → 2026.8.27

package/.agents/skills/HARNESS_COMPATIBILITY.md

@@ -0,0 +1,32 @@
+# Harness Compatibility
+
+This repository supports external automation harnesses through shared docs and `.agents/skills` workflows only. Harness-specific runtime code belongs in separate adapter packages, not in the main `pm` CLI or SDK.
+
+## Progressive-Disclosure Route
+
+Use the same low-token route in every harness:
+
+1. `pm install guide-shell --project` (enable optional local guide commands)
+2. `pm guide` (topic index)
+3. `pm guide <topic>` (focused route)
+4. `pm guide <topic> --depth standard|deep` (details only when needed)
+5. `pm contracts --command <command> --flags-only --json` (strict machine flags)
+
+## Harness Mapping
+
+| Harness need | Preferred prompt/doc entrypoint | Skill route |
+|--------------|----------------------------------|-------------|
+| Development loop | `AGENTS.md` + optional `pm guide workflows` | `.agents/skills/pm-developer/SKILL.md` |
+| User/operator workflow | repository docs + optional `pm guide quickstart` | `.agents/skills/pm-user/SKILL.md` |
+| Package authoring | repository docs + optional `pm guide extensions` | `.agents/skills/pm-extensions/SKILL.md` |
+| SDK integration | repository docs + optional `pm guide sdk` | `.agents/skills/pm-sdk/SKILL.md` |
+
+## Verification
+
+Before release, run:
+
+```bash
+pm install guide-shell --project
+pm guide skills --depth standard
+node scripts/release/docs-skills-gate.mjs
+```

package/.agents/skills/README.md

@@ -0,0 +1,47 @@
+# pm Agent Skills
+
+`agentskills.io`-style skill bundles for `pm` workflows, written for
+progressive disclosure: each `SKILL.md` is a router of roughly one screen, each
+`references/*.md` is a bounded expansion, and the exhaustive surface is fetched
+at runtime from contracts rather than copied into prose that can drift.
+
+## Load Order
+
+| Tier | Source                                 | Typical cost | Staleness risk |
+| ---- | -------------------------------------- | ------------ | -------------- |
+| 0    | `SKILL.md`                             | ~650 tok     | Gated          |
+| 1    | `pm next`, `pm context`, `pm search`   | ~0.5-2.5k    | None (live)    |
+| 2    | `pm contracts ...`, `pm <cmd> --help --json` | ~1-3.4k | None (generated) |
+| 2    | `pm guide <topic> --depth brief`       | ~0.6-1k      | Gated          |
+| 3    | `references/*.md`                      | ~0.3-1k each | Gated          |
+| 4    | `docs/*.md`                            | 0.7k-45k     | Gated          |
+
+Never load a tier-4 document whole when a reference routes into a section of
+it. `docs/COMMANDS.md` is ~29k tokens and `docs/SDK.md` is ~45k.
+
+## Bundles
+
+| Skill                             | Use when                                              |
+| --------------------------------- | ------------------------------------------------------ |
+| [`pm-developer`](pm-developer/SKILL.md) | Changing code, docs, tests, or release gates      |
+| [`pm-user`](pm-user/SKILL.md)     | Intake, triage, prioritization, planning, reporting    |
+| [`pm-extensions`](pm-extensions/SKILL.md) | Package and extension lifecycle and authoring  |
+| [`pm-sdk`](pm-sdk/SKILL.md)       | Integrations, embedding, and domain packs on the SDK   |
+
+Harness-specific bundles ship with the plugins under `plugins/pm-claude/skills`
+and `plugins/pm-codex/skills`; they route to the same guide topics and
+contracts.
+
+## Runtime Routing
+
+```bash
+pm install guide-shell --project
+pm guide                       # topic index
+pm guide skills
+pm guide harnesses --depth standard
+```
+
+Guide topics: `quickstart`, `commands`, `workflows`, `sdk`, `extensions`,
+`skills`, `harnesses`, `release`, `tokens`, `graph`, `assurance`, `merge`.
+
+Compatibility routing: [Harness compatibility matrix](HARNESS_COMPATIBILITY.md)

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

@@ -0,0 +1,117 @@
+---
+name: pm-developer
+description: Runs the pm-cli developer execution loop (orient, claim, implement, verify, close) with linked files/tests/docs evidence, under an explicit token budget. 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
+
+Implementation work that changes code, docs, tests, or release gates. `pm` is the
+system of record: every change is linked to an item, and every mutation is
+recorded in an append-only history stream.
+
+## Load Order
+
+Load only the tier the task needs. Costs are measured, not estimated.
+
+| Tier | Load                                          | Cost      | When                                     |
+| ---- | --------------------------------------------- | --------- | ---------------------------------------- |
+| 0    | This file                                     | ~650 tok  | Always.                                  |
+| 1    | `pm next` or `pm context --limit 10`          | ~2.1-2.5k | Pick or resume work.                     |
+| 2    | `pm contracts --command <cmd> --flags-only`   | ~1-3.4k   | Exact flags for one command.             |
+| 2    | `pm guide <topic> --depth brief`              | ~0.6-1k   | A capability family you have not used.   |
+| 3    | `references/*.md` below                       | ~0.3-1k   | Repeatable procedure detail.             |
+| 4    | `docs/*.md`                                   | 0.7k-45k  | Only when a reference routes you there.  |
+
+Never load `docs/COMMANDS.md` (~29k) or `docs/SDK.md` (~45k) whole. Both are
+routed into by section from the references below.
+
+Optional deep routing that never goes stale:
+
+```bash
+pm install guide-shell --project
+pm guide workflows --depth brief
+```
+
+## Non-Negotiables
+
+- Author identity is detected automatically. **Never pass `--author` and never
+  set `PM_AUTHOR`.** The harness, model, effort, role, and topic are probed and
+  recorded on every history entry.
+- Never edit files under `.agents/pm` directly. Every mutation goes through `pm`.
+- Never claim an item's state from memory. Read it live before asserting it.
+- Claim before substantial edits; release when paused, handed off, or closed.
+- Search before creating. Record the duplicate check as a create-time comment.
+
+## Canonical Loop
+
+```bash
+pm next                                   # or: pm context --limit 10
+pm search "<task keywords>" --limit 10
+pm claim <ID>
+pm update <ID> --status in_progress --message "Start implementation"
+# ...implement...
+pm files <ID> --add path=<path>,scope=project,note="<why>"
+pm docs  <ID> --add path=<doc>,scope=project,note="<why>"
+pm test  <ID> --add command="node scripts/run-tests.mjs test -- <target>",scope=project,timeout_seconds=240
+pm comments <ID> "Evidence: <what changed and what passed>"
+pm test <ID> --run --progress
+pm close <ID> "<reason with evidence>" --validate-close warn
+pm release <ID>
+```
+
+## Capability Map
+
+Capability families and their commands are generated from the public SDK
+contract. Start with `pm guide capabilities`, expand only the family the task
+enters, and use these drift-gated references:
+
+- [Capability routing](../../../docs/generated/AGENT_CAPABILITY_ROUTING.md)
+- [Visibility tiers and families](../../../docs/generated/AGENT_COMMAND_SURFACE.md)
+
+`pm help` shows the bounded core tier. Use `pm guide capabilities`, `pm
+contracts --summary`, or `pm <command> --help --json` for progressive
+disclosure into the wider surface.
+
+## Token Discipline
+
+Every read declares a default ceiling and degrades deterministically rather
+than truncating silently. Choose in this order:
+
+1. **Projection** — ask for fewer fields: `pm get <ID> --output-include id,title,status,dependencies`.
+2. **Row limit** — `--output-limit 20`, or the command's own `--limit`.
+3. **Budget** — `--output-budget <tokens>` only when the first two are set.
+4. **Continuation** — when a response carries `output_budget_truncation`, use
+   the declared `--output-cursor`. Re-running with `--output-budget unbounded`
+   can cost orders of magnitude more.
+
+Always read the `omission_receipt` before treating a result as complete. See
+[Token budgets and read output](references/TOKEN_BUDGETS.md).
+
+## 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
+pm health --summary
+```
+
+Repository-wide gates before proposing a merge: `pnpm quality:static`.
+
+## References
+
+| Need                                             | Load                                                     | Cost     |
+| ------------------------------------------------ | -------------------------------------------------------- | -------- |
+| Command recipes for the developer loop            | [Command playbook](references/COMMAND_PLAYBOOK.md)        | ~275 tok |
+| Prompt templates                                  | [Prompts](references/PROMPTS.md)                          | ~250 tok |
+| Bounded reads, cursors, projections, receipts     | [Token budgets](references/TOKEN_BUDGETS.md)              | ~900 tok |
+| Typed edges, traversal, planning analytics        | [Relationship graph](references/GRAPH_AND_RELATIONSHIPS.md) | ~900 tok |
+| Branching, merging, concurrent agents             | [Multi-agent and merge](references/MULTI_AGENT_MERGE.md)  | ~800 tok |
+| Composing pm with grep, jq, xargs, and scripts    | [Scripting](references/SCRIPTING_COMPOSITION.md)          | ~800 tok |

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

@@ -0,0 +1,49 @@
+# 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 install guide-shell --project
+pm guide workflows
+pm guide commands --depth standard
+pm guide release --json
+```

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

@@ -0,0 +1,91 @@
+# Relationships and Graph Analytics
+
+The tracker is a directed graph, not a list. Typed edges are what make the
+project's history readable by algorithm. Full contract:
+[docs/RELATIONSHIP_GRAPH.md](../../../../docs/RELATIONSHIP_GRAPH.md) (~7.4k tok)
+and [docs/DEPENDENCY_KIND_CONTRACT.md](../../../../docs/DEPENDENCY_KIND_CONTRACT.md) (~700 tok).
+
+## The Edge Vocabulary
+
+Authoritative at runtime:
+
+```bash
+pm contracts --json --full | jq '.relationship_kind_contracts'
+```
+
+| Kind              | Meaning                                        | Ordering | Hierarchy |
+| ----------------- | ---------------------------------------------- | -------- | --------- |
+| `parent`          | This item belongs under that one                | no       | yes       |
+| `child`           | Inverse of `parent`                             | no       | yes       |
+| `blocked_by`      | This item waits for that one                    | yes      | no        |
+| `blocks`          | Inverse of `blocked_by`                         | yes      | no        |
+| `implements`      | This item realizes that goal, story, or ADR     | no       | no        |
+| `verifies`        | This item proves that one behaves as claimed    | no       | no        |
+| `discovered_from` | This item was found while doing that one        | no       | no        |
+| `incident_from`   | This item originates in that recorded incident  | no       | no        |
+| `supersedes`      | This item replaces that one                     | no       | no        |
+| `commits_to`      | This item lands in that changeset or release    | yes      | no        |
+| `related`         | Associative, non-directional                    | no       | no        |
+
+`related` carries the least information. Prefer a typed kind whenever one
+applies — `discovered_from`, `implements`, and `verifies` are the three that
+most often replace a reflexive `related`.
+
+## Adding Edges
+
+```bash
+pm update <ID> --dep "id=<other>,kind=implements"
+pm update <ID> --dep "id=<other>,kind=discovered_from"
+pm update <ID> --dep-remove "id=<other>,kind=related"
+```
+
+Rules that prevent damage:
+
+- `--dep` **appends**; it does not replace the dependency list.
+- `--dep-remove` with a bare id deletes **every** row for that id. Always pass
+  `kind=` unless removing all of them is the intent.
+- Never record both `A blocks B` and `B blocked_by A`. They are inverse
+  spellings of one edge, and recording both creates a cycle.
+- Never add an edge to satisfy a count. Each edge should cite durable text, a
+  history event, or a linked artifact.
+- A placeholder or misspelled id passes `create` silently. Verify with
+  `pm deps <ID>` after adding.
+
+## Reading The Graph
+
+```bash
+pm deps <ID>                              # tree view of one item's neighborhood
+pm deps <ID> --format context --direction both --kind implements,verifies
+pm graph analyze                          # layers, critical path, components, hubs
+pm graph audit                            # findings, coverage, edge composition
+pm graph impact <ID> --direction downstream
+pm graph ancestors <ID> / descendants <ID>
+pm graph paths <A> <B>
+pm graph dominators <ID>                  # what must pass through this node
+pm graph articulation                     # single points of failure
+pm graph communities / centrality / slack / redundancy
+pm graph plan                             # critical path method over the ordering DAG
+```
+
+`pm graph impact` and the traversal verbs are directional. Pass `--direction`
+explicitly rather than relying on a default when the answer depends on it.
+
+## Governance Signals Worth Checking
+
+`pm graph audit` reports the properties that decide whether the graph is
+trustworthy:
+
+- `isolated_active_nodes` and `degree_leq_one_active_nodes` — work nobody can
+  reach from anywhere.
+- `redundant_edges` — edges implied by another path; they cost storage and
+  dilute analytics.
+- `ordering_contradiction_edges` — a scheduling claim contradicted elsewhere.
+- `outcome_unreachable_nodes` — items that resolve to no declared goal.
+- `articulation_points` and `bridge_edges` — the structural chokepoints.
+
+When a workspace declares these as assurance bounds, adding edges can move a
+ratchet. Check headroom before a bulk enrichment pass:
+
+```bash
+pm assurance run graph-composition --trigger ci --dry-run --json
+```

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

@@ -0,0 +1,72 @@
+# Multiple Agents, Branches, and Merges
+
+Tracker data is versioned alongside the code, so several agents can work on
+separate branches and merge without hand-resolving item files. Full contract:
+[docs/MERGE_SAFETY.md](../../../../docs/MERGE_SAFETY.md) (~4.4k tok).
+
+## Once Per Clone Or Worktree
+
+The `.gitattributes` merge fence is committed, but the driver definitions it
+names are clone-local git config. A fresh clone or worktree merges tracker data
+textually until the installer has run:
+
+```bash
+pm merge install
+pm merge install --dry-run     # preview
+```
+
+Skipping this is the single most common cause of tracker merge conflicts.
+
+## Ownership Across Agents
+
+- `pm claim <ID>` before substantial edits. A claim is a recorded lease, not a
+  lock file, and it survives branching.
+- `pm release <ID>` when pausing, handing off, closing, or canceling.
+- `pm list-in-progress` shows what the fleet currently holds.
+- Never force an ownership or lock override without explicit human approval.
+
+Author identity is detected per invocation — harness, model, effort, role, and
+topic — so two agents on the same branch remain distinguishable in history
+without anyone passing `--author`.
+
+## What Merges Field-Aware
+
+The driver resolves four artifact classes: `item`, `history`, `relationship`,
+and `json`. Set-valued fields such as tags and dependency rows union rather
+than collide. Scalar fields follow the recorded field policy.
+
+Two properties to keep in mind when designing concurrent work:
+
+- **Additive beats rewriting.** `pm comments`, `pm notes`, and `--dep` append.
+  Rewriting a description or replacing acceptance criteria on two branches is a
+  genuine conflict that no driver can invent an answer for.
+- **Independent ids do not collide** unless two branches mint the same id for
+  unrelated items. Prefer creating items on a branch that has seen the other
+  branch's ids when doing bulk creation.
+
+## After A Merge
+
+A clean field-aware merge can still leave history streams needing
+reconciliation. Always run the post-merge gate:
+
+```bash
+pm merge report
+pm merge reconcile --message "Post-merge history reconciliation"
+pm validate --check-history-drift
+pm health --check-only
+```
+
+`pm merge report` lists what the driver decided and what it discarded. Review
+it before reconciling; reconciliation is an audited write.
+
+## Proving Nothing Was Lost
+
+```bash
+pm validate --check-resolution --check-history-drift
+pm graph audit
+pm activity --limit 20
+```
+
+History is append-only and hash-chained. `--check-history-drift` compares each
+stream's recorded chain against its contents, so a silently rewritten entry
+fails the check rather than passing unnoticed.

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-developer/references/SCRIPTING_COMPOSITION.md

@@ -0,0 +1,82 @@
+# Composing pm With Shell Tools
+
+`pm` is designed to be a process in a pipeline. Full contract:
+[docs/SCRIPTING.md](../../../../docs/SCRIPTING.md) (~1.9k tok).
+
+## Exit Codes Are Part Of The Answer
+
+| Exit | Meaning                                   | Response                            |
+| ---- | ----------------------------------------- | ----------------------------------- |
+| 0    | Completed (a read may return zero rows)   | Parse stdout.                       |
+| 1    | Runtime failure                           | Preserve stderr and stop.           |
+| 2    | Invalid flags or composition              | Fix the invocation; do not retry.   |
+| 3    | Tracker or resource not found             | Fix the path or id.                 |
+| 4    | State or concurrency conflict             | Refresh live state, then decide.    |
+| 5    | A dependency operation failed             | Inspect dependency evidence.        |
+| 6    | Succeeded, matched nothing to change      | Success. Inspect the receipt.       |
+| 7    | Succeeded, changed part of the selection  | Success. Inspect unmatched rows.    |
+
+`0`, `6`, and `7` are all success. A bare `if pm ...; then` treats `6` and `7`
+as failure, so classify the status explicitly in scripts.
+
+## JSON Shapes
+
+- CLI JSON has **no result wrapper**. `pm get <ID> --json` returns the entity
+  envelope directly.
+- Collections return `items`, `count`, `total`, `has_more`, `next_cursor`, and
+  a `completeness` block.
+- Mutations return a flat receipt: `id`, `status`, `changed_field_count`.
+- `--lean` drops nulls and empty containers, which makes `jq` selectors shorter
+  and the payload smaller.
+
+## Patterns
+
+Select ids and act on them:
+
+```bash
+ids=$(pm list --status open --type Issue --json --output-budget unbounded \
+  | jq -r '.items[] | select(.title | test("Semgrep")) | .id' | paste -sd,)
+pm update-many --ids "$ids" --tags triaged --dry-run
+```
+
+Bulk writes take ids comma-joined in a single argument; reads emit one id per
+line. `paste -sd,` or `tr '\n' ','` bridges the two.
+
+Aggregate without loading rows:
+
+```bash
+pm aggregate --group-by type --json | jq '.groups'
+pm stats --json | jq '.by_status'
+```
+
+Drive a check from graph structure:
+
+```bash
+pm graph audit --json | jq '{findings: .finding_count, redundant: .profile.redundant_edges}'
+```
+
+Stream history:
+
+```bash
+pm activity --limit 50 --json | jq -r '.events[] | [.at, .op, .item_id] | @tsv'
+```
+
+## Guardrails
+
+- One malformed flag makes a whole bulk update apply nothing. Use `--dry-run`
+  first on any `*-many` command.
+- Never delete items by search match. Delete only by exact id.
+- Do not write absolute filesystem paths into item text; run the repository
+  secret scan before committing tracker changes.
+- Prefer `--output-budget unbounded` only inside scripts that consume the output
+  programmatically, never in an agent's own context.
+
+## Discovering Exact Flags
+
+The contract is authoritative and never stale:
+
+```bash
+pm <command> --help --json
+pm contracts --command <command> --flags-only --json
+pm contracts --command <command> --full --json | jq '.command_exit_contracts'
+```

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

@@ -0,0 +1,85 @@
+# Token Budgets and Read Output
+
+Every `pm` read declares a default token ceiling, degrades deterministically
+when it is reached, and reports what it withheld. This reference is the
+operating procedure; [docs/READ_OUTPUT_CONTRACTS.md](../../../../docs/READ_OUTPUT_CONTRACTS.md)
+(~3.6k tok) is the full contract.
+
+## The Four Levers, In Order
+
+Apply the cheapest lever that answers the question.
+
+1. **Projection.** Ask for fewer fields or sections.
+
+   ```bash
+   pm get <ID> --output-include id,title,status,dependencies
+   pm list --status open --output-include id,title,type
+   ```
+
+2. **Row limit.** Bound the number of rows before bounding tokens.
+
+   ```bash
+   pm list --status open --output-limit 20
+   pm search "<terms>" --limit 10
+   ```
+
+3. **Budget.** Only after 1 and 2 are set.
+
+   ```bash
+   pm context --limit 10 --output-budget 4000
+   ```
+
+4. **Continuation.** Resume rather than re-read.
+
+   ```bash
+   pm notes <ID> --output-cursor <cursor-from-previous-response>
+   ```
+
+## Reading The Receipt
+
+Two blocks decide whether a result may be treated as complete.
+
+- `omission_receipt` — declares whether field groups were dropped and the flag
+  that restores each one. `has_omissions: false` means the projection is whole.
+- `output_budget_truncation` — appears only when a ceiling bound the result. It
+  names the `reason`, the `budget_source`, the row collections it compacted, and
+  whether a continuation is available.
+
+A truncated read is a claim about the part it withheld. Never summarize a
+truncated list as if it were the population. When `continuation_available` is
+true, the cursor is the correct recovery; `--output-budget unbounded` is the
+last resort and can be hundreds of times more expensive.
+
+## Formats
+
+- `--output-format toon` (default) is the agent-loop encoding: tabular rows are
+  emitted once as a header plus values, not repeated per row.
+- `--output-format json` / `--json` is for strict parsing. JSON ceilings are
+  higher than TOON ceilings for the same command because the encoding is larger.
+- `--lean` omits null and empty containers from JSON output.
+- `--token-accounting` attaches a per-section cost receipt so a read can be
+  profiled before it is made routine.
+
+## Measuring Before Committing To A Pattern
+
+```bash
+pm contracts --summary --json | jq '.command_summaries[]
+  | {command, toon: .default_max_estimated_tokens_by_format.toon}'
+pm list --status open --token-accounting
+```
+
+Use the declared ceiling per command rather than assuming a global one. A
+command with no declared ceiling inherits the workspace default, which is a
+weaker guarantee than a declared one.
+
+## Cold-Start Cost
+
+The cheapest useful orientation is two calls:
+
+```bash
+pm next                 # ~2.5k tok — one actionable item with its context
+pm contracts --summary  # ~2.6k tok — the command surface with per-command ceilings
+```
+
+Prefer `pm next` over `pm list-open` when the goal is to start work: it applies
+relevance ranking and returns a working set rather than a page of rows.