session-orchestrator 3.16.0

package/.cursor/rules/030-wave-execution.mdc

@@ -0,0 +1,216 @@
+---
+description: "When executing session plan waves via /go command — task sequencing, quality checks, progress tracking"
+globs: ""
+alwaysApply: false
+---
+
+# Wave Execution (Cursor Adaptation)
+
+> **CRITICAL**: Cursor does NOT have an `Agent()` tool. All wave tasks execute **sequentially in the current Composer session**. You are both the coordinator AND the implementer. Agent dispatch (3-tier resolution: project > plugin > general-purpose) is NOT applicable — follow the role's agent-prompt patterns directly.
+
+> **State directory**: All state files live in `.cursor/` (STATE.md, wave-scope.json).
+
+## Pre-Execution
+
+Before starting Wave 1:
+
+1. `git status --short` — commit or stash any uncommitted changes
+2. Capture baseline: `SESSION_START_REF=$(git rev-parse HEAD)` — keep for the whole session
+3. Confirm the agreed plan is still valid
+4. Read `persistence` from Session Config (default: `true`)
+
+### Initialize STATE.md (if persistence enabled)
+
+Create `.cursor/STATE.md` (`mkdir -p .cursor` if needed):
+
+```yaml
+---
+schema-version: 1
+session-type: feature|deep|housekeeping
+branch: <current branch>
+issues: [<issue numbers from plan>]
+started_at: <ISO 8601 timestamp>
+status: active
+current-wave: 0
+total-waves: <from session plan>
+---
+```
+
+```markdown
+## Current Wave
+
+Wave 0 — Initializing
+
+## Wave History
+
+(none yet)
+
+## Deviations
+
+(none yet)
+```
+
+## Wave Loop
+
+For each wave in the session plan:
+
+### Step 1: Write Scope Manifest
+
+Write `.cursor/wave-scope.json` before each wave. Set `enforcement: warn` — Cursor's afterFileEdit hook is post-hoc (warns only, cannot block):
+
+```json
+{
+  "wave": 1,
+  "role": "<role>",
+  "enforcement": "warn",
+  "allowedPaths": ["<union of all task file scopes for this wave>"],
+  "blockedCommands": ["rm -rf", "git push --force", "DROP TABLE", "git reset --hard", "git checkout -- ."]
+}
+```
+
+Role-specific scope rules:
+- **Discovery**: `allowedPaths: []` — READ-ONLY, do not edit files
+- **Quality Phase 1 (Simplification)**: production files changed this session only (no test files)
+- **Quality Phase 2 (Tests)**: test file patterns only (`**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`)
+
+Validate with: `bash "$CURSOR_RULES_DIR/../scripts/validate-wave-scope.sh"` — fix JSON if it exits 1.
+
+### Step 2: Execute Tasks Sequentially
+
+For each task in the wave:
+1. Read the task description and acceptance criteria
+2. Implement the task fully (you are the implementer)
+3. Report status after each task:
+   ```
+   Task "[description]": done|partial|failed — [1-line summary]
+   ```
+4. If stuck, note the blocker and move to the next task
+
+**DO NOT commit during wave execution** — `/close` handles commits.
+
+### Step 3: Run Incremental Quality Checks
+
+After ALL tasks in the wave complete:
+
+| Role | Quality check |
+|------|--------------|
+| Discovery | None (read-only) |
+| Impl-Core | typecheck + test changed files |
+| Impl-Polish | typecheck + test changed files + integration verification |
+| Quality | Full Gate: typecheck + test + lint — all must pass |
+| Finalization | `git status` — verify clean state |
+
+### Step 4: Quality Wave — Simplification Pass
+
+At the START of the Quality wave, before running tests:
+
+1. `git diff --name-only $SESSION_START_REF..HEAD` — list files changed this session
+2. Filter to production files (exclude `*.test.*`, `*.spec.*`, `__tests__/`). If none, skip.
+3. Review each production file for AI-generated patterns and apply targeted cleanup:
+   - Remove unnecessary try-catch around non-throwing operations
+   - Delete over-documentation (params that restate the name, returns that say "the result")
+   - Replace re-implemented stdlib functions with standard alternatives
+   - Simplify redundant boolean logic (if/else returning true/false, double negation)
+   - **Do NOT change functionality**
+4. After simplification, run Full Gate quality checks (typecheck + test + lint)
+
+**Note:** Session-reviewer cannot be dispatched as a subagent on Cursor. Quality review is deferred to session-end Phase 1.8. In-wave quality relies on incremental checks + this simplification pass.
+
+### Step 5: Update STATE.md (if persistence enabled)
+
+After each wave:
+
+1. **Frontmatter**: update `current-wave` to the completed wave number
+2. **`## Current Wave`**: replace with next wave info
+3. **`## Wave History`**: append:
+   ```
+   ### Wave N — <Role>
+   - Task "[description]": done|partial|failed — [files changed] — [1-line note]
+   ```
+4. **`## Deviations`**: if plan was adapted, append:
+   ```
+   - [<ISO timestamp>] Wave N: <what changed and why>
+   ```
+
+### Step 6: Capture Wave Metrics (if persistence enabled)
+
+Record after each wave:
+- `wave_number`, `role`, `agent_count` (always 1 on Cursor), `files_changed`
+- Per-task results: `{description, status: done|partial|failed}`
+- `quality_check`: pass/fail/skipped
+
+This data is written to `.orchestrator/metrics/sessions.jsonl` by session-end.
+
+### Step 7: Report Wave Status
+
+```
+## Wave [N] ([Role]) Complete
+
+- Task 1: [done/partial/failed] — [1-line summary]
+- Task 2: [done/partial/failed] — [1-line summary]
+- Tests: [passing/failing] | TypeScript: [0 errors / N errors]
+- Adaptations for Wave [N+1] ([NextRole]): [none / list changes]
+```
+
+### Step 8: Adapt Plan (if needed)
+
+- **On track**: proceed to next wave as planned
+- **Minor issues**: add fix tasks to the next wave
+- **Major blocker**: STOP — inform the user, propose revised plan
+- **Scope change**: document WHY, adjust remaining waves, inform user
+
+## Agent-Mapping Config (Reference Only)
+
+If Session Config includes `agent-mapping`, use it to determine which role's prompt patterns to follow for each task type (e.g., `db-specialist` patterns for DB tasks). On Cursor this is reference only — no actual agent dispatch occurs.
+
+## Circuit Breaker
+
+**If the same error appears 3+ times:**
+
+1. STOP immediately
+2. Report:
+   ```
+   CIRCUIT BREAKER: Stuck on [error description].
+   Attempted [N] times. Same error persists.
+
+   Options:
+   1. Narrow scope and retry with a different approach
+   2. Skip this task and continue with remaining waves
+   3. Abort session
+   ```
+3. Wait for user decision
+
+**Spiral indicators**: same file edited 3+ times without progress, same error repeating, reverting own changes.
+
+## Session Type Behavior
+
+| Type | Behavior |
+|------|----------|
+| Housekeeping | Serial tasks, no wave-scope.json, Baseline QC at end, single commit via /close |
+| Feature | Full 5-role wave execution, incremental QC |
+| Deep | Full 5-role wave execution, extra emphasis on Discovery and Quality roles |
+
+## Completion
+
+After the final (Finalization) wave:
+1. Delete `.cursor/wave-scope.json`
+2. Report final status to the user
+3. Suggest running `/close` — do NOT auto-commit
+
+## Error Recovery
+
+| Situation | Action |
+|-----------|--------|
+| Tests fail after wave | Diagnose and fix, don't skip |
+| TypeScript errors introduced | Track count, fix by Quality wave |
+| New critical issue discovered | Inform user, add to remaining waves if in scope |
+| Edits to wrong files | Revert via git, redo with correct scope |
+| Stuck in loop | Trigger circuit breaker (see above) |
+
+## Anti-Patterns
+
+- **NEVER** skip inter-wave review — quality degrades exponentially
+- **NEVER** commit during wave execution — `/close` handles that
+- **NEVER** continue to next wave with unresolved failures
+- **NEVER** execute without reporting progress to the user
+- **NEVER** modify files outside the wave's `allowedPaths`

