Menu
Turns high-level brainstorming and ideas into well-structured, actionable implementation plans.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Executes an implementation plan — writes code and tests, runs quality review, and ships a pull request.
Reviews an externally-authored implementation plan for quality, VGV conventions, and scope. Plans created by /plan are already reviewed during creation.
Applies a minimal, targeted fix for emergency bugs — enforces review and testing without brainstorm or planning phases.
Runs quality review agents on demand — reviews code against VGV standards for architecture, tests, and simplicity, then writes one consolidated, numbered report.
Explores requirements and approaches through collaborative dialogue before planning implementation.
Stage, commit, push, and open a pull request following project conventions and the Conventional Commits spec. Accepts optional skip-checks argument to bypass validation when called from /build.
| 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) |
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>$ARGUMENTS</feature_description>
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.
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:
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.
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:
After all research steps complete, consolidate findings:
src/authentication/forms/authentication_form:42)Optional validation: Briefly summarize findings and ask if anything looks off or missing before proceeding to planning.
Think like a product manager — what would make this issue clear and actionable?
Title & Categorization:
feat: add user authentication, fix: cart total calculation)-plan suffix
feat: add user authentication → 2026-01-21-feat-add-user-authentication-plan.mdStakeholder Analysis:
Content Planning:
After planning the issue structure, run the user-flow-analysis-agent to analyze the plan for flow completeness and gap identification:
Flow Analysis Output:
Before selecting a template, derive the plan's success criteria and make each one machine-checkable. This block is the contract /build consumes, so it must be precise.
For each criterion, apply one rule — can a command prove this without human judgment?
verify: <command> (exit code 0 = pass).verify: manual <numbered steps>.Surface every rejected or rewritten criterion to the user with AskUserQuestion before writing the plan file — do not silently change the spec they approved.
These criteria populate the success-criteria block defined in success-criteria.md; fill it in when you write the plan file in Step 6. That reference shows the block's shape and the verify: convention.
verify: commands reflect the project's own toolchain. If the project has a companion verification skill available, its gates are the canonical verify: commands.
Default to Standard. Use a different level only when the task clearly warrants it.
| Level | When to use | Template |
|---|---|---|
| Minimal | Simple bugs, small enhancements, straightforward implementation | minimal |
| Standard (default) | Most features and bug fixes needing moderate detail | standard |
| Extensive | Major features, architectural changes, significant risk or uncertainty | extensive |
Before writing the plan file, ensure the session is not on the base branch:
git rev-parse --abbrev-ref HEAD. If the current branch is a base branch (main, master, or develop), use AskUserQuestion to offer creating a feature branch — git checkout -b <type>/<kebab-topic>, name under 60 characters — before writing. If already on a feature branch, continue without prompting.Formatting checklist:
- [ ]) for trackable items; collapsible <details> for lengthy content#number), commits (SHA), and code (GitHub permalinks)Pre-submission Checklist:
verify: command (or verify: manual <steps>)Filename: Use the date and kebab-case filename from Step 2 Title & Categorization: docs/plan/YYYY-MM-DD-<type>-<descriptive-name>-plan.md
Examples:
docs/plan/2026-01-15-feat-user-authentication-flow-plan.mddocs/plan/2026-01-15-feat-thing-plan.md (not descriptive)docs/plan/feat-user-auth-plan.md (missing date prefix)After writing the plan file and before presenting options, run a mandatory quality pass on it. This replaces the separate /plan-technical-review step — plans created here are reviewed here.
<PLAN_PATH> set to the plan file. It runs the simplicity, VGV, and scope-splitting agents in parallel, applies their findings to the plan inline, and — if the plan is too large for one PR — offers to restructure the work into phases or split it into part-N files.Return here once the review completes, then present the options below.
After the review completes, use the AskUserQuestion tool and present the following options:
Options:
/buildIf the user selects "Clear context and build" → Follow the clear context handoff for /build with the actual plan file path. Then stop.
For other selections:
/build skill with the plan file pathopen docs/plan/<plan_filename>.md to open the file in the user's default editor/refine-approach skill.NEVER CODE at this stage. Only focus on producing a plan.