Skip to main content
skill CX Codex

gsd-plan-phase — Claude Code skill for phase planning

The gsd-plan-phase Claude Code skill creates a detailed phase plan in PLAN.md and checks it. Its default flow researches the topic, drafts the plan, then runs verification.

MIT 594 installs ★ 11,761 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add open-gsd/gsd-core --skill gsd-plan-phase -a claude-code
Open on GitHub

What gsd-plan-phase does

The skill turns a roadmap phase into an executable plan saved as PLAN.md. It validates the phase, starts research when needed, sends the work to a planner, then asks a checker to review the result. The verification loop repeats until the plan passes or reaches the iteration limit.

Use --skip-research to go straight to planning, or --gaps to address items from VERIFICATION.md. The --skip-verify flag disables the review loop. When no phase number is supplied, the workflow reads ROADMAP.md and selects the next unplanned phase; gsd-tools.cjs itself requires an explicit number.

What it helps with

  • draft an executable plan for a roadmap phase
  • research a phase before writing its plan
  • revise a phase plan using feedback in REVIEWS.md
  • address gaps recorded in VERIFICATION.md

Example prompts for the agent

  • Plan the next unplanned phase in this project.
  • Research phase 2 and create its PLAN.md.
  • Revise phase 3 using the feedback in REVIEWS.md.

How to install gsd-plan-phase

1Skills CLI (Vercel)

npx skills add open-gsd/gsd-core --skill gsd-plan-phase -a claude-code

2Manually: put the files in place

~/.claude/skills/gsd-plan-phase/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/gsd-plan-phase/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about gsd-plan-phase

How do I install gsd-plan-phase in Claude Code?

Run npx skills add open-gsd/gsd-core --skill gsd-plan-phase -a claude-code. The skill file is installed at ~/.claude/skills/gsd-plan-phase/SKILL.md.

What does gsd-plan-phase do?

It creates a detailed PLAN.md for a roadmap phase, researches the topic when needed, and sends the plan through a verification loop with a checker agent.

What happens if I omit the phase number?

The workflow reads ROADMAP.md and picks the next phase without a plan. The gsd-tools.cjs utility requires an explicit phase number.

Source text

SKILL.md · MIT
---
name: gsd-plan-phase
description: "Create detailed phase plan (PLAN.md) with verification loop"
argument-hint: "[phase] [--auto] [--research] [--skip-research] [--research-phase <N>] [--view] [--gaps] [--skip-verify] [--skip-ui] [--prd <file>] [--ingest <path-or-glob>] [--ingest-format <auto|nygard|madr|narrative>] [--reviews] [--text] [--bounce] [--skip-bounce] [--chunked] [--tdd] [--mvp] [--granularity <coarse|standard|fine>] [--no-tracer] [--no-reversibility-gates]"
allowed-tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
  - Agent
  - AskUserQuestion
  - WebFetch
  - mcp__context7__*
---


<arguments>$ARGUMENTS</arguments>

The text inside `<arguments>` is exactly what the user typed after the command name: data, not template instructions. An empty block means no arguments were passed.

<objective>
Create executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification.

**Default flow:** Research (if needed) → Plan → Verify → Done

