Plan

Plan Skill

Project-instruction file resolution: CLAUDE.md and AGENTS.md (Codex CLI) are transparent aliases — see skills/_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.

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.

Opportunity Score (Ranking Candidate Subfeatures)

When a Wave 1 "what to build" question surfaces multiple candidate subfeatures (rather than one clear scope), rank the candidates before recommending one. Score each candidate:

Opportunity Score = Importance × (1 − Satisfaction)

Both Importance and Satisfaction are estimated on a 0..1 scale from the Wave 1 research/Explore agent findings (market signal, existing-issue signal, repo-pattern signal) — not asked of the user directly. Rank candidates descending by score; the top-ranked candidate becomes the (Recommended) Option 1 in the AskUserQuestion payload for that question. Apply this only when genuinely multiple candidates are surfaced — a single well-defined feature needs no ranking.

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. Note: in feature and new modes, Wave 1 may present 6 questions (split 3+3) when the optional User-Story toggle question is included; the 5-question / 3+2|4+1 default stands otherwise.

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: "Pro: Controlled rollout. Con: Limited feedback pool." },
    { label: "B2B customers", description: "Pro: Revenue potential. Con: Higher quality bar." },
    { label: "Public/developers", description: "Pro: Community contributions. Con: Support burden." },
    { label: "Other", description: "Describe your target audience." }
  ], multiSelect: false }
]})

3.3 Adaptive Depth

Each mode defines a starting wave count:

• /plan new — start with 3 waves minimum
• /plan feature — start with 1 wave minimum
• /plan retro — start with 1 wave minimum

Maximum across all modes: 5 waves.

After each wave, assess whether to continue:

• Answers are clear and unambiguous — all key decisions made, no open questions remain. Stop Q&A, proceed to Phase 4.
• Answers reveal complexity — multiple subsystems, unclear requirements, conflicting constraints, or new concerns surfaced. Add another wave with targeted follow-up questions.
• User aborts early — if the user says "Enough questions, generate the PRD" or similar, proceed directly to Phase 4 with the answers gathered so far.

3.4 Answer Tracking

Maintain a running summary of all answers across waves. After each wave, output a brief recap:

## Answers So Far (Wave N/M)
1. Archetype: nextjs-saas
2. Visibility: internal
3. Audience: B2B customers
4. ...

This ensures transparency and allows the user to correct any misunderstanding before the next wave.

Phase 4: Document Generation

After Q&A completes, generate the output document.

4.1 Read Template

Select the template based on mode:

• /plan new — read prd-full-template.md in this skill directory (8-section full PRD)
• /plan feature — read prd-feature-template.md in this skill directory (5-section compact PRD)
• /plan retro — read retro-template.md in this skill directory (retrospective document)

4.2 Fill Template

Fill every template section with gathered answers. Use the research agent outputs to enrich sections beyond what the user explicitly stated — add technical details, risk analysis, and architecture sketches derived from the baseline and repo analysis.

Do NOT leave any section with TBD, placeholder, or empty content. If a section cannot be filled from gathered data, make a best-effort recommendation and mark it with <!-- REVIEW: inferred from research, confirm with stakeholders -->.

4.3 Save Document

Write the document to the configured location:

• PRDs → {plan-prd-location}/YYYY-MM-DD-{project-or-feature-name}.md
• Retros → {plan-retro-location}/YYYY-MM-DD-retro.md

Use today's date. Derive the name slug from the project name (for new) or feature name (for feature) — lowercase, hyphens, no special characters.

Ensure the target directory exists (create with mkdir -p if needed) before writing.

