plan

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

Before each Q&A wave, dispatch 2-3 Agent() tool calls in a single message (parallel execution) with subagent_type: "Explore":

1. Market/online context agent — searches for relevant market data, best practices, competitor analysis, or technical patterns depending on the questions to be asked. Tools: WebSearch, WebFetch.
2. Baseline analysis agent — reads projects-baseline templates, rules, and scripts at $BASELINE_PATH to discover available options (archetypes, styles, configurations). Tools: Read, Glob, Grep.
3. Repo context agent (skip for /plan new wave 1) — analyzes the current repository for existing patterns, file structure, dependencies, and conventions. Tools: Read, Glob, Grep.

Example dispatch:

Agent({ subagent_type: "Explore", description: "Research market context for [topic]",
  prompt: "Search online for [topic]. Report findings with pros/cons for each option." })
Agent({ subagent_type: "Explore", description: "Analyze baseline templates",
  prompt: "Read projects-baseline at $BASELINE_PATH/templates/. List available archetypes, their README descriptions, and key features." })
Agent({ subagent_type: "Explore", description: "Analyze repo context",
  prompt: "Explore current repo for [relevant patterns]. Report affected files and existing conventions." })

Wait for ALL agents to complete before proceeding. Use run_in_background: false for all agents.

3.2 Question Presentation

Synthesize research results into 5 questions per wave. Split across 2 AskUserQuestion calls (3+2 or 4+1) to stay within the 4-question-per-call limit.

Option format rules:

• Option 1 is ALWAYS the recommendation, marked with (Recommended) in the label
• Each option includes a description with Pros/Cons drawn from the research
• Include an "Other" option when custom input makes sense
• Use multiSelect: false unless the question genuinely requires multiple selections

Example payload:

AskUserQuestion({ questions: [
  { question: "Which project archetype fits best?", header: "Archetype", options: [
    { label: "nextjs-saas (Recommended)", description: "Pro: Full SaaS stack with auth, payments. Con: Heavier initial setup." },
    { label: "express-service", description: "Pro: Lightweight API. Con: No frontend." },
    { label: "docker-service", description: "Pro: Maximum flexibility. Con: More manual setup." },
    { label: "Other", description: "Describe your preferred archetype." }
  ], multiSelect: false },
  { question: "Which visibility tier?", header: "Visibility", options: [
    { label: "internal (Recommended)", description: "Pro: GitLab private, team access. Con: No external visibility." },
    { label: "private", description: "Pro: + optional GitHub mirror. Con: Limited collaboration." },
    { label: "public/OSS", description: "Pro: Open source, GitHub public + license. Con: Requires careful secret management." }
  ], multiSelect: false },
  { question: "Who is the target audience?", header: "Audience", options: [
    { label: "Internal team (Recommended)", description: "