Plan Refiner Skill

This skill implements an iterative plan refinement process that transforms an initial specification into a polished implementation plan through multiple review passes with fresh agent perspective.

Workflow Overview

Input: initial_spec.md (starting prompt/requirements)
         ↓
Step 1: Generate Initial Plan (plan.md v0)
         ↓
Step 2: Review Loop (minimum 3 passes)
  - Spawn fresh review agent with spec + clarifications + plan
  - Agent provides feedback + identifies critical assumptions
  - Agent verifies versions/APIs against live docs via Context7
  - Surface identified issues and assumptions to user
  - Prompt user for optional additional feedback
  - Apply all feedback to plan
  - After pass 3+, ask user to continue or finalize
         ↓
Output: Final plan.md + clarifications.md + audit trail

Note: Review agents use Context7 (mcp__context7__resolve-library-id → mcp__context7__query-docs) to verify that any package versions, GitHub Actions, APIs, or framework versions mentioned in the plan are current. This prevents recommending outdated versions based on training data.

Fallback: If Context7 MCP tools are unavailable, install the context7 skill which provides equivalent functionality via HTTP API.

Input Requirements

The user must provide an initial specification or prompt. This can be:

A file path to an existing spec document
Text content to save as initial_spec.md
A description of what they want to plan

Working Directory Structure

Create a namespaced directory under Claude's plan directory:

~/.claude/plans/plan-refiner/{spec-slug}/
├── initial_spec.md           # The starting requirements (immutable)
├── plan.md                   # Current plan (updated each pass)
├── clarifications.md         # Accumulated Q&A and user feedback
├── config.json               # Run configuration (includes custom_reviewer settings)
├── audit/
│   ├── plan_v0.md            # Initial plan from spec
│   ├── plan_v1.md            # After pass 1
│   ├── plan_v2.md            # After pass 2
│   └── plan_v3.md            # After pass 3, etc.
├── pass_N_feedback.md        # Default review feedback for each pass
└── pass_N_custom_feedback.md # Custom review feedback (if custom reviewer enabled)

Global Preferences

~/.claude/plans/plan-refiner/
└── preferences.json          # Global preferences across all runs

Spec Slug Generation:

From file path: Use filename without extension (e.g., my-feature.md → my-feature)
From content: Slugify first heading or first line (e.g., "Auth Feature Spec" → auth-feature-spec)
Add timestamp suffix if directory exists: my-feature-20260128

Context Preservation Strategy

To preserve orchestrator context across multiple passes, this skill uses file-based delegation:

Subagents read from files - Don't embed full content in prompts; tell subagents which files to read
Subagents write to files - Feedback and plan updates go directly to disk
Summaries only returned - Subagents return brief summaries, not full content
Orchestrator stays thin - Main agent manages paths and workflow, not content

Drift Mitigation: Spec-Always-Included

To prevent drift from the original specification:

All subagents always re-read initial_spec.md before performing their task
Review agents explicitly check spec alignment and flag drift in their feedback
Update agents verify changes align with spec before writing
Summaries include alignment status (e.g., "Aligned" or "Warning: divergence detected")

Startup Configuration

Before beginning refinement, ask about optional custom review.

Startup Questions

Question 1: Custom Reviewer

Check for ~/.claude/plans/plan-refiner/preferences.json:

If preferences.json exists and has a previous custom_reviewer:

Ask: "Last time you used '{skill-name}' as additional reviewer. Use it again?"
Options: Yes / No / Different skill

Otherwise:

Ask: "Add a custom review agent for specialized feedback? (e.g., security, performance)"
Options: No (default only) / Yes, specify skill

Question 2: Skill Specification (if yes to custom reviewer)

Ask: "Specify the custom review skill:"

Skill name (e.g., 'security-reviewer')
Skill path (absolute path)
Skip (use default only)

Also ask for the focus description (e.g., "security considerations", "performance optimization", "accessibility compliance").

Preferences Persistence

Store in ~/.claude/plans/plan-refiner/preferences.json:

{
  "custom_reviewer": {
    "enabled": true,
    "type": "skill_name",
    "value": "security-reviewer",
    "focus": "security considerations"
  },
  "custom_reviewer_history": ["security-reviewer", "performance-reviewer"],
  "updated_at": "2026-01-28T..."
}

custom_reviewer: Current configuration (or null if disabled)
custom_reviewer_history: Previously used skills (for suggestions)
updated_at: Last modification timestamp

Execution Steps

Step 1: Setup and Initial Plan Generation

Generate spec slug from input (filename or content title)
Create namespaced directory at ~/.claude/plans/plan-refiner/{spec-slug}/
- If directory exists, append timestamp suffix (e.g., -20260128)
Save or verify initial_spec.md from user input
Create clarifications.md (empty initially)
Create audit/ directory

Create config.json with run configuration:

{
  "created_at": "2026-01-28T...",
  "custom_reviewer": {
    "enabled": true,
    "type": "skill_name",
    "value": "security-reviewer",
    "focus": "security considerations"
  },
  "current_pass": 0,
  "status": "in_progress"
}

Set custom_reviewer to null if not configured

Spawn Plan Generation Agent to create initial plan:
- Use Task tool with subagent_type: general-purpose
- Provide file paths (not contents): initial_spec.md, plan.md, audit/plan_v0.md
- Agent reads spec, writes plan to both locations
- Agent returns: brief summary of plan structure (not full content)
- See references/generation-prompt.md for the prompt template

Step 2: Review Loop (Minimum 3 Passes)

For each pass (1, 2, 3, ...):

2a. Spawn Default Review Agent

Use the Task tool with subagent_type: general-purpose to create a fresh agent context.

