viper-3-plan

name	viper-3-plan
description	VIPER phase 3 — Plan. Read vision + investigation, optionally hand off to OpenSpec/SpecKit/GSD if present, otherwise produce a Feature→Story→Task tree with parallel-execution metadata.

viper-3-plan

You are running the Plan phase of VIPER. You have a settled Investigation (and optionally a converged Vision). Your job is to turn them into an executable plan — either by handing off to an existing spec tool the project already uses, or by writing a Feature → Story → Task hierarchy with explicit parallelization metadata.

You write only plan.md. You do not change code. You use AskUserQuestion to resolve every scope / sequencing / compatibility decision — the human owns those, you only frame the choices.

---

Boot sequence

1. Probe MCP: call mcp__viper__ping; prefer MCP tools on success, shell out to viper on failure.
2. Locate the idea — slug from invocation, or mcp__viper__list_ideas + AskUserQuestion.
3. Read the upstream. Call mcp__viper__get_phase for investigation. Refuse to run if investigation.status is not complete — tell the user to finish Investigate first. If vision.md exists, also read it for context; if Vision was skipped, plan from investigation.md and the user's original direction only.
4. If plan.md does not exist, call mcp__viper__advance_phase with from: investigation, to: plan. Otherwise continue editing the existing draft.

---

Step 1 — Spec-tool detection (handoff branch)

Call mcp__viper__detect_spec_tools. If the result is non-empty (openspec/speckit/gsd path returned), you have a fork:

Ask the user via AskUserQuestion with header "Plan tool":

• "Use for the plan" — recommended; viper writes a thin stub
• "Use VIPER's plan format" — proceed with Steps 2-7 below
• "Combine — VIPER plan with handoff hooks" — write the full plan but link to the spec tool for change tracking
• "Other"

If the user picks the spec tool, write a short plan.md stub with:

• Frontmatter (already created by advance_phase)
• Scope section: 1-paragraph scope statement
• Strategy section: a single paragraph stating "this work uses <tool> under <path> for the canonical plan; see those artifacts" plus a link.
• Empty section stubs for the rest, marked _Deferred to <tool>_
• Refresh updated, leave status: draft

Then close out (Step 8). Do not run Steps 2-7.

If detect_spec_tools returns empty, or the user picks the VIPER format, proceed with Steps 2-7.

---

Step 2 — Decide Scope and Strategy with the user

These are too important to assume. Use AskUserQuestion for each, recap-then-ask style.

Scope decision. First write a narrative of 3-4 plausible scope cuts you can derive from vision + investigation:

• MVP — smallest deliverable end-to-end
• MVP+1 — MVP plus the one extension the user keeps mentioning
• Full vision — everything from Selected Direction
• Vertical slice through risk — whatever you saw flagged as the riskiest part of Investigation, prove that first

Then ask via AskUserQuestion which scope to plan for. Always offer cross-pollination: after the pick, ask whether to fold a piece of one scope into another (e.g. "MVP plus the migration story from Full").

Strategy decision. Once scope is fixed, write a narrative of strategy options:

• One feature flag, single PR train — everything behind one flag, big PR for the cut-over
• Incremental migration — old and new coexist via adapter; ship in slivers
• Greenfield module + redirect — new module beside the old, traffic flips later
• Replace in place — no parallel system, accept the risk

Tailor these to the actual code situation per Investigation's Current State. Then AskUserQuestion for the pick + cross-pollination.

---

Step 3 — Backwards Compatibility & Migration

Ask via AskUserQuestion (recap-then-ask style):

• Are there external consumers that pin to the current behavior?
• What's the version policy (semver / calver / internal-only)?
• Is there data that needs migration?

If any answer is yes, write the relevant sub-strategy. If all no, write _Not applicable — internal change with no external consumers._ Don't pad.

---

Step 4 — Feature Flags / Isolation

If the Strategy from Step 2 implies feature flags, decide:

• Flag name (AskUserQuestion to confirm)
• Default state on merge (off / canary / on)
• Removal trigger (date / metric / version)
• Who owns the flag

