plan
/plan
Turns high-level brainstorming and ideas into well-structured, actionable implementation plans. Use when the user says "plan this", "create a plan", "how should we implement", or "write an implementation plan".
- Author
- verygoodopensource ↗
- Repository
- vgv-wingspan ↗
- Licence
- MIT
- Last repository change
- 12.11.2026
Assessment and security
- Files in this package
- 10
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Turns high-level brainstorming and ideas into well-structured, actionable implementation plans. Use when the user says "plan this", "create a plan", "how should we implement", or "write an implementation plan".
Triggers from the description
Arguments
/plan feature, bug fix, or improvement to plan
Original author description
Turns high-level brainstorming and ideas into well-structured, actionable implementation plans. Use when the user says "plan this", "create a plan", "how should we implement", or "write an implementation plan".
How it works
- Feature Description
- Output Format
- Plan Review
- Post-Generation Options
- The handoff block
SKILL.md preview
--- name: plan user-invocable: true description: Turns high-level brainstorming and ideas into well-structured, actionable implementation plans. Use when the 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, at a detail level matched to the work. > **Every question in this skill goes through the AskUserQuestion tool.** When that tool is > not available — another harness, or a non-interactive session — put the same question and > the same options in your reply as a short numbered list, and stop there for the answer. > Never answer a question on the user's behalf and carry on: a question the user never sees > is not a question, and a step that waits on one is not optional. **Never write code at this stage.** The output is a plan. ## Feature Description <feature_description>$ARGUMENTS</feature_description> ### 0. Idea Refinement Check for brainstorm output first — before asking the user anything. If `<feature_description>` contains a GitHub issue URL or `#<number>`, the brainstorm lives in that issue. Read it and skip the local search: ```bash gh issue view <url-or-number> --json title,body ``` Treat the issue body as the brainstorm document, announce "Found brainstorm issue: [title]", and proceed. If the command fails, fall back to the local search below. ```bash 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.2 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.3 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. Title, filename, and structure Draft the plan's title, derive its filename, and gather supporting material per [plan authoring](references/plan-authoring.md). ### 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 analysis results - [ ] Incorporate any identified gaps or edge cases into the issue - [ ] Update success criteria based on flow analysis findings ### 4. Success Criteria Gate 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?** - **Yes** → attach `verify: <command>` (exit code 0 = pass). - **No, but a human can check it** → attach `verify: manual <numbered steps>`. - **Neither (vacuous or unmeasurable, e.g. "make it work", "code is clean")** → reject it and rewrite it into a concrete, provable criterion. 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](references/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. `/build` reads the block back, so its shape holds even when the reference cannot be read from here. The plan carries a `## Success Criteria` section, and every criterion names what proves it after `verify:` — a shell command whose exit 0 is the pass, or `verify: manual` followed by numbered human steps. A criterion with nothing to run against it — "make it work", "the feature is done" — is not a criterion; rewrite it as something a command or a numbered procedure can settle. `verify:` commands reflect the project's own toolchain. If the project has a companion verification skill available, its gates are the canonical `verify:` commands. ### 5. Select implementation detail template **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](references/minimal.md) | | **Standard** (default) | Most features and bug fixes needing moderate detail | [standard](references/standard.md) | | **Extensive** | Major features, architectural changes, significant risk or uncertainty | [extensive](references/extensive.md) | Whatever the level, a plan that carries more than one phase embeds the [Implementation Phases block](references/implementation-phases.md) verbatim: `## Implementation Phases`, one `### Phase N:` each, and the `**Status:**`, `**Scope:**`, `**Files touched:**`, `**Acceptance criteria:**` and `**Validation:**` fields. `/build` parses those names to execute one phase per context window — renaming them to anything of your own, however clear, breaks execution. ### 5.1. Set up workspace Run the [feature branch check](references/feature-branch.md) before writing anything to disk. ### 6. Write and review the plan file Write the file, then check it against the formatting and pre-submission rules in [plan authoring](references/plan-authoring.md). ## Output Format **Filename:** `docs/plan/YYYY-MM-DD-<type>-<descriptive-name>-plan.md`, derived in Step 2 — e.g. `docs/plan/2026-01-15-feat-user-authentication-flow-plan.md`. ## Plan Review 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. - **Minimal template** → skip this section. The overhead is not worth it for a small plan. - **Standard or Extensive template** → follow the [plan review procedure](references/plan-review.md) with `<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 (still one PR) or split it into part-N files (one PR per part). Return here once the review completes, then present the options below. ## Post-Generation Options After the review completes, use the **AskUserQuestion tool** and present the following options: **Options:** 1. **Clear context and build (Recommended)**: clear context for a fresh start, then build 2. **Start building**: execute this plan with `/build` 3. **Open the plan file in my code editor**: open the plan file for review 4. **Review and refine**: improve the plan through self-review **If the user selects "Clear context and build"** → Follow the [clear context handoff](references/clear-context-handoff.md) for `/build` with the actual plan file path. Then stop. **For other selections:** - **Start building** → Call the `/build` skill with the plan file path - **Open plan in editor** → Run `open docs/plan/<plan_filename>.md` to open the file in the user's default editor - **Review and refine** → Load `/refine-approach` skill. - **Other** (automatically provided) → Accept free text for rework or specific changes ## The handoff block The handoff is the user's only instruction for picking the work up in a fresh session, so its shape is fixed here as well as in the reference. Print exactly this and then **stop**, substituting the next skill and the real document path: ```md To continue with a fresh context, run: /clear Then start <NEXT_ACTION> with: /<NEXT_SKILL> <DOC_PATH> ``` Print it even when the document cannot be read from here, and even when the reference file cannot be read — a cleared context is a new session, and the skill that picks it up validates the path. Withholding the block because a check failed strands the user mid-handoff.
Files in this package (10)
- SKILL.md 11 KB
- references/clear-context-handoff.md 1 KB
- references/extensive.md 1 KB
- references/feature-branch.md 1 KB
- references/implementation-phases.md 1 KB
- references/minimal.md 1 KB
- references/plan-authoring.md 2 KB
- references/plan-review.md 1 KB
- references/standard.md 1 KB
- references/success-criteria.md 1 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · verygoodopensource/vgv-wingspan | 100 | MIT |
| mlophez/polix-ai | 100 | Apache-2.0 |
| jeremylongshore/tons-of-skills-marketplace | 100 | MIT |
| duronext/jig | 100 | MIT |
| rjmurillo/ai-agents | 100 | MIT |
| rjmurillo/ai-agents | 100 | MIT |
| rjmurillo/ai-agents | 100 | MIT |
| xoai/sage | 100 | MIT |
| JoDi-27/JoDi-SDD | 100 | MIT |
Database snapshot: 13.11.2026 · package version a610b20f5ebb (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100planner
Create comprehensive, phased implementation plans with sprints and atomic tasks. Use when user says: "make a plan", "create a plan", "plan this out", "plan the implementation", "help me plan", "design a plan", "draft a plan", "write a plan", "outline the steps", "break this down… - 100writing-plans
Write structured implementation plans from specs or requirements before touching code. Use when given a spec, requirements doc, or feature description, when user says "plan this out", "write a plan for", "how should we implement", or before starting any multi-step coding task. - 100brainstorming
<EXTREMELY_IMPORTANT>You MUST use brainstorming when the user wants to explore ideas, discuss approaches, research a topic, or has been stuck on a problem. Always brainstorm before beginning implementation.</EXTREMELY_IMPORTANT> - 90create-plan
Interviews the user and writes an implementation plan for the current request. Use when the user names /create-plan or asks for an implementation plan of this feature. - 100brainstorming-ideas
Brainstorm ideas and stress-test draft plans before coding. Use when brainstorming, exploring approaches, designing a feature/API/flow, grilling or debating a bounded plan, challenging assumptions, or resolving design-blocking terminology. NOT for implementation task breakdown.… - 100new
Create and manage implementation plans in .agent/plan/ files. Use this skill when: starting a new feature or refactor, the user says "plan this", "think about how to", "design the approach", "prepare a plan", or any time structured planning is needed before execution. Plans are…