v-planning

name

v-planning

description

Vertical / parallel implementation planning skill. Creates DAG-structured plan directories where each step is an independent, QA-able vertical slice that sub-agents can pick up and implement in parallel. Use whenever the user wants a plan that fans out (multiple independent features), invokes /v-plan, or asks for a "parallel plan", "DAG plan", "vertical plan", or "plan that can be parallelized" — even if they don't say those exact words. Prefer the linear `planning` skill for strictly sequential work.

v-planning

You create implementation plans as a DAG of vertical steps — each step a complete, QA-able slice of value (DB + API + UI + tests for one feature). The DAG captures feature-level dependencies, so independent steps can be implemented in parallel by sub-agents.

Output is a plan directory at thoughts/<username|shared>/plans/YYYY-MM-DD-description/:

root.md            # Overview, mermaid DAG, step index, Global Verification
step-1.md          # frontmatter (id, name, depends_on) + Success Criteria
step-2.md
└── step-N.md

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 dir, present for final review only
   Critical (Default)	After each research step, ask clarifying questions before drafting; surface design options especially at DAG decomposition
   Verbose	Check in at every sub-step: validate understanding, confirm scope, surface unknowns, confirm before writing each step file

2. Commit preference — unless Autopilot, ask once via AskUserQuestion:

   Question	Options
   "Create a commit after each step once manual verification passes?"	1. Yes (Recommended), 2. No, I'll handle commits

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

The 10 Rules

1. Scaffold first — before any research, exit plan mode and create the plan directory with root.md from cc-plugin/base/skills/v-planning/templates/root.md. (Use the user's name when known, e.g. taras; fall back to thoughts/shared/ otherwise.) Step files are added as the DAG emerges in rule 4. The directory grows incrementally; the user can correct course early.

2. Sub-agent everything heavy — file reads, research, validation. Default 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).

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 → DAG Decomposition → Per-Step Details. For each section: spawn sub-agents → synthesize findings (with file:line refs) → ask gaps via AskUserQuestion → draft → next section.

   • DAG Decomposition: identify vertical slices (each QA-able on its own), their dependencies, and any explicit integration step. Present the proposed step list + mermaid graph and confirm shape via AskUserQuestion before drafting step files.
   • Per-Step Details: create each step-<n>.md from cc-plugin/base/skills/v-planning/templates/step.md. Frontmatter depends_on: [step-X, ...] is canonical; root.md's mermaid graph + step-index table is a derived view — keep them in sync.

5. Concrete deliverable per step (vertical slice) — every step's Overview names what file/feature/output exists when it's done. Each step must be QA-able on its own. Layer-only steps ("DB migration", "just the endpoint") are smells — collapse them into vertical slices. "Improve X" and "refactor Y" are also smells.

DAG Specifics

• Frontmatter is canonical for deps. root.md's mermaid graph is derived. If they disagree, frontmatter wins.
• Self-contained steps. A sub-agent handed only one step-<n>.md (plus plan-level context from root.md) should be able to implement it without reading sibling steps.
• Frontmatter carries execution state. Initial status: ready on every step; desplega:step-running transitions it through claimed → done (or back to ready on retry-able failure) and writes assignee / claimed_at while claimed. This makes the same plan dir safe to drive from multiple orchestrator instances. The body of the step (Changes Required, Success Criteria) is immutable during execution — only frontmatter and checkbox state change.
• Integration steps are explicit when needed. If parallel siblings need non-trivial stitching (cross-cutting e2e, shared-surface reconciliation), add an explicit step-N with depends_on: [step-X, step-Y, ...] whose work is "stitch + e2e". Otherwise the DAG just terminates at its leaves.

Commit Integration

If commit-per-step was enabled in Setup:

• After each step's manual verification passes, commit with format [step-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 live in:

• cc-plugin/base/skills/v-planning/templates/root.md (## Global Verification)
• cc-plugin/base/skills/v-planning/templates/step.md (per-step three-bucket Success Criteria)

Structure validation runs automatically (rule 9, Haiku sub-agent).