Skip to content
Skills Library
Management & product · Planning

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".

Licence
MIT
Last repository change
12.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
10
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.

Licence

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

plan thiscreate a planhow should we implementwrite an implementation plan

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

  1. Feature Description
  2. Output Format
  3. Plan Review
  4. Post-Generation Options
  5. The handoff block
Original SKILL.md headings · 213 lines, 1,634 words
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

RepositoryScoreLicence
This page · verygoodopensource/vgv-wingspan100MIT
mlophez/polix-ai100Apache-2.0
jeremylongshore/tons-of-skills-marketplace100MIT
duronext/jig100MIT
rjmurillo/ai-agents100MIT
rjmurillo/ai-agents100MIT
rjmurillo/ai-agents100MIT
xoai/sage100MIT
JoDi-27/JoDi-SDD100MIT

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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.