@unbrained/pm-cli 2026.8.16 → 2026.8.18

package/plugins/pm-claude/skills/pm-audit/SKILL.md

@@ -82,3 +82,29 @@ For each **finding item** created during the audit, also create a matching `Task
 ## Privacy
 
 Keep sensitive operational data (telemetry credentials, user PII, internal endpoints) out of public docs and tracked comments. Use `pm notes` for sensitive context instead of `pm comments`.
+
+## Progressive Disclosure and Token Discipline
+
+Load the smallest thing that answers the question. Costs are measured.
+
+| Need | Call | Cost |
+|------|------|------|
+| Pick or resume work | `pm_next`, or `pm_context` with `limit: 10` | ~2.1-2.5k tok |
+| Exact flags for one command | `pm_contracts` with `command: "<name>", flagsOnly: true` | ~1-3.4k tok |
+| The whole command surface with per-command ceilings | `pm_contracts` with `summary: true` | ~2.6k tok |
+| An unfamiliar capability family | `pm_run` with `action: "guide", topic: "<topic>", depth: "brief"` | ~0.6-1k tok |
+
+Guide topics: `quickstart`, `commands`, `workflows`, `sdk`, `extensions`,
+`skills`, `harnesses`, `release`, `tokens`, `graph`, `assurance`, `merge`.
+
+Never load `docs/COMMANDS.md` (~29k tok) or `docs/SDK.md` (~45k tok) whole.
+
+Bound every read in this order: projection (`outputInclude`), then row limit
+(`outputLimit` or `limit`), then `outputBudget`, then `outputCursor` to resume.
+Read the `omission_receipt` before treating a result as complete — a
+budget-truncated read is a claim about the part it withheld, and a truncated
+list must never be summarized as if it were the whole population.
+
+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.

package/plugins/pm-claude/skills/pm-developer/SKILL.md

@@ -121,3 +121,29 @@ When no existing item matches:
 ```
 
 Then call `TaskCreate` + `TaskUpdate(in_progress)` after claiming.
+
+## Progressive Disclosure and Token Discipline
+
+Load the smallest thing that answers the question. Costs are measured.
+
+| Need | Call | Cost |
+|------|------|------|
+| Pick or resume work | `pm_next`, or `pm_context` with `limit: 10` | ~2.1-2.5k tok |
+| Exact flags for one command | `pm_contracts` with `command: "<name>", flagsOnly: true` | ~1-3.4k tok |
+| The whole command surface with per-command ceilings | `pm_contracts` with `summary: true` | ~2.6k tok |
+| An unfamiliar capability family | `pm_run` with `action: "guide", topic: "<topic>", depth: "brief"` | ~0.6-1k tok |
+
+Guide topics: `quickstart`, `commands`, `workflows`, `sdk`, `extensions`,
+`skills`, `harnesses`, `release`, `tokens`, `graph`, `assurance`, `merge`.
+
+Never load `docs/COMMANDS.md` (~29k tok) or `docs/SDK.md` (~45k tok) whole.
+
+Bound every read in this order: projection (`outputInclude`), then row limit
+(`outputLimit` or `limit`), then `outputBudget`, then `outputCursor` to resume.
+Read the `omission_receipt` before treating a result as complete — a
+budget-truncated read is a claim about the part it withheld, and a truncated
+list must never be summarized as if it were the whole population.
+
+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.

package/plugins/pm-claude/skills/pm-planner/SKILL.md

