gh-kasperjunge-30-minute-vibe-coding-challenge-plugins-spec-driven-development/commands/create_plan.md

Create Implementation Plan

Creates detailed implementation plan based on requirements and design specifications.

Initial Setup

Respond with:

I'm ready to create an implementation plan.

I'll read your requirements from spec/requirements.md and design from spec/design.md to create a detailed plan.

Then proceed to read documents and generate plan.

Workflow

1. Read spec/requirements.md FULLY
2. Read spec/design.md FULLY
3. Generate implementation plan at spec/plan.md with:
   • 3-5 phases, each with specific tasks
   • Every task has: file paths, code structure, test requirements, verification steps, success criteria
   • Map tasks to user stories from requirements
   • Clear scope boundaries

Planning Strategy

UI-First Planning Approach

When to use: Use UI-first planning unless there's no UI involved (e.g., pure API, CLI tool, library, data pipeline).

Why UI-First matters:

The traditional backend-first approach (database → API → UI) has a critical flaw: you don't see or interact with anything until late in the process. This causes:

• Late discovery of design misalignments - Costly to fix after backend is built
• Loss of momentum - Abstract data models feel like slow progress
• Inability to verify direction - Can't know if it's right until you see it

UI-first solves this by:

• Immediate visual verification - See the UI running with mock data early, giving confidence about direction
• Catch misunderstandings early - Find issues when UI is easy to adjust, not after complex data layer is built
• Better data model design - Building UI first reveals what data shapes actually make sense
• Maintains energy - Working interactive UI (even with fake data) keeps momentum high
• Easier iteration - Refine UX freely with mocks, then build backend to support validated design

Key insight: UI with mock data is cheap to change. Backend with real data/APIs is expensive to change. So validate the expensive part by building the cheap part first.

Example phase structure (adapt to project needs, this is inspiration not a strict template):

• Phase 1: Project Setup & UI Shell - Initialize project, setup dev tools, create basic app shell, verify dev server runs and shows basic UI
• Phase 2: Complete UI with Mock Data - Implement ALL UI components with hardcoded/mock data, make it fully interactive and navigable
• Phase 3: Data Layer & Backend - Build database/storage, API endpoints, business logic, backend tests
• Phase 4: Integration - Replace mocks with real data, connect UI to backend, handle loading/error states
• Phase 5: Polish & Testing - Edge cases, error handling, final acceptance criteria verification

Backend-First Planning Approach

When to use: Projects with no user interface (REST APIs, CLI tools, libraries, background services, data pipelines).

Planning approach: Structure phases around core functionality, data model, API contracts, and verification strategies appropriate for non-UI projects.

Guidelines

• Detect if project has a UI based on design.md
• If UI exists: Use UI-first planning approach (see above for reasoning)
• If no UI: Use appropriate structure for that project type (backend-first)
• The 5-phase UI-first structure is an example for inspiration - adapt to project needs
• Key principle for UI projects: See working UI with mocks early → build backend → integrate
• Be specific: every task needs concrete file paths and line numbers
• Every task MUST have:
  • Test Requirements section
  • Verification Steps section
  • Success criteria (what tests to run, what to verify)
• Break work into 3-5 discrete phases
• Each phase should be independently verifiable
• Order matters - explain why phases come in sequence
• Map tasks to specific user stories from requirements.md
• Include "What We're NOT Doing" section to prevent scope creep
• Plan should be detailed enough to execute mechanically

Chat Output Format

After completing plan:

I've created a detailed implementation plan at spec/plan.md.

The plan includes:
- [X] phases with specific tasks
- File paths and code structures from design.md
- Acceptance criteria from requirements.md
- Clear verification checklist

Please review and let me know if you'd like any adjustments.

File Output Format

Create spec/plan.md:

# Implementation Plan: [Project Name]

