sf-agentpmd 0.1.0

package/skill/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: agentforcepmd
+description: Use this skill whenever working with the sf-agentpmd SF CLI plugin — discovering its commands, installing or upgrading it, running it against an Agentforce / AgentScript project, or interpreting its text / JSON / Markdown / SARIF / CSV outputs. Triggers on mentions of `sf agentpmd`, "AgentScript cyclomatic complexity", "Agent CC", "McCabe analysis of .agent files", "agent PMD", or any request to compute or report complexity / action-reference inventory for AgentScript bundles and the Apex backing logic they invoke.
+metadata:
+  type: skill
+  version: "0.1.0"
+  last_updated: "2026-05-19"
+---
+
+# sf-agentpmd
+
+`sf-agentpmd` is an SF CLI plugin that computes **standard McCabe
+cyclomatic complexity** for AgentScript (`.agent`) bundles and the Apex
+classes they invoke through `apex://` action targets. It also inventories
+action declarations and references, and emits a "CC by location"
+roll-up (AgentScript vs. Apex vs. Combined) suitable for posture analysis
+or static-analysis CI gates.
+
+## What it does at a glance
+
+- Walks every `.agent` file under a source directory (or auto-discovers
+  `sfdx-project.json` and uses its `packageDirectories`).
+- For each `before_reasoning:`, `after_reasoning:`, and
+  `reasoning.instructions:` block, computes McCabe CC.
+- For each `actions:` declaration, classifies the `target:` URI
+  (`apex://`, `flow://`, `prompt://`).
+- For every `apex://ClassName` target, resolves the `.cls` file and
+  computes per-method McCabe CC with the same convention SonarQube / PMD
+  use for Apex.
+- Renders the result as **text** (TTY-aware), **JSON** (SF CLI envelope),
+  **markdown** (with a Mermaid by-location chart), **SARIF** (for GitHub
+  Code Scanning), or **CSV** (for spreadsheet pivots).
+
+## Task domains
+
+Identify which of the four common questions the user is asking and read
+the matching reference file before answering.
+
+### "What commands does this plugin offer?"
+
+Read [`references/command-structure.md`](references/command-structure.md).
+Covers the topic / command tree, every flag, defaults, and short aliases.
+
+### "How do I install it?"
+
+Read [`references/install.md`](references/install.md). Covers both:
+- **Today (pre-publication):** clone + `npm install` + `npm run build` +
+  `sf plugins link`.
+- **Future (after npm publish):** `sf plugins install sf-agentpmd`.
+
+### "How do I upgrade it?"
+
+Read [`references/upgrade.md`](references/upgrade.md). Covers the
+linked-checkout refresh path (`git pull && npm run build`) and the
+published-plugin path (`sf plugins update` or
+`sf plugins install <name>@latest`).
+
+### "How do I make sense of the output?"
+
+Read [`references/output-formats.md`](references/output-formats.md).
+Covers every format the plugin emits, what each column / field means,
+how to read the "CC by location" roll-up, and which format to pick for
+which downstream consumer (terminal, PR comment, CI gate, spreadsheet).
+
+## Rules that always apply
+
+1. **Always include `--json`** when programmatically consuming output
+   (CI, follow-on `jq` pipelines, another plugin). Non-JSON formats are
+   for humans.
+2. **Prefer auto-discovery.** When run from inside an sfdx project,
+   omit `--source-dir`. The plugin will walk up to `sfdx-project.json`
+   and use its `packageDirectories`. Print the resolved root from the
+   header line to confirm.
+3. **Apex CC follow-through happens for free.** Any `apex://` target
+   referenced by an analyzed `.agent` file resolves to a sibling
+   `classes/<ClassName>.cls` and gets walked automatically — no flag
+   needed. Override with `--apex-source <dir>` only when the layout
+   differs from the standard sfdx convention.
+4. **`--fail-on N` thresholds on combined CC** (agent + Apex), not
+   agent-only. This is intentional for CI gates: a posture that pushes
+   complexity from AgentScript into Apex shouldn't slip past the gate.
+
+## Common workflows
+
+| You want to… | Run |
+| --- | --- |
+| Inspect a whole sfdx project | `sf agentpmd analyze` (inside the project) |
+| Inspect a specific bundle | `sf agentpmd analyze -n <DeveloperName>` |
+| Generate a PR / whitepaper appendix | `sf agentpmd analyze --format markdown > report.md` |
+| Gate a PR in CI | `sf agentpmd analyze --format sarif > out.sarif` (upload to Code Scanning) or `--fail-on 50` |
+| Pipe into another sf tool | `sf agentpmd analyze --json \| jq '.result.apexClasses[].classComplexity'` |
+
+## When *not* to use this plugin
+
+- **General Apex static analysis.** That's PMD / sfdx-scanner /
+  `@salesforce/code-analyzer`. sf-agentpmd's Apex pass only walks classes
+  reachable via `apex://` targets from an `.agent` file.
+- **Old Bot Builder XML or GenAiPlannerBundle XML.** Currently unsupported
+  (see the project's `TODO.md`). The plugin will skip them silently and
+  may dramatically under-report the implementation surface of agents
+  that store actions in a sibling planner bundle.
+- **Flow CC.** Not implemented; tracked in `TODO.md` § 9 / Flow
+  incorporation.

package/skill/references/command-structure.md

@@ -0,0 +1,89 @@
+# Command structure
+
+`sf-agentpmd` registers the topic `agentpmd` with one command:
+
+```
+sf agentpmd analyze [flags]
+```
+
+Discover the command surface yourself with `sf agentpmd --help` or
+`sf agentpmd analyze --help`.
+
+## The one command — `sf agentpmd analyze`
+
+Compute McCabe cyclomatic complexity and action-reference inventory for
+AgentScript bundles and their Apex backing logic.
+
+### Flags
+
+| Flag | Short | Type | Default | Purpose |
+| --- | --- | --- | --- | --- |
+| `--source-dir` | `-d` | path | _auto_ | Directory or single `.agent` file to analyze. When omitted, walks up from cwd looking for `sfdx-project.json` and uses its `packageDirectories`. |
+| `--api-name` | `-n` | string (repeatable) | _all_ | Filter to specific bundles by api-name. Matches against the bundle directory name **or** `config.developer_name` inside the `.agent`. Pass multiple times to union: `-n A -n B`. |
+| `--apex-source` | — | path | _auto_ | Override directory for resolving `apex://` targets. Default: walks up from each `.agent` looking for a sibling `classes/` directory. |
+| `--format` | — | enum | `text` | Non-JSON output: `text`, `markdown`, `sarif`, `csv`. Ignored when `--json` is set. |
+| `--width` | — | integer | `60` | Rule width for the text renderer. |
+| `--ascii` | — | boolean | _auto_ | Force ASCII-only output (no emoji / Unicode box chars). Auto-enabled when stdout isn't a TTY (e.g. piped). |
+| `--no-color` | — | boolean | `false` | Disable ANSI color in the text renderer. `NO_COLOR` env var also disables. |
+| `--sarif-warning` | — | integer | `10` | SARIF "warning" level threshold (per-method/per-procedure CC). |
+| `--sarif-error` | — | integer | `20` | SARIF "error" level threshold. |
+| `--fail-on` | — | integer | _off_ | Exit non-zero (code 2) if **combined** (agent + Apex) CC ≥ N. CI gate. |
+| `--json` | — | boolean | `false` | Emit SF CLI JSON envelope. Takes precedence over `--format`. |
+| `--flags-dir` | — | path | — | Standard SF CLI flag — import flag values from a directory. Inherited from `@salesforce/sf-plugins-core`. |
+
+### Auto-discovery rules
+
+When `--source-dir` is omitted, the plugin walks up from `process.cwd()`
+looking for `sfdx-project.json`. If found, it uses the project's
+`packageDirectories` as source roots and prints
+`Analyzing sfdx project <root> (N package director{y|ies}).` as the
+first line of human output. If no project file is found, it errors with
+`No --source-dir was provided and no sfdx-project.json was found …`.
+
+This matches the standard SF CLI ergonomics (`sf project deploy start`,
+`sf project retrieve start`, etc.).
+
+### Filter semantics for `--api-name`
+
+A bundle matches a `-n <X>` value if **either**:
+
+1. The bundle's directory name equals `<X>` (fast path, no parse).
+2. The bundle's `config.developer_name:` value equals `<X>` (slow path,
+   used only when (1) misses).
+
+If multiple `-n` values are supplied, the union is included. When none
+match anything discovered, the command errors with the list of
+available bundle names so the user can correct.
+
+The slow path means `--api-name` works even when the bundle's developer
+name has been edited away from the directory name — common after a
+manual rename.
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success. Report rendered to stdout. |
+| 1 | Standard usage / configuration error (missing flag, unknown bundle, no project found, invalid path). |
+| 2 | `--fail-on N` was set and combined CC reached or exceeded N. |
+
+### What "combined CC" includes
+
+- Sum of CC of every analyzed `.agent` procedure body
+  (`before_reasoning`, `after_reasoning`, `reasoning.instructions:->`).
+- Sum of CC of every method/constructor body in every Apex class reached
+  through an `apex://` action target.
+- Apex classes referenced by multiple bundles are counted **once** in the
+  combined total (de-duplicated by class path).
+
+### What the plugin does NOT count
+
+- `else` clauses, `when else` arms, `finally` blocks, `try` itself
+  (per standard McCabe).
+- AgentScript constructs the language doesn't have (loops, switch on AS
+  side — the AS grammar has no `for`/`while`/`case`).
+- Methods without a body (interface methods, abstract methods).
+- Apex methods reachable only through `flow://` or `prompt://` targets
+  (those URIs aren't followed yet).
+- Old-style Bot dialogs or GenAiPlannerBundle action declarations
+  (tracked as TODO).

package/skill/references/install.md

@@ -0,0 +1,112 @@
+# Install
+
+There are two install paths depending on the plugin's distribution
+state. As of the date this skill was last updated (2026-05-19), the
+plugin is **not yet published to npm**, so the from-source path is the
+only one that works today.
+
+## Path A — From source (today, pre-publication)
+
+The plugin lives at `~/projects/AgentForcePMD/` (or wherever the user
+cloned it). To install it into the `sf` CLI:
+
+```bash
+cd ~/projects/AgentForcePMD
+npm install
+npm run build
+sf plugins link "$(pwd)"
+```
+
+The link survives across `sf` invocations. You only need to rebuild
+(`npm run build`) when source under `src/` changes; the link itself
+remains. See [`upgrade.md`](upgrade.md) for the refresh dance.
+
+### Verify the install
+
+```bash
+sf plugins                    # should list 'sf-agentpmd  X.Y.Z (link)'
+sf agentpmd analyze --help    # should render the flag reference
+```
+
+`sf` will emit a one-time warning per process the first time you
+invoke a linked ESM plugin:
+
+> Warning: sf-agentpmd is a linked ESM module and cannot be
+> auto-transpiled. Existing compiled source will be used instead.
+
+This is benign. It's telling you `sf` is reading `lib/` (the build
+output), not running TypeScript directly. Just remember to
+`npm run build` after `src/` edits.
+
+### Where the linked plugin lives
+
+`sf plugins link` records the absolute path under
+`~/.local/share/sf/client/<version>/`. Inspecting:
+
+```bash
+sf plugins --core      # nothing — not a core plugin
+sf plugins             # sf-agentpmd appears here under its link path
+```
+
+## Path B — From npm (future, post-publication)
+
+When the plugin is published to the npm registry, the standard SF CLI
+install path applies:
+
+```bash
+sf plugins install sf-agentpmd
+```
+
+Verify the same way:
+
+```bash
+sf plugins                    # should list 'sf-agentpmd  X.Y.Z'
+sf agentpmd analyze --help
+```
+
+No build step, no link. Plain npm install under the hood.
+
+## Install the Claude Code skill
+
+The plugin bundles this Claude Code skill. After the plugin is installed
+(Path A or Path B), copy the skill tree into `~/.claude/skills/` with:
+
+```bash
+sf agentpmd install-skill
+```
+
+This recursively copies the bundled `skill/` tree (SKILL.md plus the
+`references/` pages) to `~/.claude/skills/agentforcepmd/`. Restart Claude
+Code (or reload skills) to activate it.
+
+For an npm install, the bundled source lives at
+`node_modules/sf-agentpmd/skill/`; local-dev contributors can instead
+symlink the in-repo `skill/` directory:
+
+```bash
+ln -sfn ~/projects/AgentForcePMD/skill ~/.claude/skills/agentforcepmd
+```
+
+## Prerequisites
+
+- **Node.js ≥ 20** (the plugin declares `"engines": { "node": ">=20" }`).
+- **`sf` CLI v2.131+** (older versions don't load linked ESM plugins
+  reliably).
+- **`@apexdevtools/apex-parser` runtime deps** — auto-installed by `npm
+  install`. Includes `antlr4` as a peer.
+
+## Uninstall
+
+```bash
+sf plugins unlink sf-agentpmd       # Path A — removes the link, source repo untouched
+sf plugins uninstall sf-agentpmd    # Path B — removes the npm-installed copy
+```
+
+## Common install issues
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `Command sf agentpmd not found` after link | `npm run build` not run, so `lib/` is empty / stale | `cd ~/projects/AgentForcePMD && npm run build` |
+| `Cannot find module '@agentscript/parser-javascript'` | Vendored deps missing — `vendor/` wasn't installed | `cd ~/projects/AgentForcePMD && npm install` (the `file:./vendor/...` deps re-symlink) |
+| `sf plugins link` reports "linked" but command absent | sf CLI cache | `rm -rf ~/.local/share/sf/client/*/node_modules/.cache 2>/dev/null && sf plugins link "$(pwd)"` |
+| Warning about ESM transpilation | Expected — see above | Ignore. |

