UltraPlan Skill

Single-command planning pipeline: /ultraplan [idea]

Orchestrates 6 phases: UNDERSTAND --> RESEARCH --> PLAN --> REVIEW --> VALIDATE --> OUTPUT

Also supports: /ultraplan update and /ultraplan status

CRITICAL: First Actions

BEFORE doing anything else, follow these steps in exact order:

1. Detect Command Variant

Parse the user's input to determine which command was invoked:

• •/ultraplan [idea text] --> Main pipeline (go to Step 2)
• •/ultraplan update --> Update mode (jump to "UPDATE COMMAND" section at bottom)
• •/ultraplan status --> Status mode (jump to "STATUS COMMAND" section at bottom)

2. Print Intro Banner

Print this immediately:

================================================================
ULTRAPLAN: From Idea to AI-Executable Plan
================================================================
UNDERSTAND --> RESEARCH --> PLAN --> REVIEW --> VALIDATE --> OUTPUT

Your idea will go through 6 phases:
  Phase 1: UNDERSTAND  - Thorough discovery questions (40-70 questions)
  Phase 2: RESEARCH    - Parallel research on best approaches
  Phase 3: PLAN        - PRD + technical plan with executable sections
  Phase 4: REVIEW      - Self-review + refinement questions
  Phase 5: VALIDATE    - Requirement traceability verification
  Phase 6: OUTPUT      - Final deliverables + summary

All output will be saved to: .ultraplan/
================================================================

3. Store Plugin Root

Determine {plugin_root} by locating the directory containing this SKILL.md file. The plugin root is two levels up from the SKILL.md location (i.e., the ultraplan/ directory that contains skills/, agents/, hooks/, etc.).

Store {plugin_root} for use throughout the workflow. All reference file paths use this variable.

4. Detect Existing .ultraplan/ Directory (Resume Detection)

Check if .ultraplan/ directory exists in the current working directory.

If .ultraplan/ does NOT exist:

• •This is a fresh run
• •Create the .ultraplan/ directory and .ultraplan/sections/ subdirectory
• •Initialize .ultraplan/STATE.md using the template from {plugin_root}/skills/ultraplan/templates/state.md
• •Set the idea text from the user's input into STATE.md
• •Proceed to Phase 1

If .ultraplan/ DOES exist:

• •Read .ultraplan/STATE.md to determine current position
• •Print resume information:

================================================================
EXISTING PLAN DETECTED
================================================================
Resuming from: Phase {N}/6 - {PHASE_NAME}
Last activity: {last_activity from STATE.md}

To start fresh, delete the .ultraplan/ directory and re-run.
================================================================

• •Apply resume logic (see Resume Behavior in each phase below)
• •Skip to the appropriate phase based on what files exist:
  • •.ultraplan/DISCOVERY.md exists AND is complete (all 9 categories) --> Skip Phase 1
  • •.ultraplan/RESEARCH.md exists --> Skip Phase 2
  • •.ultraplan/sections/ contains section files --> Skip Phase 3
  • •.ultraplan/PLAN.md contains "Review Notes" section --> Skip Phase 4
  • •.ultraplan/VALIDATE.md exists --> Skip Phase 5
  • •.ultraplan/SUMMARY.md exists --> Already complete, show completion banner

If DISCOVERY.md exists but is incomplete (not all 9 categories covered), resume Phase 1 from the next uncovered category.

If PRD.md exists but no section files exist, resume Phase 3 from Step 3b (technical plan generation).

5. Validate Idea Input

If this is a fresh run (not resume), verify the user provided an idea:

• •If the user typed just /ultraplan with no idea text:

================================================================
ULTRAPLAN: Idea Required
================================================================

Please provide your idea in plain English. Examples:

  /ultraplan I want to build a recipe sharing app
  /ultraplan Build me a task management tool with team features
  /ultraplan Create an online store for handmade jewelry

Just describe what you want to build - no technical knowledge needed!
================================================================

Do not continue. Wait for user to re-invoke with an idea.

• •If idea text is present: record it in STATE.md and proceed to Phase 1.

Phase 1: UNDERSTAND

Purpose: Exhaustively gather requirements through structured questioning.

Progress format: Phase 1/6: UNDERSTAND [===== ] 45% - Category: Edge Cases (6/9 categories)

Before Starting

Read {plugin_root}/skills/ultraplan/references/understand-protocol.md for detailed question examples and category guidance.

Step 1.1: Codebase Detection

Scan the current project directory for existing code:

• •Look for: package.json, requirements.txt, go.mod, Cargo.toml, *.csproj, pubspec.yaml, Gemfile, pom.xml, build.gradle, or any src/, app/, lib/ directories
• •Look for: .git/ directory, README files, configuration files

If codebase exists:

