/plan

name: plan
user-invocable: false
tags: [planning, prd, requirements, research]
model: inherit
model-preference: opus
model-preference-codex: gpt-5.4
model-preference-cursor: claude-opus-4-6
description: >
  Use this skill when performing structured project planning and PRD generation with three modes:
  new (project kickoff with repo scaffolding), feature (compact feature PRD),
  retro (data-driven retrospective). All modes share a researched Q&A engine
  that dispatches parallel Explore agents before each question wave, presents
  options via AskUserQuestion with recommendations, and produces documents
  with prioritized issue creation.

Plan Skill

> Project-instruction file resolution: CLAUDE.md and AGENTS.md (Codex CLI) are transparent aliases — see [skills/_shared/instruction-file-resolution.md](../_shared/instruction-file-resolution.md). All references below to `CLAUDE.md` resolve via that precedence rule.

File Structure

• `SKILL.md` — Core framework: mode router, Q&A engine, shared phases
• `mode-new.md` — Project kickoff: 3 Q&A waves, PRD template, repo scaffolding
• `mode-feature.md` — Feature PRD: 2 Q&A waves, compact scope, acceptance criteria
• `mode-retro.md` — Retrospective: metrics analysis, reflection waves, improvement actions
• `soul.md` — Product Strategist identity and behavioral anchor

Soul Reference

Before anything else, read and internalize `soul.md` in this skill directory. It defines WHO you are — a Product Strategist who drives planning outcomes through structured research and decisive recommendations. Every interaction in this skill should reflect this identity. You are not a generic assistant; you are an opinionated product leader who backs every recommendation with data.

Phase 0: Bootstrap Gate

Read `skills/_shared/bootstrap-gate.md` and execute the gate check. If the gate is CLOSED, invoke `skills/bootstrap/SKILL.md` and wait for completion before proceeding. If the gate is OPEN, continue to Phase 1.

<HARD-GATE> Do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to `skills/_shared/bootstrap-gate.md` for the full HARD-GATE constraints. </HARD-GATE>

Phase 1: Read Session Config

Read and parse Session Config per `skills/_shared/config-reading.md`. Store result as `$CONFIG`.

After parsing, verify that `plan-baseline-path` is not null: `echo "$CONFIG" | jq -e '."plan-baseline-path"'`. If null, stop with: "Error: `plan-baseline-path` is not configured in Session Config. Add it to your CLAUDE.md (or AGENTS.md on Codex CLI) under `## Session Config`. Example: `plan-baseline-path: ~/Projects/projects-baseline`"

Plan-specific fields (also parse these): `plan-default-visibility`, `plan-prd-location`, `plan-retro-location`, `vcs`

Store all values for use in subsequent phases.

**Path expansion:** Expand `~` to `$HOME` in `plan-baseline-path`, `plan-prd-location`, and `plan-retro-location`. Verify expanded paths exist. If `plan-baseline-path` doesn't exist, warn: "Baseline path not found at [path]. `/plan new` repo scaffolding will be unavailable."

If no `## Session Config` section exists at all, stop and report: "Error: No Session Config section found in CLAUDE.md (or AGENTS.md on Codex CLI). The `/plan` skill requires at minimum `plan-baseline-path` to be configured."

> **Platform Note:** This skill uses `AskUserQuestion` extensively. On Codex CLI where this tool is unavailable, present all choices as numbered Markdown lists with "(Recommended)" on the first option. The user responds with their choice number. See `skills/_shared/platform-tools.md`.

> On Codex CLI, Explore agents map to the `explorer` agent role. See `skills/_shared/platform-tools.md`.

Phase 2: Mode Router

> **Ambiguous scope?** If the feature's UX/scope is still ambiguous before starting, run `/brainstorm` first (see `skills/brainstorm/SKILL.md`) to produce a design spec, then return here with the spec as input. `/brainstorm` outputs `docs/specs/YYYY-MM-DD-<slug>-design.md`.

Parse `$ARGUMENTS` to determine the planning mode:

• **`new`** — Read `mode-new.md` in this skill directory for mode-specific instructions. This mode handles full project kickoff: requirement gathering, PRD generation, repo scaffolding, and issue creation.
• **`feature`** — Read `mode-feature.md` in this skill directory for mode-specific instructions. This mode handles feature-level PRDs with compact scope and acceptance criteria.
• **`retro`** — Read `mode-retro.md` in this skill directory for mode-specific instructions. This mode handles data-driven retrospectives with metrics analysis and improvement actions.

If `$ARGUMENTS` is empty or does not match any mode, use AskUserQuestion to ask:

AskUserQuestion({
  questions: [{
    question: "Which planning mode do you want to run?",
    header: "Plan Mode",
    options: [
      { label: "new", description: "Project kickoff — full PRD, repo setup, issue creation. Use when starting a brand new project." },
      { label: "feature", description: "Feature PRD — compact scope, acceptance criteria, issues. Use when adding a feature to an existing project." },
      { label: "retro", description: "Retrospective — metrics analysis, reflection, improvement actions. Use after completing a project phase or sprint." }
    ],
    multiSelect: false
  }]
})

After mode selection, proceed to Phase 3 with the chosen mode.

Phase 3: Q&A Engine (Shared Core)

This is the distinctive mechanic shared by all three modes. Every question wave follows the same pattern: research first, then ask.

3.1 Pre-Question Research

Read [Research Evidence Contract](../_shared/research-evidence.md) before the first research wave. Apply it to findings that materially affect an option or recommendation; keep trivial local lookups concise. Carry the source revision or date, evidence basis, local equivalent, disposition, and any falsifiable next check into each research brief and the synthesis so documented claims and inferences remain distinc