agent-skills/create-plan/SKILL.md

name	description	license	compatibility	metadata
create-plan	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.	MIT	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.	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. 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.

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.
   • 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.