/plan

name: plan
user-invocable: true
description: Turns high-level brainstorming and ideas into well-structured, actionable implementation plans.
when_to_use: Use when user says "plan this", "create a plan", "how should we implement", or "write an implementation plan".
effort: high
argument-hint: feature, bug fix, or improvement to plan
compatibility: Designed for Claude Code (or similar products with agent support)

Create a new implementation plan (or bug fix)

Transform feature descriptions, bug reports, or improvement ideas into well-structured markdown files that follow VGV conventions and best practices. This command provides flexible detail levels to match your needs.

Feature Description

<feature_description>$ARGUMENTS</feature_description>

0. Idea Refinement

Check for brainstorm output first — before asking the user anything.

ls docs/brainstorm/

A brainstorm is relevant if created within the last 7 days and its topic semantically matches the feature description (if provided).

| Brainstorms found | Feature description provided? | Action | |-------------------|------------------------------|--------| | One relevant | Yes | Read it, announce "Found brainstorm from [date]: [topic]", extract key decisions, proceed | | One relevant | No | **AskUserQuestion**: "Plan this brainstorm?" — (Recommended) use it, or describe something different | | Multiple relevant | Either | **AskUserQuestion**: list candidates, ask which to use | | None / not relevant | No | Ask: "What would you like to plan?" | | None / not relevant | Yes | Run /brainstorm to clarify the idea first |

Do not proceed until you have a clear feature description — from arguments, a brainstorm, or the user.

**Skip option**: if the description is already detailed enough, ask the user if they want to skip idea refinement and proceed directly to planning.

1. Tasks to complete

1.1 Local research (always runs, and runs in parallel)

**Do not re-run `codebase-review-agent` here.** Codebase context was already captured in the brainstorm from `/brainstorm`.

Instead, extract what's needed from the brainstorm and run targeted searches:

1. **From the brainstorm doc**: Extract the architecture patterns, conventions, and relevant file paths already identified. 2. **Targeted codebase search**: Use Glob and Grep to search only the areas this plan will touch — the specific packages, layers, or features mentioned in the feature description and brainstorm.

• Example: If planning a new repository, search for existing repository patterns in the relevant package.
• Example: If planning a new state management unit, search for existing implementations in the same feature area.

3. **Read referenced files**: Read any specific files called out in the brainstorm as relevant context.

1.1.1 Research decision

Based on the findings from `0. Idea Refinement` and `1.1 Local research`, decide whether external research is needed:

| Signal | Decision | |--------|----------| | High-risk topic (security, payments, external APIs, personal data) | Always research — cost of missing something is too high | | Strong local context (good patterns, CLAUDE.md guidance, clear user intent) | Skip external research | | Uncertainty or unfamiliar territory (no codebase examples, new technology) | Research |

Announce the decision briefly and proceed. User can redirect if needed.

1.1.1.1 Conditional external research

Only run this step if `1.1.1 Research decision` determines that external research is needed.

Run these agents in parallel to gather external information:

• **@official-docs-research-agent**: Fetches and synthesizes official documentation for relevant frameworks, libraries, and APIs.
• **@best-practices-research-agent**: Researches and synthesizes best practices for the project's technology stack, following VGV conventions first, then official documentation, and finally industry standards.

1.1.2. Consolidate research findings

After all research steps complete, consolidate findings:

• Document relevant file paths from repo research (e.g., `src/authentication/forms/authentication_form:42`)
• **Include relevant institutional learnings** from project documentation (key insights, gotchas to avoid)
• Note external documentation URLs and best practices (if external research was done)
• List related issues or PRs discovered
• Capture CLAUDE.md conventions

**Optional validation:** Briefly summarize findings and ask if anything looks off or missing before proceeding to planning.

2. Issue planning and structure

Think like a product manager — what would make this issue clear and actionable?

**Title & Categorization:**

• [ ] Draft clear, searchable issue title using the conventional commits format (e.g., `feat: add user authentication`, `fix: cart total calculation`)
• [ ] Determine issue type: enhancement, bug, refactor
• [ ] Convert title to filename: add today's date prefix, strip prefix colon, kebab-case, add `-plan` suffix
• Example: `feat: add user authentication` → `2026-01-21-feat-add-user-authentication-plan.md`
• Keep it descriptive (3-5 words after prefix) so plans are findable by context

**Stakeholder Analysis:**

• [ ] Identify who will be affected by this issue (end users, developers, operations)
• [ ] Consider implementation complexity and required expertise

**Content Planning:**

• [ ] Choose appropriate detail level based on issue complexity and audience
• [ ] List all necessary sections for the chosen template
• [ ] Gather supporting materials (error logs, screenshots, design mockups)
• [ ] Prepare code examples or reproduction steps if applicable, name the mock filenames in the lists

3. User Flow Analysis

After planning the issue structure, run the **user-flow-analysis-agent** to analyze the plan for flow completeness and gap identification:

• Task @user-flow-analysis-agent(feature_description, research_findings)

**Flow Analysis Output:**

• [ ] Review flow an