viepilot 2.4.0 → 2.15.0

package/lib/screenshot-artifact.cjs

@@ -0,0 +1,142 @@
+'use strict';
+/**
+ * screenshot-artifact.cjs
+ * ENH-042 + ENH-043: Optional screenshot/render utility for vp-proposal visual embedding.
+ *
+ * - puppeteer (optional): screenshots HTML artifact files → PNG
+ * - mmdc CLI (optional): renders Mermaid source → PNG
+ * Both return null gracefully when the tool is absent — no crash, no hard dep.
+ *
+ * Usage:
+ *   const { screenshotArtifact, isPuppeteerAvailable,
+ *           isMmdcAvailable, renderMermaidToPng, cleanupScreenshot }
+ *     = require('./lib/screenshot-artifact.cjs');
+ */
+
+const os   = require('os');
+const path = require('path');
+const fs   = require('fs');
+const cp   = require('child_process');
+
+/**
+ * Check if puppeteer is available without throwing.
+ * @returns {boolean}
+ */
+function isPuppeteerAvailable() {
+  try { require.resolve('puppeteer'); return true; } catch { return false; }
+}
+
+/**
+ * Screenshot an HTML file to a temporary PNG using puppeteer (headless Chrome).
+ * Returns null silently when puppeteer is not installed.
+ *
+ * @param {string} htmlPath - Absolute path to the HTML file to screenshot
+ * @param {object} [opts]
+ * @param {number} [opts.width=1280] - Viewport width in px
+ * @param {number} [opts.height=720] - Viewport height in px (matches 16:9 slide ratio)
+ * @returns {Promise<string|null>} Absolute path to a temp PNG file, or null if unavailable
+ */
+async function screenshotArtifact(htmlPath, opts = {}) {
+  // Graceful: return null if puppeteer not installed
+  let puppeteer;
+  try { puppeteer = require('puppeteer'); } catch { return null; }
+
+  if (!htmlPath || !fs.existsSync(htmlPath)) return null;
+
+  const { width = 1280, height = 720 } = opts;
+  const tmpFile = path.join(os.tmpdir(), `vp-artifact-${Date.now()}.png`);
+
+  const browser = await puppeteer.launch({
+    headless: 'new',        // puppeteer ≥ 20 compat
+    args: ['--no-sandbox', '--disable-setuid-sandbox'],  // CI-safe
+  });
+  try {
+    const page = await browser.newPage();
+    await page.setViewport({ width, height });
+    await page.goto(`file://${htmlPath}`, { waitUntil: 'networkidle0', timeout: 15000 });
+    await page.screenshot({ path: tmpFile, fullPage: false });
+    return tmpFile;
+  } finally {
+    await browser.close();
+  }
+}
+
+/**
+ * Clean up a temp screenshot file after embedding.
+ * @param {string|null} tmpPath
+ */
+function cleanupScreenshot(tmpPath) {
+  if (tmpPath && fs.existsSync(tmpPath)) {
+    try { fs.unlinkSync(tmpPath); } catch { /* ignore cleanup errors */ }
+  }
+}
+
+// ── Mermaid rendering (ENH-043) ───────────────────────────────────────────────
+
+/**
+ * Check if @mermaid-js/mermaid-cli (mmdc) is available on PATH.
+ * @returns {boolean}
+ */
+function isMmdcAvailable() {
+  try {
+    const r = cp.spawnSync('mmdc', ['--version'], { encoding: 'utf8', timeout: 5000 });
+    return r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Render a Mermaid diagram source string to a PNG file using the mmdc CLI.
+ * Returns null silently when mmdc is not available or rendering fails.
+ *
+ * @param {string} mermaidSource - Valid Mermaid 10+ source code
+ * @param {string} outputPath - Absolute path for the output .png file
+ * @returns {string|null} outputPath on success, null if mmdc absent or error
+ */
+function renderMermaidToPng(mermaidSource, outputPath) {
+  if (!isMmdcAvailable()) return null;
+  if (!mermaidSource || !mermaidSource.trim()) return null;
+  if (!outputPath) return null;
+
+  const tmpInput = outputPath.replace(/\.png$/i, '.mmd');
+  try {
+    fs.writeFileSync(tmpInput, mermaidSource, 'utf8');
+    const r = cp.spawnSync(
+      'mmdc',
+      ['-i', tmpInput, '-o', outputPath, '-b', 'white'],
+      { encoding: 'utf8', timeout: 30000 }
+    );
+    return (r.status === 0 && fs.existsSync(outputPath)) ? outputPath : null;
+  } catch {
+    return null;
+  } finally {
+    try { if (fs.existsSync(tmpInput)) fs.unlinkSync(tmpInput); } catch { /* ignore */ }
+  }
+}
+
+// ── Missing-tool warning (ENH-044) ───────────────────────────────────────────
+
+/**
+ * Emit a standardized warning to stderr when a visual rendering tool is absent
+ * but visual artifacts exist and embedding is mandatory.
+ *
+ * @param {string} tool - Tool name (e.g. 'puppeteer', 'mmdc')
+ * @param {string} installCmd - Install hint (e.g. 'npm install puppeteer')
+ */
+function warnMissingTool(tool, installCmd) {
+  process.stderr.write(
+    `\n[vp-proposal] ⚠  Visual artifacts found but '${tool}' is not installed.\n` +
+    `  Install to enable screenshots: ${installCmd}\n` +
+    `  Using placeholder/text fallback instead.\n\n`
+  );
+}
+
+module.exports = {
+  screenshotArtifact,
+  isPuppeteerAvailable,
+  cleanupScreenshot,
+  isMmdcAvailable,
+  renderMermaidToPng,
+  warnMissingTool,
+};

package/lib/viepilot-config.cjs

@@ -13,12 +13,16 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
-/** @type {{ language: { communication: string, document: string } }} */
+/** @type {{ language: { communication: string, document: string }, proposal: { recentLangs: string[], defaultLang: string } }} */
 const DEFAULTS = {
   language: {
     communication: 'en',
     document: 'en',
   },
+  proposal: {
+    recentLangs: [],   // MRU list, most recent first, max 5
+    defaultLang: 'en', // kept in sync with recentLangs[0]
+  },
 };
 
 /**
@@ -94,10 +98,37 @@ function resetConfig(overrideHomedir) {
   fs.writeFileSync(configPath, JSON.stringify(DEFAULTS, null, 2) + '\n', 'utf8');
 }
 
+/**
+ * Get the suggested default language for proposals.
+ * Returns recentLangs[0] if present, else 'en'.
+ * @param {string | undefined} overrideHomedir
+ * @returns {string}
+ */
+function getProposalLang(overrideHomedir) {
+  const cfg = readConfig(overrideHomedir);
+  const recent = cfg.proposal && cfg.proposal.recentLangs;
+  return (Array.isArray(recent) && recent.length > 0) ? recent[0] : 'en';
+}
+
+/**
+ * Record a used language: prepend to recentLangs, dedup, cap at 5, sync defaultLang.
+ * @param {string} lang - ISO 639-1 code
+ * @param {string | undefined} overrideHomedir
+ */
+function recordProposalLang(lang, overrideHomedir) {
+  const cfg = readConfig(overrideHomedir);
+  const existing = (cfg.proposal && Array.isArray(cfg.proposal.recentLangs))
+    ? cfg.proposal.recentLangs : [];
+  const updated = [lang, ...existing.filter(l => l !== lang)].slice(0, 5);
+  writeConfig({ proposal: { recentLangs: updated, defaultLang: updated[0] } }, overrideHomedir);
+}
+
 module.exports = {
   DEFAULTS,
   getConfigPath,
   readConfig,
   writeConfig,
   resetConfig,
+  getProposalLang,
+  recordProposalLang,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viepilot",
-  "version": "2.4.0",
+  "version": "2.15.0",
   "description": "**Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**",
   "main": "index.js",
   "bin": {
@@ -72,6 +72,13 @@
       }
     }
   },
+  "dependencies": {
+    "docx": "^9.0.0",
+    "pptxgenjs": "^3.12.0"
+  },
+  "optionalDependencies": {
+    "@googleapis/slides": "^1.0.0"
+  },
   "devDependencies": {
     "jest": "^30.3.0"
   }

package/skills/vp-audit/SKILL.md

@@ -34,6 +34,17 @@ Audit ViePilot project state and documentation to detect drift.
 Works on **any project** using ViePilot (Java, Node, Python, etc.).
 Auto-detects if running inside the viepilot framework repo to enable framework-specific checks.
 
+**Brownfield Import Compatibility (FEAT-018):**
+
+When auditing a project bootstrapped via `vp-crystallize --brownfield`:
+
+- If `docs/brainstorm/` exists and contains **only** `session-brownfield-import.md` (no `session-*.md` greenfield files):
+  - **Valid brownfield import** — do NOT flag as missing brainstorm session.
+  - Verify `session-brownfield-import.md` contains a `## Scan Report` section with a YAML block.
+    - If YAML block absent → flag LOW severity: "Brownfield stub missing Scan Report content."
+  - If `.viepilot/TRACKER.md` contains `## Brownfield Import` section → brownfield metadata confirmed; no further brainstorm check needed.
+- If `docs/brainstorm/` is completely absent → flag MEDIUM severity: "No brainstorm session or brownfield stub found — run `/vp-crystallize` or `/vp-crystallize --brownfield`."
+
 **Tier 1 — ViePilot State Consistency (all projects):**
 - `.viepilot/TRACKER.md` current state vs `.viepilot/phases/*/PHASE-STATE.md`
 - `.viepilot/ROADMAP.md` phase status vs PHASE-STATE.md

package/skills/vp-brainstorm/SKILL.md

@@ -107,3 +107,24 @@ Key steps:
 - [ ] **FEAT-009**: intake completed, binding already present, **or** waiver with reason before Completed; session records **`## Project meta intake (FEAT-009)`**
 - [ ] Next steps suggested
 </success_criteria>
+
+## Adapter Compatibility
+
+### AskUserQuestion Tool (ENH-048)
+This skill uses adapter-aware interactive prompts. Behavior depends on your adapter:
+
+| Adapter | Interactive Prompts | Notes |
+|---------|---------------------|-------|
+| Claude Code (terminal) | ✅ `AskUserQuestion` tool | Click-to-select UI, multi-select, preview panels |
+| Claude Code (VS Code ext) | ⚠️ Partial | Terminal yes; VS Code UI pending [anthropics/claude-code#12609](https://github.com/anthropics/claude-code/issues/12609) |
+| Cursor (Plan Mode) | ⚠️ Partial | `AskQuestion` in Plan Mode only — not in Agent/Skills Mode |
+| Cursor (Agent/Skills) | ❌ Text fallback | AskQuestion not available in Agent Mode |
+| Codex CLI | ❌ Text fallback | Native tool N/A; community MCP available |
+| Antigravity (native agent) | ❌ Text fallback | Artifact model, no raw tool calls |
+
+When `AskUserQuestion` is not available, the skill automatically falls back to
+plain-text numbered list prompts — no configuration required.
+
+**Prompts using AskUserQuestion in this skill:**
+- Session intent (continue / review / new — Step 2)
+- Landing page layout selection (Step 4 — Layout A/B/C/D)

package/skills/vp-crystallize/SKILL.md

@@ -77,6 +77,46 @@ Convert brainstorm sessions into structured artifacts for autonomous AI executio
 - `DOCUMENT_LANG` controls content language for all generated files (ROADMAP, TRACKER, ARCHITECTURE, etc.).
 - `COMMUNICATION_LANG` controls prompt/confirmation language for this session.
 - Configure via: `vp-tools config set language.document vi`
+
+**Brownfield Mode (`--brownfield`) — FEAT-018:**
+
+Use when adopting ViePilot on an **existing project** (no brainstorm session required).
+
+Flags:
+- `--brownfield` : Explicit brownfield mode
+- *(auto-detected)* : Triggers when `docs/brainstorm/` is absent/empty AND `.viepilot/` does not exist
+
+Scanner runs 12 signal categories across the existing codebase:
+1. **Build manifests** — `package.json`, `pom.xml`, `pyproject.toml`, `Cargo.toml`, `go.mod`, etc. (11 platforms) → infers project_name, version, language, deps
+2. **Framework detection** — 40+ dependency patterns → backend/frontend/ORM/auth/broker/test frameworks
+3. **Architecture layers** — 18 directory patterns → controller/service/repository/frontend/infra/etc.
+4. **Database schema signals** — Flyway/Liquibase/Prisma/Rails migrations + docker-compose services
+5. **API contracts** — OpenAPI, gRPC `.proto`, GraphQL schemas
+6. **Infrastructure** — Dockerfile, docker-compose, k8s, Terraform, Vercel, Fly.io, etc. (16 patterns)
+7. **Environment config** — `.env.example` key names (never reads `.env`)
+8. **Test coverage** — Jest/pytest/JUnit/Cypress config + coverage report dirs
+9. **Code quality tools** — ESLint/Prettier/SonarQube/pre-commit/golangci-lint/etc. (14 patterns)
+10. **Documentation** — README, CHANGELOG, ADRs, docs/ (priority-ordered)
+11. **Git history** — commit convention, version pattern, contributors, repo URL
+12. **Language survey** — file extension glob → language distribution
+
+**Multi-repo / monorepo support (ENH-047):**
+
+- **Git submodule detection** — reads `.gitmodules`; scans each initialized submodule path (Signal Cat 1+2+4); records uninitialized paths as `primary_language: MISSING`. Never runs `git submodule update` — read-only.
+- **Polyrepo hints** — detects docker-compose `../` build contexts, `file:../` deps, CI cross-repo clones, README external links, Makefile `cd ../` targets; outputs `polyrepo_hints[]`; prompts user to supply `related_repos[]` (optional).
+- **Per-module gap detection** — every `modules[]` entry carries `gap_tier` (DETECTED/ASSUMED/MISSING), `must_detect_status{}` (evidence per field: value + source + tier), and `open_questions[]`. A module with `gap_tier: MISSING` blocks artifact generation with a targeted per-field prompt.
+
+**Scan Report contains:**
+- Root `gap_tier` (= worst tier across all modules: MISSING > ASSUMED > DETECTED)
+- `modules[]` — one entry per workspace/submodule/root with `gap_tier`, `must_detect_status{}`, `open_questions[]`
+- `polyrepo_hints[]` — polyrepo signals (omitted when empty, no empty arrays)
+- `related_repos[]` — user-supplied sibling repos (omitted when empty)
+- Root `open_questions[]` — includes rollup from all modules
+
+Produces **Scan Report** (YAML) with DETECTED / ASSUMED / MISSING classification.
+MUST-DETECT gaps (root: project_name, primary_language, ≥1 framework, current_version; per-module: primary_language, framework, module_purpose, entry_point) block artifact generation until user fills interactively.
+Generates `docs/brainstorm/session-brownfield-import.md` stub for `vp-audit` compatibility.
+Safety: never reads `.env`; skips `node_modules/`, `.git/`, `target/`, `build/`, `dist/`.
 </objective>
 
 <execution_context>
@@ -223,3 +263,27 @@ Ask user for (confirm proposals from profile if present):
 - [ ] **ENH-022:** Every generated Mermaid diagram has a `.viepilot/architecture/<canonical-name>.mermaid` file in sync with `ARCHITECTURE.md` (no extra files created for N/A)
 - [ ] **FEAT-009:** When profile is bound — ARCHITECTURE + PROJECT-CONTEXT record the profile source; if not — state none / not configured explicitly
 </success_criteria>
+
+## Adapter Compatibility
+
+### AskUserQuestion Tool (ENH-048)
+This skill uses adapter-aware interactive prompts. Behavior depends on your adapter:
+
+| Adapter | Interactive Prompts | Notes |
+|---------|---------------------|-------|
+| Claude Code (terminal) | ✅ `AskUserQuestion` tool | Click-to-select UI, multi-select, preview panels |
+| Claude Code (VS Code ext) | ⚠️ Partial | Terminal yes; VS Code UI pending [anthropics/claude-code#12609](https://github.com/anthropics/claude-code/issues/12609) |
+| Cursor (Plan Mode) | ⚠️ Partial | `AskQuestion` in Plan Mode only — not in Agent/Skills Mode |
+| Cursor (Agent/Skills) | ❌ Text fallback | AskQuestion not available in Agent Mode |
+| Codex CLI | ❌ Text fallback | Native tool N/A; community MCP available |
+| Antigravity (native agent) | ❌ Text fallback | Artifact model, no raw tool calls |
+
+When `AskUserQuestion` is not available, the skill automatically falls back to
+plain-text numbered list prompts — no configuration required.
+
+**Prompts using AskUserQuestion in this skill:**
+- License selection (Step 0 metadata)
+- Brownfield overwrite confirmation (Step 0-B)
+- Polyrepo related-repos prompt (Step 0-B)
+- UI direction gate choice (Step 1A)
+- Architect mode suggestion (Step 1D)

package/skills/vp-docs/SKILL.md

@@ -80,19 +80,29 @@ Optional flags:
 
 ### Step 0: Resolve Project Context (ALWAYS first)
 ```bash
-# Read actual GitHub URL — never use hardcoded placeholder
+# Forge-agnostic remote URL parser — supports GitHub, GitLab, Bitbucket, Azure DevOps, Gitea, self-hosted
 REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo "")
-GITHUB_SLUG=$(echo "$REMOTE_URL" | sed 's|.*github\.com[:/]||; s|\.git$||')
-GITHUB_OWNER=$(echo "$GITHUB_SLUG" | cut -d'/' -f1)
-GITHUB_REPO=$(echo "$GITHUB_SLUG" | cut -d'/' -f2)
+if echo "$REMOTE_URL" | grep -q 'dev\.azure\.com'; then
+  GIT_HOST="dev.azure.com"
+  GIT_OWNER=$(echo "$REMOTE_URL" | sed 's|.*dev\.azure\.com/||; s|/.*||')
+  GIT_REPO=$(echo "$REMOTE_URL" | sed 's|.*/_git/||; s|\.git$||; s|/$||')
+elif echo "$REMOTE_URL" | grep -q '^git@'; then
+  GIT_HOST=$(echo "$REMOTE_URL" | sed 's|^git@||; s|:.*||')
+  GIT_OWNER=$(echo "$REMOTE_URL" | sed 's|^git@[^:]*:||; s|/.*||')
+  GIT_REPO=$(echo "$REMOTE_URL" | sed 's|^git@[^:]*:[^/]*/||; s|\.git$||')
+else
+  GIT_HOST=$(echo "$REMOTE_URL" | sed 's|^https\?://||; s|/.*||')
+  GIT_OWNER=$(echo "$REMOTE_URL" | sed 's|^https\?://[^/]*/||; s|/.*||')
+  GIT_REPO=$(echo "$REMOTE_URL" | sed 's|^https\?://[^/]*/[^/]*/||; s|\.git$||; s|/$||')
+fi
 # Fallback: use searchable placeholder, not 'your-org'
-[ -z "$GITHUB_OWNER" ] && GITHUB_OWNER="{GITHUB_OWNER}" && GITHUB_REPO="{GITHUB_REPO}"
+[ -z "$GIT_OWNER" ] && GIT_HOST="{GIT_HOST}" && GIT_OWNER="{GIT_OWNER}" && GIT_REPO="{GIT_REPO}"
 
 ACTUAL_SKILLS=$(ls skills/*/SKILL.md 2>/dev/null | wc -l | tr -d ' ')
 ACTUAL_WORKFLOWS=$(ls workflows/*.md 2>/dev/null | wc -l | tr -d ' ')
 ```
 
-> Use `$GITHUB_OWNER/$GITHUB_REPO` in all generated files.
+> Use `$GIT_HOST`, `$GIT_OWNER`, `$GIT_REPO` in all generated files.
 > Use `$ACTUAL_SKILLS` and `$ACTUAL_WORKFLOWS` for counts.
 > **Never write** `your-org`, `YOUR_USERNAME`, `YOUR_ORG` into generated files.
 

package/skills/vp-proposal/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: vp-proposal
+description: "Generate professional proposal packages (.pptx + .docx + .md) from brainstorm sessions or direct briefs"
+version: 0.1.0
+---
+
+<cursor_skill_adapter>
+## A. Skill Invocation
+- Skill được gọi khi user mention `vp-proposal`, `/vp-proposal`, "proposal", "pitch deck", "presentation", "tài liệu đề xuất"
+- Treat all user text after the skill mention as `{{VP_ARGS}}`
+
+## B. User Prompting
+Prompt user conversationally with numbered list options.
+
+## C. Tool Usage
+Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
+</cursor_skill_adapter>
+<scope_policy>
+## ViePilot Namespace Guard (BUG-004)
+- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+</scope_policy>
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- **`/vp-proposal`** generates **output artifacts** (`docs/proposals/*.pptx`, `*.docx`, `*.md`) — it does **not** implement shipping code for `lib/`, `tests/`, `bin/`, or framework `workflows/`/`skills/`.
+- This skill is the **delivery lane** after `/vp-brainstorm` captures the ideas. Use `/vp-request` → `/vp-evolve` → `/vp-auto` for ViePilot framework feature work.
+- **Exception:** User **explicit** bypass — state clearly in chat.
+</implementation_routing_guard>
+
+<objective>
+Generate a professional proposal package from a brainstorm session or direct brief.
+
+**Output files** (written to `docs/proposals/`):
+- `{slug}-{date}.md` — structured proposal Markdown (source of truth)
+- `{slug}-{date}.pptx` — presentation file (ViePilot branded, dark navy/charcoal)
+- `{slug}-{date}.docx` — detailed project document
+- `{slug}-{date}-slides.txt` — Google Slides URL (only with `--slides` flag)
+
+**Proposal types:**
+| Type | Slides | Use case |
+|------|--------|----------|
+| `project-proposal` | 10 | Scope, timeline, budget for clients |
+| `tech-architecture` | 12 | Technical design for partners |
+| `product-pitch` | 12 | Investor / partner pitch deck |
+| `general` | 8 | Generic, fallback |
+
+**Template resolution (2-tier):**
+1. `.viepilot/proposal-templates/{type}.pptx` — project-level override
+2. `{viepilot-install}/templates/proposal/pptx/{type}.pptx` — ViePilot stock
+
+**Context detection:**
+- Auto-loads latest `docs/brainstorm/session-*.md` when present
+- Standalone mode if no session found (user provides brief)
+- `--from session-YYYY-MM-DD.md` for explicit session selection
+</objective>
+
+<execution_context>
+workflows/proposal.md
+</execution_context>
+
+<context>
+Optional flags:
+- `--type <id>` : Proposal type — `project-proposal` | `tech-architecture` | `product-pitch` | `general`
+                  If omitted: guided selection menu is shown
+- `--from <file>` : Explicit brainstorm session file to use as context
+                    Default: auto-detect latest `docs/brainstorm/session-*.md`
+- `--lang <code>` : Language for generated content — ISO 639-1 (e.g. vi, en, ja, fr, zh).
+                    If omitted: prompted with MRU suggestions from config.
+                    Saved to ~/.viepilot/config.json → proposal.recentLangs after generation.
+- `--lang-content-only` : Translate content (bullets, notes, paragraphs) only.
+                           Keep structural labels / section names in English.
+- `--slides` : After .pptx is generated, upload to Google Slides via service account auth
+               Requires: `@googleapis/slides` installed + `GOOGLE_APPLICATION_CREDENTIALS` env var
+- `--dry-run` : Show slide manifest (JSON) without writing any files
+</context>
+
+<process>
+Execute workflow from `workflows/proposal.md`
+
+### Step 1: Context Detection
+- Scan `docs/brainstorm/` for `session-*.md` → sort descending → load latest
+- If `--from` specified: load that file directly
+- If no session found: prompt user for brief:
+  - Project name
+  - One-line description
+  - Target audience (client / partner / investor)
+  - 3–5 key points to cover
+
+### Step 2: Proposal Type Selection
+- If `--type` provided: validate; show type + slide count to confirm
+- Else: present menu:
+  ```
+  1. Project Proposal     (10 slides) — scope, timeline, budget
+  2. Tech Architecture    (12 slides) — system design for partners
+  3. Product Pitch Deck   (12 slides) — investor / partner pitch
+  4. General Proposal     ( 8 slides) — generic fallback
+  ```
+
+### Step 3: AI Slide Manifest Generation
+- Structure context into JSON manifest:
+  ```json
+  {
+    "title": "...",
+    "subtitle": "...",
+    "slides": [
+      { "index": 1, "layout": "cover", "heading": "...", "body": "...", "speakerNotes": "..." },
+      { "index": 2, "layout": "section", "heading": "...", "bullets": ["..."], "speakerNotes": "..." }
+    ]
+  }
+  ```
+- Slide count MUST match `PROPOSAL_TYPES[typeId].slides`
+- If `--dry-run`: print manifest and stop
+
+### Step 4: Template Resolution
+- Call `resolveTemplate(typeId, 'pptx', projectRoot)` → pptx template path
+- Call `resolveTemplate('project-detail', 'docx', projectRoot)` → docx template path
+- Warn (not error) if stock fallback is used
+
+### Step 5: Generate .pptx
+- Load template via pptxgenjs
+- Apply slide manifest: inject titles, bullets, speaker notes per slide
+- Ensure `docs/proposals/` directory exists
+- Write `{slug}-{date}.pptx`
+
+### Step 6: Generate .docx
+- Build detailed document from same manifest + extended content
+- Sections: Executive Summary, Problem & Solution, Features & Specifications,
+            Technical Architecture (if relevant), Timeline, Team, Appendix
+- Write `{slug}-{date}.docx`
+
+### Step 7: Generate .md summary
+- Write Markdown mirror of the manifest
+- Save `{slug}-{date}.md`
+
+### Step 8: Optional Google Slides upload (`--slides`)
+- Call `lib/google-slides-exporter.cjs` → `uploadToSlides(pptxPath, title)`
+- Write URL to `{slug}-{date}-slides.txt`
+- On failure: surface error but do NOT fail the whole command (files already written)
+
+### Step 9: Confirm output
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► PROPOSAL GENERATED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Type:    {type label}  ({N} slides)
+ Context: {session file or "direct brief"}
+
+ Files:
+   docs/proposals/{slug}-{date}.md
+   docs/proposals/{slug}-{date}.pptx
+   docs/proposals/{slug}-{date}.docx
+   [docs/proposals/{slug}-{date}-slides.txt]  ← if --slides
+
+ Next:
+   Open .pptx in PowerPoint / Keynote / LibreOffice
+   Share .docx as supporting document
+   Run /vp-proposal --slides to upload to Google Slides
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</process>
+
+<success_criteria>
+- [ ] Context detected (brainstorm session or user brief)
+- [ ] Proposal type selected and validated
+- [ ] Slide manifest generated with correct slide count
+- [ ] .pptx written to docs/proposals/
+- [ ] .docx written to docs/proposals/
+- [ ] .md summary written to docs/proposals/
+- [ ] Template resolution: project override takes precedence over stock
+- [ ] --lang: content generated in specified language; MRU saved to config
+- [ ] --lang-content-only: bullets/notes translated; structural labels stay English
+- [ ] --slides: Google Slides URL written to -slides.txt (or clear error shown)
+- [ ] --dry-run: manifest printed, no files written
+</success_criteria>

package/skills/vp-request/SKILL.md

@@ -265,3 +265,25 @@ Update `.viepilot/TRACKER.md`:
 - [ ] TRACKER.md updated
 - [ ] Appropriate routing suggested
 </success_criteria>
+
+## Adapter Compatibility
+
+### AskUserQuestion Tool (ENH-048)
+This skill uses adapter-aware interactive prompts. Behavior depends on your adapter:
+
+| Adapter | Interactive Prompts | Notes |
+|---------|---------------------|-------|
+| Claude Code (terminal) | ✅ `AskUserQuestion` tool | Click-to-select UI, multi-select, preview panels |
+| Claude Code (VS Code ext) | ⚠️ Partial | Terminal yes; VS Code UI pending [anthropics/claude-code#12609](https://github.com/anthropics/claude-code/issues/12609) |
+| Cursor (Plan Mode) | ⚠️ Partial | `AskQuestion` in Plan Mode only — not in Agent/Skills Mode |
+| Cursor (Agent/Skills) | ❌ Text fallback | AskQuestion not available in Agent Mode |
+| Codex CLI | ❌ Text fallback | Native tool N/A; community MCP available |
+| Antigravity (native agent) | ❌ Text fallback | Artifact model, no raw tool calls |
+
+When `AskUserQuestion` is not available, the skill automatically falls back to
+plain-text numbered list prompts — no configuration required.
+
+**Prompts using AskUserQuestion in this skill:**
+- Request type detection (Bug / Feature / Enhancement / Tech Debt — Step 2)
+- Bug severity selection (Critical / High / Medium / Low — Step 4A)
+- Feature priority selection (Must-have / Should-have / Nice-to-have — Step 4B)

package/workflows/brainstorm.md

@@ -3,6 +3,14 @@ Interactive brainstorm session to gather ideas, requirements, and decisions for
 Allows research inline within the same brainstorm session when needed.
 </purpose>
 
+## Adapter Compatibility
+
+| Feature | Claude Code (terminal) | Cursor (Agent/Skills) | Codex CLI | Antigravity (native) |
+|---------|----------------------|-----------------------|-----------|----------------------|
+| Interactive prompts | ✅ `AskUserQuestion` tool | ❌ text fallback | ❌ text fallback | ❌ text fallback |
+
+When `AskUserQuestion` is not available, each prompt block falls back to the plain-text numbered list shown below it — no configuration needed.
+
 ## ViePilot Skill Scope Policy (BUG-004)
 
 - Default behavior: only use and suggest skills under `vp-*`.
@@ -37,6 +45,15 @@ Parse results to get list of existing sessions.
 ## 2. Ask User Intent
 
 **If previous sessions exist:**
+
+> **Adapter-aware prompt:**
+> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+>   - question: "Previous brainstorm sessions found. What would you like to do?"
+>   - header: "Session"
+>   - options: [{ label: "Continue recent session", description: "Resume the most recent session from where it stopped" }, { label: "Review specific session", description: "Choose a particular session to review or continue" }, { label: "New brainstorm session", description: "Start fresh — previous sessions are preserved" }]
+>   - multiSelect: false
+> - **Cursor / Codex / Antigravity / other:** use text menu below
+
 ```
 I found previous brainstorm sessions:
 {list sessions with dates}
@@ -118,6 +135,15 @@ If the user is brainstorming a landing page / homepage / marketing page:
    - Visual tone? (minimal, modern, bold, enterprise, playful)
    - Primary CTA and secondary CTA?
 2. Present a layout menu for the user to choose from:
+
+> **Adapter-aware prompt:**
+> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+>   - question: "Which landing page layout fits your goals and audience?"
+>   - header: "Layout"
+>   - options: [{ label: "Layout A — Hero centric", description: "Hero + trust logos + features + CTA — best for brand awareness and conversions" }, { label: "Layout B — Problem/Solution", description: "Problem/Solution + social proof + pricing + FAQ — best for SaaS sign-ups" }, { label: "Layout C — Product storytelling", description: "Screenshots + testimonials + final CTA — best for product demos" }, { label: "Layout D — SaaS conversion", description: "Integrations + comparison + onboarding steps — best for tool adoption" }]
+>   - multiSelect: false
+> - **Cursor / Codex / Antigravity / other:** use list below
+
    - Layout A: Hero centric + trust logos + features + CTA
    - Layout B: Problem/Solution + social proof + pricing + FAQ
    - Layout C: Product storytelling + screenshots + testimonials + final CTA