package/.cursor/rules/040-discovery.mdc

@@ -0,0 +1,242 @@
+---
+description: "When the user types /discovery or requests quality analysis, code audit, or issue detection"
+globs: ""
+alwaysApply: false
+---
+
+# Discovery — Quality Analysis & Issue Detection
+
+Systematic quality discovery that runs modular probes adapted to the project's tech stack, presents findings interactively, and creates VCS issues for confirmed problems.
+
+## Invocation
+
+- **Standalone** (`/discovery [scope]`): Full flow with interactive triage (Phases 0-5 + Phase 6 stats)
+- **Embedded** (from session-end when `discovery-on-close: true`): Phases 0-3 only, returns structured JSON to caller
+
+Scope accepts: `all` (default), `code`, `infra`, `ui`, `arch`, `session`, `audit`, `vault`, `feature`, or comma-separated like `code,session`.
+
+## Phase 0: Read Session Config
+
+Read Session Config from CLAUDE.md. Parse discovery-specific fields:
+- `discovery-probes`, `discovery-exclude-paths`, `discovery-severity-threshold`, `discovery-confidence-threshold`, `discovery-on-close`
+
+## Phase 1: Stack Detection
+
+Detect the project's tech stack via marker file checks (Glob):
+
+| Marker File(s) | Activates |
+|----------------|-----------|
+| `package.json` | JS/TS probes |
+| `tsconfig.json` | TypeScript probes |
+| `requirements.txt` / `pyproject.toml` | Python probes |
+| `Dockerfile` / `docker-compose.yml` | Container probes |
+| `.github/workflows/` | GitHub CI probes |
+| `.gitlab-ci.yml` | GitLab CI probes |
+| `next.config.*` / `nuxt.config.*` | SSR probes |
+| `tailwind.config.*` | Tailwind probes |
+| `.orchestrator/` exists | Session probes |
+
+Build activation set: start with marker-matched probes → intersect `discovery-probes` config (if set) → restrict to scope argument (if passed).
+
+Default exclude paths (always apply): `node_modules/`, `.git/`, `dist/`, `build/`, `.next/`, `.nuxt/`, `coverage/`. Add paths from `discovery-exclude-paths`.
+
+Report: "Discovery: [N] probes active across [categories]. Stack: [detected]. Threshold: [severity]."
+
+## Phase 2: Probe Execution
+
+Run probes **sequentially** — Cursor has no parallel agents. One category at a time. Complete each category's analysis before moving to the next.
+
+### 6 Probe Categories
+
+**Code probes** (any project with source files):
+- `hardcoded-values`, `orphaned-annotations`, `dead-code`, `ai-slop`, `type-safety-gaps`, `test-coverage-gaps`, `test-anti-patterns`, `security-basics`
+
+**Infra probes** (when CI/Docker markers found):
+- CI configuration issues, Dockerfile anti-patterns
+
+**UI probes** (when frontend frameworks detected):
+- Accessibility gaps, component anti-patterns
+
+**Arch probes** (any project):
+- Circular dependencies, complexity hotspots, deep nesting
+
+**Session probes** (when `.orchestrator/` exists):
+- Session metric anomalies, recurring failures, stale learnings
+
+For each probe match, record a finding in this exact format:
+```
+FINDING:
+  probe: <probe_name>
+  category: <category>
+  severity: <critical|high|medium|low>
+  file_path: <absolute path>
+  line_number: <number>
+  matched_text: <exact text from tool output>
+  title: <short title>
+  description: <1-2 sentence description>
+  recommended_fix: <concrete fix suggestion>
+```
+
+If a probe's activation condition is not met, skip with note. If a probe command fails, skip gracefully and continue.
+
+**CRITICAL**: Do NOT fabricate findings. Only report what tool output confirms.
+
+### Key Detection Patterns
+
+| Probe | Severity | Pattern |
+|-------|----------|---------|
+| Hardcoded secrets | Critical | `(password\|api_key\|secret\|token)\s*[:=]\s*["'][^"']+["']` (exclude test/env/fixtures) |
+| eval usage | High | `eval\s*\(` |
+| XSS (React) | High | `dangerouslySetInnerHTML` |
+| SQL injection | High | `` `[^`]*SELECT[^`]*\$\{`` |
+| any type | Medium | `:\s*any\b` or `as\s+any\b` |
+| TS suppression | Medium | `@ts-ignore` |
+| AI filler | Medium | `(as you can see\|it's worth noting\|needless to say)` |
+
+## Phase 3: Verification & Scoring
+
+### 3.1 Verify Each Finding
+
+For EACH finding: read the file at `file_path:line_number`. Confirm `matched_text` appears at or near that line (+/-3 lines tolerance). If NOT confirmed, discard as false positive.
+
+Report: "Verification: N confirmed, M discarded as false positives"
+
+### 3.2 Confidence Scoring
+
+Start at 40 baseline, add factor scores, clamp to 0-100. Critical severity findings always get minimum 70.
+
+| Factor | Low (+0) | Medium (+10) | High (+20) |
+|--------|----------|-------------|------------|
+| Pattern specificity | Generic (URL, TODO) | Moderate (orphaned annotation) | Specific (API key regex, eval()) |
+| File context | Test/example/docs | Utility/config/scripts | Production source/API handler |
+| Historical signal | Previously dismissed | No prior data | Recurring issue |
+
+Read `discovery-confidence-threshold` from config (default: 60).
+
+### 3.3 Deduplication
+
+Same `file_path` + overlapping line range (+/-5 lines) + different probes = duplicate. Keep higher severity finding.
+
+### 3.4 Apply Thresholds
+
+Remove findings below `discovery-severity-threshold` and below `discovery-confidence-threshold`. Log auto-dismissed count.
+
+### 3.5 Embedded Mode Exit
+
+If in embedded mode (called from session-end): STOP HERE. Return this JSON schema:
+
+```json
+{
+  "findings": [
+    {"probe": "string", "category": "string", "severity": "critical|high|medium|low",
+     "confidence": 0, "file": "string", "line": 0, "description": "string", "recommendation": "string"}
+  ],
+  "stats": {
+    "probes_run": 0, "findings_raw": 0, "verified": 0,
+    "false_positives": 0, "by_category": {"<category>": {"findings": 0}}
+  }
+}
+```
+
+## Phase 4: Interactive Triage (Standalone Only)
+
+Use **numbered Markdown lists** for all choices — Cursor does not have AskUserQuestion.
+
+### Step 1: Summary Table
+
+```
+## Discovery Results
+
+Probes run: [N] | Findings verified: [N] | False positives discarded: [N]
+
+| Category | Critical | High | Medium | Low | Total |
+|----------|----------|------|--------|-----|-------|
+| Code     | ...      | ...  | ...    | ... | ...   |
+| Infra    | ...      | ...  | ...    | ... | ...   |
+| UI       | ...      | ...  | ...    | ... | ...   |
+| Arch     | ...      | ...  | ...    | ... | ...   |
+| Session  | ...      | ...  | ...    | ... | ...   |
+| Audit    | ...      | ...  | ...    | ... | ...   |
+| Vault    | ...      | ...  | ...    | ... | ...   |
+| Feature  | ...      | ...  | ...    | ... | ...   |
+```
+
+### Step 2: Critical + High Findings — Review Individually
+
+For each Critical or High finding, present with file context (+/-3 lines):
+
+```
+[CRITICAL] (confidence: 85) hardcoded-values: API key found in src/config.ts:42
+
+<file context>
+
+Recommended fix: <suggestion>
+
+Options:
+1. Create issue (critical)
+2. Adjust priority
+3. Dismiss — intentional
+4. Dismiss — false positive
+```
+
+### Step 3: Medium + Low Findings — Review Batched
+
+```
+[N] medium/low findings in [category]:
+1. [title] — [file_path]:[line] ([severity])
+
+Options:
+1. Accept all (Recommended) — create issues for all
+2. Review individually
+3. Dismiss all
+```
+
+### Step 4: Batch Confirmation
+
+```
+Ready to create [N] issues? ([X] critical, [Y] high, [Z] medium, [W] low)
+
+1. Create all [N] issues (Recommended)
+2. Review list first
+3. Cancel
+```
+
+## Phase 5: Issue Creation
+
+For each approved finding:
+1. Format using gitlab-ops discovery issue template
+2. Labels: `type:discovery` + `priority:<level>` + `area:<inferred>` + `status:ready`
+3. **GitLab**: `glab issue create --title "[Discovery] <title>" --label "type:discovery,priority:<level>,area:<area>,status:ready" --description "<body>"`
+4. **GitHub**: `gh issue create --title "[Discovery] <title>" --label "..." --body "<body>"`
+5. Brief pause (1s) between creations
+
+### Final Report
+
+```
+## Discovery Report
+- Probes run: [N] across [categories]
+- Verified: [N] (false positives: [M])
+- User approved: [N]
+- Issues created: [N]
+
+| # | Title | Priority | Area | Probe |
+|---|-------|----------|------|-------|
+```
+
+## Phase 6: Capture Stats (Standalone Only)
+
+After Phase 5, prepare stats for session metrics (do NOT write to `sessions.jsonl` directly — session-end handles that):
+
+- `probes_run`, `findings_raw`, `findings_verified`, `false_positives`, `user_dismissed`, `issues_created`, `by_category`
+
+Report: "Discovery stats: [probes_run] probes, [findings_raw] raw → [findings_verified] verified ([false_positives] false positives). Created [issues_created] issues."
+
+## Critical Rules
+
+- **NEVER** fabricate findings — every finding must come from tool output with verifiable evidence
+- **NEVER** create issues without user approval (standalone mode)
+- **ALWAYS** verify findings by re-reading the file at the reported line (Phase 3)
+- **ALWAYS** use numbered Markdown lists for choices — Cursor has no AskUserQuestion
+- If a probe command fails, skip gracefully, continue with others
+- If in embedded mode, stop after Phase 3, return findings as structured JSON
+- Default exclude paths always apply

package/.cursor/rules/050-plan.mdc

@@ -0,0 +1,235 @@
+---
+description: "When the user types /plan or asks to create a project plan, feature PRD, or retrospective"
+globs: ""
+alwaysApply: false
+---
+
+# Plan — Structured Project Planning & PRD Generation
+
+Three planning modes with a shared research-driven Q&A engine. Pattern across all modes: **research → questions → document → review → issues**.
+
+## Phase 0: Read Session Config
+
+Read Session Config from CLAUDE.md. Required field: `plan-baseline-path`. If missing or absent, stop with error:
+
+> "Error: `plan-baseline-path` is not configured in Session Config. Add it to your CLAUDE.md under `## Session Config`. Example: `plan-baseline-path: ~/Projects/projects-baseline`"
+
+Additional fields: `plan-default-visibility`, `plan-prd-location`, `plan-retro-location`, `vcs`. Expand `~` in paths.
+
+## Phase 1: Mode Selection
+
+Parse the argument to determine mode:
+
+- **`new`** — Project kickoff: scaffolding, architecture decisions, initial setup
+- **`feature`** — Feature PRD: requirements gathering, compact scope, acceptance criteria
+- **`retro`** — Retrospective: data-driven analysis of recent work, learnings extraction
+
+If no mode specified, ask via numbered list:
+
+```
+Which planning mode?
+
+1. new (Recommended) — Project kickoff (full PRD, repo setup, issue creation)
+2. feature — Feature PRD (compact scope, acceptance criteria, issues)
+3. retro — Retrospective (metrics analysis, reflection, improvement actions)
+```
+
+## Phase 2: Q&A Engine (Shared Core)
+
+Every question wave follows the same pattern. This is the core mechanic across all modes.
+
+### 2.1 Pre-Question Research
+
+Before each Q&A wave, perform research **sequentially** — Cursor has no parallel agents:
+
+1. **Market/online context** — Search for relevant market data, best practices, competitor analysis, or technical patterns for the upcoming questions
+2. **Baseline analysis** — Read projects-baseline templates, rules, and scripts at `$BASELINE_PATH` (Glob, Grep, Read)
+3. **Repo context** — Analyze current repository for patterns, file structure, dependencies, conventions (skip for `/plan new` wave 1)
+
+### 2.2 Question Presentation
+
+Synthesize research into **5 questions per wave**. Present as numbered Markdown lists — Cursor has no AskUserQuestion:
+
+- **Option 1 is ALWAYS the recommendation**, marked with `(Recommended)`
+- Include Pros/Cons drawn from the research for each option
+- Include an "Other" option when custom input makes sense
+
+Example:
+```
+## Architecture (Wave 1, Q1)
+
+Which project archetype fits best?
+
+1. nextjs-saas (Recommended) — Pro: Full SaaS stack with auth, payments. Con: Heavier setup.
+2. express-service — Pro: Lightweight API. Con: No frontend.
+3. docker-service — Pro: Maximum flexibility. Con: More manual setup.
+4. Other — Describe your preferred archetype.
+```
+
+### 2.3 Adaptive Depth
+
+Starting wave counts: `new` → 3 waves minimum, `feature` → 1 wave minimum, `retro` → 1 wave minimum. Maximum 5 waves across all modes.
+
+After each wave:
+- **Answers clear** → proceed to document generation
+- **Complexity revealed** → add targeted follow-up wave
+- **User aborts** → proceed with answers gathered
+
+### 2.4 Answer Tracking
+
+After each wave, output a recap:
+```
+## Answers So Far (Wave N/M)
+1. Archetype: nextjs-saas
+2. Visibility: internal
+3. Audience: B2B customers
+```
+
+---
+
+## Mode: new — Project Kickoff
+
+**Wave 1** — Core Decisions: archetype (read `$BASELINE_PATH/templates/`), visibility, target audience, core problem, GitLab group.
+
+**Wave 2** — Technical Details (per chosen archetype): tech stack decisions, design style, external integrations, performance requirements, security requirements.
+
+**Wave 3** — Business & Scope: MVP appetite (1w/2w/6w), success criteria (SMART), known risks, post-launch plan, ecosystem dependencies.
+
+Document: 8-section full PRD. Save to `{plan-prd-location}/YYYY-MM-DD-{project-name}.md`.
+
+After PRD approval: run `$BASELINE_PATH/scripts/setup-project.sh`, verify repo, populate CLAUDE.md, commit PRD.
+
+Issues: Epic (project name) + sub-issues per MVP feature from PRD Section 4 (Solution & Scope).
+
+---
+
+## Mode: feature — Feature PRD
+
+**Wave 1** — Feature Core: what to build, why now, who uses it, scope + explicit exclusions, dependencies.
+
+**Wave 2** (conditional — only if Wave 1 reveals multiple subsystems or unclear integration): architecture decisions, integration points, data model changes, edge cases, performance impact.
+
+Document: 5-section compact PRD. Save to `{plan-prd-location}/YYYY-MM-DD-{feature-slug}.md`.
+
+Issues: Epic (feature name) + sub-issues per acceptance criterion group.
+
+---
+
+## Mode: retro — Retrospective
+
+**Phase 1 (automatic, no user input):** Read `.orchestrator/metrics/sessions.jsonl`, run git log analysis, query open issues, compare last 5 vs prior 5 sessions.
+
+**Wave 1** — What went well / what didn't: highlights, blockers with root causes, carryover items, process assessment, data anomalies.
+
+**Wave 2** (conditional — if Wave 1 reveals significant blockers or process issues): improvement actions, priority ranking, ownership, baseline changes, Session Config adjustments.
+
+Artifacts: retro doc → `{plan-retro-location}/YYYY-MM-DD-retro.md`. Improvement issues + learnings update (`.orchestrator/metrics/learnings.jsonl`).
+
+---
+
+## Phase 3: Document Generation
+
+Read the appropriate template from the skill directory:
+- `new` → `prd-full-template.md` (8 sections)
+- `feature` → `prd-feature-template.md` (5 sections)
+- `retro` → `retro-template.md`
+
+Fill ALL sections — no TBD or placeholder content. If a section cannot be filled from gathered data, make a best-effort recommendation and mark it `<!-- REVIEW: inferred from research, confirm with stakeholders -->`.
+
+Save the document, creating the target directory (`mkdir -p`) if needed.
+
+## Phase 4: PRD Review (skip for retro)
+
+Dispatch a sequential self-review (read `prd-reviewer-prompt.md` from skill directory). Reviewer checks 6 criteria:
+1. **Completeness** — all sections filled
+2. **Consistency** — no internal contradictions
+3. **Clarity** — implementable by a developer from this document alone
+4. **Scope** — focused on one project/feature
+5. **YAGNI** — no unrequested features
+6. **SMART metrics** — success criteria are measurable
+
+If any criterion fails, revise and re-review. Maximum **3 iterations**. After 3 rounds with remaining issues, present to user as numbered list:
+
+```
+The PRD reviewer flagged these remaining issues:
+[list]
+
+1. Accept as-is (Recommended) — issues are minor, proceed
+2. Manual edit — I'll edit the PRD myself before continuing
+3. Re-run review — try one more revision round
+```
+
+Then present the saved PRD path and ask for final approval:
+
+```
+PRD saved to [path]. Ready for your review.
+
+1. Approve PRD (Recommended) — proceed to issue creation
+2. Request changes — describe what to change
+```
+
+## Phase 5: Issue Creation
+
+### Auto-Prioritize
+
+Score each issue by three factors:
+1. **Technical dependencies** (highest weight) — blocking issues get `priority:critical` or `priority:high`. DB schema before API, API before frontend.
+2. **Business value** (medium weight) — core MVP = `priority:high`, nice-to-haves = `priority:medium/low`.
+3. **Risk** (tiebreaker) — unknowns or external dependencies bump priority up one level.
+
+Labels: `priority:<level>`, `type:feature/enhancement/chore`, `status:ready`, `area:<inferred>`. For `new`: add `appetite:<1w|2w|6w>`.
+
+### User Confirmation (numbered list)
+
+```
+Proposed issue structure:
+
+Epic: [title]
+
+| # | Sub-Issue | Priority | Labels | Blocked By |
+|---|-----------|----------|--------|------------|
+
+Total: [N] issues.
+
+1. Create all issues (Recommended)
+2. Adjust priorities
+3. Remove issues
+4. Cancel
+```
+
+### Issue Creation
+
+- **GitLab**: `glab issue create --title "[Plan] <title>" --label "<labels>" --description "<body>"`
+- **GitHub**: `gh issue create --title "[Plan] <title>" --label "<labels>" --body "<body>"`
+- 1s pause between creations. Set dependency links after all issues are created (GitLab: `glab api` blocking relations).
+
+### Final Report
+
+```
+## Plan Complete
+
+### Document
+- [PRD/Retro] saved to: [path]
+
+### Issues Created
+| # | Title | Priority | Labels | Blocks |
+|---|-------|----------|--------|--------|
+
+### Dependencies
+[Dependency graph: #1 → #2 → #4, #3 (independent)]
+
+### Next Steps
+- [Contextual: run /session feature to implement, or address improvement issues]
+```
+
+## Critical Rules
+
+- **NEVER skip the Q&A phase** — even with a detailed brief, validate through structured questions
+- **NEVER assume baseline templates** — always read from the configured `plan-baseline-path`
+- **ALWAYS research before asking** — sequential research before every Q&A wave
+- **ALWAYS mark Option 1 as recommended** — with `(Recommended)` on every question
+- **ALWAYS use numbered Markdown lists** — Cursor has no AskUserQuestion
+- **ALWAYS save documents before creating issues** — the PRD/retro document is the source of truth
+- **NEVER leave PRD sections with TBD** — make a best-effort recommendation if data is insufficient
+- **NEVER create issues without user confirmation**
+- **NEVER include internal paths, IPs, or infrastructure details in output documents**