• •Analyze the tech stack, frameworks, patterns, and conventions
• •Note findings for use in questions (e.g., "I see you're using React + Supabase. Should this feature follow the same patterns?")
• •Category 6 (Existing Patterns) will be heavily used
• •Record codebase analysis in a variable for use throughout Phase 1

If no codebase (greenfield):

• •Skip Category 6 (Existing Patterns) entirely
• •Add greenfield-specific questions about tech stack preferences to Category 7 (Preferences & Tradeoffs)
• •Note this is a greenfield project

Step 1.2: Initialize Discovery Document

Create .ultraplan/DISCOVERY.md with header:

# UltraPlan Discovery

## Project Idea
[User's original idea text]

## Codebase Context
[Greenfield / Existing codebase summary]

## Discovery Q&A

<!-- Categories: 9 total -->
<!-- Progress is tracked per category -->

Step 1.3: Run Question Loop

Execute the question loop across all 9 categories. For each category:

Categories (must cover ALL 9):

For each category:

1. •Ask questions in batches of 2-4 related questions per AskUserQuestion call
2. •Every question MUST use AskUserQuestion with multiple-choice options:
   • •First option is always the recommended choice, marked "(Recommended)"
   • •Include 2-4 options total
   • •Always include an "Other (let me describe)" option as the last choice
   • •Use plain English, zero technical jargon
3. •After each user response, evaluate:
   • •If the answer is complex or ambiguous: ask 1-2 follow-up questions to go deeper
   • •If the answer is clear and simple: move to the next question
4. •After each batch: append the Q&A to .ultraplan/DISCOVERY.md under the current category heading
5. •Show progress indicator after each batch:
   code

   Phase 1/6: UNDERSTAND [=====     ] {pct}% - Category: {category_name} ({N}/9 categories)
   

Question count enforcement:

• •Target: 40-70 questions total across all categories
• •System MUST NOT stop early unless user explicitly says "enough", "stop", or "move on"
• •Aim for 4-8 questions per category (varies by complexity)
• •If approaching 40 questions and not all categories are covered, reduce remaining category depth but still cover them

Early stop handling:

• •If user says "enough", "stop", or "move on":
  1. •Summarize what has been gathered so far
  2. •List which categories were NOT fully covered
  3. •Append a "Gaps & Skipped Categories" section to DISCOVERY.md
  4. •Proceed to Phase 2

Step 1.4: Finalize Discovery

After all 9 categories are covered (or user triggered early stop):

1. •Append a summary section to .ultraplan/DISCOVERY.md:

## Discovery Summary
- Total questions asked: {count}
- Categories fully covered: {list}
- Categories partially covered: {list}
- Categories skipped: {list}
- Key themes identified: {bullet list}

1. •

   Update .ultraplan/STATE.md:

   • •Phase: 2 of 6
   • •Status: in_progress
   • •Last activity: Phase 1 UNDERSTAND complete: {N} questions, {M}/9 categories
2. •

   Print:

Phase 1/6: UNDERSTAND [==========] 100% - COMPLETE
{N} questions asked across {M} categories.
Proceeding to Phase 2: RESEARCH...

Resume Behavior (Phase 1)

If .ultraplan/DISCOVERY.md exists when resuming:

• •Read the file
• •Count which categories have Q&A content
• •Identify the last completed category
• •Resume from the NEXT category
• •Print: Resuming Phase 1: UNDERSTAND - picking up from Category {N}: {name}

Phase 2: RESEARCH

Purpose: Investigate solutions, best practices, and technical approaches based on discovery findings.

Progress format: Phase 2/6: RESEARCH [=== ] 30% - Launching subagents...

Before Starting

Read {plugin_root}/skills/ultraplan/references/research-protocol.md for detailed research guidance.

Step 2.1: Extract Research Topics

1. •Read .ultraplan/DISCOVERY.md
2. •Auto-extract research topics:
   • •Technologies mentioned or implied
   • •Patterns and approaches needed
   • •Integrations required (payment, auth, email, etc.)
   • •Competitor or similar products mentioned
   • •Tech stack decisions that need research
3. •No user input needed for topic selection

Print:

Phase 2/6: RESEARCH [==        ] 20% - Topics extracted
Research topics identified:
  - {topic 1}
  - {topic 2}
  - ...

Launching parallel research subagents...

Step 2.2: Launch Parallel Research Subagents

Spawn 3 subagents simultaneously in a SINGLE message (all 3 Task tool calls in one response):

Subagent 1: Codebase Researcher

• •Tool: Task with subagent_type="Explore" (if codebase exists)
• •Tool: Task with general purpose (if greenfield -- do tech stack comparison instead)
• •Prompt: Include the research topics, discovery summary, and specific questions about code patterns
• •If codebase exists: "Analyze the existing codebase for patterns, conventions, file structure, tech stack, and any relevant existing implementations that relate to: {topics}"
• •If greenfield: "Compare 2-3 tech stack options for building {idea}. For each option, provide pros, cons, learning curve, and community support. Also find 3-5 similar products and analyze their approach."

Subagent 2: Web Researcher

• •Tool: Task with general purpose
• •Prompt: "Research current best practices, common approaches, and ecosystem state for: {topics}. Search the web for recent articles, tutorials, and community discussions. Focus on practical, proven approaches suitable for a project built by AI."

Subagent 3: Docs Researcher

• •Tool: Task with general purpose
• •Prompt: "Use Context7 MCP (resolve-library-id first, then get-library-docs) to fetch current documentation for these technologies: {tech list from topics}. Focus on: setup guides, key APIs, integration patterns, and any gotchas or breaking changes."

IMPORTANT: Launch all 3 in a single message so they run in parallel. Do NOT wait for one to finish before starting the next.

Step 2.3: Collect and Write Research

After all 3 subagents complete:

1. •Combine their findings into .ultraplan/RESEARCH.md using the template from {plugin_root}/skills/ultraplan/templates/research.md
2. •Organize by topic area, not by subagent
3. •Include:
   • •Tech stack analysis and recommendation
   • •Best practices found
   • •Competitor insights (if greenfield)
   • •Library recommendations with sources
   • •Relevant code patterns from existing codebase (if applicable)

Print:

Phase 2/6: RESEARCH [=======   ] 70% - Research collected. Checking for conflicts...

Step 2.4: Conflict Detection

Compare research findings against user's discovery answers:

• •

  If research contradicts any user preference or assumption:

  • •For each conflict, use AskUserQuestion:
    • •Question: "Research finding vs. your preference: {plain English description of conflict}"
    • •Options:
      • •"Keep my original choice"
      • •"Switch to the researched alternative (Recommended)" (only mark recommended if research strongly supports it)
      • •"Let me think about this"
  • •Record each resolution in RESEARCH.md
• •

  If no conflicts found: note "No conflicts detected between discovery and research."

Step 2.5: User Review of Research

Present a plain-English summary of key research findings (5-10 bullet points, no jargon).

Use AskUserQuestion:

• •Question: "Here's what our research found. Does this align with your vision?"
• •Options:
  • •"Looks good, proceed to planning (Recommended)"
  • •"Research more on a specific topic"
  • •"I have concerns about some findings"

If user wants more research: ask which topic, spawn another subagent for that topic only, then re-present.

If user has concerns: ask follow-up questions to understand, update RESEARCH.md.

Step 2.6: Finalize Research

1. •

   Ensure .ultraplan/RESEARCH.md is complete and saved

2. •

   Update .ultraplan/STATE.md:

   • •Phase: 3 of 6
   • •Status: in_progress
   • •Last activity: Phase 2 RESEARCH complete: 3 subagents, {N} topics researched
3. •

   Print:

Phase 2/6: RESEARCH [==========] 100% - COMPLETE
Proceeding to Phase 3: PLAN...

Resume Behavior (Phase 2)

If .ultraplan/RESEARCH.md exists: skip entirely to Phase 3.

Phase 3: PLAN

Purpose: Create a human-readable PRD and AI-executable technical plan with sections.

Progress format: Phase 3/6: PLAN - PRD Section 4/10: What It Does

Before Starting

Read {plugin_root}/skills/ultraplan/references/prd-writing.md for PRD generation rules. Read {plugin_root}/skills/ultraplan/references/plan-writing.md for technical plan generation rules.

Step 3a: Generate PRD (Section-by-Section with User Approval)

Generate the PRD one section at a time, getting user approval for each section before moving to the next.

PRD Sections (10 total):

For each PRD section:

1. •Generate the section content (200-300 words) using:
   • •DISCOVERY.md answers as primary source
   • •RESEARCH.md findings as supporting context
   • •Plain English, ZERO jargon (see prd-writing.md for rules)
2. •Present the section to the user via AskUserQuestion:
   • •Question: "Here's the '{section_name}' section of your PRD:\n\n{section_content}\n\nDoes this look right?"
   • •Options:
     • •"Looks right, move on (Recommended)"
     • •"Change this part"
     • •"Remove this section"
     • •"Add something to this"
3. •Handle responses:
   • •"Looks right": Move to next section
   • •"Change this part": Ask what to change, regenerate section, re-present for approval
   • •"Remove this section": Note removal, move to next
   • •"Add something": Ask what to add, regenerate, re-present
4. •After approval, append section to .ultraplan/PRD.md
5. •Show progress:
   code

   Phase 3/6: PLAN - PRD Section {N}/10: {section_name}
   

After all PRD sections are approved, write the final .ultraplan/PRD.md using the template from {plugin_root}/skills/ultraplan/templates/prd.md.

Print:

Phase 3/6: PLAN [====      ] 40% - PRD complete. Generating technical plan...

Step 3b: Generate Technical Plan

Read {plugin_root}/skills/ultraplan/references/plan-writing.md for constraints and format rules. Read {plugin_root}/skills/ultraplan/references/xml-task-format.md for XML task schema.

Step 3b.1: Derive Sections from PRD

1. •Analyze the approved PRD features
2. •Derive technical implementation sections - each is a self-contained implementation unit
3. •Order sections by dependency:
   • •Independent sections grouped into parallel batches
   • •Dependent sections ordered sequentially
4. •Assign risk ratings to each section:
   • •green: Straightforward, well-understood patterns
   • •yellow: Some complexity, may need iteration
   • •red: High uncertainty, novel approach, critical path, security-sensitive
   • •Risk factors: complexity, dependencies, security sensitivity, third-party reliance

Step 3b.2: Write Section Index

Create .ultraplan/sections/index.md with a manifest of all sections:

# Section Index

## Overview
Total sections: {N}
Total tasks: {M}
Parallel batches: {X}

## Batch Execution Order

### Batch 1 (parallel)
- Section 01: {name} [green/yellow/red]
- Section 02: {name} [green/yellow/red]

### Batch 2 (parallel, depends on Batch 1)
- Section 03: {name} [green/yellow/red]

...

## Section Manifest

| # | Section | Risk | Batch | Depends On | Blocks |
|---|---------|------|-------|------------|--------|
| 01 | {name} | green | 1 | none | 03, 04 |
| 02 | {name} | yellow | 1 | none | 05 |
| 03 | {name} | green | 2 | 01 | 06 |
...

Step 3b.3: Write Individual Section Files

For each section, create .ultraplan/sections/section-{NN}-{slug}.md using the template from {plugin_root}/skills/ultraplan/templates/section.md.

Each section file MUST contain:

# Section {NN}: {Name}

## Overview
[Plain English description of what this section builds]

## Risk: [{green/yellow/red}] - {one-line risk summary}

## Dependencies
- Depends on: {none / section-XX}
- Blocks: {section-XX, section-YY}
- Parallel batch: {batch number}

## TDD Test Stubs
- Test: {human-readable test description}
- Test: {human-readable test description}
- Test: {human-readable test description}
...

## Tasks

<task type="auto" id="{NN}-01">
  <name>{task name}</name>
  <files>{file paths this task touches}</files>
  <action>
    {Step-by-step instructions for what to implement.
    Written for an AI coding tool to execute.
    Clear, specific, no ambiguity.}
  </action>
  <verify>{How to verify this task is done correctly}</verify>
  <done>{Definition of done - what state the code should be in}</done>
</task>

<task type="auto" id="{NN}-02">
  ...
</task>

Task granularity rules:

• •Each task touches 1-3 files maximum
• •Each task represents roughly one git commit of work
• •Each task has: name, files, action, verify, done
• •Tasks within a section are ordered sequentially
• •Action text is written for an AI coding tool (clear instructions, no jargon)

Step 3b.4: Write Master Plan

Create .ultraplan/PLAN.md using the template from {plugin_root}/skills/ultraplan/templates/plan.md:

• •Architecture overview
• •Tech stack (from research)
• •Section index reference
• •Dependency graph (text-based)
• •Parallel batch execution order
• •Total section and task counts

Step 3b.5: Finalize Phase 3

1. •

   Update .ultraplan/STATE.md:

   • •Phase: 4 of 6
   • •Status: in_progress
   • •Last activity: Phase 3 PLAN complete: {N} sections, {M} tasks, PRD approved
2. •

   Print:

Phase 3/6: PLAN [==========] 100% - COMPLETE
PRD: 10 sections approved
Technical Plan: {N} sections, {M} tasks, {X} parallel batches
Proceeding to Phase 4: REVIEW...

Resume Behavior (Phase 3)

• •If .ultraplan/PRD.md exists but .ultraplan/sections/ is empty: resume from Step 3b
• •If .ultraplan/sections/ contains section files: skip to Phase 4

Phase 4: REVIEW

Purpose: Critical self-review of the plan + non-obvious refinement questions.

Progress format: Phase 4/6: REVIEW [==== ] 40% - Running checklist: Security (4/8)

Before Starting

Read {plugin_root}/skills/ultraplan/references/review-checklist.md for the 8-category quality checklist details.

Step 4a: Self-Review Checklist

Run the 8-category quality checklist against ALL plan documents (PRD.md, PLAN.md, all section files):

For each category:

1. •Review all relevant documents
2. •Log findings: issues found, severity (minor/major/critical)
3. •Auto-fix where possible:
   • •Missing error handling task --> add a task to the relevant section
   • •Missing input validation --> add validation step to relevant task
   • •Inconsistent naming --> standardize across sections
4. •Flag issues that require user decision (cannot auto-fix)
5. •Show progress:
   code

   Phase 4/6: REVIEW [===       ] {pct}% - Checklist: {category} ({N}/8)
   

Step 4b: Show Review Summary

Present results to user in plain English:

================================================================
REVIEW RESULTS
================================================================
Issues found:  {total}
Auto-fixed:    {auto_fixed_count}
Need decision: {needs_decision_count}

Category Breakdown:
  [pass] Completeness: No issues
  [pass] Consistency: 1 minor issue (auto-fixed)
  [WARN] Feasibility: 2 issues (1 auto-fixed, 1 needs your input)
  [pass] Security: No issues
  [pass] Scalability: No issues
  [WARN] Edge Cases: 3 issues (2 auto-fixed, 1 needs your input)
  [pass] User Experience: No issues
  [pass] Cost & Complexity: No issues
================================================================

If there are issues needing user decision, present each one via AskUserQuestion:

• •Question: "{plain English description of the issue and why it matters}"
• •Options: Contextual options relevant to the specific issue + "Skip this for now"

Step 4c: User Refinement Questions (Interview-Me Style)

Ask 5-10 NON-OBVIOUS questions the user probably did not think about. These are derived from:

• •Gaps found during self-review
• •Tricky edge cases specific to their product
• •UX details that matter but are easy to miss

Format: AskUserQuestion with multiple-choice options + "(Recommended)" on first option.

Example questions:

• •"What happens if a user uploads a 50MB recipe photo? Should there be a size limit?"
• •"If two users edit the same recipe at the same time, who wins?"
• •"Should deleted recipes be permanently gone or recoverable for 30 days?"
• •"If payment fails mid-checkout, should the cart be saved or reset?"
• •"What happens when a user's internet connection drops while they're filling out a long form?"

Step 4d: Update Plan with Review Findings

1. •Integrate auto-fixes and user answers into affected section files
2. •Re-run a quick consistency check on modified sections only (not full 8-category again)
3. •Append "Review Notes" section to .ultraplan/PLAN.md:

## Review Notes

### Review Date: {date}

### Self-Review Results
- Total issues found: {N}
- Auto-fixed: {M}
- User decisions: {K}

### Category Results
{table of pass/warn/fail per category}

### Refinement Questions Asked
{list of questions and user answers}

### Sections Modified
{list of sections that were updated and what changed}

Step 4e: Finalize Phase 4

1. •

   Update .ultraplan/STATE.md:

   • •Phase: 5 of 6
   • •Status: in_progress
   • •Last activity: Phase 4 REVIEW complete: {N} issues found, {M} auto-fixed, {K} user decisions
2. •

   Print:

Phase 4/6: REVIEW [==========] 100% - COMPLETE
{N} issues found, {M} auto-fixed, {K} resolved by you.
{J} refinement questions answered.
Proceeding to Phase 5: VALIDATE...

Resume Behavior (Phase 4)

If .ultraplan/PLAN.md contains a "Review Notes" section: skip to Phase 5.

Phase 5: VALIDATE

Purpose: Cross-reference alignment: verify every discovery requirement traces to a plan section and vice versa.

Progress format: Phase 5/6: VALIDATE [====== ] 60% - Building traceability matrix...

Before Starting

Read {plugin_root}/skills/ultraplan/references/validate-protocol.md for traceability rules.

Step 5.1: Build Traceability Matrix

1. •Read .ultraplan/DISCOVERY.md: extract every distinct requirement and user answer that implies a feature or behavior
2. •Read all .ultraplan/sections/section-*.md files: extract every task ID and its purpose
3. •Read .ultraplan/PRD.md: extract each feature listed in "What It Does" and other sections
4. •Build the mapping:

Requirement (from Discovery) --> PRD Section --> Plan Section --> Task IDs

1. •Identify:
   • •Unmapped requirements: Requirements from discovery that do NOT trace to any task
   • •Unmapped tasks: Tasks that do NOT trace to any discovery requirement (potential scope creep)

Print:

Phase 5/6: VALIDATE [====      ] 40% - Traceability matrix built
  Requirements found: {N}
  Tasks found: {M}
  Fully covered: {K}
  Gaps detected: {G}
  Potential scope creep: {S}

Step 5.2: Resolve Gaps

For each unmapped requirement, use AskUserQuestion:

• •Question: "Your requirement '{requirement description}' from discovery isn't covered in the plan. What should we do?"
• •Options:
  • •"Add it as a new section (Recommended)"
  • •"Merge it into an existing section"
  • •"It was actually out of scope, skip it"
  • •"I changed my mind, remove it"

If user picks "Add as new section": create a new section file and update the index. If user picks "Merge into existing": ask which section, add tasks to that section.

Step 5.3: Resolve Scope Creep

For each unmapped task (task exists but no matching requirement), use AskUserQuestion:

• •Question: "The plan includes '{task description}' but you didn't specifically ask for it. It was added because {reason}. Keep or remove?"
• •Options:
  • •"Keep it, it's needed (Recommended)" (if it supports a related requirement)
  • •"Remove it"

If user says remove: delete the task from its section file. If the section becomes empty, remove the section and update the index.

Step 5.4: Generate Traceability Table

Write .ultraplan/VALIDATE.md using the template from {plugin_root}/skills/ultraplan/templates/validate.md:

# Traceability Matrix

## Summary
- Total requirements from discovery: {N}
- Total tasks in plan: {M}
- Requirements fully covered: {K}
- Requirements partially covered: {P}
- Requirements excluded (user choice): {E}
- Tasks added beyond requirements (approved): {A}

## Requirement-to-Task Mapping

| # | Requirement (from Discovery) | PRD Section | Plan Section | Task IDs | Status |
|---|------------------------------|-------------|--------------|----------|--------|
| 1 | {requirement} | {prd section} | section-{NN} | {NN}-01, {NN}-02 | Covered |
| 2 | {requirement} | {prd section} | section-{NN} | {NN}-01 | Covered |
| 3 | {requirement} | {prd section} | -- | -- | Excluded (user choice) |
...

## Gap Resolution Log
| # | Gap Type | Description | Resolution | Date |
|---|----------|-------------|------------|------|
| 1 | Missing requirement | {desc} | Added to section-{NN} | {date} |
| 2 | Scope creep | {desc} | Kept (user approved) | {date} |
...

Step 5.5: Final User Approval

Present the traceability summary to the user via AskUserQuestion:

• •Question: "All requirements have been verified against the plan. {N} requirements covered, {E} excluded by your choice. Ready to generate final output?"
• •Options:
  • •"Yes, finalize the plan (Recommended)"
  • •"I want to add something"
  • •"I want to change something"

If user wants to add/change: handle the addition/change, update affected files, re-validate the changed portion only, then ask again.

Step 5.6: Finalize Phase 5

1. •

   Update .ultraplan/STATE.md:

   • •Phase: 6 of 6
   • •Status: in_progress
   • •Last activity: Phase 5 VALIDATE complete: {N} requirements traced, {E} excluded
2. •

   Print:

Phase 5/6: VALIDATE [==========] 100% - COMPLETE
All requirements verified. Proceeding to Phase 6: OUTPUT...

Resume Behavior (Phase 5)

If .ultraplan/VALIDATE.md exists: skip to Phase 6.

Phase 6: OUTPUT

Purpose: Produce all final deliverable files and present completion summary.

Progress format: Phase 6/6: OUTPUT [======== ] 80% - Writing summary...

Before Starting

Read {plugin_root}/skills/ultraplan/references/output-format.md for file format specifications.

Step 6.1: Finalize All Files

Ensure every output file exists and is internally consistent:

1. •.ultraplan/PRD.md - Verify complete (should exist from Phase 3)
2. •.ultraplan/PLAN.md - Verify includes Review Notes (from Phase 4)
3. •.ultraplan/RESEARCH.md - Verify complete (from Phase 2)
4. •.ultraplan/DISCOVERY.md - Verify complete (from Phase 1)
5. •.ultraplan/VALIDATE.md - Verify complete (from Phase 5)
6. •.ultraplan/sections/index.md - Verify section count matches actual files
7. •.ultraplan/sections/section-*.md - Verify all listed in index exist

Fix any inconsistencies found (e.g., index references a section that doesn't exist).

Step 6.2: Generate SUMMARY.md

Create .ultraplan/SUMMARY.md using the template from {plugin_root}/skills/ultraplan/templates/summary.md:

# UltraPlan Summary

## What We're Building
[3 sentences from PRD "What We're Building" section]

## Key Features
- [Bullet list of top features from PRD "What It Does"]

## Tech Stack
- [Recommended stack from RESEARCH.md]

## Risk Areas
- [{color}] {risk description}
- [{color}] {risk description}

## Plan Structure
- {N} sections, {M} total tasks
- {X} parallel batches
- {Y} sequential dependencies

## How to Execute This Plan
1. Open any AI coding tool (Claude Code, Cursor, etc.)
2. Share the .ultraplan/ folder
3. Say: "Read .ultraplan/sections/index.md and execute section 1"
4. After each section completes, say: "Execute section [next]"
5. Sections in the same batch can be run in parallel

## How to Update This Plan
Run: /ultraplan update
Describe what changed, and only affected sections will be regenerated.

Step 6.3: Finalize STATE.md

Update .ultraplan/STATE.md to completion state:

# UltraPlan State

## Current Position
Phase: 6 of 6
Status: complete
Last activity: {date} - Plan finalized

## Progress
[==========] Phase 6/6: OUTPUT - COMPLETE

## Session History
| Date | Action | Details |
|------|--------|---------|
| {date} | Created | /ultraplan {idea} |
| {date} | Phase 1 | UNDERSTAND complete: {N} questions, {M}/9 categories |
| {date} | Phase 2 | RESEARCH complete: 3 subagents, {topics} researched |
| {date} | Phase 3 | PLAN complete: PRD approved, {N} sections, {M} tasks |
| {date} | Phase 4 | REVIEW complete: {issues} issues, {fixed} auto-fixed |
| {date} | Phase 5 | VALIDATE complete: {reqs} requirements traced |
| {date} | Phase 6 | OUTPUT complete: all files finalized |

## Change Log (from /ultraplan update)
| Date | What Changed | Sections Affected |
|------|-------------|-------------------|
| (none yet) |

Step 6.4: Present Completion

Print the completion banner:

================================================================
ULTRAPLAN COMPLETE
================================================================

Your plan is ready! Here's what was created:

.ultraplan/
  PRD.md          - Your product requirements (plain English)
  PLAN.md         - Technical implementation plan
  RESEARCH.md     - Research findings
  DISCOVERY.md    - Complete Q&A transcript
  VALIDATE.md     - Requirement traceability matrix
  STATE.md        - Session state (for resume/updates)
  SUMMARY.md      - One-page cheat sheet
  sections/
    index.md      - Section manifest
    section-01-*  - {section 1 name} [{risk color}]
    section-02-*  - {section 2 name} [{risk color}]
    ...

Total: {N} sections, {M} tasks

----------------------------------------------------------------
WHAT TO DO NEXT
----------------------------------------------------------------

To start building:
  Give the .ultraplan/ folder to any AI coding tool and say:
  "Read .ultraplan/sections/index.md and execute section 1"

To update this plan:
  Run: /ultraplan update

To view the summary:
  Read: .ultraplan/SUMMARY.md
================================================================

Resume Behavior (Phase 6)

If .ultraplan/SUMMARY.md exists: the plan is already complete. Show the completion banner again and remind about /ultraplan update.

UPDATE COMMAND

Triggered by: /ultraplan update

Before Starting

1. •Check if .ultraplan/ directory exists. If not:

================================================================
ULTRAPLAN: No Plan Found
================================================================
No .ultraplan/ directory found. Run /ultraplan [your idea] first.
================================================================

Stop and wait.

1. •Check if .ultraplan/STATE.md shows "complete" status. If not:

================================================================
ULTRAPLAN: Plan Not Complete
================================================================
Your plan is still in progress (Phase {N}/6).
Run /ultraplan to continue, or delete .ultraplan/ to start fresh.
================================================================

Stop and wait.

1. •Read {plugin_root}/skills/ultraplan/references/update-protocol.md for detailed update behavior.

Step U.1: Ask What Changed

Use AskUserQuestion:

• •Question: "What changed about your plan? Pick the type of change:"
• •Options:
  • •"Add a new feature"
  • •"Remove a feature"
  • •"Change how something works"
  • •"Change priorities or ordering"
  • •"Other (let me describe)"

Step U.2: Gather Change Details

Based on the change type, ask 5-10 follow-up questions via AskUserQuestion to understand the specific change. Use plain English, multiple choice with recommendations.

Step U.3: Identify Affected Sections

1. •Read all section files and the PRD
2. •Determine which sections are affected by the change
3. •Present to user:

Affected sections:
  - Section {NN}: {name} - {reason for change}
  - Section {MM}: {name} - {reason for change}

Unchanged sections ({X} of {Y}):
  - All other sections remain exactly as they are

Step U.4: Regenerate Affected Sections ONLY

Key principle: NEVER regenerate the entire plan. Only touch what's affected.

1. •Regenerate only the affected section files
2. •Update .ultraplan/PRD.md if the change affects product requirements
3. •Update .ultraplan/sections/index.md if sections were added/removed or dependencies changed
4. •Run a quick consistency check on modified sections
5. •Update traceability in .ultraplan/VALIDATE.md for affected requirements

Step U.5: Log the Change

Update .ultraplan/STATE.md Change Log:

| {date} | {change description} | section-{NN}, section-{MM} |

Step U.6: Show Update Summary

================================================================
ULTRAPLAN UPDATE COMPLETE
================================================================
Changed: {list of changed sections}
Added:   {list of new sections, if any}
Removed: {list of removed sections, if any}
Unchanged: {count} sections preserved

Change logged in STATE.md.

To review changes: Read the affected section files
To update again: /ultraplan update
================================================================

STATUS COMMAND

Triggered by: /ultraplan status

Behavior

1. •Check if .ultraplan/ directory exists. If not:

No plan in progress. Run /ultraplan [your idea] to start.

Stop.

1. •Read .ultraplan/STATE.md
2. •Present current status:

================================================================
ULTRAPLAN STATUS
================================================================
{progress bar from STATE.md}

Phase: {current phase}/6 - {phase name}
Status: {in_progress / complete}
Last activity: {date} - {description}

Files:
  [exists/missing] PRD.md
  [exists/missing] PLAN.md
  [exists/missing] RESEARCH.md
  [exists/missing] DISCOVERY.md
  [exists/missing] VALIDATE.md
  [exists/missing] SUMMARY.md
  [exists/missing] sections/index.md
  [{N} files]      sections/section-*.md

Session History:
{table from STATE.md}

To continue: /ultraplan
To update:   /ultraplan update
================================================================

Resuming After Compaction

CRITICAL: When resuming this workflow after context compaction, the detailed instructions from this SKILL.md file are lost. Follow these rules:

1. •

   ALWAYS read STATE.md first to determine current position

   • •Phase tells you where you are
   • •Status tells you if the plan is complete or in-progress
   • •Last activity tells you what was done last
2. •

   ALWAYS read the reference file for your current phase before proceeding

   • •Phase 1: Read {plugin_root}/skills/ultraplan/references/understand-protocol.md
   • •Phase 2: Read {plugin_root}/skills/ultraplan/references/research-protocol.md
   • •Phase 3: Read {plugin_root}/skills/ultraplan/references/prd-writing.md AND {plugin_root}/skills/ultraplan/references/plan-writing.md
   • •Phase 4: Read {plugin_root}/skills/ultraplan/references/review-checklist.md
   • •Phase 5: Read {plugin_root}/skills/ultraplan/references/validate-protocol.md
   • •Phase 6: Read {plugin_root}/skills/ultraplan/references/output-format.md
3. •

   NEVER skip phases - follow the pipeline order exactly: UNDERSTAND --> RESEARCH --> PLAN --> REVIEW --> VALIDATE --> OUTPUT

4. •

   Use file existence to determine resume point:

   • •No DISCOVERY.md --> Start at Phase 1
   • •DISCOVERY.md exists, no RESEARCH.md --> Start at Phase 2
   • •RESEARCH.md exists, no section files --> Start at Phase 3
   • •Section files exist, PLAN.md has no "Review Notes" --> Start at Phase 4
   • •PLAN.md has "Review Notes", no VALIDATE.md --> Start at Phase 5
   • •VALIDATE.md exists, no SUMMARY.md --> Start at Phase 6
   • •SUMMARY.md exists --> Plan is complete
5. •

   Get {plugin_root} by locating this SKILL.md file - search for it if needed:

   • •It is the grandparent directory of this file
   • •Or look for a directory containing skills/ultraplan/SKILL.md
6. •

   All user interactions use AskUserQuestion with multiple-choice options

   • •First option is always the recommended choice marked "(Recommended)"
   • •Last option is always "Other" for custom input
   • •Plain English, zero jargon

Key Rules (Always Apply)

1. •

   Plain English everywhere. The target user is a no-coder. Never use technical jargon in user-facing text. Technical details go in section files (read by AI executors, not users).

2. •

   AskUserQuestion for ALL user input. Never ask open-ended questions without options. Always provide multiple-choice with a recommended first option.

3. •

   Auto-save after every batch/step. Never lose progress. Write to disk frequently.

4. •

   Progress indicators after every meaningful step. The user should always know where they are in the 6-phase pipeline.

5. •

   Non-destructive updates. The /ultraplan update command NEVER regenerates the full plan. Only affected sections are touched.

6. •

   Sections are the atomic unit. Each section is a self-contained, AI-executable implementation unit with XML tasks, TDD stubs, risk rating, and dependency info.

7. •

   Discovery is exhaustive. 40-70 questions across 9 categories. Do not stop early unless the user explicitly requests it.

8. •

   Research is parallel. Always launch 3 subagents simultaneously in a single message.

9. •

   PRD approval is incremental. One section at a time, user must approve before moving on.

10. •

    Review is self-critical. Run the 8-category checklist honestly. Auto-fix what you can, flag what you cannot.

11. •

    Validation is bidirectional. Check requirements-to-tasks AND tasks-to-requirements. Catch both gaps and scope creep.

12. •

    State is always saved. STATE.md is the source of truth for resume. Update it at every phase transition.