session-orchestrator 3.16.0

package/skills/plan/SKILL.md

@@ -0,0 +1,496 @@
+---
+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
+
+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
+
+```javascript
+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 <name> has audit warning: <evidence>.
+  Continue anyway, replace, or remove?"
+- **SLOP**: AskUserQuestion (BLOCKING): "Package <name> not found in <registry>
+  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)
+
+<HARD-GATE>
+Do NOT proceed to Phase 6 (Issue Creation) until the generated document (PRD or retro) is committed to HEAD. There is no bypass. An issue referencing an uncommitted file is an unverifiable claim — see `.claude/rules/verification-before-completion.md` (VBC).
+</HARD-GATE>
+
+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:
+
+```bash
+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:
+
+```bash
+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:
+   ```bash
+   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:
+
+| File | Purpose |
+|------|---------|
+| `soul.md` | Product Strategist identity — read first, defines communication style and values |
+| `mode-new.md` | Project kickoff mode: 3-wave requirement gathering, repo scaffolding, full PRD |
+| `mode-feature.md` | Feature PRD mode: 1-2 wave discovery, compact PRD, acceptance criteria |
+| `mode-retro.md` | Retrospective mode: metrics analysis, reflection waves, improvement actions |
+| `prd-full-template.md` | 8-section PRD template for `/plan new` |
+| `prd-feature-template.md` | 5-section compact PRD template for `/plan feature` |
+| `retro-template.md` | Retrospective document template for `/plan retro` |
+| `prd-reviewer-prompt.md` | PRD quality review instructions for the reviewer subagent |

package/skills/plan/mode-feature.md

