---
name: create-plan
description: >-
  Creates, reviews, and improves implementation-ready plans through pi-subagents
  research, drafting, and iterative independent review. Use this skill when the
  user asks to plan a non-trivial feature or change, prepare an implementation
  handoff, or improve an unimplemented plan. Do not use to implement work, audit
  completed implementation, or answer a small conceptual question that needs no
  durable handoff.
license: MIT
compatibility: >-
  Requires Pi with a compatible pi-subagents extension loaded, a callable
  subagent tool, and executable context-builder, planner, and reviewer agents;
  researcher is required when external research matters. Installation method is
  environment-specific. Saving requires project write access.
metadata:
  short-description: Plan through pi-subagents research and review loops
---

# Create Plan

## Critical rules

- **Plan only.** Never implement or modify implementation files.
- The parent owns scope, user questions, synthesis, dispositions, revisions, readiness, and the final plan.
- Child output is evidence or a draft, never acceptance. Never apply reviewer recommendations automatically.
- Prefer the smallest evidence-backed design. Exclude speculative scope and machinery.
- Ask the user when ambiguity can materially change behavior, scope, architecture, migration, risk, or complexity.
- Write only `.plans/<kebab-name>.md`. Keep child outputs inline and disable run artifacts unless diagnostics require retention.

## Dependency gate

Complete this gate before repository research or drafting:

1. Confirm the active tool set contains `subagent`. If absent, stop and report that `pi-subagents` is missing or inactive. Tell the user to enable it through their existing package-management method and restart Pi. For declarative or Nix-managed installations, require a configuration change and rebuild; never run `pi install`, npm installation, or mutate package configuration automatically.
2. Call `subagent({ action: "doctor" })`; stop on errors that prevent required fresh-context runs or their completion from being observed.
3. Call `subagent({ action: "list" })`; require executable, non-disabled `context-builder`, `planner`, and `reviewer` agents. Require `researcher` when current external evidence can affect the design.
4. Report exact missing capabilities. Do not silently substitute a parent-only or competing subagent workflow.

Before launching any child, read [`references/subagent-plan-loop.md`](references/subagent-plan-loop.md). It defines lane contracts, call shapes, and review closure.

## Workflow

1. **Frame**
   - Read repository instructions, the request, relevant existing plans, and obvious starting files.
   - State the outcome, in-scope behavior, non-goals, constraints, risks, and validation target.
   - Enumerate decision-relevant research questions; avoid deep parent exploration that belongs in a lane.

2. **Load the output contract**
   - Before research synthesis or drafting, read [`assets/implementation-plan-template.md`](assets/implementation-plan-template.md).

3. **Research**
   - Follow `references/subagent-plan-loop.md` and launch fresh-context, read-only `context-builder` lanes for request/scope, codebase/patterns, and validation/risks as warranted.
   - Add `researcher` only for decision-relevant external facts. Require authoritative, version-matched sources.
   - Inspect critical local evidence in the parent. Map each material finding to a decision, task, check, non-goal, or open gate.

4. **Resolve gates**
   - Ask the user about unresolved material questions before treating an answer as fact.
   - Mark the plan `Blocked` when an unanswered gate can change implementation; otherwise continue.

5. **Draft**
   - Give `planner` the resolved contract, distilled evidence, non-goals, and template requirements.
   - Treat its response as a structural draft. The parent verifies claims, removes unsupported scope, and writes `.plans/<kebab-name>.md` with `Draft` status.
   - Prefer flat stable-ID tasks. Use phases only for real sequencing, migration, or release boundaries.

6. **Plan ↔ review loop**
   - Commission fresh-context reviewers with distinct feasibility, validation, and simplicity angles.
   - Disposition every finding as `Accept`, `Validate`, `Reject`, `Ask user`, or `Block`, with a short reason.
   - Revise only accepted or validated findings, then re-review material edits. Continue until all commissioned reviewers report `Clear`.
   - Ask the user after three review rounds, two no-progress rounds, recurring disagreement, or unresolved complexity trade-offs.

7. **Finalize**
   - Before final delivery and after material revisions, read and apply [`references/plan-quality-checklist.md`](references/plan-quality-checklist.md).
   - Set final status to `Ready for implementation` only when no material gate remains; otherwise use `Blocked on <decision>`.
   - Report the plan path, decisions and gates, review closure, validation strategy, fallbacks, and remaining risks.

## Stop conditions

- Missing dependency, template, checklist, or required role: stop and report it.
- Unsafe or failed required research/review: block rather than imply closure.
- Persistent uncertainty or reviewer disagreement: ask the user.