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.

create-plan/assets/implementation-plan-template.md

@@ -0,0 +1,36 @@
+# Implementation Plan
+
+> **Status:** Draft
+
+## Outcome and boundaries
+
+- **Problem and target:**
+- **In scope:**
+- **Out of scope:**
+- **Approach:**
+
+## Key files, evidence, and decisions
+
+| File or source | Why it matters | Decision or plan impact |
+|---|---|---|
+
+- **Open gate:** Omit this line when no gate remains.
+
+## Tasks
+
+#### T1 — First implementation task
+
+- **Change:**
+  - One concrete edit or behavior per bullet.
+- **Starts at:** Non-exhaustive paths and symbols.
+- **Depends on:** Omit when independent.
+- **Tests:** Name the behavior each test protects.
+- **Verify:**
+  - Run an exact command; state its expected successful signal.
+- **Risk/recovery:** Omit when immaterial.
+
+## Final acceptance
+
+- **Checks:** Repository gates and end-to-end behavior checks.
+- **End state:** Observable implementation outcome.
+- **Deferrals or blockers:** Omit when none.

create-plan/evals/evals.json

@@ -0,0 +1,47 @@
+{
+  "skill_name": "create-plan",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Plan OAuth support for this application and leave an implementation-ready handoff, but do not change code.",
+      "expected_output": "Runs the pi-subagents dependency gate, delegates bounded local and external research where relevant, resolves material user questions, produces a stable-ID plan under .plans/, and iterates fresh independent plan review until clear or blocked. It does not implement.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Review and improve .plans/cache-migration.md before anyone implements it.",
+      "expected_output": "Loads the existing unimplemented plan, verifies pi-subagents and required roles, inspects repository evidence, runs fresh plan reviewers, dispositions every finding, revises accepted items, re-reviews material changes, and leaves the plan Ready or explicitly Blocked.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Research the current SDK docs and create a rollout plan for upgrading our integration.",
+      "expected_output": "Requires the researcher role in addition to the core planning roles, uses authoritative version-matched external evidence plus local context, asks about material migration choices, and produces an evidence-backed reviewed plan with exact validation commands and recovery guidance.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "Create an implementation plan for the authentication refactor.",
+      "expected_output": "Before repository research, checks for the active subagent tool, runs doctor, and lists executable roles. If pi-subagents or a required role is missing, it stops with the exact dependency problem and directs the user to their existing package-management method. For a declarative or Nix-managed setup it requires a configuration change, rebuild, and Pi restart; it never runs pi install, npm installation, or silently falls back.",
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "Implement the approved authentication plan now and run the tests.",
+      "expected_output": "Does not route to create-plan because this is implementation work; it uses an implementation workflow instead.",
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "Audit the code that was just merged against the original implementation plan.",
+      "expected_output": "Does not route to create-plan because the target is completed implementation; it uses code review or plan-compliance review instead.",
+      "files": []
+    },
+    {
+      "id": 7,
+      "prompt": "Briefly explain what dependency injection means.",
+      "expected_output": "Does not route to create-plan because the request is a small conceptual explanation without an implementation handoff.",
+      "files": []
+    }
+  ]
+}

create-plan/references/plan-quality-checklist.md

@@ -0,0 +1,38 @@
+# Plan Quality Checklist
+
+Apply before final delivery and after material revisions. Require evidence, not intent.
+
+## Dependencies and evidence
+
+- [ ] `subagent` was active; `doctor` had no blocking error.
+- [ ] `list` confirmed executable `context-builder`, `planner`, and `reviewer`; `researcher` was confirmed when required.
+- [ ] Every foreground or forced-async child reached an observed terminal state before its output was used.
+- [ ] Required research and independent review completed safely.
+- [ ] Outcome, in-scope behavior, material non-goals, constraints, and approach are unambiguous.
+- [ ] Material ambiguity was answered by the user or remains an explicit blocking gate.
+- [ ] Key local files appear in the evidence table with path, relevance, and plan impact.
+- [ ] External claims cite inspected, authoritative, version-matched sources.
+- [ ] Every material finding affects a decision, task, check, non-goal, or open gate.
+
+## Tasks and readiness
+
+- [ ] Final status is `Ready for implementation` only when no material gate remains; otherwise it is `Blocked`.
+- [ ] Stable-ID tasks contain concrete **Change** bullets, not prose blobs.
+- [ ] Starting paths and symbols are useful but non-exhaustive.
+- [ ] Tests name the behavior they protect.
+- [ ] Verification uses exact commands and expected success signals.
+- [ ] Dependencies, migration/operator steps, risks, and recovery are present when material.
+- [ ] Tasks are flat unless real sequencing, migration, or release boundaries require phases.
+- [ ] Each task was challenged for a smaller alternative; speculative machinery and scope are absent.
+- [ ] Final acceptance covers repository gates, end-to-end behavior, deferrals, and the observable end state.
+- [ ] Template guidance, empty optional fields, duplicated rationale, and review ledgers were removed.
+
+## Review and delivery
+
+- [ ] Fresh reviewers covered feasibility, validation, and simplicity in proportion to risk.
+- [ ] Every finding was dispositioned as `Accept`, `Validate`, `Reject`, `Ask user`, or `Block`.
+- [ ] Accepted material changes were independently re-reviewed.
+- [ ] All commissioned reviewers reported `Clear`, or the plan is blocked/escalated without claiming closure.
+- [ ] The parent inspected critical evidence and owns the final synthesis.
+- [ ] Only `.plans/<kebab-name>.md` was written by this workflow, excluding explicitly retained dependency diagnostics.
+- [ ] Delivery reports the path, decisions and gates, review closure, validation strategy, fallbacks, and remaining risks.

create-plan/references/subagent-plan-loop.md

@@ -0,0 +1,138 @@
+# Pi-subagents Plan Loop
+
+Read this before launching planning children. The live `subagent` tool schema is authoritative after package upgrades; preserve these semantics if optional fields change.
+
+## Contents
+
+1. Preflight
+2. Assignment contract
+3. Research fanout
+4. Planner draft
+5. Independent review
+6. Disposition and closure
+7. Failure handling
+
+## 1. Preflight
+
+Use read-only management calls:
+
+```text
+subagent({ action: "doctor" })
+subagent({ action: "list" })
+```
+
+Continue only when the runtime is healthy enough to launch and the list shows executable, non-disabled `context-builder`, `planner`, and `reviewer` agents. Require `researcher` only when external evidence is decision-relevant. Do not infer availability from package files or settings alone.
+
+## 2. Assignment contract
+
+Every child task includes:
+
+- **Goal:** one bounded question or output.
+- **Context:** request, cwd, known files, decisions, and evidence pointers.
+- **Scope:** owned question, requirements, and non-goals.
+- **Permissions:** read-only; no project/source edits and no recursive delegation.
+- **Validation:** evidence to inspect and claims to verify.
+- **Output:** concise findings or draft shape, with file/line or source pointers.
+- **Stop:** completion condition and ambiguities that must return to the parent.
+
+Use `context: "fresh"` so lanes rely on explicit assignments. Use `async: false` because this workflow must synthesize each gate before proceeding. If runtime policy still returns an async run, do not continue until its exact completion is observed through enabled `subagent_wait` or completion/status delivery; stop if no safe observation path exists. Set `output: false` on each task and `artifacts: false` on the run so advisory work does not create repository artifacts. Retain diagnostics only when a failed run needs investigation.
+
+## 3. Research fanout
+
+Choose two or three independent lanes; do not create lanes as a quota.
+
+```text
+subagent({
+  tasks: [
+    {
+      agent: "context-builder",
+      task: "Analyze request, scope, constraints, non-goals, and material open decisions. Inspect named targets. Return evidence and questions; do not edit project/source files.",
+      output: false
+    },
+    {
+      agent: "context-builder",
+      task: "Map relevant files, symbols, call paths, tests, configuration, and existing patterns. Return file/line evidence and implementation starting points; do not edit project/source files.",
+      output: false
+    },
+    {
+      agent: "context-builder",
+      task: "Identify validation commands, protected behaviors, migration/operational risks, and recovery needs. Return evidence and gaps; do not edit project/source files.",
+      output: false
+    }
+  ],
+  context: "fresh",
+  concurrency: 3,
+  async: false,
+  artifacts: false
+})
+```
+
+Replace or add a `researcher` lane when current external information affects a decision. Ask for official, version-matched sources, exact claims, confidence, and local implications. The parent verifies load-bearing evidence and resolves conflicts.
+
+## 4. Planner draft
+
+After user gates are resolved, invoke one planner:
+
+```text
+subagent({
+  agent: "planner",
+  task: "Create a plan-only structural draft from the supplied outcome, boundaries, decisions, evidence, and validation contract. Follow the provided implementation-plan template. Use stable task IDs, concrete Change bullets, non-exhaustive starts-at paths/symbols, tests with protected behavior, and exact verify commands with expected signals. Surface blockers; do not edit project/source files.",
+  context: "fresh",
+  async: false,
+  output: false,
+  artifacts: false
+})
+```
+
+Include the actual distilled evidence and decisions in the task; never send only the generic text above. The parent checks the response against repository evidence and writes the draft plan.
+
+## 5. Independent review
+
+Launch two or three fresh reviewers according to consequence:
+
+```text
+subagent({
+  tasks: [
+    {
+      agent: "reviewer",
+      task: "Review the plan path for feasibility, scope, architecture fit, and missing implementation gates. Inspect repository evidence directly. Return Clear or evidence-backed findings with IDs; do not edit files.",
+      output: false
+    },
+    {
+      agent: "reviewer",
+      task: "Review the plan path for task completeness, tests, exact verification, expected signals, sequencing, migration, and recovery. Return Clear or evidence-backed findings with IDs; do not edit files.",
+      output: false
+    },
+    {
+      agent: "reviewer",
+      task: "Review the plan path for unnecessary complexity, speculative machinery, simpler alternatives, hidden risk, and non-goal leakage. Return Clear or evidence-backed findings with IDs; do not edit files.",
+      output: false
+    }
+  ],
+  context: "fresh",
+  concurrency: 3,
+  async: false,
+  artifacts: false
+})
+```
+
+Replace “the plan path” with the exact `.plans/` path and include the approved boundaries in every task. Each finding must include an ID, affected plan section, repository evidence, implementation consequence, and smallest corrective recommendation. Reviewers inspect the current plan and repository, not prior reviewer prose.
+
+## 6. Disposition and closure
+
+For every finding, the parent records an internal disposition:
+
+- `Accept` — evidence supports the smallest correction; revise.
+- `Validate` — gather bounded evidence before deciding.
+- `Reject` — unsupported, incorrect, out of scope, or needlessly complex.
+- `Ask user` — requires a product, scope, architecture, migration, risk, or complexity choice.
+- `Block` — planning cannot safely continue.
+
+Do not copy the disposition ledger into the implementation plan unless it creates implementation work. Re-review materially changed sections with fresh reviewers. Closure requires all commissioned reviewers to return `Clear`; optional polish can be explicitly rejected or deferred. Escalate after three total rounds, two rounds without material progress, or recurring disagreement.
+
+## 7. Failure handling
+
+- Unknown/disabled role: rerun `list`, then stop with the exact missing role.
+- Runtime/discovery failure: run `doctor`; retain and report diagnostics.
+- Child failure: do not treat partial output as acceptance; retry once only with a materially corrected assignment.
+- Missing independence: stop rather than self-certify a consequential plan.