From 21f309fdf0758ed784777ace360a75a1d25c1ef9 Mon Sep 17 00:00:00 2001 From: Dmitry Verkhoturov Date: Tue, 1 Sep 2026 23:51:09 +0200 Subject: [PATCH 1/3] feat(codex): package revdiff skills for marketplace install --- .agents/plugins/marketplace.json | 32 ++++++++ .github/scripts/validate-codex-marketplace.py | 80 +++++++++++++++++++ .github/workflows/ci.yml | 3 + CLAUDE.md | 5 +- README.md | 17 +--- plugins/codex/.codex-plugin/plugin.json | 37 +++++++++ plugins/codex/README.md | 28 +------ plugins/codex/skills/revdiff-plan/SKILL.md | 15 +--- plugins/codex/skills/revdiff/SKILL.md | 14 ++-- .../skills/revdiff/references/install.md | 9 ++- site/docs.html | 12 +-- site/index.html | 2 +- site/llms.txt | 4 +- 13 files changed, 186 insertions(+), 72 deletions(-) create mode 100644 .agents/plugins/marketplace.json create mode 100644 .github/scripts/validate-codex-marketplace.py create mode 100644 plugins/codex/.codex-plugin/plugin.json diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 00000000..37c84c4a --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,32 @@ +{ + "name": "revdiff", + "interface": { + "displayName": "RevDiff" + }, + "plugins": [ + { + "name": "revdiff", + "source": { + "source": "local", + "path": "./plugins/codex" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Developer Tools" + }, + { + "name": "revdiff-planning", + "source": { + "source": "local", + "path": "./plugins/revdiff-planning" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Developer Tools" + } + ] +} diff --git a/.github/scripts/validate-codex-marketplace.py b/.github/scripts/validate-codex-marketplace.py new file mode 100644 index 00000000..2fcaf58c --- /dev/null +++ b/.github/scripts/validate-codex-marketplace.py @@ -0,0 +1,80 @@ +#!/usr/bin/env python3 +"""Validate the Codex marketplace and its local plugin manifests.""" + +import json +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[2] +MARKETPLACE = ROOT / ".agents" / "plugins" / "marketplace.json" +EXPECTED_PLUGINS = { + "revdiff": { + "source": "./plugins/codex", + "files": ( + "skills/revdiff/SKILL.md", + "skills/revdiff-plan/SKILL.md", + ), + }, + "revdiff-planning": { + "source": "./plugins/revdiff-planning", + "files": ("hooks/codex-hooks.json",), + }, +} + + +def load_json(path: Path) -> dict: + with path.open(encoding="utf-8") as stream: + return json.load(stream) + + +def main() -> None: + if not __debug__: + raise RuntimeError("assertions must be enabled for marketplace validation") + + marketplace = load_json(MARKETPLACE) + claude_marketplace = load_json(ROOT / ".claude-plugin" / "marketplace.json") + claude_versions = { + plugin["name"]: plugin["version"] for plugin in claude_marketplace["plugins"] + } + plugins = {plugin["name"]: plugin for plugin in marketplace["plugins"]} + assert set(plugins) == set(EXPECTED_PLUGINS), "unexpected Codex plugin set" + + for name, expected in EXPECTED_PLUGINS.items(): + plugin = plugins[name] + source = plugin["source"] + assert source["source"] == "local", f"{plugin['name']}: source must be local" + assert source["path"] == expected["source"], ( + f"{name}: source is {source['path']}, expected {expected['source']}" + ) + + plugin_root = (ROOT / source["path"]).resolve() + assert plugin_root.is_relative_to(ROOT), f"{plugin['name']}: source escapes repo" + + manifest_path = plugin_root / ".codex-plugin" / "plugin.json" + manifest = load_json(manifest_path) + assert manifest["name"] == plugin["name"], ( + f"{plugin['name']}: manifest name is {manifest['name']}" + ) + assert manifest["version"] == claude_versions[plugin["name"]], ( + f"{plugin['name']}: Codex and Claude marketplace versions differ" + ) + + for field in ("skills", "hooks"): + if field not in manifest: + continue + component = (plugin_root / manifest[field]).resolve() + assert component.is_relative_to(plugin_root), ( + f"{plugin['name']}: {field} path escapes plugin" + ) + assert component.exists(), f"{plugin['name']}: missing {field} path" + + for relative_path in expected["files"]: + assert (plugin_root / relative_path).is_file(), ( + f"{plugin['name']}: missing packaged file {relative_path}" + ) + + print("Codex marketplace manifests are valid") + + +if __name__ == "__main__": + main() diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 43b25c02..5473a356 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -65,6 +65,9 @@ jobs: pip install pyyaml python3 .github/scripts/validate-frontmatter.py + - name: validate Codex marketplace manifests + run: python3 .github/scripts/validate-codex-marketplace.py + - name: shellcheck run: | find . -name '*.sh' -not -path './.git/*' -not -path './vendor/*' -print0 | xargs -0 shellcheck diff --git a/CLAUDE.md b/CLAUDE.md index 29ac43aa..cce144c0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -78,9 +78,10 @@ TUI for reviewing diffs, files, and documents with inline annotations, built wit ## Codex Plugin and Skills - Codex skills live at `plugins/codex/skills/` — two skills: `revdiff` (diff review) and `revdiff-plan` (plan review via last Codex assistant message) -- Manual skill install copies to `~/.codex/skills//`; automatic plan review is distributed separately through the `revdiff-planning` Codex plugin +- The `revdiff` Codex plugin packages both skills; automatic plan review is distributed separately through the `revdiff-planning` Codex plugin +- Codex marketplace metadata lives at `.agents/plugins/marketplace.json`; keep its local sources aligned with each `.codex-plugin/plugin.json` - Keep Claude's default-discovered `PreToolUse/ExitPlanMode` config in `hooks/hooks.json`; the Codex manifest explicitly points its opt-in `Stop` hook at `hooks/codex-hooks.json` -- Script path resolution in SKILL.md falls back to `${CODEX_HOME:-$HOME/.codex}/skills//scripts` when not running inside the revdiff repo +- Script path resolution in SKILL.md derives the installed plugin root from the skill's absolute catalogue path; marketplace installs live under Codex's plugin cache, not `~/.codex/skills/` - Scripts are copies from `.claude-plugin/skills/revdiff/scripts/`, not symlinks — each has a source comment at top - `detect-ref.sh` dispatches by VCS (`detect_git` / `detect_hg` / `detect_jj`) via `command -v` probes (jj → git → hg, matching `DetectVCS` precedence); git path stays byte-identical to the pre-refactor output. `read-latest-history.sh` uses the same VCS probe order for repo-root resolution. - Codex automatic plan review runs only for `permission_mode=plan`, prefers a complete plan in `last_assistant_message`, and falls back whenever that field has no complete block to the last assistant message for the exact transcript/session/turn; manual `/revdiff-plan` remains the best-effort rollout fallback diff --git a/README.md b/README.md index 8d6661df..89f6d543 100644 --- a/README.md +++ b/README.md @@ -273,10 +273,11 @@ revdiff ships with a [Codex CLI](https://github.com/openai/codex) plugin for int The plugin uses the same terminal overlay mechanism (tmux, Zellij, herdr, kitty, wezterm, etc.) as the Claude Code plugin. -**Install the automatic plan-review plugin:** +**Install the diff-review skills and automatic plan-review plugin:** ```bash codex plugin marketplace add umputun/revdiff +codex plugin add revdiff@revdiff codex plugin add revdiff-planning@revdiff ``` @@ -284,17 +285,7 @@ Start a new session and trust the plugin hook through `/hooks`. The `Stop` hook When annotations are present, the hook asks Codex to return the complete revised plan with a snapshot marker on the first line inside ``. The next round opens a rolling compare (` `); reviewed snapshots are replaced, and a clean review removes the final snapshot. -**Install the manual skills:** - -```bash -# clone the repo first -git clone https://github.com/umputun/revdiff.git -cd revdiff - -# copy skills to Codex skills directory -cp -r plugins/codex/skills/revdiff ~/.codex/skills/revdiff -cp -r plugins/codex/skills/revdiff-plan ~/.codex/skills/revdiff-plan -``` +The `revdiff` plugin installs both interactive skills. The separate `revdiff-planning` plugin adds automatic Plan-mode review. **Requirements:** @@ -307,7 +298,7 @@ cp -r plugins/codex/skills/revdiff-plan ~/.codex/skills/revdiff-plan - Codex treats exit code `10` as success-with-annotations and keeps captured output - Automatic review uses the opt-in `revdiff-planning` plugin; `/revdiff-plan` remains a manual fallback - Scripts are portable copies from the Claude Code plugin, not symlinks -- Plugin source lives under `plugins/codex/` in the repository +- Codex plugin source lives under `plugins/codex/` in the repository ### Integration with Other Tools diff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.json new file mode 100644 index 00000000..88076f78 --- /dev/null +++ b/plugins/codex/.codex-plugin/plugin.json @@ -0,0 +1,37 @@ +{ + "name": "revdiff", + "version": "0.8.23", + "description": "Review diffs, files, and documents with inline annotations in a TUI overlay", + "author": { + "name": "Umputun", + "url": "https://github.com/umputun" + }, + "homepage": "https://revdiff.com", + "repository": "https://github.com/umputun/revdiff", + "license": "MIT", + "keywords": [ + "code-review", + "diff", + "annotations", + "tui" + ], + "skills": "./skills/", + "interface": { + "displayName": "RevDiff", + "shortDescription": "Review diffs and plans with inline annotations", + "longDescription": "Review diffs, files, documents, and Codex responses in RevDiff, return line-level annotations to Codex, and repeat until the review is complete.", + "developerName": "Umputun", + "category": "Developer Tools", + "capabilities": [ + "Interactive", + "Read", + "Write" + ], + "websiteURL": "https://revdiff.com", + "defaultPrompt": [ + "Review my current changes in RevDiff", + "Open this file in RevDiff", + "Review the last Codex response" + ] + } +} diff --git a/plugins/codex/README.md b/plugins/codex/README.md index eb02a044..d8674acd 100644 --- a/plugins/codex/README.md +++ b/plugins/codex/README.md @@ -18,35 +18,15 @@ This directory contains the **Codex CLI** skills for revdiff. ## Install -Install automatic Plan-mode review as an opt-in plugin: +Add the marketplace and install both plugins: ```bash codex plugin marketplace add umputun/revdiff +codex plugin add revdiff@revdiff codex plugin add revdiff-planning@revdiff ``` -Start a new session and trust the hook through `/hooks`. It runs only in Plan mode and first checks the current Stop payload's `last_assistant_message`. If that field has no complete ``, the hook reads the exact event transcript and selects the last assistant message for the matching session and turn, regardless of provider-specific phase fields. Annotated revisions use rolling snapshot comparisons; `/revdiff-plan` below remains the manual fallback. - -Install the manual skills by cloning the repository first: - -```bash -git clone https://github.com/umputun/revdiff.git -cd revdiff -``` - -Then copy each skill to your Codex skills directory: - -```bash -cp -r plugins/codex/skills/revdiff ~/.codex/skills/revdiff -cp -r plugins/codex/skills/revdiff-plan ~/.codex/skills/revdiff-plan -``` - -Alternatively, symlink them so `git pull` updates propagate without re-copying: - -```bash -ln -s "$PWD/plugins/codex/skills/revdiff" ~/.codex/skills/revdiff -ln -s "$PWD/plugins/codex/skills/revdiff-plan" ~/.codex/skills/revdiff-plan -``` +The `revdiff` plugin installs the manual `/revdiff` and `/revdiff-plan` skills. The separate `revdiff-planning` plugin adds automatic Plan-mode review. Start a new session and trust its hook through `/hooks`. It runs only in Plan mode and first checks the current Stop payload's `last_assistant_message`. If that field has no complete ``, the hook reads the exact event transcript and selects the last assistant message for the matching session and turn, regardless of provider-specific phase fields. Annotated revisions use rolling snapshot comparisons; `/revdiff-plan` remains the manual fallback. ## Skills @@ -78,7 +58,7 @@ The skill reads `~/.codex/sessions/` rollout JSONL files, extracts the most rece - Automatic review uses a Codex `Stop` hook; Claude Code uses `PreToolUse/ExitPlanMode` - The automatic hook falls back whenever `last_assistant_message` lacks a complete plan, then uses the last assistant message for the exact transcript/session/turn; manual `/revdiff-plan` uses best-effort rollout discovery -- Script path resolution falls back to `$CODEX_HOME` (or `~/.codex`) instead of `$CLAUDE_SKILL_DIR` +- Script path resolution derives the installed plugin root from each skill's absolute catalogue path - `AskUserQuestion` tool replaced with numbered-list prompts (Codex convention) - `EnterPlanMode` replaced with inline markdown plan + confirmation prompt diff --git a/plugins/codex/skills/revdiff-plan/SKILL.md b/plugins/codex/skills/revdiff-plan/SKILL.md index 27cc2784..436c3733 100644 --- a/plugins/codex/skills/revdiff-plan/SKILL.md +++ b/plugins/codex/skills/revdiff-plan/SKILL.md @@ -1,7 +1,6 @@ --- name: revdiff-plan description: Review the last Codex assistant message (plan, analysis, or proposal) with inline annotations in a TUI overlay. Extracts the most recent response from Codex rollout files and opens it in revdiff for review and annotation. Activates on "revdiff-plan", "review plan with revdiff", "annotate plan", "review last response", "annotate codex output". -argument-hint: 'none' allowed-tools: [Bash, Read, Edit, Write, Grep, Glob] --- @@ -11,25 +10,19 @@ Review the last Codex assistant message with inline annotations using revdiff TU ## Script Path Resolution -Resolve the script directory using repo root first, then fall back to Codex home: +Resolve `` from this skill's absolute path in the available-skills catalogue. It is the directory containing this plugin's `.codex-plugin/plugin.json`. Then set: ```bash -SCRIPT_DIR="$(git rev-parse --show-toplevel 2>/dev/null)/plugins/codex/skills/revdiff-plan/scripts" -if [ ! -d "$SCRIPT_DIR" ]; then - SCRIPT_DIR="${CODEX_HOME:-$HOME/.codex}/skills/revdiff-plan/scripts" -fi +SCRIPT_DIR="/skills/revdiff-plan/scripts" ``` Also resolve the launcher script from the revdiff skill: ```bash -LAUNCHER_DIR="$(git rev-parse --show-toplevel 2>/dev/null)/plugins/codex/skills/revdiff/scripts" -if [ ! -d "$LAUNCHER_DIR" ]; then - LAUNCHER_DIR="${CODEX_HOME:-$HOME/.codex}/skills/revdiff/scripts" -fi +LAUNCHER_DIR="/skills/revdiff/scripts" ``` -Use `$SCRIPT_DIR` and `$LAUNCHER_DIR` in place of script paths throughout this skill. +Replace `` with the resolved absolute path before running either command. Use `$SCRIPT_DIR` and `$LAUNCHER_DIR` in place of script paths throughout this skill. ## Activation Triggers diff --git a/plugins/codex/skills/revdiff/SKILL.md b/plugins/codex/skills/revdiff/SKILL.md index 8c4736c5..992a9c0b 100644 --- a/plugins/codex/skills/revdiff/SKILL.md +++ b/plugins/codex/skills/revdiff/SKILL.md @@ -1,7 +1,6 @@ --- name: revdiff -description: Review diffs, files, and documents with inline annotations in a TUI overlay, or answer questions about revdiff usage, configuration, themes, and keybindings. Opens revdiff in agterm/tmux/zellij/herdr/kitty/wezterm/cmux/ghostty/iterm2/emacs-vterm, captures annotations, and addresses them. Works in git, hg, and jj repos (auto-detected). Activates on "revdiff", "review diff", "review changes", "annotate diff", "git review with revdiff", "hg review with revdiff", "review jj change", "interactive diff review", "revdiff all files", "review all files", "browse all files", "revdiff ", "revdiff README.md", "revdiff /tmp/notes.txt", "review this file", "annotate this file", "review file with revdiff", "open this review in revdiff", "show review in revdiff", "review in revdiff", "revdiff config", "revdiff themes", "revdiff keybindings", "how to configure revdiff", "what themes does revdiff have". -argument-hint: 'optional: ref(s), "all files", or file path' +description: Review diffs, files, and documents with inline annotations in a TUI overlay, or answer questions about revdiff usage, configuration, themes, and keybindings. Opens revdiff in agterm/tmux/zellij/herdr/kitty/wezterm/cmux/ghostty/iterm2/emacs-vterm, captures annotations, and addresses them. Works in git, hg, and jj repos (auto-detected). Activates on "revdiff", "review diff", "review changes", "annotate diff", "git review with revdiff", "hg review with revdiff", "review jj change", "interactive diff review", "revdiff all files", "review all files", "browse all files", "revdiff FILE", "revdiff README.md", "revdiff /tmp/notes.txt", "review this file", "annotate this file", "review file with revdiff", "open this review in revdiff", "show review in revdiff", "review in revdiff", "revdiff config", "revdiff themes", "revdiff keybindings", "how to configure revdiff", "what themes does revdiff have". allowed-tools: [Bash, Read, Edit, Write, Grep, Glob] --- @@ -11,18 +10,15 @@ Review diffs with inline annotations using revdiff TUI in a terminal overlay. Wo ## Script Path Resolution -Resolve the script directory using repo root first, then fall back to Codex home: +Resolve `` from this skill's absolute path in the available-skills catalogue. It is the directory containing this plugin's `.codex-plugin/plugin.json`. Then set: ```bash -SCRIPT_DIR="$(git rev-parse --show-toplevel 2>/dev/null)/plugins/codex/skills/revdiff/scripts" -if [ ! -d "$SCRIPT_DIR" ]; then - SCRIPT_DIR="${CODEX_HOME:-$HOME/.codex}/skills/revdiff/scripts" -fi +SCRIPT_DIR="/skills/revdiff/scripts" ``` -Use `$SCRIPT_DIR` in place of script paths throughout this skill. +Replace `` with the resolved absolute path before running the command. Use `$SCRIPT_DIR` in place of script paths throughout this skill. -**Note**: the launcher override chain (user via `${CLAUDE_PLUGIN_DATA}` → bundled) is Claude-only — codex users customize the launcher by editing `~/.codex/skills/revdiff/scripts/launch-revdiff.sh` directly. +**Note**: the launcher override chain (user via `${CLAUDE_PLUGIN_DATA}` → bundled) is Claude-only. Codex users can customize the launcher in a local marketplace checkout and reinstall the plugin. ## Activation Triggers diff --git a/plugins/codex/skills/revdiff/references/install.md b/plugins/codex/skills/revdiff/references/install.md index da1e7ede..fc911876 100644 --- a/plugins/codex/skills/revdiff/references/install.md +++ b/plugins/codex/skills/revdiff/references/install.md @@ -9,7 +9,14 @@ brew install umputun/apps/revdiff ## Codex Plugin -Install the revdiff Codex plugin from the marketplace or manually copy the `plugins/codex/` directory to your Codex plugins location. +Install the revdiff Codex plugin from the marketplace: + +```bash +codex plugin marketplace add umputun/revdiff +codex plugin add revdiff@revdiff +``` + +The plugin provides both `/revdiff` and `/revdiff-plan`. Install `revdiff-planning@revdiff` separately for automatic Plan-mode review. Use: `/revdiff [base] [against]` — opens review session in a terminal overlay (tmux, Zellij, herdr, kitty, wezterm, cmux, ghostty, iTerm2, or Emacs vterm). The bundled launcher sets `REVDIFF_EXIT_CODE_ON_ANNOTATIONS`; exit `10` is success-with-annotations, not launcher failure. diff --git a/site/docs.html b/site/docs.html index d497282a..2de0817f 100644 --- a/site/docs.html +++ b/site/docs.html @@ -779,19 +779,13 @@

Custom launchers

Codex plugin

revdiff ships with a Codex CLI plugin for interactive diff review and plan annotation directly from a Codex session.

-

Install automatic Plan-mode review:

+

Add the marketplace and install the diff-review skills and automatic Plan-mode review:

codex plugin marketplace add umputun/revdiff +codex plugin add revdiff@revdiff codex plugin add revdiff-planning@revdiff

Start a new session and trust the hook through /hooks. The hook runs only in Plan mode and first checks that session's last_assistant_message. Whenever no complete <proposed_plan> is present, it reads the exact event transcript and selects the last assistant message for the matching session and turn without requiring a provider-specific phase. Clarifications are ignored; missing or mismatched event data, dependencies, and launcher failures warn and fail open.

Annotated revisions include a guarded snapshot marker on the first line inside <proposed_plan>, so later rounds open a rolling compare. Reviewed snapshots are replaced and a clean review removes the final snapshot.

-

Install the manual skills:

-
# clone the repo first -git clone https://github.com/umputun/revdiff.git -cd revdiff - -# copy skills to Codex skills directory -cp -r plugins/codex/skills/revdiff ~/.codex/skills/revdiff -cp -r plugins/codex/skills/revdiff-plan ~/.codex/skills/revdiff-plan
+

The revdiff plugin installs both interactive skills. The separate revdiff-planning plugin adds automatic Plan-mode review.

Requirements: revdiff binary on PATH, jq (only for manual /revdiff-plan), and a supported terminal multiplexer.

Skills

diff --git a/site/index.html b/site/index.html index 56f98f1d..c2888c02 100644 --- a/site/index.html +++ b/site/index.html @@ -439,7 +439,7 @@

Codex plugin

1

Install

-
git clone https://github.com/umputun/revdiff.git
cd revdiff
cp -r plugins/codex/skills/revdiff ~/.codex/skills/revdiff
cp -r plugins/codex/skills/revdiff-plan ~/.codex/skills/revdiff-plan
+
codex plugin marketplace add umputun/revdiff
codex plugin add revdiff@revdiff
codex plugin add revdiff-planning@revdiff
diff --git a/site/llms.txt b/site/llms.txt index 7608755f..f494c627 100644 --- a/site/llms.txt +++ b/site/llms.txt @@ -8,7 +8,7 @@ revdiff is a terminal-based UI for code review and document annotation. It displ - Code review for AI agents: revdiff is the human review layer in AI coding sessions - Code review for Claude Code: ships as a Claude Code plugin with terminal overlay support -- Code review for Codex: ships as a Codex CLI skill with the same workflow +- Code review for Codex: ships as a Codex CLI plugin with the same workflow - Code review for OpenCode: integration via /revdiff command and tool call - Plan review: separate plugins for annotating implementation plans before approval - General file annotation: browse and annotate any file, not just version-controlled diffs @@ -58,7 +58,7 @@ The plugin supports a full review loop: annotate -> Claude plans fixes -> Claude ## Codex Plugin -Skills installed under ~/.codex/skills/revdiff and ~/.codex/skills/revdiff-plan. Same /revdiff workflow as Claude Code, plus /revdiff-plan which extracts the last Codex assistant message for annotation. +Install with `codex plugin marketplace add umputun/revdiff` and `codex plugin add revdiff@revdiff`. The plugin provides the same /revdiff workflow as Claude Code, plus /revdiff-plan which extracts the last Codex assistant message for annotation. ## OpenCode Integration From 3f773ccd925bce97db85e59d13d1e55c1c0dfbfa Mon Sep 17 00:00:00 2001 From: Dmitry Verkhoturov Date: Wed, 2 Sep 2026 01:27:59 +0200 Subject: [PATCH 2/3] fix(codex): align release metadata and migration docs Document the four plugin manifests that must stay aligned with their marketplace entries. Remove unsupported `allowed-tools` frontmatter from both Codex skills and tell manual-install users to remove the superseded skill directories after plugin installation. --- CLAUDE.md | 2 +- README.md | 2 ++ plugins/codex/README.md | 2 ++ plugins/codex/skills/revdiff-plan/SKILL.md | 1 - plugins/codex/skills/revdiff/SKILL.md | 1 - plugins/codex/skills/revdiff/references/install.md | 2 ++ site/docs.html | 1 + site/llms.txt | 2 +- 8 files changed, 9 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index cce144c0..dbdcf0c4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -62,7 +62,7 @@ TUI for reviewing diffs, files, and documents with inline annotations, built wit - Plugin lives at `.claude-plugin/` with `plugin.json`, `marketplace.json`, and `skills/` - Skills path in `plugin.json` is relative to repo root, not to `.claude-plugin/` - **CRITICAL: Version bumps happen at release only — never per-PR or per-change.** Do NOT prompt to bump `plugin.json` / `marketplace.json` after a plugin file change; the bump is done as part of the release process. -- When bumping at release, keep each marketplace entry synchronized with its plugin manifest. For `revdiff-planning`, update both `.claude-plugin/plugin.json` and `.codex-plugin/plugin.json` plus its version in `.claude-plugin/marketplace.json`. +- When bumping at release, keep every marketplace entry synchronized with its plugin manifests. For `revdiff`, update `.claude-plugin/plugin.json`, `plugins/codex/.codex-plugin/plugin.json`, and its version in `.claude-plugin/marketplace.json`. For `revdiff-planning`, update `plugins/revdiff-planning/.claude-plugin/plugin.json`, `plugins/revdiff-planning/.codex-plugin/plugin.json`, and its version in `.claude-plugin/marketplace.json`. - **CRITICAL: Defer plugin version bumps when the change depends on a new binary feature.** If a plugin/launcher change relies on a `revdiff` binary feature, flag, env var, or exit code that is not yet in a tagged release, do NOT bump `plugin.json` / `marketplace.json` / `package.json` on the feature branch. The plugin (marketplace) and the binary (brew / `go install`) version independently — bumping the plugin early ships an updated launcher to users still running an old binary, causing a hard mismatch (e.g. the launcher passes an unknown flag, the old binary exits 1, every plugin-triggered review fails). Bump plugin/package versions as part of the binary version release, after the binary is tagged. - Reference docs at `.claude-plugin/skills/revdiff/references/` — keep in sync with README.md: - `install.md` — installation methods and plugin setup diff --git a/README.md b/README.md index 89f6d543..4c314fb8 100644 --- a/README.md +++ b/README.md @@ -281,6 +281,8 @@ codex plugin add revdiff@revdiff codex plugin add revdiff-planning@revdiff ``` +If you previously copied the skills manually, remove `~/.codex/skills/revdiff` and `~/.codex/skills/revdiff-plan` after installing the plugin so the plugin copy is the only one in use. + Start a new session and trust the plugin hook through `/hooks`. The `Stop` hook runs only in Plan mode and first checks `last_assistant_message`; whenever that field has no complete ``, it reads the exact event transcript and selects the last assistant message for the matching `session_id` and `turn_id`, without depending on a provider-specific phase. A readable clarification turn is ignored. Missing or mismatched event data, dependencies, and launcher failures warn and fail open. When annotations are present, the hook asks Codex to return the complete revised plan with a snapshot marker on the first line inside ``. The next round opens a rolling compare (` `); reviewed snapshots are replaced, and a clean review removes the final snapshot. diff --git a/plugins/codex/README.md b/plugins/codex/README.md index d8674acd..b394c12f 100644 --- a/plugins/codex/README.md +++ b/plugins/codex/README.md @@ -26,6 +26,8 @@ codex plugin add revdiff@revdiff codex plugin add revdiff-planning@revdiff ``` +If you previously copied the skills manually, remove `~/.codex/skills/revdiff` and `~/.codex/skills/revdiff-plan` after installing the plugin so the plugin copy is the only one in use. + The `revdiff` plugin installs the manual `/revdiff` and `/revdiff-plan` skills. The separate `revdiff-planning` plugin adds automatic Plan-mode review. Start a new session and trust its hook through `/hooks`. It runs only in Plan mode and first checks the current Stop payload's `last_assistant_message`. If that field has no complete ``, the hook reads the exact event transcript and selects the last assistant message for the matching session and turn, regardless of provider-specific phase fields. Annotated revisions use rolling snapshot comparisons; `/revdiff-plan` remains the manual fallback. ## Skills diff --git a/plugins/codex/skills/revdiff-plan/SKILL.md b/plugins/codex/skills/revdiff-plan/SKILL.md index 436c3733..0b3e0159 100644 --- a/plugins/codex/skills/revdiff-plan/SKILL.md +++ b/plugins/codex/skills/revdiff-plan/SKILL.md @@ -1,7 +1,6 @@ --- name: revdiff-plan description: Review the last Codex assistant message (plan, analysis, or proposal) with inline annotations in a TUI overlay. Extracts the most recent response from Codex rollout files and opens it in revdiff for review and annotation. Activates on "revdiff-plan", "review plan with revdiff", "annotate plan", "review last response", "annotate codex output". -allowed-tools: [Bash, Read, Edit, Write, Grep, Glob] --- # revdiff-plan - Review Codex Output diff --git a/plugins/codex/skills/revdiff/SKILL.md b/plugins/codex/skills/revdiff/SKILL.md index 992a9c0b..b238e54c 100644 --- a/plugins/codex/skills/revdiff/SKILL.md +++ b/plugins/codex/skills/revdiff/SKILL.md @@ -1,7 +1,6 @@ --- name: revdiff description: Review diffs, files, and documents with inline annotations in a TUI overlay, or answer questions about revdiff usage, configuration, themes, and keybindings. Opens revdiff in agterm/tmux/zellij/herdr/kitty/wezterm/cmux/ghostty/iterm2/emacs-vterm, captures annotations, and addresses them. Works in git, hg, and jj repos (auto-detected). Activates on "revdiff", "review diff", "review changes", "annotate diff", "git review with revdiff", "hg review with revdiff", "review jj change", "interactive diff review", "revdiff all files", "review all files", "browse all files", "revdiff FILE", "revdiff README.md", "revdiff /tmp/notes.txt", "review this file", "annotate this file", "review file with revdiff", "open this review in revdiff", "show review in revdiff", "review in revdiff", "revdiff config", "revdiff themes", "revdiff keybindings", "how to configure revdiff", "what themes does revdiff have". -allowed-tools: [Bash, Read, Edit, Write, Grep, Glob] --- # revdiff - TUI Diff Review diff --git a/plugins/codex/skills/revdiff/references/install.md b/plugins/codex/skills/revdiff/references/install.md index fc911876..935ca56f 100644 --- a/plugins/codex/skills/revdiff/references/install.md +++ b/plugins/codex/skills/revdiff/references/install.md @@ -16,6 +16,8 @@ codex plugin marketplace add umputun/revdiff codex plugin add revdiff@revdiff ``` +If you previously copied the skills manually, remove `~/.codex/skills/revdiff` and `~/.codex/skills/revdiff-plan` after installing the plugin so the plugin copy is the only one in use. + The plugin provides both `/revdiff` and `/revdiff-plan`. Install `revdiff-planning@revdiff` separately for automatic Plan-mode review. Use: `/revdiff [base] [against]` — opens review session in a terminal overlay (tmux, Zellij, herdr, kitty, wezterm, cmux, ghostty, iTerm2, or Emacs vterm). The bundled launcher sets `REVDIFF_EXIT_CODE_ON_ANNOTATIONS`; exit `10` is success-with-annotations, not launcher failure. diff --git a/site/docs.html b/site/docs.html index 2de0817f..2989be07 100644 --- a/site/docs.html +++ b/site/docs.html @@ -783,6 +783,7 @@

Codex plugin

codex plugin marketplace add umputun/revdiff codex plugin add revdiff@revdiff codex plugin add revdiff-planning@revdiff
+

If you previously copied the skills manually, remove ~/.codex/skills/revdiff and ~/.codex/skills/revdiff-plan after installing the plugin so the plugin copy is the only one in use.

Start a new session and trust the hook through /hooks. The hook runs only in Plan mode and first checks that session's last_assistant_message. Whenever no complete <proposed_plan> is present, it reads the exact event transcript and selects the last assistant message for the matching session and turn without requiring a provider-specific phase. Clarifications are ignored; missing or mismatched event data, dependencies, and launcher failures warn and fail open.

Annotated revisions include a guarded snapshot marker on the first line inside <proposed_plan>, so later rounds open a rolling compare. Reviewed snapshots are replaced and a clean review removes the final snapshot.

The revdiff plugin installs both interactive skills. The separate revdiff-planning plugin adds automatic Plan-mode review.

diff --git a/site/llms.txt b/site/llms.txt index f494c627..908aa688 100644 --- a/site/llms.txt +++ b/site/llms.txt @@ -58,7 +58,7 @@ The plugin supports a full review loop: annotate -> Claude plans fixes -> Claude ## Codex Plugin -Install with `codex plugin marketplace add umputun/revdiff` and `codex plugin add revdiff@revdiff`. The plugin provides the same /revdiff workflow as Claude Code, plus /revdiff-plan which extracts the last Codex assistant message for annotation. +Install with `codex plugin marketplace add umputun/revdiff` and `codex plugin add revdiff@revdiff`. The plugin provides the same /revdiff workflow as Claude Code, plus /revdiff-plan which extracts the last Codex assistant message for annotation. If you previously copied the skills manually, remove `~/.codex/skills/revdiff` and `~/.codex/skills/revdiff-plan` after installing the plugin so the plugin copy is the only one in use. ## OpenCode Integration From 9565a0991d094ade11b92147f805898e254cc6c7 Mon Sep 17 00:00:00 2001 From: Dmitry Verkhoturov Date: Wed, 2 Sep 2026 01:48:22 +0200 Subject: [PATCH 3/3] docs(codex): complete migration guidance Add manual-skill cleanup to the website install section so every published installation surface gives the same migration instruction. --- site/index.html | 1 + 1 file changed, 1 insertion(+) diff --git a/site/index.html b/site/index.html index c2888c02..de3b5560 100644 --- a/site/index.html +++ b/site/index.html @@ -440,6 +440,7 @@

Codex plugin

Install

codex plugin marketplace add umputun/revdiff
codex plugin add revdiff@revdiff
codex plugin add revdiff-planning@revdiff
+

If you previously copied the skills manually, remove ~/.codex/skills/revdiff and ~/.codex/skills/revdiff-plan after installing the plugin so the plugin copy is the only one in use.