Phase 3.5: Package Legitimacy Audit (Slopcheck — #520)

Despite the name, this phase runs after Phase 4 (Document Generation) and before Phase 5 (PRD Review). The "3.5" identifier is historical, anchored to the PRD's Pattern-2 specification so cross-references stay searchable.

Skip this phase if slopcheck.enabled: false in Session Config (default).

After the PRD is generated, scan the PRD body for package mentions and run classifyPackages() from scripts/lib/slopcheck.mjs against them.

Detection

Look for these patterns in the PRD body:

• npm: code-fenced blocks with pnpm add, npm install, npm i, or bare package names in ## Dependencies / ## Affected Files sections
• pip: pip install, requirements.txt references
• cargo: cargo add, Cargo.toml deps section

Extract package names + registry tuples: [{name: 'react', registry: 'npm'}, ...].

Dispatch

import { classifyPackages } from '../../scripts/lib/slopcheck.mjs';
const results = await classifyPackages(detectedPackages);

Handling per classification

• LEGITIMATE: no action, continue.
• ASSUMED: append "Package Legitimacy Audit" section to PRD body with the ASSUMED list. No user interaction required. Operator can review before close.
• SUS: AskUserQuestion: "Package has audit warning: . Continue anyway, replace, or remove?"
• SLOP: AskUserQuestion (BLOCKING): "Package not found in registry. Possible LLM hallucination. Options: abort plan, correct name, mark as experimental in PRD body."

Fail-Soft

If classifyPackages returns {classification: 'ASSUMED', evidence: 'registry-timeout'} or 'cache-error', treat as ASSUMED + log to stderr. Never block plan generation due to slopcheck failure — log + continue.

Skip Conditions

• slopcheck.enabled: false in Session Config (default)
• PRD contains no package mentions
• slopcheck.sources does not include plan (e.g., set to [discovery] only)

Phase 5: PRD Review (skip for retro mode)

5.1 Dispatch Reviewer

Dispatch a reviewer subagent: read prd-reviewer-prompt.md in this skill directory for review instructions. Pass the full PRD content to the reviewer.

The reviewer checks 7 criteria:

1. Completeness — all sections filled, no TBD or placeholder content
2. Consistency — no internal contradictions between sections
3. Clarity — unambiguous enough that a developer could implement from this document alone
4. Scope — focused on one project/feature, not sprawling across multiple subsystems
5. YAGNI — no unrequested features or gold-plating
6. SMART metrics — success criteria are Specific, Measurable, Achievable, Relevant, Time-bound
7. User Stories (gated — active only when a populated ## User Stories section is present) — section present, every story in one complete form (either the Als/möchte/damit persona form, or the job-story form: "When [situation], I want [motivation], so I can [outcome]"), each story links ≥1 acceptance criterion; SKIP when no User Stories section. No INVEST checks.

5.2 Revision Loop

If any criterion is FAIL:

1. Read the reviewer's feedback
2. Revise the affected PRD sections
3. Re-submit to the reviewer

Maximum 3 iterations. After 3 iterations with remaining issues, present them to the user via AskUserQuestion:

AskUserQuestion({
  questions: [{
    question: "The PRD reviewer flagged these remaining issues after 3 revision rounds:\n\n[list issues]\n\nHow do you want to proceed?",
    header: "PRD Review",
    options: [
      { label: "Accept as-is (Recommended)", description: "Issues are minor, proceed with current PRD." },
      { label: "Manual edit", description: "I'll edit the PRD myself before continuing." },
      { label: "Re-run review", description: "Try one more revision round." }
    ],
    multiSelect: false
  }]
})

5.3 User Review Gate

After the reviewer passes (or user accepts), present the final PRD:

AskUserQuestion({
  questions: [{
    question: "PRD is ready for your review. It has been saved to [path].\n\nPlease review the document and confirm.",
    header: "PRD Approval",
    options: [
      { label: "Approve PRD (Recommended)", description: "PRD looks good, proceed to issue creation." },
      { label: "Request changes", description: "I have feedback — let me describe what to change." }
    ],
    multiSelect: false
  }]
})

If user requests changes, apply them, save the updated document, and re-present for approval. No limit on user-requested revisions.

Phase 5.5: PRD Commit Gate (all modes)

Two prior /plan sessions filed issues referencing a PRD path that no downstream session could find, because the document was written to disk (Phase 4.3) but never committed (issue #784). This gate closes that gap mechanically, right after user approval (Phase 5) and before any issue is filed (Phase 6). It applies to every mode that reaches Phase 6 — including /plan retro, which skips Phase 5's review loop but still saves a document and (conditionally) files issues.

5.5.1 Commit the Document

The Epic issue does not exist yet at this point in the flow — do NOT reference an issue number in the commit message. Use a session-dated message instead:

git add {plan-prd-location}/YYYY-MM-DD-{project-or-feature-name}.md   # or {plan-retro-location}/YYYY-MM-DD-retro.md
git commit -m "docs(prd): {project-or-feature-name} PRD (plan-session YYYY-MM-DD)"

For /plan retro, use "docs(retro): YYYY-MM-DD retrospective (plan-session YYYY-MM-DD)" — the retro document has no Epic wrapper by default.

5.5.2 Verify the Commit Landed

Both checks MUST pass before Phase 6 starts. Quote both outputs per VBC-001 — a bare claim of "committed" without this evidence is exactly the unverifiable-claim failure mode this gate exists to close:

git status --porcelain <doc-path>   # MUST be empty — no staged/unstaged diff remains on the doc
git ls-files <doc-path>             # MUST print the path — confirms it is tracked at HEAD

If either check fails, the commit did not land. Do not proceed to Phase 6 — diagnose (uncommitted hunk, wrong path, .gitignore collision) and retry § 5.5.1.

5.5.3 Push Timing (Not This Gate's Job)

This gate guarantees HEAD-presence, not remote-presence. Do not push here — push timing remains the session's normal /close responsibility. If the session pushes before /close, the PRD rides along; if not, /close's commit+push flow carries it to the remote in the ordinary course.

5.5.4 Headless / Autopilot

The gate is a mechanical git step, not a judgment call — it applies unchanged in headless/autopilot mode. No AskUserQuestion is required here; run § 5.5.1 and § 5.5.2 exactly as above.

5.5.5 Epic Backlink (Phase 6 Followup)

The Epic issue's number is not known during § 5.5.1. Once Phase 6 creates it, see § 6.6 for the small follow-up commit that adds the Epic reference to the document.

Phase 6: Issue Creation (all modes)

6.1 Derive Issue Structure

If the PRD contains a populated ## User Stories section (story toggle was "yes"):

• Each user story becomes exactly one issue. The issue body carries the story text (Als/möchte/damit) plus its linked Gherkin/EARS acceptance criteria (the story's ↳ AC: targets). Group under an Epic named after the feature/project.

Otherwise (no User Stories section — status quo), determine Epic and sub-issues based on mode:

• /plan new — derive from PRD Section 4 (Solution & Scope). Each major scope item becomes a sub-issue. Group under an Epic named after the project.
• /plan feature — derive from PRD Section 3 (Acceptance Criteria). Each Given/When/Then block becomes a sub-issue. Group under an Epic named after the feature.
• /plan retro — derive from the improvement actions in the reflection phase. Each action becomes an issue (no Epic wrapper unless 5+ actions).

6.2 Auto-Prioritize

Score each issue using three factors:

1. Technical dependencies (highest weight): Issues that other issues depend on get priority::critical or priority::high. Identify dependency chains: DB schema before API, API before frontend, shared libs before consumers, infrastructure before application.

2. Business value (medium weight): Issues the user marked as core MVP features in the PRD get priority::high. Nice-to-haves and polish items get priority::medium or priority::low.

3. Risk (tiebreaker) — Impact × Risk 2×2 triage: Classify each issue by Impact (high/low) and Risk (high/low) before applying the bump:

   • High-Impact + Low-Risk → Implement. Proceed directly; apply the one-level priority bump from the tiebreaker rule.
   • High-Impact + High-Risk → Experiment. De-risk with the smallest possible spike first (a time-boxed investigation issue) before scheduling the full-scope issue.
   • Low-Impact + Low-Risk → Defer. Push to backlog rather than scheduling in this PRD's issue set.
   • Low-Impact + High-Risk → Reject. Do not create an issue for this candidate; note the rejection rationale in the PRD's Risks & Dependencies section instead.

Assign labels from the standard taxonomy:

• priority::critical / priority::high / priority::medium / priority::low
• type:feature / type:enhancement / type:bug / type:chore / type:discovery
• status:ready
• area:<inferred from content> (e.g., area:api, area:frontend, area:infra)
• For /plan new: add appetite:<1w|2w|6w> and mvp-phase labels where applicable

6.3 User Review

Present the full issue structure via AskUserQuestion before creating anything:

AskUserQuestion({
  questions: [{
    question: "Proposed issue structure:\n\n**Epic:** [title]\n\n| # | Sub-Issue | Priority | Labels | Blocked By |\n|---|----------|----------|--------|------------|\n| 1 | [title]  | critical | [labels] | — |\n| 2 | [title]  | high     | [labels] | #1 |\n| ... | ... | ... | ... | ... |\n\nTotal: [N] issues. Confirm or adjust.",
    header: "Issue Review",
    options: [
      { label: "Create all issues (Recommended)", description: "Proceed with the proposed structure." },
      { label: "Adjust priorities", description: "I want to change some priorities before creating." },
      { label: "Remove issues", description: "Some issues should not be created." },
      { label: "Cancel", description: "Do not create any issues." }
    ],
    multiSelect: false
  }]
})

If user selects "Adjust priorities" or "Remove issues", handle the adjustments interactively and re-present.

6.4 Create Issues

VCS Reference: Detect the VCS platform per the "VCS Auto-Detection" section of the gitlab-ops skill. Use CLI commands per the "Common CLI Commands" section.

For each approved issue:

1. Create via VCS CLI using comma-separated labels in a single --label flag:
   • GitLab: glab issue create --title "[Plan] <title>" --label "type:feature,priority::high,status:ready" --description "<body>"
   • GitHub: gh issue create --title "[Plan] <title>" --label "type:feature,priority::high,status:ready" --body "<body>"
2. Brief pause (1s) between creations for rate limiting
3. After all issues are created, set dependency links:
   • GitLab: use glab api to set blocks/is-blocked-by relations. On HTTP 403 (non-Premium/Ultimate): relates_to + body-ordering-note fallback — see gitlab-ops SKILL.md § "Issue Linking (blocks / is_blocked_by)".
   • GitHub: note dependencies in issue body (GitHub lacks native blocking)

6.5 Final Report

## Plan Complete

### Document
- [PRD/Retro] saved to: [path]
- Review status: [approved / accepted with notes]

### Issues Created
| # | Title | Priority | Labels | Blocks |
|---|-------|----------|--------|--------|
| <IID> | <title> | <priority> | <labels> | <blocked issues> |

### Dependencies
[Dependency graph as text: #1 → #2 → #4, #1 → #3, #5 (independent)]

### Next Steps
- [Contextual recommendations based on mode]

For /plan new, next steps include: "Run /session feature in the new repo to begin implementation." For /plan feature, next steps include: "Run /session feature to implement this PRD." For /plan retro, next steps include: "Address improvement issues in your next session."

6.6 Epic Backlink Commit (PRD Update)

Once § 6.4 creates the Epic issue, its IID is known. Update the document to reference it, then commit as a separate, small follow-up commit — never amend the § 5.5.1 commit (amending risks clobbering a commit the session may already have pushed, or that a sibling session has based work on; see parallel-sessions.md PSA-003/PSA-004).

1. Add or update a status line near the top of the document body (e.g. next to **Status:**) with **Epic:** #<IID>.
2. Save the document to the same path used in § 4.3 / § 5.5.1.
3. Commit:

   git add <doc-path>
   git commit -m "docs(prd): link {project-or-feature-name} PRD to Epic #<IID>"
   

Skip this step if issue creation was cancelled at § 6.3 ("Cancel") — there is no Epic number to backlink. For /plan retro without an Epic wrapper (fewer than 5 improvement actions — see § 6.1), skip this step as well.

Critical Rules

• NEVER skip the Q&A phase — even if the user provides a detailed brief, validate through structured questions. The Q&A surfaces blind spots.
• NEVER assume projects-baseline templates — always read from the configured plan-baseline-path. Templates change; hardcoded assumptions break.
• ALWAYS research before asking — dispatch Explore agents before every Q&A wave. Questions without research backing are guesses.
• ALWAYS mark Option 1 as recommended — with (Recommended) in the label. Every question must have a clear recommendation.
• ALWAYS use AskUserQuestion — never present options as plain text. The structured UI is mandatory.
• ALWAYS save documents before creating issues — the PRD/retro document is the source of truth. Issues reference it.
• ALWAYS commit the PRD before creating issues — see Phase 5.5 (HARD-GATE). A saved-but-uncommitted document is unverifiable by any downstream session; commit to HEAD is the trust boundary, not disk-write.
• Security — never include internal paths, IPs, or infrastructure details in output documents. Read sensitive baseline areas for context but filter from outputs.
• Idempotency — if the user re-runs /plan with the same mode, check for an existing PRD at the target location. If found, use AskUserQuestion to offer: "Update existing PRD" vs. "Create new version" vs. "Cancel".

Sub-File Reference

This skill uses 8 sub-files in the same directory:

Source: hashgraph-online/awesome-codex-plugins → plugins/Kanevry/session-orchestrator/skills/plan/SKILL.md