Align Pi revdiff integration with Claude review workflow

[umputun]

pi revdiff integration should match Claude Code's normal /revdiff behavior. Current Pi flow stores annotations as pending UI state with apply/rerun/results commands. That is a different UX and makes the standard review loop harder.

scope

• keep one public command: /revdiff [args]
• use Pi direct terminal handoff only
• remove Pi overlay mode and the launch-revdiff.sh dependency from the Pi review path
• remove overlay options from the Pi command/tool docs and revdiff_review parameters
• remove pending annotation inbox UI:
  • /revdiff-rerun
  • /revdiff-results
  • /revdiff-apply
  • /revdiff-clear
  • pending annotation status/widget/panel
• remove the post-edit reminder command from the default Pi package surface
• keep revdiff_review as the agent tool for rerun loops after fixes
• use revdiff exit status in automation: 0 means clean, 10 means annotations captured, other nonzero statuses mean failure

target workflow

• /revdiff [args] launches revdiff through direct terminal handoff
• no annotations means review is clean
• captured annotations are sent to the main agent immediately as a user message
• the agent handles annotations and reruns review with revdiff_review using the same args
• the loop stops only when revdiff returns no annotations

Claude parity gaps to cover

• update plugins/pi/skills/revdiff/SKILL.md to document the Claude-style loop
• classify annotations into explanation requests and code-change directives
• support the explanation loop with temp markdown files reviewed through revdiff
• instruct the agent to list planned changes before editing files, without relying on a Pi plan-mode feature
• document --untracked guidance for agent-created files
• document --description and --description-file guidance for launches after analysis or refactor work
• document the existing-history workflow for "use my latest revdiff annotations"
• document in-session review preload with --annotations=<tempfile>

extension fixes

• parse use_staged from .claude-plugin/skills/revdiff/scripts/detect-ref.sh
• auto-add --staged for staged-only no-arg reviews
• keep generic pass-through for revdiff flags, including:
  • --untracked
  • --description
  • --description-file
  • --annotations
  • --include
  • --exclude
• keep file review detection for existing files and path-like args
• treat exit 10 as success-with-annotations and preserve captured output
• treat nonzero statuses other than 10 as launch failures

out of scope

• Pi planning integration
• Claude revdiff-planning parity

acceptance criteria

• /revdiff [args] starts direct revdiff and hands captured annotations to the agent without an apply step
• agent reruns review with revdiff_review until no annotations are captured
• no pending annotation widget or apply/clear/results commands remain in the Pi user workflow
• staged-only no-arg review opens staged changes correctly
• Pi skill documents the same normal review loop as Claude Code, minus overlay and planning details

[umputun]

cc @melonamin @adstastic @Guria @dljsjr

I'm pinging you because you participated in earlier Pi integration discussions: #52, #167, #182, #186, #188, and #196.

This issue proposes removing the Pi-only pending annotation inbox and making Pi match Claude Code's /revdiff loop:

• /revdiff captures annotations and sends them to the agent immediately
• the agent handles them and reruns revdiff_review until clean
• no /revdiff-apply, /revdiff-results, /revdiff-rerun, or pending widget/panel
• no Pi overlay path, since Pi can hand the terminal directly to revdiff

I'd like opinions from people who used or worked on the Pi integration before this gets implemented.

I started using Pi actively over the last week and hit several rough edges in the current flow. Sometimes Pi doesn't get a completion signal back in the normal flow. Sometimes it falls into the interactive pending-widget path instead, with extra commands and state. It also lacks some behavior already covered by the Claude skill. The current integration works, but I want the UX to be simpler and more consistent.

Specific concern: #186 depends on the current apply prompt. If the apply step goes away, discussion-oriented annotations should probably be handled by the Claude-style classification flow instead: questions/explanations are answered first, code-change directives are edited only after that. Does that cover your use case, or do you still need a configurable prompt hook somewhere?

If any of you rely on the pending widget/results panel as a real workflow, pls say so here. Otherwise I plan to treat it as accidental extra state and simplify the Pi UX to the Claude-style loop.

[Guria]

I am not heavy user and have no strong opinion yet. Description looks reasonable for me and I see no issues with it.

[adstastic]

I think this works for me - I can edit the SKILL.md to to customise how the agent interprets the review comments, and its a cleaner flow for me than the pending widget. It's better this way because a hardcoded prompt doesn't override AGENTS.md, SKILL.md, and the comment itself.

[umputun]

implemented in #213.

what changed:

• /revdiff [args] is now the single Pi command and uses direct terminal handoff
• captured annotations go straight back to the agent, with revdiff_review used for rerun loops
• removed pending annotation inbox UI and /revdiff-rerun, /revdiff-results, /revdiff-apply, /revdiff-clear
• kept staged-only detection and pass-through support for --untracked, --description, --description-file, --annotations, --include, and --exclude
• documented the agent loop for explanation requests vs code-change directives
• updated README, site docs, Pi skill docs, and Pi package contents

closing this as done.