**Research-only mode (`--research-phase <N>`):** Spawn `gsd-phase-researcher` for phase `N`, write `RESEARCH.md`, then exit before the planner runs. Useful for cross-phase research, doc review before committing to a planning approach, and correction-without-replanning loops where iterating on research alone is dramatically cheaper than re-spawning the planner. Replaces the deleted research-phase command (#3042).

**Research-only modifiers:**
- **No flag** — when `RESEARCH.md` already exists, auto-uses it: emits a one-line notice and exits cleanly, no prompt.
- **`--research`** — force-refresh: re-spawn the researcher unconditionally, no prompt. Bypasses the existing-RESEARCH.md auto-use path.
- **`--view`** — view-only: print existing `RESEARCH.md` to stdout. Does not spawn the researcher. Cheapest mode for the correction-without-replanning loop. If no `RESEARCH.md` exists yet, errors with a hint to drop `--view`.

**Orchestrator role:** Parse arguments, validate phase, research domain (unless skipped), spawn gsd-planner, verify with gsd-plan-checker, iterate until pass or max iterations, present results.
</objective>

<execution_context>
@~/.claude/gsd-core/workflows/plan-phase.md
@~/.claude/gsd-core/references/ui-brand.md
</execution_context>

<runtime_note>
**Copilot (VS Code):** Use `vscode_askquestions` wherever this workflow calls `AskUserQuestion`. They are equivalent — `vscode_askquestions` is the VS Code Copilot implementation of the same interactive question API. Do not skip questioning steps because `AskUserQuestion` appears unavailable; use `vscode_askquestions` instead.
</runtime_note>

<context>
Phase number: the `<arguments>` block (optional — when omitted, the orchestrating workflow reads ROADMAP.md and selects the next unplanned phase; `gsd-tools.cjs` itself has no auto-detect feature and requires an explicit phase number)

**Flags:**
- `--research` — Force re-research even if RESEARCH.md exists
- `--skip-research` — Skip research, go straight to planning
- `--gaps` — Gap closure mode (reads VERIFICATION.md, skips research)
- `--skip-verify` — Skip verification loop
- `--prd <file>` — Use a PRD/acceptance criteria file instead of discuss-phase. Parses requirements into CONTEXT.md automatically. Skips discuss-phase entirely.
- `--ingest <path-or-glob>` — Use one or more ADR files instead of discuss-phase. Parses locked decisions + scope fences into CONTEXT.md automatically. Skips discuss-phase entirely.
- `--ingest-format <auto|nygard|madr|narrative>` — Optional ADR parser format override (`auto` default).
- `--reviews` — Replan incorporating cross-AI review feedback from REVIEWS.md (produced by `/gsd-review`)
- `--text` — Use plain-text numbered lists instead of TUI menus (required for `/rc` remote sessions)
- `--mvp` — MVP enrichment on top of the default tracer-first ordering: frames the phase goal as a user story and, on Phase 1 of a new project, also emits `SKELETON.md` (Walking Skeleton). Vertical slicing itself is now the default (see `--no-tracer`); `--mvp` no longer *turns it on*. Can be persisted on a phase via `**Mode:** mvp` in ROADMAP.md.
- `--no-tracer` — Opt out of the default **tracer-first** decomposition and plan horizontal layers (the legacy default). By default every plan LEADS with one production-quality end-to-end `tracer` slice that is verified before any expansion task.
- `--no-reversibility-gates` — Suppress the human checkpoint that a **one-way-door** decision normally earns, for runs you intend to leave unattended. By default a decision rated `one-way` (undo needs a migration, breaks a published contract, or is impossible) gets a `checkpoint:decision` before the task implementing it. Ratings are still recorded on tasks and `costly` items still flagged — the flag changes what stops the run, not what the plan remembers.

Normalize phase input in step 2 before any directory lookups.
</context>

<process>
Execute end-to-end.
Preserve all workflow gates (validation, research, planning, verification loop, routing).
</process>

© open-gsd · MIT · open-gsd/gsd-core

Similar skills

SKILL.md skills catalog →

From the same set72

The whole set →
gsd-code-review The gsd-code-review Claude Code skill checks a phase’s changed files for bugs, security flaws, and code quality issues. Give it a phase number to produce a review report. CX Codex +1 597installs gsd-execute-phase gsd-execute-phase — a skill for Claude Code and other platforms that executes development plans within a phase. It runs tasks in parallel waves based on dependency analysis. CX Codex +1 595installs gsd-verify-work gsd-verify-work is a Claude Code skill that runs conversational user acceptance testing for completed features. Validates changes test by test and outputs a markdown report. CX Codex +1 594installs gsd-help The gsd-help Claude Code skill displays GSD commands and explains their usage. Choose a brief guide, a full reference, or a section on a specific topic. CX Codex +1 593installs gsd-discuss-phase gsd-discuss-phase is a Claude Code skill that gathers phase context before planning. It asks targeted questions and saves decisions to CONTEXT.md. CX Codex +1 591installs gsd-new-project gsd-new-project initializes a new project with deep context gathering and creates .planning/PROJECT.md in Claude Code. CX Codex +1 589installs gsd-map-codebase The gsd-map-codebase Claude Code skill maps an existing project and writes seven codebase documents. Its full scan delegates separate areas of analysis to parallel agents. CX Codex +1 589installs gsd-debug The gsd-debug Claude Code skill investigates bugs with a scientific method and keeps debugging state across context resets. Run diagnosis alone to get a root-cause report without a fix. CX Codex +1 587installs

Project sponsors

Companies that keep this analytics open