planning

name	planning
description	Implementation planning skill. Creates detailed technical plans through interactive research and iteration.

Planning

You create detailed implementation plans through an interactive, iterative process. Be skeptical, thorough, collaborative.

Setup (before starting)

1. Autonomy Mode — passed by the invoking command; default to Critical if unspecified.

   Mode	Behavior
   Autopilot	Research independently, write the full plan, present for final review only
   Critical (Default)	After each research step, ask clarifying questions before drafting; surface design options at decision points
   Verbose	Check in at every sub-step: validate understanding, confirm scope, surface unknowns, confirm before each phase

2. Commit preference & orchestration — unless Autopilot, ask once via AskUserQuestion (bundle both questions in one call; drop the second when the Workflow tool is not available in the session):

   Question	Options
   "Create a commit after each phase once manual verification passes?"	1. Yes (Recommended), 2. No, I'll handle commits
   "Run the research spikes as Workflow scripts? (more parallel agents, higher token use)"	1. Yes — Workflow fan-out, 2. No — plain sub-agents (Default)

   A "yes" on the second question is the explicit opt-in the Workflow tool requires. In Autopilot (no questions asked), default to plain sub-agents.

3. Prior learnings — OPTIONAL SUB-SKILL: if ~/.agentic-learnings.json exists, run /learning recall <topic> first.

4. Design docs (read-and-abide) — if a design doc exists for the touched system (thoughts/*/design-docs/<system-slug>.md), read it before researching: use its Glossary terms in the plan, don't violate its Invariants or Boundaries, and flag conflicts to the user as explicit decisions instead of silently planning around them. If the plan intentionally changes the design, updating the doc (Decision log + Amendment log) is a plan step. See desplega:design-docs.

The 10 Rules

1. Scaffold first — before any research, exit plan mode and create thoughts/<username|shared>/plans/YYYY-MM-DD-description.md from cc-plugin/base/skills/planning/template.md. (Use the user's name when known, e.g. taras; fall back to thoughts/shared/ otherwise.) The file grows incrementally; the user can correct course early.

2. Sub-agent everything heavy — file reads, research, validation. Default to run_in_background: true. Keep raw tool output out of the main session. Sub-agent menu: codebase-locator (find files), codebase-analyzer (understand current implementation), codebase-pattern-finder (find similar features), context7 MCP (library/framework specifics), Explore or general-purpose (read mentioned files). Executor routing: if desplega:delegate-work is available, pick each sub-agent's model per its matrix (locate → Haiku, analyze → Sonnet) instead of spawning on defaults. If Workflow fan-out was opted in during Setup, run each section's research spike as a Workflow script (model/effort/agentType opts per the same matrix) — the plan drafting itself always stays in the main session.

3. Ask via AskUserQuestion — see desplega:ask-user for conventions. Never ask in chat as plain bullets.

4. Ask after each step (Critical/Verbose), then loop — work the plan section by section: Current State Analysis → Implementation Approach → Phase Outline → Phase Details. For each section: spawn sub-agents → synthesize findings (with file:line refs) → ask gaps via AskUserQuestion → draft → next section. Assumed inputs are the #1 source of bad plans.

5. Concrete deliverable per phase — every phase Overview names what file/feature/output exists when it's done. "Improve X", "refactor Y" are smells.

6. Proof of work: maximize Automated Verification + Automated QA — push everything into runnable commands (low-level) and agent-driven QA (browser-use, screenshot diff, CLI walkthrough). Manual Verification is the exception. A separate ### QA Spec (optional): linking to a desplega:qa doc is reserved for cross-cutting or evidence-heavy QA — not for routine per-phase checks.

Commit Integration

If commit-per-phase was enabled in Setup:

• After each phase's manual verification passes, commit with format [phase N] <brief description>.
• Only commit after explicit confirmation that manual verification passed.
• Otherwise, skip — the user handles commits.

Success Criteria Format (MANDATORY)

Canonical format and heading hierarchy lives in cc-plugin/base/skills/planning/template.md. Structure validation runs automatically (rule 9, Haiku sub-agent).