vt-d-2-plan¶

Phase 2 - Design and architecture planning. Runs one planning pipeline for the active spec — research, technical plan, plan-checker validation loop, and task breakdown — using the conceptual-orchestrator for research and architecture decisions.

Plugin: vt-product-dev
Category: Development Workflow
Command: /vt-d-2-plan

Phase 2: Plan - Design & Architecture¶

Orchestrate the full planning pipeline for the active spec: confirm the specification, research best practices, create a technical plan, validate it, and break it into executable tasks.

Workflow Position¶

/activate → [ /vt-d-2-plan ] → /vt-d-3-build → /vt-d-4-review → /vt-d-5-finalize → /vt-d-complete
              ▲ YOU ARE HERE
              ↑ deliverable_types determines dispatch at each phase

Invocation¶

/vt-d-2-plan                                 # Plan for the currently active spec
/vt-d-2-plan "Implement user authentication" # Plan with additional context

Execution Instructions¶

Step 0a: Read Phase Checkpoint¶

If .claude-checkpoint.md exists in the project root: 1. Read the file 2. Display: Resuming from checkpoint: {completed_phase} completed at {timestamp} 3. Display the "Context for Next Phase" section content 4. If next_phase doesn't match 2-plan: warn "Checkpoint suggests /{next_phase}, but you're running /vt-d-2-plan" (advisory, not blocking)

If no checkpoint exists: proceed silently.

Step 0: Load Constitution & Resolve Active Spec¶

