repoprompt-tool-guidance-refresh

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:

   ~/.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.)

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

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

3. 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:

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

2. 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)

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

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

4. (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.

5. 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)

2. 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):

   ./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.

2. Generate the cross-app diffs:

   ./scripts/track-rp-version.sh --compare-apps
   

   This writes, under rp-tool-defs/:

   • xapp-help__rpcli-{CLASSIC}__rpcecli-{CE}.diff — --help differences
   • xapp-l__rpcli-{CLASSIC}__rpcecli-{CE}.diff — tool-definition differences

3. 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., extract_handoff and get_log 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