Skip to content

vt-c-2-plan

Phase 2 - Design and architecture planning. Orchestrates the SpecKit pipeline (specify → plan → tasks) for the active spec, using the conceptual-orchestrator for research and architecture decisions.

Plugin: core-standards
Category: Development Workflow
Command: /vt-c-2-plan

Phase 2: Plan - Design & Architecture

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

Workflow Position

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

Invocation

/vt-c-2-plan                                 # Plan for the currently active spec
/vt-c-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-c-2-plan" (advisory, not blocking)

If no checkpoint exists: proceed silently.

Step 0: SpecKit Detection

IMPORTANT: Check for SpecKit setup first:

  1. If .specify/ directory exists:
  2. Load .specify/memory/constitution.md if present
  3. All planning MUST respect constitution boundaries

  4. Display: "✓ SpecKit detected - planning will respect constitution constraints"

  5. Derive active spec from branch:

  6. Check .active-spec file first (override), then parse branch name (feature/spec-NNN-* → SPEC-NNN)
  7. Look up specs_dir in .design-state.yaml specs_status for the derived SPEC-NNN
  8. If active spec found: Display: "✓ Active spec: SPEC-001 — User Authentication (from branch)"

  9. If active spec has a specs_dir: Load specs/[N]-feature/spec.md if it exists

  10. If NO .specify/ directory:

  11. Display: "⚠ No SpecKit setup found"
  12. Suggest: "For spec-driven development, initialize SpecKit with specify init . --ai claude"
  13. Ask: "Continue with standard planning, or set up SpecKit first?"

  14. If continuing without SpecKit → skip to Step 2 (standard planning)

  15. If NO active spec (no .design-state.yaml or branch doesn't match feature/spec-NNN-*):

  16. Display: "⚠ No active spec found"
  17. Suggest: "Run /vt-c-activate to select a specs for development"
  18. Ask: "Continue with standard planning for the described feature, or activate a spec first?"

Step 0.5: Project Registration Check

  1. Read TOOLKIT_ROOT/intake/projects.yaml (resolve TOOLKIT_ROOT from this skill's base directory)
  2. Check if the current working directory appears in the projects list
  3. If NOT registered and the project has a CLAUDE.md or .design-state.yaml:
  4. Ask: "This project is not registered in the toolkit. Register now to enable cross-project scanning and journal aggregation?"
  5. Options: Register now (invoke /vt-c-project-register) | Skip for now
  6. If registered: continue silently

Step 0.7: Read Deliverable Types

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

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

Step 1: Load Institutional Knowledge

Before planning, check for existing patterns:

  1. If docs/solutions/patterns/critical-patterns.md exists → Load into context
  2. If docs/solutions/ has relevant past solutions → Reference them
  3. If docs/adr/ has Architecture Decision Records → Review relevant decisions
  4. If .specify/memory/constitution.md was loaded in Step 0 → Already in context
  5. If specs/[N]-feature/decisions.md exists (from /vt-c-shape):
  6. Load into context — these are user-locked implementation decisions
  7. Display: "✓ Shaping decisions loaded from decisions.md ({N} decisions)"
  8. 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:

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

For code-only specs, most of these are already in the spec from /vt-c-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: Formalize Specification (/speckit.specify)

When SpecKit is detected and an active spec exists:

The active spec originates from Product Design as a specs (feature brief). Formalize it into the full SpecKit specification format:

  1. Read the active spec from specs/[N]-feature/spec.md (copied there by /vt-c-activate)
  2. Invoke /speckit.specify to enrich it:
  3. Add structured user stories with priorities (P1, P2, P3)
  4. Define acceptance criteria (Given/When/Then)
  5. Identify edge cases
  6. Create specs/[N]-feature/checklists/requirements.md
  7. Output: enriched specs/[N]-feature/spec.md

When no SpecKit (standard planning): Skip this step. 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 (/speckit.plan)

When SpecKit is detected:

Invoke /speckit.plan to produce the technical implementation plan using the formalized spec and research findings:

  1. Fills Technical Context section (language, dependencies, storage, testing)
  2. Validates against constitution (if exists)
  3. Resolves all "NEEDS CLARIFICATION" items
  4. Output (all in specs/[N]-feature/):
  5. plan.md — implementation plan with architecture decisions
  6. research.md — decisions, rationale, alternatives considered
  7. data-model.md — entities, fields, relationships, validation
  8. contracts/ — API schemas (OpenAPI/GraphQL)
  9. 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.

When no SpecKit (standard planning): Produce planning outputs directly: 1. Implementation Plan — Step-by-step approach 2. Architecture Decisions — Key technical choices with rationale 3. Risk Assessment — Potential issues and mitigations 4. User Flow Analysis — All paths through the feature 5. 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 SpecKit is detected and plan.md exists:

  1. Initialize loop state:

  2. iteration = 0, max_iterations = 3, previous_failures = null

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

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

  1. 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 SpecKit or no plan.md: Skip this step silently.

Step 5: Task Breakdown (/speckit.tasks)

When SpecKit is detected:

Invoke /speckit.tasks to break the plan into executable tasks:

  1. Reads spec, plan, data-model, contracts, research
  2. Organizes tasks by user story (P1 first, then P2, P3)
  3. Creates phases: Setup → Foundational → User Stories → Polish
  4. Marks parallelizable tasks with [P]
  5. 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").

When no SpecKit: Skip this step. Task breakdown happens during /vt-c-3-build.

Step 5b: Cross-Artifact Consistency Check (/speckit.analyze)

When SpecKit is detected:

After task generation, run /speckit.analyze to verify cross-artifact consistency:

  1. Invoke /speckit.analyze which checks:
  2. Spec ↔ plan alignment (requirements covered by plan steps)
  3. Plan ↔ tasks alignment (plan steps covered by tasks)
  4. Data model ↔ spec consistency (entities match requirements)
  5. Ambiguity detection (underspecified areas across all artifacts)
  6. Present findings to the user before marking planning complete
  7. If significant ambiguities found: allow user to iterate on fixes before proceeding
  8. This catches cross-artifact drift that individual validation steps miss

When no SpecKit: Skip this step.

Step 5c: Persist Plan Gate

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

  1. Derive the active spec from the branch name (feature/spec-NNN-* → SPEC-NNN)
  2. Look up specs_dir in .design-state.yaml
  3. Read specs/[N]-feature/state.yaml
  4. Add or update the plan_gate section: 
    plan_gate:
  status: COMPLETE
  date: "YYYY-MM-DD"
  artifacts: [list of files created in specs/[N]-feature/]
  5. Write the updated state.yaml
  6. Stage: git add specs/[N]-feature/state.yaml

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

When SpecKit pipeline completed:

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

Deliverables (in specs/1-user-auth/):
✓ spec.md — formalized specification with acceptance criteria
✓ plan.md — implementation plan with architecture decisions
✓ research.md — best practices and alternatives considered
✓ data-model.md — entity definitions and relationships
✓ .plan-gate.md — plan validated in N iteration(s)
✓ tasks.md — executable task breakdown by user story

Constitution: ✓ All decisions validated against .specify/memory/constitution.md

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

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

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

When standard planning (no SpecKit):

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Phase 2 Complete: Plan Created
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Deliverables:
✓ Implementation plan with prioritized steps
✓ Architecture decisions documented
✓ Risk assessment with mitigations
✓ User flows mapped
✓ Test strategy defined

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

1. /vt-c-3-build — implement the plan
2. /vt-c-4-review — mandatory security + quality review (do NOT skip)
3. Create PR after review passes

TIP: For spec-driven development, consider initializing SpecKit.
Run: specify init . --ai claude

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

SpecKit Integration

When SpecKit is detected (.specify/ directory exists), this phase orchestrates the full pipeline:

Pipeline Orchestration

/vt-c-2-plan orchestrates:
  Step 2.   /speckit.specify        → formalize feature brief into spec
  Step 3.   conceptual-orchestrator → research + architecture
  Step 4.   /speckit.plan           → technical planning
  Step 4.5. plan-checker + strategic-mentor → validate plan quality (max 3 iterations)
  Step 5.   /speckit.tasks          → task breakdown
  Step 5b.  /speckit.analyze        → cross-artifact consistency check

Constitution Enforcement

  • Loads .specify/memory/constitution.md constraints
  • Validates all architectural decisions against 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
  • Maps plan steps to spec requirements
  • Identifies gaps between spec and planned features

Output Directory

All artifacts are written to specs/[N]-feature/: - spec.md — enriched specification - plan.md — implementation plan - research.md — research findings and decisions - data-model.md — entity definitions - contracts/ — API schemas - .plan-gate.md — plan validation result (PASS/FAIL/SKIPPED) - tasks.md — task breakdown - checklists/ — quality validation checklists