@@ -0,0 +1,141 @@
+# Mode: `/plan feature` — Feature PRD
+
+> Reference file for the plan skill. Read by SKILL.md when mode is `feature`.
+> Covers: feature discovery (1-2 waves) → compact PRD → issue creation.
+> 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).
+
+---
+
+## Phase 1: Feature Discovery (1-2 waves)
+
+### Wave 1 — Feature Core (6 questions)
+
+Before asking questions, dispatch 3 Explore agents in parallel:
+
+```
+Agent({ subagent_type: "Explore", description: "Analyze codebase for related patterns",
+  prompt: "Use Glob and Grep to find existing implementations related to [feature topic].
+  Search relevant directories for similar patterns, naming conventions, and architecture.
+  Report: affected files, current patterns, reuse opportunities." })
+
+Agent({ subagent_type: "Explore", description: "Check VCS for related issues",
+  prompt: "Use Bash to run VCS CLI (glab/gh, auto-detect per gitlab-ops skill).
+  List open issues mentioning [feature topic] or related keywords.
+  Check recent merged MRs/PRs for related work. Report: open issues, recent changes, blockers." })
+
+Agent({ subagent_type: "Explore", description: "Research best practices",
+  prompt: "Use WebSearch to find best practices for [feature type].
+  Look for common pitfalls, recommended patterns, and prior art.
+  Report: top 3 approaches with pros/cons." })
+```
+
+Synthesize agent findings into 2 AskUserQuestion calls (3+3 split):
+
+**Questions:**
+
+1. **What to build** — Open-ended. Analyze the answer and suggest structure (e.g., break into sub-features, identify components). Use codebase agent findings to ground suggestions.
+   - *Multiple candidate subfeatures surfaced?* Rank them by Opportunity Score (see `SKILL.md` § "Opportunity Score (Ranking Candidate Subfeatures)") and present the top-ranked candidate as the `(Recommended)` Option 1.
+2. **Why now** — Business driver, user feedback, or technical necessity? Present agent-found context (related issues, recent changes) as options.
+3. **Who uses it** — Existing personas or new audience? Reference existing user research if available in the repo.
+4. **User-Story-Schicht** — "User-Story-Schicht für dieses Feature erzeugen?" Immer fragen (kein Audience-Heuristik-Gate). Drei Antwortoptionen: **Ja (Als/möchte/damit)** — klassische Persona-Story-Form; **Ja (job-story)** — job-story-Form ("When [situation], I want [motivation], so I can [outcome]"); **Nein** — byte-identisches Status-quo-Verhalten. Bei einer der beiden "Ja"-Optionen emittiert die PRD eine optionale ## User Stories Sektion (je Story ein ↳ AC-Pointer) in der gewählten Form; bei "Nein" wird die Sektion vollständig weggelassen.
+5. **Scope** — MVP appetite (Shape Up: 1w/2w/6w) + explicit exclusions. Push hard for "what is NOT in this feature." First option is always the recommended appetite based on complexity.
+6. **Dependencies** — On existing issues, features, or other repos. Pre-populate from VCS agent findings. Flag blockers.
+
+### Wave 2 — Technical Deep Dive (conditional, 5 questions)
+
+> Trigger Wave 2 only if Wave 1 answers reveal: multiple subsystems affected, unclear
+> integration points, significant architectural decisions needed, or user explicitly
+> requests deeper analysis. Skip otherwise — proceed to Phase 2.
+
+Before asking, dispatch 3 Explore agents:
+
+```
+Agent({ subagent_type: "Explore", description: "Deep-read affected source files",
+  prompt: "Read the specific files identified in Wave 1 findings.
+  Trace call paths from entry points to data layer.
+  Report: file list, function signatures, data flow, coupling points." })
+
+Agent({ subagent_type: "Explore", description: "Check test patterns for affected area",
+  prompt: "Use Glob to find test files for the affected modules.
+  Read test structure and coverage patterns.
+  Report: existing test approach, gaps, suggested test strategy." })
+
+Agent({ subagent_type: "Explore", description: "Research technical approach",
+  prompt: "Use WebSearch and WebFetch for the specific technical challenge identified.
+  Look for library options, performance benchmarks, migration guides.
+  Report: recommended approach with evidence." })
+```
+
+**Questions:**
+
+1. **Architecture decisions** — Based on codebase patterns found by agents. Present 2-3 approaches with trade-offs. First option is the recommendation.
+2. **Integration points** — API changes, new endpoints, event hooks. Pre-populated from deep-read agent findings.
+3. **Data model changes** — DB migrations, schema changes, new tables. Show current schema context.
+4. **Edge cases** — Error handling, concurrent access, backwards compatibility. Agent findings inform likely failure modes.
+5. **Performance impact** — Query complexity, caching needs, load implications. Ground in current performance patterns.
+
+---
+
+## Phase 2: Feature PRD Generation
+
+1. Read `prd-feature-template.md` from this skill directory.
+2. Fill all 5 sections:
+
+| Section | Source |
+|---------|--------|
+| 1. Problem & Motivation | Wave 1 Q1 (what) + Q2 (why). Concise, 2-3 paragraphs. |
+| 2. Solution & Scope | Wave 1 Q5 (scope). Explicit In-Scope and Out-of-Scope lists. |
+| ## User Stories (conditional) | Emit only when the User-Story-Schicht toggle ≠ "Nein"; one story per persona-goal, each linking ≥1 §3/§3.A acceptance criterion. Toggle = "Ja (Als/möchte/damit)" → emit the classic Als/möchte/damit form. Toggle = "Ja (job-story)" → emit the job-story form ("When [situation], I want [motivation], so I can [outcome]"). Omit the section entirely when toggle = "Nein" (byte-for-byte status quo). |
+| 3. Acceptance Criteria | Derive Given/When/Then scenarios from Wave 1 answers. Each sub-feature produces 1-3 Gherkin scenarios. |
+| 3.A Acceptance Criteria (EARS) | OPTIONAL — emit EARS clauses (Ubiquitous/State-driven/Event-driven/Optional feature/Unwanted behaviour) for the same Feature Areas. Used by `/write-executable-plan` for 1:1 vitest stub generation. Leave blank if Section 3 narrative suffices. |
+| 4. Technical Notes | Wave 2 findings if it ran (architecture, affected files, data model). If Wave 2 was skipped, populate from Wave 1 Explore agent findings. |
+| 5. Risks & Dependencies | Wave 1 Q6 (dependencies) + Wave 2 Q4-Q5 (edge cases, performance) if available. |
+
+3. Save to `{plan-prd-location}/YYYY-MM-DD-{feature-slug}.md`. Read `plan-prd-location` from Session Config in CLAUDE.md (or AGENTS.md on Codex CLI) (default: `docs/prd/`).
+4. Dispatch PRD reviewer subagent per `prd-reviewer-prompt.md`. Max 3 iterations. Surface unresolved issues to user.
+5. **Package Legitimacy Audit (Slopcheck — #520):** if Session Config has `slopcheck.enabled: true` and `slopcheck.sources` includes `plan`, run the Phase 3.5 audit defined in `SKILL.md` against the generated PRD body (scan `## Affected Files`, `## Dependencies`, and code-fenced `pnpm add` / `npm install` / `pip install` / `cargo add` blocks for npm/pip/cargo package mentions, then call `classifyPackages()` from `scripts/lib/slopcheck.mjs`). Fail-soft on registry errors. See `SKILL.md` § "Phase 3.5: Package Legitimacy Audit" for the full handling matrix.
+6. **PRD Commit Gate:** before proceeding to Phase 3 (Issue Creation), satisfy the PRD Commit Gate — see `SKILL.md` § Phase 5.5 (HARD-GATE). Do not create issues referencing an uncommitted PRD.
+
+---
+
+## Phase 3: Issue Creation
+
+### Derive Epic + Sub-Issues
+
+Source: PRD Section 3 (Acceptance Criteria).
+
+- **Epic title:** feature name + one-line purpose.
+- **Sub-issues:** one per acceptance criterion group. Group related Given/When/Then scenarios — do not create one issue per individual scenario.
+
+### Auto-Prioritize
+
+Apply this scoring:
+
+1. **Technical dependencies** — Issues that block other issues get `priority:critical` or `priority:high`. DB before API, API before UI, shared before consumers.
+2. **Core acceptance criteria** — Issues covering primary happy-path scenarios get `priority:high`.
+3. **Edge cases / nice-to-haves** — Defensive scenarios, error handling, optional behaviors get `priority:medium` or `priority:low`.
+4. **Risk factor — Impact × Risk 2×2 triage:** Classify by Impact (high/low) × Risk (high/low): **High-Impact + Low-Risk → Implement** (bump priority up one level); **High-Impact + High-Risk → Experiment** (smallest spike first); **Low-Impact + Low-Risk → Defer** (backlog, no issue in this set); **Low-Impact + High-Risk → Reject** (no issue — note rationale in § Risks & Dependencies). Full quadrant definitions: `SKILL.md` § 6.2 Auto-Prioritize.
+
+### Labels
+
+Apply per gitlab-ops skill label taxonomy:
+
+- **Type:** `type:feature` for new capabilities, `type:enhancement` for extensions of existing features.
+- **Priority:** `priority:critical` / `priority:high` / `priority:medium` / `priority:low` from auto-prioritize above.
+- **Area:** Infer from affected code paths (e.g., `area:api`, `area:frontend`, `area:infra`).
+- **Appetite:** Map from Wave 1 Q5 scope answer (`appetite:1w`, `appetite:2w`, `appetite:6w`).
+
+### User Review Gate
+
+Present the full issue structure via AskUserQuestion before creation:
+
+- Epic title and description
+- Each sub-issue: title, priority, labels, dependency links
+- User confirms, adjusts priorities, or removes issues
+
+### Create Issues
+
+1. Create via VCS CLI (auto-detect per gitlab-ops skill: `glab` or `gh`).
+2. Set `blocks` / `is-blocked-by` dependency links between issues. On HTTP 403 (non-Premium/Ultimate): `relates_to` + body-ordering-note fallback — see gitlab-ops SKILL.md § "Issue Linking (`blocks` / `is_blocked_by`)".
+3. Report created issue URLs to user.
+4. **Epic Backlink Commit:** once the Epic issue's IID is known, follow `SKILL.md` § 6.6 to add an `**Epic:** #<IID>` line to the PRD and commit it as a separate follow-up commit.