refined-plan-mode

Refined Plan Mode

Use this skill when the user asks to plan, review, revise, continue, checkpoint, handoff, reset, or execute work using Refined Plan Mode.

This skill is additive to the agent's current planning guidance. It turns a plan into a versioned Markdown artifact that can be reviewed with line, range, and text-selection comments. The agent remains responsible for reading feedback, revising the plan, and moving only when the user has approved the plan or explicitly asks to proceed.

Core Protocol

Before deciding what to do, inspect the local .plan-review state:

• .plan-review/.current-version
• .plan-review/approved-plan.md
• .plan-review/plans/
• .plan-review/feedback/

Then choose the next state transition:

1. If .plan-review/approved-plan.md exists, read it and execute the approved plan carefully.
2. If a current version exists and .plan-review/feedback/plan-vN-feedback.json exists for it, read the current plan and feedback, address every feedback item in a revised next plan version, update .plan-review/.current-version, and stop for review.
3. If a current version exists with no feedback and no approval, report that the plan is awaiting review and include the reviewer launch command.
4. If no current plan exists, clarify only what is necessary, inspect the repository enough to produce a useful plan, write .plan-review/plans/plan-v1.md, write v1 to .plan-review/.current-version, and stop for review.

Users can ask for checkpoint, handoff, or reset in natural language:

• For a checkpoint, report the current version, latest plan path, feedback status, approval status, and recommended next action.
• For a handoff, summarize the goal, current plan, feedback status, approval status, important assumptions, unresolved decisions, and recommended next action.
• For a reset, empty only .plan-review while keeping the .plan-review directory itself. Do not remove source files or any other workspace files.

File Convention

.plan-review/
  .current-version
  plans/
    plan-v1.md
    plan-v2.md
  feedback/
    plan-v1-feedback.json
    plan-v2-feedback.json
  approved-plan.md

Create missing directories when needed. Never summarize or truncate the plan file itself. The file should be self-contained enough for another agent to understand the goal, context, constraints, implementation steps, validation steps, and open questions.

Plan Shape

Prefer this structure unless the task clearly calls for something else:

# Plan vN: Short Title

## Goal

## Current Understanding

## Assumptions

## Open Questions

## Proposed Changes

## Validation

## Risks

## Rollback or Recovery

Keep the plan practical. Include file paths, commands, and decision points when known. Call out assumptions explicitly instead of hiding uncertainty inside confident prose.

Reviewer Launch Command

Whenever you write or advance to a plan version that is ready for user review, include a command the user can run from the Refined Plan Mode project root.

Prefer an absolute path to the target project's .plan-review directory when you know it:

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

If only a home-relative path is known, shell expansion is acceptable:

PLAN_REVIEW_DIR=~/dev/target-project/.plan-review vp dev --host 127.0.0.1 --port 5173

Use the toolchain command documented by the Refined Plan Mode project. For the Vite+ project, use vp dev rather than invoking the package manager directly.

Feedback Handling

When feedback exists:

• Read the relevant JSON feedback file before revising.
• Treat every unresolved comment as actionable until clearly addressed.
• Preserve useful parts of the previous plan.
• Add a short Feedback Addressed section to the revised plan that maps comments to the changes made.
• If feedback conflicts or cannot be satisfied safely, explain that in the revised plan and ask the user for the smallest useful decision.

Execution Gate

Do not begin implementation from an unapproved plan unless the user explicitly asks you to proceed. Once .plan-review/approved-plan.md exists or the user directly approves the plan in conversation, execute the approved plan and keep the normal agent workflow: inspect files, make focused edits, validate, and report the outcome.

User Updates

In conversation, keep updates brief:

• Say which plan version was written.
• Say where feedback should be submitted.
• Include the reviewer launch command when a plan is ready for review.
• Say which feedback file was read when revising.
• Say when the plan is approved and execution is beginning.

The plan file carries the detail; the chat message should help the user orient without duplicating the full artifact.