Workflow

RepoPrompt CE (rpce-cli) is the maintained target and the default for this skill. RepoPrompt Classic (rp-cli) is frozen — it no longer changes, so you only touch it for a one-shot cross-app comparison.

Two comparison modes:

• Same CLI across versions (the normal loop): older rpce-cli → newer rpce-cli, run as a pre/post pair around a CE upgrade.
• Across apps (one-shot): Classic rp-cli vs CE rpce-cli, to understand where CE's tools/flags diverge from frozen Classic.

Canonical locations (use these even if your working directory differs):

• Skill directory: ~/.pi/agent/skills/repoprompt-tool-guidance-refresh/ (may be a symlink target)
• Script: ~/.pi/agent/skills/repoprompt-tool-guidance-refresh/scripts/track-rp-version.sh
• Output directory: ~/.pi/agent/skills/repoprompt-tool-guidance-refresh/rp-tool-defs/

Snapshots are namespaced per CLI so Classic and CE never collide: CE writes rpcecli-help{VERSION}.txt / rpcecli-l{VERSION}.txt with baseline .baseline_version__rpcecli; Classic writes rpcli-* (frozen, last captured at v2.1.29).

Phase A — Pre-Upgrade (invoke BEFORE updating RepoPrompt CE)

1. Run the version tracking script:

``bash ~/.pi/agent/skills/repoprompt-tool-guidance-refresh/scripts/track-rp-version.sh --pre ` (Defaults to CE. Equivalent if you cd into the skill dir: ./scripts/track-rp-version.sh --pre`.)

1. The script writes a baseline snapshot under rp-tool-defs/:

- .baseline_versionrpcecli — the baseline rpce-cli version - rpcecli-help{VERSION}.txt — output of rpce-cli --help - rpcecli-l__{VERSION}.txt — output of rpce-cli -l

1. Stop here. Tell the user:

> ✓ Baseline captured at v{VERSION}. Go update RepoPrompt CE, then re-invoke this skill.

Phase B — Post-Upgrade (invoke AFTER updating RepoPrompt CE)

1. Run the version tracking script:

``bash ~/.pi/agent/skills/repoprompt-tool-guidance-refresh/scripts/track-rp-version.sh --post ``

1. On version change, the script captures a new snapshot and generates diffs under rp-tool-defs/:

- rpcecli-help__{NEW_VERSION}.txt / rpcecli-l__{NEW_VERSION}.txt — new snapshots - rpcecli-help__{NEW_VERSION}.diff — changes in rpce-cli --help - rpcecli-l__{NEW_VERSION}.diff — changes in rpce-cli -l (MCP tool definitions)

1. If no changes detected in the diffs, tell the user and stop:

> ✓ No MCP/CLI tool changes detected. Documentation is current.

1. (Optional) Changelog context: Ask the user:

> Paste release notes for v{NEW_VERSION} (or press Enter to skip):

If provided, write to ~/.pi/agent/skills/repoprompt-tool-guidance-refresh/references/changelog-latest.md. If skipped, proceed using diffs as ground truth.

1. Review diffs and identify what changed:

- New tools - Removed tools - Changed parameters or descriptions - New modes/options

Phase C — Update MCP documentation (primary output)

The rp MCP tool surface is what Pi agents actually use, and it is app-neutral, so CE tool/help changes flow here.

1. The MCP files live outside this skill folder:

- AGENTS prefaces: agent/AGENTS-prefaces/rp-mcp-.md - Prompts: agent/prompts/rp-.md (excluding *-cli.md)

1. Using the diffs as reference, make surgical updates to bring these files into alignment with the new tool definitions.

Phase D — Classic CLI documentation (only if a cross-app diff demands it)

Classic rp-cli is frozen, so its CLI docs do not need routine updates. The Classic-CLI artifacts are:

• AGENTS preface: agent/AGENTS-prefaces/rp-cli-preface.md
• Prompts: ~/.pi/agent/skills/repoprompt-tool-guidance-refresh/rp-cli-prompts/rp-*-cli.md
• Extension: agent/extensions/repoprompt-cli/ (deprecated)

Only touch these if a cross-app comparison (Phase F) shows the guidance relies on a Classic-only behavior that CE has changed or dropped.

Phase E — Git

Stage the changed files (new snapshots/diffs under rp-tool-defs/, plus any updated docs).

Phase F — Cross-app comparison (one-shot: Classic vs CE)

Use this to understand how CE's CLI/tool surface diverges from frozen Classic — useful when migrating guidance or validating the repoprompt-mcp extension's compatibility assumptions.

1. Ensure a current CE snapshot exists (capture one if needed):

``bash ./scripts/track-rp-version.sh --ce --force ` The frozen Classic baseline is already captured (rpcli-*, v2.1.29). To refresh it while Classic is still installed: ./scripts/track-rp-version.sh --classic --force`.

1. Generate the cross-app diffs:

``bash ./scripts/track-rp-version.sh --compare-apps ` This writes, under rp-tool-defs/: - xapp-helprpcli-{CLASSIC}rpcecli-{CE}.diff — --help differences - xapp-lrpcli-{CLASSIC}rpcecli-{CE}.diff` — tool-definition differences

1. These diffs are large by design (different apps). Read them to spot CE tools, flags, or parameters that differ from Classic, then update Phase C (and only if necessary, Phase D).

Scope of Relevant Changes

Only update documentation for changes that affect levers you directly use:

• New/changed/removed MCP tools
• New/changed/removed CLI commands or flags
• Changed parameters, modes, or behaviors

Ignore changes that only affect:

• RepoPrompt desktop app UI (without MCP/CLI changes)
• Integrations with other apps/harnesses (without MCP/CLI changes)
• Internal implementation details not exposed via tools

The diffs are the source of truth. If a changelog item has no corresponding signature in the diffs, it's not relevant to this refresh.

Token Economy

The preface files are included in every session's system prompt. Keep them tight:

• Do not document OS-level implementation details (e.g., how delete works under the hood) unless agents need to reason about it
• When two ops overlap significantly (e.g., extracthandoff and getlog both read session transcripts), pick one canonical op for the preface and omit the other. Skills and prompts can expand on the omitted op when a specific workflow needs it
• Behavioral notes about agent roles (e.g., what design produces) should be ≤10 tokens — just enough to route correctly