@@ -145,3 +145,29 @@ Call the same lifecycle through the `pm_plan` MCP tool. Use `harness: "claude-co
 - Run `pm_validate` after batch changes.
 - Set exactly one step `in_progress` per plan; pass `allowMultipleActive: true` only for explicit parallel branches.
 - Use `pm_plan` `subcommand=resume` after long-running sessions so the next agent can pick up with a deterministic context.
+
+## Progressive Disclosure and Token Discipline
+
+Load the smallest thing that answers the question. Costs are measured.
+
+| Need | Call | Cost |
+|------|------|------|
+| Pick or resume work | `pm_next`, or `pm_context` with `limit: 10` | ~2.1-2.5k tok |
+| Exact flags for one command | `pm_contracts` with `command: "<name>", flagsOnly: true` | ~1-3.4k tok |
+| The whole command surface with per-command ceilings | `pm_contracts` with `summary: true` | ~2.6k tok |
+| An unfamiliar capability family | `pm_run` with `action: "guide", topic: "<topic>", depth: "brief"` | ~0.6-1k tok |
+
+Guide topics: `quickstart`, `commands`, `workflows`, `sdk`, `extensions`,
+`skills`, `harnesses`, `release`, `tokens`, `graph`, `assurance`, `merge`.
+
+Never load `docs/COMMANDS.md` (~29k tok) or `docs/SDK.md` (~45k tok) whole.
+
+Bound every read in this order: projection (`outputInclude`), then row limit
+(`outputLimit` or `limit`), then `outputBudget`, then `outputCursor` to resume.
+Read the `omission_receipt` before treating a result as complete — a
+budget-truncated read is a claim about the part it withheld, and a truncated
+list must never be summarized as if it were the whole population.
+
+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.

package/plugins/pm-claude/skills/pm-release/SKILL.md

@@ -80,3 +80,29 @@ gh run view <run-id>                         # Detailed run status
 - Never set `path` for real repository tracking — only for sandbox tests.
 - Run coverage gate before any `npm publish` or version tag.
 - Confirm GitHub CI green before closing the release item.
+
+## Progressive Disclosure and Token Discipline
+
+Load the smallest thing that answers the question. Costs are measured.
+
+| Need | Call | Cost |
+|------|------|------|
+| Pick or resume work | `pm_next`, or `pm_context` with `limit: 10` | ~2.1-2.5k tok |
+| Exact flags for one command | `pm_contracts` with `command: "<name>", flagsOnly: true` | ~1-3.4k tok |
+| The whole command surface with per-command ceilings | `pm_contracts` with `summary: true` | ~2.6k tok |
+| An unfamiliar capability family | `pm_run` with `action: "guide", topic: "<topic>", depth: "brief"` | ~0.6-1k tok |
+
+Guide topics: `quickstart`, `commands`, `workflows`, `sdk`, `extensions`,
+`skills`, `harnesses`, `release`, `tokens`, `graph`, `assurance`, `merge`.
+
+Never load `docs/COMMANDS.md` (~29k tok) or `docs/SDK.md` (~45k tok) whole.
+
+Bound every read in this order: projection (`outputInclude`), then row limit
+(`outputLimit` or `limit`), then `outputBudget`, then `outputCursor` to resume.
+Read the `omission_receipt` before treating a result as complete — a
+budget-truncated read is a claim about the part it withheld, and a truncated
+list must never be summarized as if it were the whole population.
+
+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.

package/plugins/pm-claude/skills/pm-workflow/SKILL.md

@@ -142,3 +142,29 @@ Most tools accept `cwd`, `author`, and `options`:
 ## Safety
 
 Do not pass `path` during real repository tracking. Only pass `path` for sandbox/test runs.
+
+## Progressive Disclosure and Token Discipline
+
+Load the smallest thing that answers the question. Costs are measured.
+
+| Need | Call | Cost |
+|------|------|------|
+| Pick or resume work | `pm_next`, or `pm_context` with `limit: 10` | ~2.1-2.5k tok |
+| Exact flags for one command | `pm_contracts` with `command: "<name>", flagsOnly: true` | ~1-3.4k tok |
+| The whole command surface with per-command ceilings | `pm_contracts` with `summary: true` | ~2.6k tok |
+| An unfamiliar capability family | `pm_run` with `action: "guide", topic: "<topic>", depth: "brief"` | ~0.6-1k tok |
+
+Guide topics: `quickstart`, `commands`, `workflows`, `sdk`, `extensions`,
+`skills`, `harnesses`, `release`, `tokens`, `graph`, `assurance`, `merge`.
+
+Never load `docs/COMMANDS.md` (~29k tok) or `docs/SDK.md` (~45k tok) whole.
+
+Bound every read in this order: projection (`outputInclude`), then row limit
+(`outputLimit` or `limit`), then `outputBudget`, then `outputCursor` to resume.
+Read the `omission_receipt` before treating a result as complete — a
+budget-truncated read is a claim about the part it withheld, and a truncated
+list must never be summarized as if it were the whole population.
+
+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.

package/plugins/pm-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pm-codex",
-  "version": "2026.8.16",
+  "version": "2026.8.18",
   "description": "Native Codex integration for pm-cli with bundled MCP tools, skills, commands, and agent workflows.",
   "author": {
     "name": "unbrained",

package/plugins/pm-codex/skills/pm-auditor/SKILL.md

@@ -18,3 +18,29 @@ Use for broad repository audits, release readiness checks, privacy reviews, and
 ## Evidence
 
 Record exact verification commands and summarized results through `pm_comments`, and link touched files through `pm_files`.
+
+## Progressive Disclosure and Token Discipline
+
+Load the smallest thing that answers the question. Costs are measured.
+
+| Need | Call | Cost |
+|------|------|------|
+| Pick or resume work | `pm_next`, or `pm_context` with `limit: 10` | ~2.1-2.5k tok |
+| Exact flags for one command | `pm_contracts` with `command: "<name>", flagsOnly: true` | ~1-3.4k tok |
+| The whole command surface with per-command ceilings | `pm_contracts` with `summary: true` | ~2.6k tok |
+| An unfamiliar capability family | `pm_run` with `action: "guide", topic: "<topic>", depth: "brief"` | ~0.6-1k tok |
+
+Guide topics: `quickstart`, `commands`, `workflows`, `sdk`, `extensions`,
+`skills`, `harnesses`, `release`, `tokens`, `graph`, `assurance`, `merge`.
+
+Never load `docs/COMMANDS.md` (~29k tok) or `docs/SDK.md` (~45k tok) whole.
+
+Bound every read in this order: projection (`outputInclude`), then row limit
+(`outputLimit` or `limit`), then `outputBudget`, then `outputCursor` to resume.
+Read the `omission_receipt` before treating a result as complete — a
+budget-truncated read is a claim about the part it withheld, and a truncated
+list must never be summarized as if it were the whole population.
+
+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.

package/plugins/pm-codex/skills/pm-native/SKILL.md

@@ -67,3 +67,29 @@ Invariants:
 - One step `in_progress` at a time by default; pass `allowMultipleActive: true` for explicit parallel branches.
 - Use `subcommand: block-step` with `stepBlockedReason` when discovery flips a step.
 - Use `subcommand: materialize` once steps are concrete enough to become Tasks.
+
+## Progressive Disclosure and Token Discipline
+
+Load the smallest thing that answers the question. Costs are measured.
+
+| Need | Call | Cost |
+|------|------|------|
+| Pick or resume work | `pm_next`, or `pm_context` with `limit: 10` | ~2.1-2.5k tok |
+| Exact flags for one command | `pm_contracts` with `command: "<name>", flagsOnly: true` | ~1-3.4k tok |
+| The whole command surface with per-command ceilings | `pm_contracts` with `summary: true` | ~2.6k tok |
+| An unfamiliar capability family | `pm_run` with `action: "guide", topic: "<topic>", depth: "brief"` | ~0.6-1k tok |
+
+Guide topics: `quickstart`, `commands`, `workflows`, `sdk`, `extensions`,
+`skills`, `harnesses`, `release`, `tokens`, `graph`, `assurance`, `merge`.
+
+Never load `docs/COMMANDS.md` (~29k tok) or `docs/SDK.md` (~45k tok) whole.
+
+Bound every read in this order: projection (`outputInclude`), then row limit
+(`outputLimit` or `limit`), then `outputBudget`, then `outputCursor` to resume.
+Read the `omission_receipt` before treating a result as complete — a
+budget-truncated read is a claim about the part it withheld, and a truncated
+list must never be summarized as if it were the whole population.
+
+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.

package/plugins/pm-codex/skills/pm-release/SKILL.md

@@ -17,3 +17,29 @@ Use for release prep, compatibility gates, publication checks, and post-release
 5. Verify public surfaces after publish and record results through `pm_comments`.
 
 Use `pm_run` for release-adjacent pm actions not exposed as narrow tools.
+
+## Progressive Disclosure and Token Discipline
+
+Load the smallest thing that answers the question. Costs are measured.
+
+| Need | Call | Cost |
+|------|------|------|
+| Pick or resume work | `pm_next`, or `pm_context` with `limit: 10` | ~2.1-2.5k tok |
+| Exact flags for one command | `pm_contracts` with `command: "<name>", flagsOnly: true` | ~1-3.4k tok |
+| The whole command surface with per-command ceilings | `pm_contracts` with `summary: true` | ~2.6k tok |
+| An unfamiliar capability family | `pm_run` with `action: "guide", topic: "<topic>", depth: "brief"` | ~0.6-1k tok |
+
+Guide topics: `quickstart`, `commands`, `workflows`, `sdk`, `extensions`,
+`skills`, `harnesses`, `release`, `tokens`, `graph`, `assurance`, `merge`.
+
+Never load `docs/COMMANDS.md` (~29k tok) or `docs/SDK.md` (~45k tok) whole.
+
+Bound every read in this order: projection (`outputInclude`), then row limit
+(`outputLimit` or `limit`), then `outputBudget`, then `outputCursor` to resume.
+Read the `omission_receipt` before treating a result as complete — a
+budget-truncated read is a claim about the part it withheld, and a truncated
+list must never be summarized as if it were the whole population.
+
+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.