refine-plan

Automates iterative plan review and edit cycles via a plan-refiner subagent until approval.

Updated May 19, 2026
One-click install
npx skills add https://github.com/davidsunglee/pi-flow --skill refine-plan-davidsunglee
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: refine-plan
Source: https://github.com/davidsunglee/pi-flow/tree/main/packages/pi-flow-core/skills/refine-plan
Command: npx skills add https://github.com/davidsunglee/pi-flow --skill refine-plan-davidsunglee

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Written implementation plans often drift from their source spec or idea, and manually reviewing and revising them across multiple rounds is slow and inconsistent. This Skill automates the review-edit loop for a plan file, dispatching a plan-refiner subagent that alternates between reviewing and editing until the plan is approved or the iteration budget is exhausted. ## Core Features & Use Cases - Iterative review-edit loop: Dispatches a plan-refiner subagent that runs plan-reviewer and planner edit passes across bounded iterations, with provenance-stamped review files per era. - Provenance and coverage gating: Auto-discovers the source spec, idea, and scout brief from the plan preamble, and requires a coverage source (task artifact or inline description) unless structural-only mode is enabled. - Commit gate ownership: On approval, optionally commits the plan plus review artifacts via the commit skill; on budget exhaustion, presents continue/save/stop choices. - Use Case: After generating an implementation plan from a spec, run this Skill to have it reviewed against the spec, automatically revised through blocking findings, and committed once approved. ## Quick Start Run the refine-plan skill on docs/plans/my-feature-plan.md to review and refine it against its source spec until approved.

Frequently Asked Questions about refine-plan

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I refine an implementation plan automatically?▼

Invoke the refine-plan skill with the path to your plan file. It dispatches a plan-refiner subagent that alternates between plan-reviewer and planner edit passes until the plan is approved or the iteration budget runs out.

How does plan review coverage checking work?▼

The skill auto-discovers the source spec, idea, and scout brief from the plan preamble, then requires a coverage source: an on-disk task artifact or an inline task description. Without one, you must pass --structural-only to opt in to a coverage-blind review.

Can I use refine-plan without a git repository?▼

No. The skill requires a git repository because it owns the commit gate for plan and review artifacts. If git rev-parse --git-dir fails, it stops immediately with an error.

What happens when the plan is not approved within budget?▼

You get three choices: continue refining into a new era with a fresh budget after committing the current era, save the plan for manual review with artifacts committed, or stop execution leaving everything uncommitted on disk.

Why does refine-plan fail after the reviewer approves a plan?▼

Approval is gated by mechanical checks: review provenance validation and an executable-plan parseability guardrail using the same parser execute-plan uses. If the approved plan is not parseable, the status is downgraded to failed with the parser's error.