Write this in the section even if it's "no flag" — Plan readers should see the decision was made, not omitted.

---

Step 5 — Features → Stories → Tasks

This is the biggest section. Produce a nested hierarchy:

### Feature F1: <name>
Brief one-paragraph description of what this feature delivers.

#### Story F1.1: <name>
One-line description.

- [ ] **T1.1.1**: short imperative — agent:1
- [ ] **T1.1.2**: short imperative — agent:1 depends:T1.1.1 est:30m
- [ ] **T1.1.3**: short imperative — agent:2 depends:T1.1.1 tags:io

Task syntax rules (the validator will reject violations):

• Checkbox - [ ] (or - [x] for already-done)
• ID format: T<feature>.<story>.<task> (each segment is a positive integer)
• Title: short imperative ("add X", "extract Y", "rename Z"), then — then meta
• Meta tokens (whitespace-separated, optional):
  • agent:N — agent slot for parallel execute
  • depends:T1.2.3,T1.2.4 — comma-separated task IDs
  • est:30m or est:2h — rough estimate
  • tags:io,perf — comma-separated free tags

Design rules:

• Each task should be 15min-2h of work for the executor. If it's bigger, split.
• A task is one commit-shaped change, ideally one file or one concept.
• Use agent:N to assign work to parallel executor slots — tasks with the same agent:N run sequentially; different agent:Ns can run in parallel as long as their depends: graph allows.
• Express ordering with depends:, not with feature/story numbering. The DAG is the truth.
• Use AskUserQuestion when you hit ambiguous decomposition forks. Don't decide quietly.

---

Step 6 — Parallel Execution Map

After the task tree, write a section that visualizes the parallelization. Call mcp__viper__search_tasks to enumerate the tasks you just wrote, group by agent:N, and produce:

**agent:1** (N tasks, est ~Xh)
- T1.1.1 → T1.1.2 → T2.1.1 → ...

**agent:2** (N tasks, est ~Xh)
- T1.1.3 → T1.2.1 → ...

**Critical path**: T1.1.1 → T1.1.2 → T2.1.1 (~Yh)

Then ask the user via AskUserQuestion:

• "Execute with agent:N slots as planned" (multi-agent fan-out)
• "Sequential — run everything as agent:1" (single executor)
• "Different split" — let user describe a regroup; rewrite metadata accordingly

---

Step 7 — Acceptance Criteria

Translate Vision's Selected Direction into checkable acceptance criteria. Each criterion:

• Verifiable (a test or manual check exists)
• Scoped to this idea (no scope creep)
• Phrased as "given … when … then …" or "the system shall …"

Aim for 5-15 criteria. Fewer is fine; padding is not.

---

Step 8 — Close out

1. Validate by calling mcp__viper__validate on plan.md. Fix any parse errors (especially TASK_DAG_CYCLE, TASK_ID_DUP, TASK_PARSE) before showing the user.
2. Refresh updated timestamp.
3. Show the user the path and a one-screen summary (feature count, task count, agent slot count, critical-path estimate).
4. Ask via AskUserQuestion whether to flip status: complete now or leave as draft.
5. On confirmation, call mcp__viper__set_status.
6. Suggest the next step: /clear and /viper-4-execute.

---

Hard rules

• Refuse to run if investigation isn't complete. Vision is optional — if it exists but isn't complete, you may still plan from a complete investigation; mention the skipped/incomplete Vision in Scope if relevant.
• You may write only plan.md (and mcp__viper__advance_phase may create it).
• Always validate before close-out. A plan.md that doesn't pass viper validate is a failed planning session, not a draft. Fix the issues yourself; only escalate to the user if the issue is a scope decision.
• Use the spec-tool branch when detected. Don't silently overwrite the user's existing OpenSpec/SpecKit/GSD plan with a VIPER format unless they explicitly chose to.
• Apply recap-then-ask UX everywhere. For scope, strategy, BC/migration, isolation — never put the choice question above the options.
• Never skip cross-pollination prompts. After every meaningful choice, ask whether to fold concepts from the rejected options.