refined-plan-mode

Refined Plan Mode

Refined Plan Mode is a local web app for reviewing AI coding-agent plans with a pull-request-style feedback loop.

Instead of reviewing a long plan in a terminal and replying with one unanchored message, you can open the plan in a browser, leave comments on specific lines, ranges, or selected text, and submit the feedback as structured JSON for the agent to consume.

https://github.com/user-attachments/assets/0a351cd8-94b2-44d7-9f5f-78aeb43a5314

Current Status

This is an MVP built for local use. The core review loop works:

• read a versioned Markdown plan from .plan-review/plans/
• view the plan as Markdown source in CodeMirror
• add line, range, and text-selection comments
• persist draft comments across reloads
• submit feedback as JSON
• approve a plan and copy it to .plan-review/approved-plan.md

Quick Start

Refined Plan Mode has two pieces:

• a browser app in this repository for reviewing plan files
• Codex and Claude Code plugins that keep the plan review loop consistent

Install the plugin for your coding-agent harness. Then run this browser app against the target workspace's .plan-review directory.

1. Install the plugin

Claude Code

Claude Code can install Refined Plan Mode directly from this GitHub repository because it includes a root marketplace at:

.claude-plugin/marketplace.json

From Claude Code, add the marketplace and install the plugin:

/plugin marketplace add schalkneethling/refined-plan-mode
/plugin install refined-plan-mode@refined-plan-mode

Or use the Claude Code CLI:

claude plugin marketplace add schalkneethling/refined-plan-mode
claude plugin install refined-plan-mode@refined-plan-mode

If you are developing locally from a clone, you can also add the repo-local marketplace:

claude plugin marketplace add ./plugins/claude-code
claude plugin install refined-plan-mode@refined-plan-mode

Both marketplaces point at the same Claude Code plugin package:

plugins/claude-code/refined-plan-mode

Codex

This repository includes a repo-local Codex marketplace at:

.agents/plugins/marketplace.json

It points at the local plugin package:

plugins/codex/refined-plan-mode

If you open this repository in Codex, the refined-plan-mode plugin should be available from the repo-local marketplace.

To use the plugin without opening this repository in Codex:

1. Clone or download this repository.
2. Copy or symlink plugins/codex/refined-plan-mode into a local plugin directory such as ~/plugins/refined-plan-mode.
3. Add a home-local Codex marketplace entry in ~/.agents/plugins/marketplace.json that points at ./plugins/refined-plan-mode.

Example home-local Codex marketplace:

{
  "name": "local",
  "interface": {
    "displayName": "Local Plugins"
  },
  "plugins": [
    {
      "name": "refined-plan-mode",
      "source": {
        "source": "local",
        "path": "./plugins/refined-plan-mode"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

After that, install or enable refined-plan-mode from Codex's plugin UI.

2. Use natural prompts

In the target project, ask your agent to use Refined Plan Mode:

Use Refined Plan Mode to plan this change.

After submitting feedback in the browser:

I submitted feedback in Refined Plan Mode. Continue.

After approving the plan:

The plan is approved. Continue with Refined Plan Mode.

The plugin skill inspects .plan-review and chooses the next state transition:

• no current plan: write .plan-review/plans/plan-v1.md, write .plan-review/.current-version, and wait for review
• feedback for the current version: write the next plan version, update .current-version, and wait for review
• current plan without feedback or approval: remind you that the plan is awaiting review
• approved plan: read .plan-review/approved-plan.md and execute it

When a plan is ready for review, the agent should also print the reviewer launch command with PLAN_REVIEW_DIR pointing at the target project's .plan-review directory:

PLAN_REVIEW_DIR=/absolute/path/to/project/.plan-review vp dev --host 127.0.0.1 --port 5173

3. Run the browser reviewer

From this repository, install dependencies and start the app:

vp install
PLAN_REVIEW_DIR=/absolute/path/to/project/.plan-review vp dev --host 127.0.0.1 --port 5173

Open:

http://127.0.0.1:5173/

Review the current plan in the browser. You can leave comments on lines, ranges, or selected text, then submit feedback. The app writes feedback for the current version to:

.plan-review/feedback/plan-v1-feedback.json

Approving a plan writes:

.plan-review/approved-plan.md

4. Continue the loop

The core loop is: