feat: add reviewed planning skill

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.