81 lines
5.2 KiB
Markdown
81 lines
5.2 KiB
Markdown
---
|
|
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.
|