Important: Do NOT use subagent_type: Plan as it triggers plan mode behavior and will prompt to execute instead of returning feedback.

Prompt the agent with file paths, not contents:

Path to initial_spec.md (agent reads it - source of truth)
Path to clarifications.md (agent reads it)
Path to plan.md (agent reads it)
Current pass number
Path to write feedback: pass_N_feedback.md
Review instructions from references/review-prompt.md

Agent responsibilities:

Read all input files (always starting with spec)
Verify plan alignment with original spec
Perform review
Write detailed feedback to pass_N_feedback.md
Return ONLY: alignment status + summary of issues + critical assumption questions

2a-bis. Spawn Custom Review Agent (if configured)

If config.json has custom_reviewer.enabled: true:

Spawn Custom Review Sub-Agent via Task tool:
- subagent_type: general-purpose
- Provide file paths:
  - Spec path: initial_spec.md
  - Plan path: plan.md
  - Default feedback path: pass_N_feedback.md
- Output path: pass_N_custom_feedback.md
- Use prompt template from references/custom-review-prompt.md
- Inject the custom focus from config (e.g., "security considerations")
Process Custom Review Summary:
- Custom agent returns: focus area + additional issue count + additional questions + assessment
- Additional issues are written to pass_N_custom_feedback.md
Merge Feedback for Processing:
- Default feedback: pass_N_feedback.md
- Custom feedback: pass_N_custom_feedback.md
- Both files remain separate for audit purposes
- Combined questions from both reviews are surfaced to user in step 2c
- Update total issue count in summaries

If custom reviewer skill not found: Log warning and continue with default review only.

2b. Process Agent Summary

The review agent returns a brief summary (not full feedback):

Alignment Status: "Aligned" or "Warning: [drift description]"
Issue Count: Number of issues found
Critical Assumptions: Questions requiring user input

Full feedback is already saved to pass_N_feedback.md by the agent.

If alignment warning received: Surface to user via AskUserQuestion before proceeding.

2b-bis. Surface Issues to User

After processing the agent summary, read feedback file(s) and display identified issues:

Read feedback files:
- Read pass_N_feedback.md for default review issues
- If custom reviewer enabled, also read pass_N_custom_feedback.md
Extract issues from the "Plan Feedback" section:
- Parse each ### Issue N: block (or #### Issue N: for custom feedback)
- Extract: title, location, problem, suggestion
Display issues to the user before asking questions:

## Pass {N} Review Findings

### Issues Identified ({count} total)

**Issue 1: {title}**
- Location: {location}
- Problem: {description}
- Suggestion: {recommendation}

**Issue 2: {title}**
...

[If custom reviewer enabled:]
### Additional Issues from {custom_focus} Review ({count})

**Issue 1: {title}**
...

If no issues found, display: "No issues identified in this pass."

2c. Surface Questions to User

If the agent identified critical assumptions:

Use AskUserQuestion to present each question
Append user answers to clarifications.md with format:

## Pass N Clarifications

**Q: [Question from agent]**
A: [User's answer]

2d. Prompt for Additional User Feedback

After answering questions, ask the user: "Do you have any additional feedback on the current plan? (You can skip this)"

If user provides feedback:

Append to clarifications.md:

### User Feedback (Pass N)
[User's feedback]

2e. Apply Feedback via Subagent

Spawn a Plan Update Agent (subagent_type: general-purpose):

Provide file paths:

Path to initial_spec.md (source of truth)
Path to plan.md (current version)
Path to pass_N_feedback.md (agent feedback)
Path to clarifications.md (includes user answers)
Path to write: audit/plan_v{pass}.md (backup) and updated plan.md
Update instructions from references/update-prompt.md

Agent responsibilities:

Read spec, current plan, feedback, and clarifications
Verify changes align with original spec
Incorporate all feedback and user clarifications
Write updated plan to plan.md
Copy to audit/plan_v{pass}.md
Return ONLY: alignment status + 2-3 sentence summary of changes

If alignment warning received: Surface to user via AskUserQuestion: "The update agent detected potential drift: [warning]. Continue with changes or revert?"

2f. Continuation Check (After Pass 3+)

After pass 3 and each subsequent pass, ask the user: "Would you like to continue refining the plan, or is it ready?"

Options:

Continue: Proceed to next pass
Finalize: Exit loop with current plan

Step 3: Finalization

Present the user with:

Final plan.md location
Summary of changes across all passes
Location of audit trail

Subagent Prompt Templates

See the following templates in references/:

generation-prompt.md - Initial plan generation agent
review-prompt.md - Default review agents for each pass
custom-review-prompt.md - Custom review agents (supplementary, specialized feedback)
update-prompt.md - Plan update agent after feedback

Pass Focus Areas

Each pass has a primary focus while still reviewing the full plan:

| Pass | Primary Focus | |------|---------------| | 1 | Alignment with spec, surface major assumptions | | 2 | Completeness and feasibility, clarify remaining gaps, version verification via Context7 | | 3+ | Final polish, coherence, edge cases |

Example Invocation

User: "Run /plan-refiner on my feature spec"

Agent asks for spec location or content
Agent generates spec slug (e.g., my-feature from my-feature.md)
Agent creates directory at ~/.claude/plans/plan-refiner/my-feature/ and saves spec
Agent generates initial plan (v0)
Agent runs 3 review passes with fresh context
After pass 3, agent asks to continue or finalize
Agent presents final plan location and audit trail

Key Principles

Fresh Perspective: Each review pass uses a new agent with no accumulated context bias
User in the Loop: Critical assumptions require user clarification before proceeding
Audit Trail: Every plan version is preserved for reference
Accumulated Context: Clarifications (Q&A + feedback) persist across all passes
Flexible Iteration: Minimum 3 passes, but user controls when to stop