feat: add reviewed planning skill

create-plan/SKILL.md

@@ -0,0 +1,81 @@
+---
+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.