plan-project

What this skill does

# Plan Skill

Orchestrate a complete project planning workflow with sequential agent handoff and parallel specialist execution.

---

## Orchestration Flow

```
/plan
  |
  v
+----------------------------------------------------------+
|  STEP 1: AskUserQuestion (MANDATORY)                     |
|  - Validate user intent                                   |
|  - Locate PRD / gather project description                |
|  - Clarify scope, tech stack, priorities                  |
+----------------------------------------------------------+
  |
  v
+----------------------------------------------------------+
|  STEP 2: Ensure /docs directory                           |
+----------------------------------------------------------+
  |
  v
+----------------------------------------------------------+
|  STEP 3: ui-ux-specialist (SEQUENTIAL)                   |
|  - Reads PRD                                              |
|  - Writes: docs/ui-ux-plan.md                            |
+----------------------------------------------------------+
  |
  v
+----------------------------------------------------------+
|  STEP 4: tech-lead-specialist (SEQUENTIAL)               |
|  - Reads: docs/ui-ux-plan.md                             |
|  - Writes: docs/dev-plan.md                              |
+----------------------------------------------------------+
  |
  v
+----------------------------------------------------------+
|  STEP 5: PARALLEL — frontend + backend specialists       |
|                                                           |
|  frontend-specialist ──Read──> docs/dev-plan.md           |
|                      ──Write─> docs/frontend-plan.md      |
|                                                           |
|  backend-specialist  ──Read──> docs/dev-plan.md           |
|                      ──Write─> docs/backend-plan.md       |
+----------------------------------------------------------+
  |
  v
+----------------------------------------------------------+
|  STEP 6: qa-specialist (SEQUENTIAL)                      |
|  - Reads: docs/dev-plan.md + docs/backend-plan.md        |
|  - Writes: docs/test-plan.md                             |
+----------------------------------------------------------+
  |
  v
+----------------------------------------------------------+
|  STEP 7: Report completion with file summary              |
+----------------------------------------------------------+
```

---

## Step 1: Validate User Intent (MANDATORY)

**You MUST use AskUserQuestion before spawning any agents. Never skip this step.**

### 1.1 Locate PRD

Search for the PRD file first:

```
Glob: **/prd.md
Glob: **/PRD.md
Glob: docs/prd.md
```

### 1.2 Ask User — Project Scope

**ALWAYS ask this question regardless of PRD existence.**

```
AskUserQuestion:
  question: "What would you like to plan? Please confirm the scope."
  header: "Plan Scope"
  options:
    - label: "Full project from PRD"
      description: "Plan the entire project from the PRD file"
    - label: "Specific feature only"
      description: "Plan a single feature or module"
    - label: "I'll describe it now"
      description: "No PRD — I'll describe what to plan"
```

### 1.3 Ask User — PRD Location (if not found automatically)

```
AskUserQuestion:
  question: "Where is your PRD file located?"
  header: "PRD Path"
  options:
    - label: "docs/prd.md (Recommended)"
      description: "Standard location in docs folder"
    - label: "prd.md (root)"
      description: "In the project root directory"
    - label: "I'll provide the path"
      description: "Enter a custom file path"
```

### 1.4 Ask User — UI/UX Priority

```
AskUserQuestion:
  question: "What is the UI/UX priority for this project?"
  header: "UI Priority"
  options:
    - label: "Speed to market (Recommended)"
      description: "Use shadcn defaults, minimal customization"
    - label: "Custom brand design"
      description: "Detailed design system, unique visual identity"
    - label: "Accessibility first"
      description: "WCAG AAA compliance, inclusive design"
```

### 1.5 Ask User — Tech Stack (if not specified in PRD)

```
AskUserQuestion:
  question: "What tech stack should we use?"
  header: "Tech Stack"
  options:
    - label: "Next.js + Supabase (Recommended)"
      description: "Full-stack React with Postgres backend"
    - label: "React + Express + PostgreSQL"
      description: "Traditional stack with Node backend"
    - label: "Already specified in PRD"
      description: "Use what's defined in the PRD"
```

### Question Rules

- **MANDATORY:** You MUST ask at least the Plan Scope question (1.2) before proceeding
- Ask a maximum of **5 questions total**
- Skip questions that are already answered in the PRD
- Track: `questionsAsked` (start at 0, stop at 5)
- Do NOT proceed to Step 2 until user has answered

---

## Step 2: Ensure /docs Directory

Before spawning agents, ensure the output directory exists:

```
Bash: mkdir -p docs
```

---

## Step 3: Spawn ui-ux-specialist (SEQUENTIAL)

**This agent runs FIRST, alone. It creates the design foundation that all other plans depend on.**

```
Task:
  subagent_type: ui-ux-specialist
  description: "Create UI/UX plan"
  prompt: |
    Read the PRD at: {prd_path}

    User preferences:
    - UI Priority: {ui_priority from Step 1.4}
    - Tech Stack: {tech_stack from Step 1.5}
    - Scope: {scope from Step 1.2}

    Write your complete ui-ux-plan.md to: docs/ui-ux-plan.md

    Include:
    - User research and personas
    - Information architecture
    - User flows
    - Design system (colors, typography, spacing)
    - Component library specifications
    - Wireframes for all key pages
    - Accessibility checklist (WCAG 2.1 AA minimum)
    - Micro-interactions and animation guidelines
    - Implementation guidelines for developer handoff

    Write the file using the Write tool. Return "Done: docs/ui-ux-plan.md" when complete.
```

**Wait for this agent to complete before proceeding to Step 4.**

After the agent completes, verify the file was created:

```
Glob: docs/ui-ux-plan.md
```

If the file does not exist, report the error and stop. Do NOT proceed.

---

## Step 4: Spawn tech-lead-specialist (SEQUENTIAL)

**This agent runs SECOND. It reads ui-ux-plan.md and creates the single source of truth dev-plan.md.**

```
Task:
  subagent_type: tech-lead-specialist
  description: "Create dev plan from UI/UX"
  prompt: |
    Read the UI/UX plan at: docs/ui-ux-plan.md
    Also read the PRD at: {prd_path}

    Create dev-plan.md as the SINGLE SOURCE OF TRUTH for this project.

    Translate the design decisions, wireframes, component specs, and accessibility
    requirements from ui-ux-plan.md into a minimal, phased development checklist.

    Phases:
    - Phase 0: Foundation (project setup, design tokens)
    - Phase 1: Backend (schema, API, RLS)
    - Phase 2: Shared UI (src/components/)
    - Phase 3: Features (src/features/)
    - Phase 4: Integration (routing, API wiring)
    - Phase 5: Polish (a11y, animations)

    Every task must have:
    - Output: file paths or artifacts
    - Behavior: how it works
    - Verify: concrete check steps

    Write the file to: docs/dev-plan.md
    Do NOT create progress.json — that is handled separately.

    Write the file using the Write tool. Return "Done: docs/dev-plan.md" when complete.
```

**Wait for this agent to complete before proceeding to Step 5.**

After the agent completes, verify the file was created:

```
Glob: docs/dev-plan.md
```

If the file does not exist, report the error and stop. Do NOT proceed.

---

## Step 5: Spawn frontend-specialist + backend-specialist (PARALLEL)

**These two agents run IN PARALLEL. Both read dev-plan.md and write their own specialist plans.**

**CRITICAL: Spawn both agents in a SINGLE message with two Task tool calls.**

```
[Single message with 2 Task tool calls]

Task 1: frontend-specialist
  subagent_type: frontend-specialist
  description: "Create frontend plan"
  prompt: |
    Re