## Overview
[1-2 sentence summary of what we're building based on requirements and design]

## Current State
- Empty project / Starting from scratch
- Target tech stack: [From design.md]

## Desired End State
[Clear description of what "done" looks like, referencing requirements]

**Success Criteria:**
- [ ] All user stories from requirements.md are implemented
- [ ] All acceptance criteria are met
- [ ] Application matches design specifications
- [ ] Code is tested and runs without errors

## What We're NOT Doing
[Explicitly list out-of-scope items from requirements.md]

## Implementation Approach
[High-level strategy: which phases, why this order, key dependencies]

---

## Phase 1: Project Setup & Foundation

### Overview
Set up the development environment and project structure according to design specifications.

### Tasks

#### 1.1 Initialize Project
**Action**:
- Create project using [tool, e.g., "Vite", "Create React App"]
- Install dependencies listed in design.md
- Set up file structure from design.md

**Files Created**:
- `package.json` / `requirements.txt` / [dependency file]
- `src/` directory structure
- Configuration files (tsconfig.json, vite.config.js, etc.)

**Success Criteria**:
- [ ] Project builds without errors: `[build command]`
- [ ] Dev server starts: `[dev command]`
- [ ] All dependencies installed correctly

#### 1.2 Setup Development Tools
**Action**:
- Configure linting and formatting
- Set up testing framework
- Add scripts to package.json

**Success Criteria**:
- [ ] Linter runs: `[lint command]`
- [ ] Formatter works: `[format command]`
- [ ] Test runner works: `[test command]`

---

## Phase 2: Data Layer

### Overview
Implement data models, storage, and state management as defined in design.md.

### Tasks

#### 2.1 Define Data Models
**File**: `src/types/index.ts` (or equivalent)
**Action**:
- Implement [Entity1] interface from design.md
- Implement [Entity2] interface from design.md
- Add type exports

**Code Structure**:
```typescript
interface Entity1 {
  id: string;
  field1: string;
  // ... from design
}

Test Requirements:

• Write tests to verify type definitions are correct
• Test type safety with valid and invalid data
• Tests pass: npm run typecheck or equivalent

Verification Steps:

1. Run type checker: [typecheck command]
2. Verify no type errors in output
3. Expected: Clean compilation, all types defined

Success Criteria:

• All code changes completed
• Types compile without errors
• All entities from design.md are defined
• Type tests written and passing

2.2 Implement Storage Layer

File: src/utils/storage.ts (or equivalent) Action:

• Create [storage approach from design.md]
• Implement CRUD operations for each entity
• Add error handling

Functions to Implement:

• create[Entity](data: Entity): Promise<Entity>
• read[Entity](id: string): Promise<Entity>
• update[Entity](id: string, data: Partial<Entity>): Promise<Entity>
• delete[Entity](id: string): Promise<void>

Test Requirements:

• Write unit tests for each CRUD operation
• Test error handling (invalid data, not found, etc.)
• Test data persistence and retrieval
• Tests pass: [test command]

Verification Steps:

1. Run tests: [test command]
2. Verify all CRUD operations tested
3. Expected: All tests passing, 100% coverage on storage functions

Success Criteria:

• All code changes completed
• All CRUD operations implemented
• Unit tests written for all operations
• All tests passing
• Error cases handled and tested

---

Phase 3: Core Components

Overview

Build the UI components defined in design.md, focusing on core functionality first.

Tasks

3.1 Create [ComponentName] Component

File: src/components/[ComponentName].tsx (from design.md) Action:

• Implement component as specified in design.md
• Add props/interface from design
• Implement event handlers
• Add basic styling

Component Structure (from design.md):

interface ComponentProps {
  // Props from design.md
}

function ComponentName({ prop1, prop2 }: ComponentProps) {
  // Implementation
}

Implements User Story: [Reference specific user story from requirements.md]

Test Requirements:

• Write component tests (rendering, props, interactions)
• Test event handlers trigger correctly
• Test edge cases (empty data, errors, etc.)
• Tests pass: [test command]

Verification Steps:

1. Run tests: [test command]
2. Manual check: Open app, verify component appears correctly
3. Expected: Tests passing, component renders and functions as designed

Success Criteria:

• All code changes completed
• Component implemented per design
• Component tests written and passing
• Manual verification confirms visual appearance
• Event handlers tested and working

---

Phase 4: User Flows & Integration

Overview

Connect components together to implement complete user flows from requirements.md.

Tasks

4.1 Implement [Flow Name] Flow

User Story: [Reference specific user story from requirements.md] Components Involved: [List from design.md]

Action:

• Connect [Component A] to [Component B]
• Implement data flow as per design.md
• Add error handling for edge cases from requirements.md

Flow Steps (from design.md):

1. User [action]
2. System [response]
3. User sees [result]

Acceptance Criteria (from requirements.md):

• [Criterion 1 from requirements]
• [Criterion 2 from requirements]
• [Criterion 3 from requirements]

Edge Cases:

• [Edge case 1 from requirements] handles correctly
• [Edge case 2 from requirements] handles correctly

---

Phase 5: Polish & Testing

Overview

Add finishing touches, handle edge cases, and verify all acceptance criteria.

Tasks

5.1 UI/UX Polish

Action:

• Refine styling to match design vision
• Add loading states
• Add empty states
• Improve error messages

Success Criteria:

• UI matches design specifications
• All interactive elements are accessible
• Loading states are clear
• Empty states are helpful

5.2 Error Handling

Action:

• Implement error boundaries (if applicable)
• Add user-friendly error messages
• Handle all edge cases from requirements.md

Success Criteria:

• No uncaught errors
• Users see helpful error messages
• Edge cases handled gracefully

5.3 Final Testing

Action:

• Write unit tests for critical functions
• Manually test all user flows
• Test all acceptance criteria from requirements.md

Success Criteria:

• All automated tests pass: [test command]
• All user stories verified manually
• All acceptance criteria met

---

Verification Checklist

Requirements Completion

[For each user story from requirements.md]

• User Story 1: [Name]
  • Acceptance criterion 1
  • Acceptance criterion 2
• User Story 2: [Name]
  • Acceptance criterion 1
  • Acceptance criterion 2

Design Implementation

• All components from design.md implemented
• Data model matches design.md
• File structure matches design.md
• Tech stack matches design.md

Quality Checks

• Code builds without errors: [build command]
• Linter passes: [lint command]
• Tests pass: [test command]
• Application runs: [dev/start command]

User Acceptance

• Manually test all user flows
• Verify all edge cases
• Check performance (if requirements specify)
• Verify accessibility (if requirements specify)

---

Development Notes

Suggested Order

1. Don't skip phases - each builds on the previous
2. Verify success criteria before moving to next task
3. Update this document if you discover issues in specs

If You Get Stuck

• Review requirements.md for the "why"
• Review design.md for the "how"
• Ask questions if specs are unclear
• Update specs if you find gaps

References

• Requirements: spec/requirements.md
• Design: spec/design.md