package/skill/references/output-formats.md

@@ -0,0 +1,205 @@
+# Making sense of the output
+
+The plugin emits one of five surfaces depending on flags. Pick by
+downstream consumer.
+
+## The five surfaces
+
+| Surface | Triggered by | Audience |
+| --- | --- | --- |
+| Text | default | Terminal eyeballs |
+| JSON envelope | `--json` | Other SF plugins / `jq` pipelines |
+| Markdown | `--format markdown` | PR descriptions, gists, whitepaper appendices |
+| SARIF | `--format sarif` | GitHub Code Scanning, IDE annotations |
+| CSV | `--format csv` | Spreadsheet pivots |
+
+`--json` is special: it wraps the data in the standard SF CLI envelope
+(`{ status, result, warnings }`) and takes precedence over `--format`.
+Use it whenever something other than a human is reading.
+
+## Text output
+
+```
+Analyzing sfdx project /path/to/proj (1 package directory).
+AgentForce PMD — Cyclomatic Complexity (McCabe)
+============================================================
+
+[agent] aiAuthoringBundles/Foo/Foo.agent   CC=19
+------------------------------------------------------------
+  start_agent play   subtotal CC=19
+    reasoning.instructions   CC=19   if=5 and=9 or=4
+
+  Action references
+  ----------------------------------------------------------
+    pickRandomChoice                 [apex  ] used 1x → apex://Foo_Random
+
+Apex backing logic (resolved via apex:// targets)
+============================================================
+
+[apex]  classes/Foo_Random.cls   class CC=12
+   referenced by: aiAuthoringBundles/Foo/Foo.agent
+------------------------------------------------------------
+   List<Result> execute(List<Request> requests) CC=8   ternary=2 ||=1 for=1 &&=2 catch=1
+   String freshCookie()                         CC=1   (base only)
+   String abbreviate(String s)                  CC=3   if=2
+
+============================================================
+CC by location (whitepaper § 7)
+  AgentScript: 19   Apex: 12   Combined: 31
+Action declarations: 1  (apex 1, flow 0, prompt 0, unknown 0)
+Action references:   2
+```
+
+### How to read it
+
+- **Header line** confirms what was analyzed (auto-discovered project or
+  explicit `--source-dir`). If you see this when you didn't expect
+  auto-discovery, you forgot `--source-dir`.
+- **`[agent]` blocks**: one per `.agent` file. The bundle's CC and a
+  per-scope breakdown (`start_agent` and each `topic`).
+- Each procedure line:
+  `<kind>  CC=<n>  <contributor breakdown>`
+  where contributor breakdown is something like `if=3 and=1`. The CC
+  number is the McCabe value (`1 + sum(contributors)`). `(base only)`
+  means no control flow; CC = 1.
+- **Action references** lists each declared action with its target kind
+  (apex/flow/prompt/unknown) and a usage count (`used Nx`). A `used 0x`
+  declaration means the action is defined but not invoked — usually a
+  red flag (dead code) unless it's a planner-only action.
+- **`[apex]` blocks**: one per `.cls` file resolved via `apex://`. Lists
+  every method and constructor with its signature, CC, and contributor
+  breakdown using Apex-flavored short names (`for`, `while`, `do-while`,
+  `when`, `catch`, `ternary`, `&&`, `||`).
+- **`CC by location`** is the headline number: `AgentScript`,
+  `Apex`, `Combined`. This maps to the whitepaper § 7 framing — same
+  agent measured in two different layers, summed for the gross posture.
+
+### TTY-aware rendering
+
+When stdout isn't a TTY (piped, redirected, captured by CI), the text
+renderer auto-degrades:
+- Emoji prefixes (`📄`, `📜`) become `[agent]` / `[apex]`.
+- Unicode rules (`═`, `─`) become `=` / `-`.
+- ANSI color is disabled.
+
+Force ASCII even on a TTY with `--ascii`. Force color off with
+`--no-color` or `NO_COLOR=1`.
+
+## JSON envelope (`--json`)
+
+Standard SF CLI shape:
+
+```json
+{
+  "status": 0,
+  "result": {
+    "files": [ { "path": "...", "procedures": [...], "fileComplexity": 19, ... } ],
+    "totalComplexity": 19,
+    "totalDeclarations": 1,
+    "totalReferences": 2,
+    "byTargetKind": { "apex": 1, "flow": 0, "prompt": 0, "utils": 0, "unknown": 0 },
+    "apexClasses": [ { "className": "...", "path": "...", "methods": [...], "classComplexity": 12, ... } ],
+    "totalApexComplexity": 12,
+    "unresolvedApexTargets": []
+  },
+  "warnings": []
+}
+```
+
+Useful `jq` recipes:
+
+```bash
+# Combined CC for a CI gate
+sf agentpmd analyze --json | jq '.result.totalComplexity + .result.totalApexComplexity'
+
+# List apex:// targets that couldn't be resolved
+sf agentpmd analyze --json | jq -r '.result.unresolvedApexTargets[]'
+
+# Per-bundle CC table
+sf agentpmd analyze --json | jq -r '.result.files[] | "\(.fileComplexity)\t\(.path)"'
+
+# Methods exceeding CC 10
+sf agentpmd analyze --json \
+  | jq -r '.result.apexClasses[].methods[] | select(.complexity >= 10) | "\(.complexity)\t\(.signature)"'
+```
+
+## Markdown (`--format markdown`)
+
+Designed for embedding in PR descriptions, gists, Slack snippets,
+whitepaper appendices.
+
+- Top: a Mermaid `xychart-beta` bar chart with one bar per `.agent`
+  bundle, split into AgentScript CC (red — whitepaper "Reasoning
+  Logic") and Apex CC (green — "Deterministic Logic"). Renders
+  natively in GitHub, GitLab, and most modern markdown previewers.
+- Followed by a per-bundle table (procedure-by-procedure).
+- Followed by a per-Apex-class table (method-by-method).
+- Final "CC by location" totals row.
+
+GFM pipe escaping is applied automatically — `||` short-circuit
+operators in the Apex breakdown render as `\|\|` in cells so they don't
+break the row.
+
+Typical use:
+
+```bash
+sf agentpmd analyze --format markdown > report.md
+gh pr comment <pr-number> --body-file report.md
+```
+
+## SARIF (`--format sarif`)
+
+SARIF 2.1.0. One result per procedure + per Apex method. Severity
+driven by `--sarif-warning` (default 10) and `--sarif-error` (default
+20), matching PMD's `methodReportLevel` convention.
+
+Upload to GitHub Code Scanning:
+
+```yaml
+# .github/workflows/agentpmd.yml
+- name: Analyze
+  run: sf agentpmd analyze --format sarif > agentpmd.sarif
+- uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: agentpmd.sarif
+```
+
+Each result carries `properties.complexity` (numeric) and
+`properties.kind` (`method` / `constructor` for Apex, `before_reasoning`
+/ `after_reasoning` / `reasoning_instructions` for AgentScript) so
+follow-on tooling can re-band severity without re-running.
+
+Row origins are normalized to 1-based in SARIF regardless of source
+parser (AgentScript CST is 0-based; ANTLR is 1-based for line, 0-based
+for column — the renderer adjusts).
+
+## CSV (`--format csv`)
+
+RFC-4180 quoted. One header row + one row per procedure / per Apex
+method.
+
+Columns:
+
+```
+type, file, scope_or_class, name, complexity, start_row, start_col, contributors
+```
+
+`type` is either `agent_procedure` or `apex_method`. `contributors`
+is a semicolon-separated `kind=count` list (e.g.
+`if_statement=3;short_circuit_and=1`).
+
+Pivot in your favorite spreadsheet on `type` × `file` for a posture
+matrix, or on `kind` (parsed from `contributors`) for a contributor
+breakdown.
+
+## Picking a format — the cheat sheet
+
+| Question | Best surface |
+| --- | --- |
+| "What's the CC of this file right now in my terminal?" | text |
+| "I want to gate the PR if combined CC ≥ 80." | `--fail-on 80` (uses text or `--json` for visibility) |
+| "I want PR annotations on the specific high-CC methods." | sarif |
+| "I want to drop a CC table into a PR description." | markdown |
+| "I want to share the numbers in a quick gist." | markdown |
+| "I want to feed the per-method numbers into a spreadsheet." | csv |
+| "I want another tool / script to consume the output." | `--json` |

package/skill/references/upgrade.md

@@ -0,0 +1,112 @@
+# Upgrade
+
+## Path A — From source (linked checkout)
+
+When `sf-agentpmd` is installed via `sf plugins link <repo>`, upgrading
+means pulling new commits and rebuilding `lib/`. The link itself does
+not need to be re-established.
+
+```bash
+cd ~/projects/AgentForcePMD
+git pull --ff-only
+npm install                   # if dependencies changed
+npm run build
+```
+
+That's it. The next `sf agentpmd analyze` invocation picks up the new
+`lib/`. No `sf plugins link` re-run is needed because the link points
+at the on-disk directory, not at a specific build.
+
+If `npm install` reports dependency tree changes that don't match
+`package-lock.json`, that's fine — it usually means upstream patched a
+transitive. To enforce a clean install matching the lockfile:
+
+```bash
+npm ci                        # exact install per package-lock.json
+npm run build
+```
+
+### When to also `npm install`
+
+| Trigger | Action |
+| --- | --- |
+| Only `src/` changed | `npm run build` |
+| `package.json` or `package-lock.json` changed | `npm install && npm run build` |
+| `vendor/` changed (e.g. agentscript parser refresh) | `npm install && npm run build` |
+| `tsconfig.json` changed | `npm run clean && npm run build` |
+
+## Path B — From npm (published plugin)
+
+```bash
+sf plugins update                       # bumps every installed sf plugin
+# or, to target this one:
+sf plugins install sf-agentpmd@latest   # explicit
+sf plugins install sf-agentpmd@0.3.1    # pin to a specific version
+```
+
+`sf plugins update` is idempotent and safe to run at any time. It
+respects the version range declared at install (defaults to `latest`).
+
+To check whether you're on the latest:
+
+```bash
+sf plugins                              # shows installed version
+npm view sf-agentpmd version   # shows current published version
+```
+
+## Downgrade
+
+```bash
+# Path B: pin to an earlier version
+sf plugins install sf-agentpmd@0.2.0
+
+# Path A: git checkout the desired tag, then rebuild
+cd ~/projects/AgentForcePMD
+git checkout v0.2.0
+npm install
+npm run build
+```
+
+## Switching between linked source and published npm
+
+To move from a linked checkout to the published version:
+
+```bash
+sf plugins unlink sf-agentpmd
+sf plugins install sf-agentpmd
+```
+
+To move from the published version back to a linked checkout:
+
+```bash
+sf plugins uninstall sf-agentpmd
+cd ~/projects/AgentForcePMD
+sf plugins link "$(pwd)"
+```
+
+## Refreshing the Claude Code skill
+
+The bundled skill ships inside the plugin, so a plugin upgrade may carry
+new skill content. After upgrading, re-copy the skill tree:
+
+```bash
+sf agentpmd install-skill   # re-copies skill/ to ~/.claude/skills/agentforcepmd/
+```
+
+Restart Claude Code (or reload skills) to pick up the new content. If you
+use a local-dev symlink (`~/.claude/skills/agentforcepmd` -> the repo's
+`skill/` directory), no re-copy is needed — a `git pull` updates the
+skill in place.
+
+## Verifying the upgrade
+
+Always sanity-check after upgrading:
+
+```bash
+sf agentpmd analyze --help              # confirm new flags / removed flags
+sf agentpmd --version 2>/dev/null \
+  || sf plugins | grep agentpmd         # confirm version bump
+```
+
+If the plugin gained new commands, they appear under the `agentpmd`
+topic. `sf agentpmd` (no subcommand) prompts to pick one.