If .specify/memory/constitution.md exists:
Load it into context
All planning MUST respect constitution boundaries
Display: "✓ Constitution loaded — planning will respect its constraints"
Derive the active spec from the branch:
Check .active-spec file first (override), then parse branch name (feature/spec-NNN-* → SPEC-NNN)
Look up specs_dir in .design-state.yaml specs_status for the derived SPEC-NNN
If active spec found: Display: "✓ Active spec: SPEC-001 — User Authentication (from branch)"
If active spec has a specs_dir: Load specs/[N]-feature/spec.md if it exists
If NO active spec (no .design-state.yaml or branch doesn't match feature/spec-NNN-*):
Display: "⚠ No active spec found"
Suggest: "Run /vt-d-activate to select a spec for development"
Ask: "Continue planning for the described feature, or activate a spec first?"

Step 0.5: Project Registration Check¶

Run the shared registration check — single source of truth. Do NOT inline the logic here (duplicating it re-introduces the cross-copy drift SPEC-150 removed):

bash ~/.claude/skills/vt-c-project-register/scripts/check_registration.sh

Act on the emitted status line (stdout); any line other than UNREGISTERED … means continue silently (keeps the gate soft even if the vocabulary grows): - REGISTERED, TOOLKIT_REPO, NOT_GIT, or DEGRADED … → continue silently. - UNREGISTERED skips=N escalate=<bool> → offer registration (soft gate — never block): - Ask (AskUserQuestion): "This project isn't registered in the toolkit, so its learnings won't reach the intake pipeline. Register now?" - If escalate=true, strengthen the wording: note that learnings have not been reaching the toolkit across N sessions. - Register now → invoke /vt-c-project-register. - Skip for now → run bash ~/.claude/skills/vt-c-project-register/scripts/check_registration.sh --record-skip, then continue.

Step 0.7: Read Deliverable Types¶

Read deliverable_types from specs/[N]-feature/spec.md YAML frontmatter
If present and non-empty: use as-is
If missing: warn "No deliverable_types in spec frontmatter — defaulting to [code]" and treat as [code]
Display: "Deliverable types: {list}"

The detected types determine which task templates, research agents, and plan sections are generated in subsequent steps.

Step 0.8: Shape Gate Check¶

Before loading institutional knowledge, verify the spec has resolved implementation decisions that would otherwise cause mid-build pivots.

Tier 1 — decisions.md fast path: If specs/[N]-feature/decisions.md exists AND is non-empty: → Display: "✓ Shaping decisions found — proceeding to plan" → Continue to Step 1

Tier 2 — heuristic scan: Run: python3 TOOLKIT_ROOT/plugins/vt-product-dev/skills/workflow-2-plan/scripts/gray-area-heuristic.py specs/[N]-feature/spec.md (resolve TOOLKIT_ROOT as the repo root — the directory containing plugin.json, one level above plugins/)

If result.total == 0: → Display: "✓ No gray areas detected — proceeding to plan" → Continue to Step 1

If result.total ≥ 1: → Display: "⚠ Gray areas detected ({N} findings):" List each finding with its type and detail → Use AskUserQuestion: 1. "Run /vt-d-shape now (Recommended)" — exit; user runs /vt-d-shape first 2. "Skip — planner defaults are fine" — write shape_gate: { skipped: true } to specs/[N]-feature/state.yaml, then continue to Step 1 3. "Cancel /vt-d-2-plan" — exit without changes

--deep mode (power users only, not shown in normal Tier 2 prompt): When /vt-d-2-plan is invoked with explicit --deep context: → After heuristic scan, also dispatch strategic-mentor agent (read-only) with spec.md as input → Display strategic-mentor verdict alongside heuristic findings → The --deep path is NOT surfaced in the AskUserQuestion options above → IMPORTANT: Do NOT add --deep as a 4th AskUserQuestion option — it must remain invisible to normal users. The AskUserQuestion always shows exactly 3 options (run shape / skip / cancel).

Step 1: Load Institutional Knowledge¶

Before planning, check for existing patterns:

If docs/solutions/patterns/critical-patterns.md exists → Load into context
If docs/solutions/ has relevant past solutions → Reference them
If docs/adr/ has Architecture Decision Records → Review relevant decisions
If .specify/memory/constitution.md was loaded in Step 0 → Already in context
If specs/[N]-feature/decisions.md exists (from /vt-d-shape):
Load into context — these are user-locked implementation decisions
Display: "✓ Shaping decisions loaded from decisions.md ({N} decisions)"
These decisions MUST be treated as constraints during planning:
- Pass to research agents so they investigate the chosen direction (not alternatives)
- Reference in plan output as locked decisions
- Do NOT propose alternatives that contradict shaping decisions

Step 1.5: Universal Pre-Planning (All Types)¶

Before formalizing the spec, verify that foundational planning inputs are defined. These apply to all deliverable types:

Goals — What does this deliverable achieve? (should be in spec "Goal" section)
Target audience — Who consumes this deliverable?
Deliverables — What artifacts are produced?
Constraints — Time, technical, regulatory, or resource constraints
Success criteria — How do we know this is done well?

For code-only specs, most of these are already in the spec from /vt-d-activate --from-prd. Just verify presence.

For non-code types (document, presentation, research, project-plan), these are the primary planning inputs. If any are missing, prompt the user to provide them before proceeding.

Step 2: Confirm the Specification¶

The active spec was already formalized at creation — by /vt-d-spec-from-requirements or /vt-d-activate --from-prd — so it should already carry structured user stories with priorities (P1, P2, P3), Given/When/Then acceptance criteria, and identified edge cases.

Read the active spec from specs/[N]-feature/spec.md (copied there by /vt-d-activate)
Confirm it has user stories, acceptance criteria, and edge cases. If any are missing, enrich the spec in place before planning — do not defer these gaps to build.
If there is no active spec, the user's feature description serves as the informal spec.

Step 3: Research & Architecture (conceptual-orchestrator)¶

Dispatch the conceptual-orchestrator which coordinates:

best-practices-researcher - Industry patterns and standards
framework-docs-researcher - Library documentation
architecture-strategist - System design decisions
spec-flow-analyzer - User flow mapping and edge cases

Type-conditional additions:

When non-code types are present in deliverable_types: - Dispatch repo-research-analyst to search for past solutions and similar deliverables in the project - When document or presentation in types: add audience analysis step (who reads/views this, what do they need to take away, what is their knowledge level)

Constitution constraints are applied throughout all research and architecture decisions.

Step 4: Technical Planning¶

Diet rules for plan.md emission:

When emitting plan.md content, follow these five rules to keep new plan.md files lean (SPEC-143).

(a) Constitution Check — Emit a ## Constitution Check H2 with exactly one body line pointing to state.yaml.plan_gate (e.g., See \state.yaml.plan_gate` for status, principles checked, and any violations.). Do NOT emit a prose checklist in plan.md. The substance lives instate.yaml.plan_gate` (see Step 5c). Validates against constitution: this logic still runs — only the output format changes (FR-1, FR-8 — required by SPEC-143).

(b) Wave components — Render each Wave's components as one 4-column table per Wave with columns Component | Files | Approach | Reuse. One row per component. A single-component Wave is still a 1-row table (EC-1); a many-component Wave stays one long table — never split into per-component sub-headings (EC-4, FR-3).

(c) Pattern Reuse — Emit ## Pattern Reuse H2 ONLY when ≥1 relevant pattern is identified. When no pattern applies, the section is omitted entirely (no empty heading). Pattern Reuse is conditional (FR-4, EC-2).

(d) Modified Files — Render as a markdown table (e.g., Component | Files), not as an ASCII directory tree. When the list is empty, the section is omitted entirely when the list is empty (EC-5, FR-5).

(e) Technical Context — Emit only fields with substantive values. Drop rows whose value matches "N/A", "Markdown", "None", "default", or any other default/inferable value — these are noise (FR-6).

(f) artifact_readiness frontmatter (SPEC-146) — Emit an artifact_readiness: field in the plan.md YAML frontmatter with value requirements-only on initial emission. This is the machine-readable readiness anchor downstream agents (implementation-orchestrator, spec-compliance-reviewer) read instead of inferring maturity by line number. The value is flipped to implementation-ready at plan completion — see Step 5c. workflow-2-plan owns BOTH the write and the flip; do NOT defer the transition to /vt-d-3-build — a write-once field with no owned transition goes permanently stale.

(g) ## Goal Capsule section (SPEC-146) — Emit a stable ## Goal Capsule H2 at the head of plan.md (immediately after the title), as a 5-line bullet list: Ziel, Deliverable, Success-Criterion, Blocker, Next-Step (one line each). This is a stable heading anchor for heading-scan navigation and is substantive content, NOT boilerplate — see the Step 5b boilerplate markers note. It does not trip plan-length-metrics.py (which flags only Constitution/Pattern-Reuse headings, ### W\d+.\d+, and ASCII trees).

Produce the technical implementation plan from the spec and research findings, applying the diet rules above:

Fill the Technical Context (language, dependencies, storage, testing)
Validate against the constitution (if loaded)
Resolve all "NEEDS CLARIFICATION" items
Output (in specs/[N]-feature/):
plan.md — implementation plan with architecture decisions
research.md — decisions, rationale, alternatives considered
For code specs that need them: data-model.md (entities, fields, relationships, validation), contracts/ (API schemas), and quickstart.md (integration scenarios)

Type-conditional plan sections (added to plan.md based on deliverable_types):

Type	Additional Plan Sections
`code`	Technical context, data model, API contracts, test strategy (unchanged from today)
`document`	Content outline (sections, key messages), audience analysis, review/approval workflow
`presentation`	Slide outline (slide-by-slide with key message per slide), narrative arc, timing budget
`research`	Research methodology, source strategy, analysis framework, synthesis approach
`project-plan`	Phase/milestone structure, dependency map, resource plan, risk register

Multi-type specs produce the union of all applicable sections.

Beyond the type-specific sections, every plan.md also captures architecture decisions with rationale, a risk assessment with mitigations, user-flow analysis (all paths through the feature), and the test strategy (automated tests, manual tests, edge cases).

Step 4.5: Plan Validation Loop¶

After the plan is generated, validate it for structural quality and strategic viability before proceeding to task breakdown.

When plan.md exists:

Initialize loop state:
iteration = 0, max_iterations = 3, previous_failures = null
Dispatch strategic-mentor in parallel with the validation loop:

Alongside the plan-checker loop below, dispatch the strategic-mentor agent (read-only, via Agent tool) with: - specs/[N]-feature/plan.md (required) - specs/[N]-feature/spec.md (if exists) - .specify/memory/constitution.md (if exists)

The strategic-mentor provides a verdict (VIABLE / NEEDS REVISION / FLAWED) with analysis of assumptions, failure modes, and risks. This verdict is informational only — it does NOT affect the .plan-gate.md PASS/FAIL outcome. Only the plan-checker determines the gate status.

Display the strategic-mentor's verdict to the user after the plan-checker loop completes (or alongside it if both finish):

Strategic Review: [VERDICT]
[Summary of key findings — assumptions, top failure mode, recommendation]

Validation loop (max 3 iterations):

iteration += 1

Dispatch plan-checker agent (read-only, via Agent tool) with:
  - specs/[N]-feature/plan.md (required)
  - specs/[N]-feature/spec.md (if exists, for cross-reference)
  - iteration_number = iteration

In parallel with the plan-checker dispatch, also dispatch strategic-mentor agent
(read-only, via Agent tool) with the same inputs (plan.md and spec.md).
Use a single message with multiple Agent tool calls so both run concurrently.

IMPORTANT: The strategic-mentor output is advisory only — it does NOT participate
in the validation loop convergence logic. The iteration/convergence/escalation
logic below applies to plan-checker results only. Display the strategic-mentor
verdict to the user alongside the plan-checker report.

IF report.overall == PASS:
  → Write specs/[N]-feature/.plan-gate.md (status: PASS, iterations: iteration)
  → Display: "✓ Plan validated in {iteration} iteration(s)"
  → Break — proceed to Step 5

Extract current_failures from report

IF previous_failures != null AND current_failures == previous_failures:
  → Stalled convergence — escalate immediately
  → Write .plan-gate.md (status: FAIL, reason: stalled)
  → Break — present escalation UI

IF previous_failures != null AND len(current_failures) > len(previous_failures):
  → Regression detected — escalate immediately
  → Write .plan-gate.md (status: FAIL, reason: regression)
  → Break — present escalation UI

previous_failures = current_failures

IF iteration < max_iterations:
  → Feed actionable feedback from the report to the planner
  → Revise plan.md addressing the specific failures
  → Continue loop

IF iteration == max_iterations AND report.overall == FAIL:
  → Write .plan-gate.md (status: FAIL, reason: max_iterations)
  → Present escalation UI

Escalation UI (when loop does not converge):

⚠ Plan validation did not converge after N iteration(s).

Persistent issues:
1. [specific failing check with task reference]
2. ...

Present options via AskUserQuestion: - (a) Revise the spec — requirements may be ambiguous - (b) Skip validation and proceed — write .plan-gate.md with status: SKIPPED and user's acknowledgment - (c) Provide additional context — feed context to the planner for another revision attempt

Gate file format (specs/[N]-feature/.plan-gate.md):

Why specs dir, not project root? Unlike .review-gate.md (one per branch), plan gates are per-spec artifacts that travel with the spec's deliverables. Placing them in specs/[N]-feature/ keeps all planning outputs co-located and avoids conflicts when multiple specs are planned in parallel.

---
status: PASS | FAIL | SKIPPED
iterations: N
timestamp: ISO-8601
---

# Plan Gate: SPEC-NNN

## Result: [STATUS]

Validated plan.md in N iteration(s) against 4 dimensions:
- Completeness: X/Y checks passed
- Testability: X/Y checks passed
- Dependencies: X/Y checks passed
- Clarity: X/Y checks passed

For FAIL: includes failure summary and persistent issues. For SKIPPED: includes user's acknowledgment and reason.

When no plan.md exists: Skip this step silently.

Step 5: Task Breakdown¶

Break the plan into executable tasks:

Read the spec, plan, and research (and data-model.md/contracts/ when present)
Organize tasks by user story (P1 first, then P2, P3)
Create phases: Setup → Foundational → User Stories → Polish
Mark parallelizable tasks with [P]
Output: specs/[N]-feature/tasks.md

Type-conditional task templates (used within tasks.md based on deliverable_types):

code tasks (TDD format, absorbed from /writing-plans):

### Task N: [Component]
Files: Create/Modify/Test
Step 1: Write failing test [complete code]
Step 2: Run to confirm failure [exact command + expected output]
Step 3: Write minimal implementation [complete code]
Step 4: Run to confirm pass [exact command + expected output]
Step 5: Commit

document tasks:

### Task N: [Section/Chapter]
Step 1: Research — gather sources and evidence
Step 2: Draft — write initial content
Step 3: Review — self-review for clarity/accuracy
Step 4: Polish — formatting, links, cross-references

presentation tasks:

### Task N: [Section/Slide Group]
Step 1: Outline — key message and supporting points
Step 2: Content — write slide text and speaker notes
Step 3: Speaker Notes — full narrative for delivery
Step 4: Visual Review — check density, consistency, CD compliance

research tasks:

### Task N: [Research Question]
Step 1: Questions — define specific sub-questions
Step 2: Sources — identify and gather sources
Step 3: Analysis — evaluate evidence, note gaps
Step 4: Synthesis — draw conclusions, check for bias
Step 5: Conclusions — actionable recommendations

project-plan tasks:

### Task N: [Phase/Workstream]
Step 1: Scope — define boundaries and deliverables
Step 2: Phases — break into sequential phases
Step 3: Dependencies — map inter-task dependencies
Step 4: Risks — identify risks and mitigations
Step 5: Timeline — estimate durations and milestones

Multi-type specs use the appropriate template for each task based on which type it serves. Cross-type dependencies are noted explicitly (e.g., "Task 5 (presentation) depends on Task 3 (code) — demo screenshots needed").

Step 5b: Plan.md Boilerplate Markers¶

Boilerplate markers (machine-checkable):

The plan-length-metrics.py script (plugins/vt-product-dev/skills/workflow-2-plan/scripts/plan-length-metrics.py, SPEC-143) flags four boilerplate patterns in any new plan.md and counts their line share. Authors of new plan.md content should keep total boilerplate share ≤8% by avoiding these patterns:

Constitution prose checklists — ^## Constitution (Compliance|Validation|Check) heading followed by a prose body. The ## Constitution Check signpost is exempt — its body must be exactly one line referencing state.yaml.plan_gate (see Step 4 diet rule (a)).
Empty Pattern Reuse sections — ^## Pattern Reuse heading followed by an empty table or "None" prose. Omit the section entirely when no pattern applies (Step 4 diet rule (c)).
Wave sub-section headings — any ^### W\d+\.\d+ per-component heading. Use a 4-column Wave table instead (Step 4 diet rule (b)).
ASCII directory trees — fenced-code blocks with ≥3 consecutive lines matching ^[│├└─ ]. Use a Modified Files markdown table instead (Step 4 diet rule (d)).

The ## Goal Capsule section (Step 4 rule (g), SPEC-146) is exempt — it is substantive content and matches none of the four flagged patterns, so it adds 0 to the boilerplate numerator and can only lower the boilerplate share. Do NOT treat it as boilerplate.

Step 5c: Persist Plan Gate¶

After all planning artifacts are written, persist the plan gate in state.yaml:

Derive the active spec from the branch name (feature/spec-NNN-* → SPEC-NNN)
Look up specs_dir in .design-state.yaml
Read specs/[N]-feature/state.yaml

Add or update the plan_gate section using the diet schema (SPEC-143):

plan_gate:
  status: PASS
  checked_at: "YYYY-MM-DD"
  principles_checked: [I, II, III, IV]
  violations: []
  artifacts: [list of files created in specs/[N]-feature/]

status — PASS when constitution-check succeeds, FAIL when at least one principle is violated.
checked_at — ISO date the constitution check ran.
principles_checked — list of constitution principle IDs the planner verified (e.g., [I, II, III, IV]). This list — together with violations — is the audit substance that used to live as prose in plan.md (FR-1, FR-2, NFR-Auditability).
violations — empty list when status: PASS; otherwise list each violated principle with a one-line reason.
artifacts — files created in specs/[N]-feature/ during planning.

Backward compatibility (read-side): Reader skills (workflow-4-review, workflow-5-finalize, toolkit-review) accept both the new status: PASS and the legacy status: COMPLETE as equivalent compliant markers. Pre-SPEC-143 plan_gate entries are NOT migrated — mixed-state repo is explicitly OK (FR-7). 5. Write the updated state.yaml 6. Stage: git add specs/[N]-feature/state.yaml

Flip artifact_readiness → implementation-ready (SPEC-146 Decision 2): After tasks.md has been generated (Step 5) AND this plan gate is PASS, update the artifact_readiness: field in specs/[N]-feature/plan.md frontmatter from requirements-only to implementation-ready. This is the owned transition for the Step 4 rule (f) field — a plan with a validated task breakdown IS implementation-ready. workflow-2-plan is the single owner of this flip; it is NOT handed off to /vt-d-3-build. If the plan gate is FAIL/SKIPPED, leave the value at requirements-only.

If no active spec or no state.yaml: skip silently.

Step 5d: Write Phase Checkpoint¶

Write .claude-checkpoint.md to the project root: - completed_phase: 2-plan - next_phase: 3-build - next_command: /vt-d-3-build - branch: current git branch - active_spec: derived from branch or .active-spec - clear_recommended: true - clear_reason: "Planning explores alternatives and research — build should start fresh with just the plan" - Key Outcomes: list planning artifacts created (plan.md, tasks.md, etc.) - Context for Next Phase: spec ID, plan location, key architecture decisions

Display the clear recommendation per the phase-checkpoint protocol.

Step 6: Show Completion Message¶

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Phase 2 Complete: Plan Created for SPEC-001 — User Authentication
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Deliverables (in specs/[N]-feature/):
✓ spec.md — specification with acceptance criteria
✓ plan.md — implementation plan with architecture decisions
✓ research.md — best practices and alternatives considered
✓ .plan-gate.md — plan validated in N iteration(s)
✓ tasks.md — executable task breakdown by user story

Constitution: ✓ decisions validated against the constitution (when one is loaded)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NEXT STEPS: /vt-d-3-build → /vt-d-4-review → PR
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. /vt-d-3-build — implement the plan (tasks from specs/[N]-feature/tasks.md)
2. /vt-d-4-review — mandatory security + quality review (do NOT skip)
3. Create PR after review passes

TIP: During /vt-d-3-build, use /vt-c-journal frequently to capture:
- Why you made certain choices
- Problems encountered and solutions
- Deviations from the plan

What the Orchestrator Does¶

Research Phase¶

Searches for industry best practices
Gathers relevant library documentation
Checks existing codebase patterns

Design Phase¶

Creates system architecture
Identifies component boundaries
Plans data models and APIs

Analysis Phase¶

Maps all user flows
Identifies edge cases
Assesses security implications

Output Phase¶

Produces actionable implementation plan
Documents architecture decisions
Creates risk mitigation strategies

Constitution & Active Spec¶

This phase honours the project constitution and the active spec throughout:

Constitution Enforcement¶

Loads .specify/memory/constitution.md constraints (when present)
Validates all architectural decisions against the constitution
Rejects plans that violate constitution principles
Documents any constitution amendments needed

Active Spec Awareness¶

Reads .design-state.yaml for the active spec and its specs_dir
References specs/[N]-feature/spec.md for requirements throughout research and planning

Output Directory¶

All artifacts are written to specs/[N]-feature/: - spec.md — specification - plan.md — implementation plan - research.md — research findings and decisions - .plan-gate.md — plan validation result (PASS/FAIL/SKIPPED) - tasks.md — task breakdown