# V Planning

> 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.

- Skill: `desplega-ai/v-planning` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add desplega-ai/v-planning`
- Raw SKILL.md: https://api.skillmd.com/api/skills/desplega-ai/v-planning/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: desplega-ai (https://skillmd.com/u/desplega-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/desplega-ai/v-planning

---


# 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.

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. Each step has its own Success Criteria block; `root.md` has `## Global Verification` for cross-cutting checks that only fire after the whole DAG drains. A `### QA Spec (optional):` linking to a `desplega:qa` doc is reserved for cross-cutting / evidence-heavy QA — not routine per-step checks.

7. **Propose splitting** — when a step has >4 sub-steps or >2 distinct concerns, split into multiple DAG nodes (wire deps appropriately). When the whole DAG won't fit one parallel implementation session, split into multiple plans (e.g., contract → storage → UI). A linear DAG is accepted but worth flagging — the linear `planning` skill may fit better.

8. **Push back with radical candor** — use `desplega:feedback` when the plan is too big, vague, mixes concerns, or has obvious risks. Silence is Ruinous Empathy.

9. **Validate structure with a Haiku sub-agent** before showing the plan (`general-purpose` with `model: haiku`). Verify: every `step-<n>.md` has all three Success Criteria subsections (Automated Verification + Automated QA + Manual Verification); all items use `- [ ]`; automated checks are runnable commands; every step's `depends_on` references an existing step ID; no cycles in the DAG; `root.md`'s mermaid graph + step-index table agree with step frontmatter; **every step's frontmatter has `status: ready`** (a fresh plan; transitions happen during `/v-implement`); referenced paths exist. Apply fixes *before* reveal.

10. **Hand off to a fresh session — never implement here.** Close-out:
    1. Open `/file-review:file-review <plan-dir>/root.md` (unless Autopilot); iterate on comments. Re-open with individual `step-<n>.md` files if needed.
    2. Optionally invoke `desplega:reviewing` for gap analysis (offer via `AskUserQuestion`).
    3. **OPTIONAL SUB-SKILL:** if significant insights emerged, capture via `/learning capture`.
    4. **If any step has a `### QA Spec (optional):` block**, generate the QA doc via `desplega:qa` *before* handoff (`thoughts/<username|shared>/qa/YYYY-MM-DD-[feature].md`). Scenarios live in the doc, not the plan.
    5. Ask via `AskUserQuestion`:

       | Question | Options |
       |----------|---------|
       | "Plan ready. What's next?" | 1. Implement in a fresh session, 2. Run `/review` first, 3. Done for now (park the plan) |

    6. Tell them explicitly: "Open a new Claude Code session and run `/desplega:v-implement <plan-dir>`. Starting fresh keeps the implementation context clean."

## 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).