Plan Skill

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

Phase 0: Bootstrap Gate

Read

skills/_shared/bootstrap-gate.md

skills/bootstrap/SKILL.md

Phase 1: Read Session Config

Read and parse Session Config per

skills/_shared/config-reading.md

$CONFIG

After parsing, verify that

plan-baseline-path

echo "$CONFIG" | jq -e '."plan-baseline-path"'

plan-baseline-path

## Session Config

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

~

$HOME

plan-baseline-path

plan-prd-location

plan-retro-location

plan-baseline-path

/plan new

If no

## Session Config

/plan

plan-baseline-path

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

Parse

$ARGUMENTS

• 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

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()

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

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

Phase 5: PRD Review (skip for retro mode)

5.1 Dispatch Reviewer

Dispatch a reviewer subagent: read

prd-reviewer-prompt.md

The reviewer checks 6 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

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 6: Issue Creation (all modes)

6.1 Derive Issue Structure

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): Issues with identified risks, unknowns, or external dependencies get bumped up one priority level.

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
   • 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

/session feature

/plan feature

/session feature

/plan retro

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.
• 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:

soul.md

mode-new.md

mode-feature.md

mode-retro.md

prd-full-template.md

/plan new

prd-feature-template.md

/plan feature

retro-template.md

/plan retro

prd-reviewer-prompt.md