viepilot 2.4.0 → 2.15.0

package/CHANGELOG.md

@@ -7,6 +7,212 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.15.0] - 2026-04-13
+
+### Changed (ENH-048 — Phase 78: AskUserQuestion Adapter-Aware Integration)
+
+All `vp-*` workflows that ask users questions now include adapter-aware interactive prompts.
+Claude Code (terminal) receives a structured click-to-select UI via `AskUserQuestion` tool.
+All other adapters (Cursor Agent/Skills, Codex CLI, Antigravity native) automatically fall back
+to the existing plain-text numbered lists — no configuration required.
+
+**Research findings (adapter compatibility):**
+- Claude Code terminal: ✅ `AskUserQuestion` fully supported (native tool)
+- Cursor Agent/Skills Mode: ❌ `AskQuestion` only available in Plan Mode (community feature request)
+- Codex CLI: ❌ not native (community MCP `ask-user-questions-mcp` exists separately)
+- Antigravity native agent: ❌ uses Artifact model, no raw tool calls
+
+**`workflows/crystallize.md`:**
+- Added `Adapter Compatibility` table near top
+- License selection (Step 0): AUQ spec with MIT/Apache-2.0/GPL-3.0/Proprietary options
+- Brownfield overwrite confirmation (Step 0-B): AUQ Yes/No prompt
+- Polyrepo related-repos prompt (Step 0-B): AUQ Yes supply/Skip options
+- UI direction gate (Step 1A): AUQ Return-to-brainstorm / Continue-with-assumptions options
+- Architect mode suggestion (Step 1D): AUQ Yes/No architect mode routing
+
+**`workflows/brainstorm.md`:**
+- Added `Adapter Compatibility` table near top
+- Session intent (Step 2): AUQ Continue-recent / Review-specific / New-session options
+- Landing page layout (Step 4): AUQ Layout A/B/C/D with descriptions (4-option fit)
+
+**`workflows/request.md`:**
+- Added `Adapter Compatibility` table near top
+- Request type detection (Step 2): AUQ Bug/Feature/Enhancement/Tech-Debt (Brainstorm+List remain text)
+- Bug severity (Step 4A): AUQ Critical/High/Medium/Low options
+- Feature priority (Step 4B): AUQ Must-have/Should-have/Nice-to-have options
+
+**`workflows/evolve.md`:**
+- Added `Adapter Compatibility` table near top
+- Intent detection (Step 2): AUQ Add-Feature/New-Milestone/Refactor options
+- Complexity question (Step 3A): AUQ S/M/L/XL options
+- Brainstorm routing (Step 3A): AUQ Yes-brainstorm/No-plan-directly options
+
+**`skills/vp-crystallize/SKILL.md`, `skills/vp-brainstorm/SKILL.md`, `skills/vp-request/SKILL.md`:**
+- Added `## Adapter Compatibility` section with 6-row adapter support table
+- Listed prompts using AskUserQuestion per skill
+
+### Added
+- `tests/unit/vp-enh048-askuserquestion.test.js` — 33 contract tests verifying AUQ specs + text fallback preservation across all affected files
+
+## [2.14.0] - 2026-04-13
+
+### Added (ENH-047 — Phase 77: Brownfield Multi-Repo, Submodules & Per-Module Gap Detection)
+
+**Gap A — Git Submodule Detection:**
+- `workflows/crystallize.md`: Signal Category 1 now reads `.gitmodules` → parses all `[submodule]` blocks (name, path, url); runs Signal Cat 1+2+4 on each initialized submodule path; records uninitialized paths with `initialized: false` + `primary_language: MISSING`
+- Scan Report `modules[]`: new fields `type` (submodule/workspace/root), `submodule_url`, `initialized`
+- Safety rule: scanner never runs `git submodule update` — local filesystem read-only
+
+**Gap B — Polyrepo / Multi-Repo Detection:**
+- `workflows/crystallize.md`: new Polyrepo Detection subsection in Signal Category 1 with 6 signal sources (docker-compose `../` build contexts, `file:../` package.json deps, CI cross-repo clones, README external repo links, Makefile `cd ../` targets)
+- Scan Report: `polyrepo_hints[]` + `related_repos[]` fields (omitted entirely when empty — no empty arrays in clean single-repo reports)
+- Interactive prompt fires when polyrepo signals detected; user can supply related repo URLs with optional role label
+- Gap-fill rule: polyrepo hints without `related_repos` → system-level context fields = ASSUMED tier
+
+**Gap C — Per-Module Gap Detection:**
+- `workflows/crystallize.md`: new Per-Module Gap Detection section with MUST-DETECT table (primary_language, framework, module_purpose, entry_point) including source signals and tier-if-absent rules
+- `must_detect_status{}` per module: records `{ value, source, tier }` per MUST-DETECT field; source conventions: `"tsconfig.json"` (file), `"inferred"` (ASSUMED), `"absent"` (MISSING), `"user"` (gap-filled)
+- Root gap tier rollup: worst tier across all modules (MISSING > ASSUMED > DETECTED)
+- Module with `gap_tier: MISSING` blocks artifact generation with targeted per-field user prompt
+- Per-module `open_questions[]` rolled up into root `open_questions[]`
+- Scan summary printout table (module | path | language | framework | gap tier)
+- `skills/vp-crystallize/SKILL.md`: Brownfield Mode section updated with Gaps A+B+C, Scan Report contents list, per-module MUST-DETECT fields
+
+## [2.13.0] - 2026-04-13
+
+### Changed (ENH-046 — Phase 76)
+- **`workflows/documentation.md`**: replaced GitHub-only URL parser with a forge-agnostic extractor supporting GitHub (SSH/HTTPS), GitLab (SSH/HTTPS), Bitbucket, Azure DevOps (`dev.azure.com`), Gitea, and any self-hosted remote
+  - Variables renamed: `GITHUB_OWNER`/`GITHUB_REPO` → `GIT_OWNER`/`GIT_REPO`; added `GIT_HOST`
+- **`skills/vp-docs/SKILL.md`**: Step 0 shell block updated to match — same forge-agnostic parser, same variable names
+- **`workflows/crystallize.md`**: Step 0 prompt label generalized from "GitHub username? (optional)" → "Git remote host / username? (optional — e.g. github.com/johndoe, gitlab.com/org)"
+
+## [2.12.0] - 2026-04-13
+
+### Added (FEAT-018 — Phase 75)
+- **`vp-crystallize --brownfield`**: Brownfield Mode — bootstrap `.viepilot/` project context from an existing codebase without a brainstorm session
+  - 12-category codebase scanner: build manifests (11 platforms), framework detection (40+ dep patterns), architecture layer inference (18 directory patterns), database schema signals, API contract detection, infrastructure config, environment config shape, test coverage, code quality tools, documentation files, git history, file extension survey
+  - Structured Scan Report (YAML) with DETECTED / ASSUMED / MISSING gap classification
+  - MUST-DETECT gap tier: blocks artifact generation until user fills interactively
+  - Synthetic brainstorm stub (`docs/brainstorm/session-brownfield-import.md`) for `vp-audit` compatibility
+  - Safety rules: never reads `.env`; skips `node_modules/`, `.git/`, `target/`, `build/`, `dist/`, `__pycache__/`, `.venv/`, `vendor/`
+  - `vp-audit` updated to accept brownfield stub as valid brainstorm source (no false-positive errors)
+  - `TRACKER.md` annotated with `## Brownfield Import` block on first-time bootstrap
+
+## [2.11.0] - 2026-04-13
+
+### Added (ENH-045 — Phase 74)
+- **`lib/proposal-generator.cjs`**: `getDesignConfig(projectContext)` helper + `DESIGN_CONFIGS` map (3 styles: modern-tech, enterprise, creative) — auto-selects palette from sector/audience/tone context
+- **`scripts/gen-proposal-pptx.cjs`**: `PALETTES` map with 3 colour schemes + 3 rich slide layouts (timeline-gantt, team-card, investment-visual) + generates `project-proposal-{modern-tech,enterprise,creative}.pptx` variants
+- **`workflows/proposal.md`**: dynamic slide count (no hard cap) + `designConfig` field in manifest + content-aware split rules (technicalNarrative > 4 → 2 slides; team > 4 → 2 slides; phases > 4 → 2 timeline slides) + DESIGN SELECTION AI prompt block
+- 31 contract tests in `vp-enh045-dynamic-slides.test.js`
+
+## [2.10.1] - 2026-04-11
+
+### Changed (ENH-044 — Phase 73)
+- **`lib/screenshot-artifact.cjs`**: `warnMissingTool(tool, installCmd)` — standardized stderr `⚠` warning when visual tool absent but artifacts exist; exports alongside existing helpers
+- **`workflows/proposal.md` Step 4c**: mandatory enforcement — `visualSlides[]` MUST be non-empty when artifacts exist; puppeteer absent → `warnMissingTool('puppeteer', ...)` + `addPlaceholderVisual()` (no more silent skip)
+- **`workflows/proposal.md` Step 7**: mandatory enforcement — Mermaid + ui/arch sections MUST be added when diagrams/artifacts exist; mmdc absent → text fallback + `warnMissingTool('mmdc', ...)`; puppeteer absent → placeholder paragraph + `warnMissingTool('puppeteer', ...)`
+- `warnMissingTool()` called once per missing tool per generation run (not per-diagram)
+- 16 tests in `vp-enh044-visual-enforce.test.js`
+
+## [2.10.0] - 2026-04-11
+
+### Added (ENH-043 — Phase 72)
+- **`lib/screenshot-artifact.cjs`**: `isMmdcAvailable()` — boolean guard for `mmdc` CLI on PATH; `renderMermaidToPng(source, outPath)` — renders Mermaid source string → PNG via `mmdc` CLI; returns null when mmdc absent (no crash)
+- **`scripts/gen-proposal-docx.cjs`**: `imageRunFromPng(pngPath, widthEmu, heightEmu)` → `ImageRun` (docx package) for embedding PNG as inline image; requires `screenshot-artifact.cjs` + `proposal-generator.cjs`; runtime visual embedding comment block documenting three injection points: Mermaid diagrams (renderMermaidToPng → ImageRun), UI prototype screenshot (before Executive Summary), architecture screenshot (after Technical Approach)
+- **`workflows/proposal.md` Step 7**: Diagram Reference updated to render `mermaidSource` → PNG via `renderMermaidToPng()`; documents `screenshotArtifact` for ui-direction + architect injection; all paths use `cleanupScreenshot()`; graceful fallback when mmdc/puppeteer absent
+- 19 tests in `vp-enh043-docx-visuals.test.js`; contracts +2 (769/769 total)
+
+## [2.9.0] - 2026-04-11
+
+### Added (ENH-042 — Phase 71)
+- **`lib/proposal-generator.cjs`**: `detectVisualArtifacts(sessionDir)` — auto-scans `.viepilot/ui-direction/{latest-session}/` for ui-direction pages (`index.html`, `pages/*.html`) and 10 architect workspace page types (`architecture.html`, `erd.html`, `sequence-diagram.html`, etc.)
+- **`lib/screenshot-artifact.cjs`** (new): `screenshotArtifact(htmlPath)` via optional puppeteer (headless Chrome) — returns `null` gracefully when puppeteer not installed; `isPuppeteerAvailable()` boolean guard; `cleanupScreenshot()` temp-file cleanup
+- **`workflows/proposal.md` Step 4c `detect_visual_artifacts`**: AI maps slide topics to HTML artifact files, produces `visualSlides[]` array with `slideIndex`, `artifactType`, `htmlPath`, `label` fields
+- **`scripts/gen-proposal-pptx.cjs`**: `addPlaceholderVisual(slide, label)` — styled navy+accent placeholder shape for when screenshots are unavailable; runtime integration comment block documenting the `screenshotArtifact` → `addImage` → `cleanupScreenshot` pattern
+- Zero breaking change: all proposal generation works without puppeteer; visuals are additive
+
+## [2.8.0] - 2026-04-11
+
+### Added (ENH-041 — Phase 70)
+- **`workflows/proposal.md` Step 4b `generate_docx_content`**: dedicated AI pass for deep `.docx` content, independent of the slide manifest — richer prose, risk analysis, diagrams
+- **`docxContent` JSON schema**: `executiveSummary[]`, `problemStatement[]`, `solutionNarrative[]`, `technicalNarrative[]`, `riskRegister[]`, `glossary[]`, `diagrams[]` (with `mermaidSource`)
+- **Step 7 updated**: `.docx` generator consumes `docxContent` for narrative paragraphs; new Risk Register and Glossary sections fed from `docxContent`
+- **Step 8 updated**: `.md` companion embeds Mermaid fenced code blocks (` ```flowchart `, ` ```sequenceDiagram `, etc.) for each diagram in `docxContent.diagrams[]`
+- **`getDiagramTypes(typeId)` helper** in `lib/proposal-generator.cjs`: maps proposal type to diagram array (`project-proposal` → `[flowchart, gantt]`, `tech-architecture` → `[flowchart, sequenceDiagram, classDiagram]`, etc.)
+- **`.docx` Risk Register table**: Risk | Probability | Impact | Mitigation (5 placeholder rows)
+- **`.docx` Glossary table**: Term | Definition (4 placeholder rows)
+- `project-detail.docx` regenerated — 12 sections (added §8 Risk Register, §11 Glossary; previous §8–10 renumbered §9–12)
+- 17 new tests in `tests/unit/vp-enh041-proposal-docx-ai.test.js`; `vp-proposal-contracts.test.js` updated (+5 ENH-041 assertions)
+
+## [2.7.0] - 2026-04-10
+
+### Added (ENH-040 — Phase 69)
+- **`workflows/proposal.md` Step 2C Quality Brief**: 4 focused questions before AI generation — CTA, budget range, timeline constraint, decision-maker — stored in manifest `meta` field
+- **Manifest `meta` schema**: `cta`, `budget`, `timeline`, `decisionMaker` fields drive tone and content specificity
+- **AI Prompt Contract** in manifest_generation step: 8–15 word outcome-oriented bullets, 3–5 sentence speaker notes, concrete CTA on closing slide, avoids filler phrases
+- **`.pptx` templates: 5 distinct layouts** (ENH-040 Layer 1):
+  - `cover` — split panel (left charcoal + ViePilot mark, right title/subtitle/meta)
+  - `section` — left accent sidebar + heading bar + bullets
+  - `two-column` — heading + dual column content (comparisons, scope, competitive)
+  - `data` — heading + up to 3 metric callout boxes (large value + label + note)
+  - `closing` — full charcoal, prominent CTA text, accent bars top/bottom
+- **`.docx` template: structured tables + narrative** (ENH-040 Layer 3):
+  - **Timeline table**: Phase | Milestone/Deliverable | Duration | Dependencies (6 rows)
+  - **Budget/Investment table**: Line Item | Estimate | Notes (with TOTAL row)
+  - **Team table**: Role | Name/Background | Responsibility
+  - Narrative paragraphs for Executive Summary, Problem & Opportunity, Why Choose Us
+  - 10 sections + explicit `{{placeholder}}` instructions for AI to fill
+- All 4 `.pptx` stock templates regenerated (137–151 KB; prev 97–126 KB)
+- `project-detail.docx` regenerated (12 KB; prev 10 KB)
+
+### Tests
+- Added `tests/unit/vp-enh040-proposal-quality.test.js` (27 tests — workflow contracts, pptx layout coverage, docx structure)
+- Updated `tests/unit/vp-proposal-contracts.test.js` (+2 tests — quality brief + outcome-oriented rules)
+- Total: **660 → 689 tests**
+
+## [2.6.0] - 2026-04-10
+
+### Added (ENH-039 — Phase 68)
+- **`/vp-proposal --lang <code>`**: language selection for AI-generated content (ISO 639-1; e.g. `vi`, `en`, `ja`, `fr`, `zh`)
+  - If omitted: prompted with MRU suggestions from `~/.viepilot/config.json → proposal.recentLangs`
+  - Language is saved to MRU after each successful generation
+- **`/vp-proposal --lang-content-only`**: translate bullets, notes, and paragraphs; keep structural labels / section names in English
+- **MRU language history**: `~/.viepilot/config.json → proposal.recentLangs` (max 5, most recent first, deduped)
+- **`lib/viepilot-config.cjs`**: `getProposalLang()` + `recordProposalLang()` helpers; `DEFAULTS` extended with `proposal.recentLangs` + `proposal.defaultLang`
+- **`lib/proposal-generator.cjs`**: `buildLangInstruction(lang, contentOnly)` — builds AI prompt language instruction; no-op for English
+- **`workflows/proposal.md`**: Step 3b Language Selection (MRU prompt); `langInstruction` injection in manifest generation; `recordProposalLang` after confirm output
+- **`skills/vp-proposal/SKILL.md`**: `--lang` + `--lang-content-only` flags documented
+
+### Tests
+- Added `tests/unit/vp-enh039-proposal-lang.test.js` (13 tests — config helpers, buildLangInstruction, SKILL.md/workflow contracts)
+- Updated `tests/unit/vp-proposal-contracts.test.js` (+2 tests — --lang and --lang-content-only flag documentation)
+- Total: **645 → 660 tests**
+
+## [2.5.0] - 2026-04-11
+
+### Added (FEAT-016 — Phases 63–67)
+- **`/vp-proposal` skill**: convert brainstorm session (or direct brief) → professional proposal package
+  - `.pptx` presentation (ViePilot branded, dark navy/charcoal)
+  - `.docx` detailed document (10 sections: executive summary → appendix)
+  - `.md` Markdown source of truth
+  - Optional `.txt` Google Slides URL (`--slides` flag)
+- **4 proposal types**: `project-proposal` (10 slides), `tech-architecture` (12), `product-pitch` (12), `general` (8)
+- **`lib/proposal-generator.cjs`**: 2-tier template resolution (project `.viepilot/proposal-templates/` override → ViePilot stock fallback), context detection, type validation, output path builder
+- **`lib/google-slides-exporter.cjs`**: service account auth; lazy-loads `@googleapis/slides`; graceful error when package or credentials absent
+- **Stock templates**: `templates/proposal/pptx/` (4 files, dark navy `#1a1f36`/charcoal `#2d3142`, ViePilot branded) + `templates/proposal/docx/project-detail.docx`
+- **`scripts/gen-proposal-pptx.cjs`** + **`scripts/gen-proposal-docx.cjs`**: template generation scripts
+- **`skills/vp-proposal/SKILL.md`**: full skill definition; `--type`, `--from`, `--slides`, `--dry-run` flags
+- **`workflows/proposal.md`**: 10-step workflow; slide manifest schema; 4 proposal type structures; error handling
+- **`docs/user/features/proposal.md`**: full user guide with Google Slides 5-step setup guide
+- **`@googleapis/slides`** added as `optionalDependencies` (install not required unless using `--slides`)
+- **`pptxgenjs` + `docx`** added as runtime `dependencies`
+
+### Tests
+- Added `tests/unit/vp-proposal-contracts.test.js` (25 tests — skill/workflow files, generator exports, stock templates, graceful degradation)
+- Added `tests/unit/vp-proposal-core.test.js` (15 tests — resolveTemplate, validateType, detectBrainstormSession)
+- Total: 607 → **647 tests**
+
 ## [2.4.0] - 2026-04-10
 
 ### Added (FEAT-015 — Phase 62)

package/README.md

@@ -2,15 +2,15 @@
 
 **Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**
 
-[![Version](https://img.shields.io/badge/version-2.4.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-2.15.0-blue.svg)](CHANGELOG.md)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-[![Skills](https://img.shields.io/badge/skills-16-purple.svg)](#skills-reference)
-[![Workflows](https://img.shields.io/badge/workflows-12-orange.svg)](#workflows)
+[![Skills](https://img.shields.io/badge/skills-17-purple.svg)](#skills-reference)
+[![Workflows](https://img.shields.io/badge/workflows-13-orange.svg)](#workflows)
 [![Templates](https://img.shields.io/badge/templates-17-cyan.svg)](#templates)
-[![Tests](https://img.shields.io/badge/tests-607%20passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-957%20passing-brightgreen.svg)](tests/)
 [![GitHub](https://img.shields.io/github/stars/0-CODE/viepilot?style=social)](https://github.com/0-CODE/viepilot)
 
-**Versioning:** Shield **2.4.0** is the **ViePilot framework SemVer** tracked in `.viepilot/TRACKER.md` and `CHANGELOG.md`. The npm `package.json` field `version` (**2.4.0**) is the Node package identifier for this repo; use the framework version for milestone releases and docs.
+**Versioning:** Shield **2.15.0** is the **ViePilot framework SemVer** tracked in `.viepilot/TRACKER.md` and `CHANGELOG.md`. The npm `package.json` field `version` (**2.15.0**) is the Node package identifier for this repo; use the framework version for milestone releases and docs.
 
 ViePilot là bộ skill framework cho phép AI assistant (Claude, GPT, etc.) phát triển dự án một cách **tự động**, **có kiểm soát**, và **có thể khôi phục**. Thiết kế theo các tiêu chuẩn chuyên nghiệp: Semantic Versioning, Conventional Commits, Keep a Changelog.
 
@@ -28,8 +28,8 @@ Nếu ViePilot giúp ích cho bạn, bạn có thể ủng hộ một ly cafe:
 
 | Chỉ số / Metric | Giá trị / Value |
 |-----------------|-----------------|
-| Total LOC | **~39,668+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
-| Skills | **16** |
+| Total LOC | **~51,713+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
+| Skills | **17** |
 | Workflows | **12** |
 | Templates | **17** (Project: 12, Phase: 5) |
 | CLI Commands | **18** (`vp-tools` 17 subcommands + `viepilot` installer) |
@@ -43,7 +43,7 @@ Nếu ViePilot giúp ích cho bạn, bạn có thể ủng hộ một ly cafe:
 
 | Thành phần / Component | Số lượng / Count | Mô tả / Description |
 |------------------------|------------------|---------------------|
-| Skill Definitions | **16** | SKILL.md files với trigger, process, success criteria |
+| Skill Definitions | **17** | SKILL.md files với trigger, process, success criteria |
 | Workflow Files | **12** | Step-by-step execution guides |
 | Project Templates | 12 | AI-GUIDE, ARCHITECTURE, VIEPILOT-META, README, SYSTEM-RULES, etc. |
 | Phase Templates | 5 | SPEC, PHASE-STATE, TASK, VERIFICATION, SUMMARY |
@@ -60,12 +60,12 @@ Tổng thể / Overall:  ██████████████████
 
 | Lĩnh vực / Area | Trạng thái | Chi tiết |
 |-----------------|------------|----------|
-| Core Skills (16) | ✅ Hoàn thiện | brainstorm, crystallize, auto, pause, resume, status, info, request, evolve, docs, update, task, debug, rollback, audit, ui-components |
-| Workflows (12) | ✅ Hoàn thiện | Full step-by-step guides với success criteria |
+| Core Skills (17) | ✅ Hoàn thiện | brainstorm, crystallize, auto, pause, resume, status, info, request, evolve, docs, update, task, debug, rollback, audit, ui-components, **proposal** |
+| Workflows (13) | ✅ Hoàn thiện | Full step-by-step guides với success criteria |
 | Project Templates (12) | ✅ Hoàn thiện | Placeholders cho customization (+ `VIEPILOT-META` FEAT-009) |
 | Phase Templates (5) | ✅ Hoàn thiện | Task tracking, verification, summary |
 | CLI Tools (18) | ✅ Hoàn thiện | vp-tools 17 subcommands + viepilot installer; bundle `info` / `update` |
-| Tests (607) | ✅ Hoàn thiện | Unit, integration, AI compat, workflow contracts, installer, scope policy, FEAT-009~015, ENH-021~037, BUG-009~013, adapter tests, info/update |
+| Tests (957) | ✅ Hoàn thiện | Unit, integration, AI compat, workflow contracts, installer, scope policy, FEAT-009~015, ENH-021~048, BUG-009~013, adapter tests, AskUserQuestion adapter-aware prompts |
 | CI/CD | ✅ Hoàn thiện | GitHub Actions, Node 18/20/22 matrix, coverage >80% |
 | Documentation | ✅ Hoàn thiện | dev/, user/, api/, videos/, examples/, troubleshooting |
 | Standards | ✅ Hoàn thiện | SemVer, Conventional Commits, Keep a Changelog |
@@ -126,6 +126,7 @@ Tổng thể / Overall:  ██████████████████
 | `/vp-debug` | Debug có hệ thống với state tracking / Systematic debugging | "debug", "gỡ lỗi" | Debug |
 | `/vp-rollback` | Khôi phục về checkpoint / Rollback to checkpoint | "rollback", "revert" | Recovery |
 | `/vp-audit` | Kiểm tra sync docs vs implementation | "audit", "kiểm tra" | Quality |
+| `/vp-proposal` | Generate .pptx + .docx proposal package từ brainstorm | "proposal", "pitch", "presentation" | Deliver |
 
 ---
 
@@ -338,7 +339,7 @@ Full guide: `docs/dev/deployment.md`.
 
 ```
 viepilot/
-├── skills/                        # 16 Skill definitions
+├── skills/                        # 17 Skill definitions
 │   ├── vp-brainstorm/             # Thu thập ý tưởng
 │   │   └── SKILL.md
 │   ├── vp-crystallize/            # Tạo artifacts
@@ -356,7 +357,7 @@ viepilot/
 │   ├── vp-rollback/               # Checkpoint recovery
 │   └── vp-audit/                  # Documentation sync
 │
-├── workflows/                     # 12 Workflow definitions
+├── workflows/                     # 13 Workflow definitions
 │   ├── brainstorm.md              # Brainstorm session flow
 │   ├── crystallize.md             # Artifact generation flow
 │   ├── autonomous.md              # Execution loop
@@ -367,6 +368,8 @@ viepilot/
 │   ├── documentation.md           # Docs generation
 │   ├── debug.md                   # Debug session workflow
 │   ├── rollback.md                # Rollback workflow
+│   ├── ui-components.md           # UI component workflow
+│   ├── proposal.md                # Proposal generation
 │   └── audit.md                   # Audit workflow
 │
 ├── templates/                     # 17 Templates

package/docs/brainstorm/session-2026-04-11.md

@@ -0,0 +1,194 @@
+# Brainstorm Session — 2026-04-11
+
+## Topic
+**vp-proposal** — Skill mới: Idea → Proposal Documents + Presentation files (.pptx, .docx)
+
+## Status
+Completed — Ready for `/vp-crystallize` / `/vp-request` → `/vp-evolve` → `/vp-auto`
+
+---
+
+## Problem Statement
+ViePilot hiện có thể đưa ý tưởng thành code nhưng chưa có cầu nối sang **tài liệu bán hàng / thuyết phục**. Developer cần trình bày dự án cho khách hàng, đối tác, nhà đầu tư — hiện phải tự làm thủ công PowerPoint/Word tốn nhiều thời gian.
+
+---
+
+## Solution: `/vp-proposal`
+
+Skill chuyển đổi ideas/brainstorm session → professional proposal package:
+- **Presentation** (`.pptx`) — thuyết trình trực tiếp
+- **Detail document** (`.docx`) — tài liệu chi tiết kèm theo
+- **Markdown summary** (`.md`) — source of truth, version-controlled
+- **Google Slides link** (optional `--slides`) — cloud sharing
+
+---
+
+## Decisions
+
+### D1: AI content generation
+Auto-generate từ brainstorm session notes (context-aware).
+- Nếu có `docs/brainstorm/session-*.md` → load latest session tự động làm input
+- Standalone mode: user cung cấp brief trực tiếp trong chat
+- Không cần user điền outline thủ công — AI extract + structure
+
+### D2: Template system (2-tier resolution)
+```
+Tier 1 (project override):  .viepilot/proposal-templates/{type}.pptx|docx
+Tier 2 (stock fallback):    {viepilot-install}/templates/proposal/pptx/{type}.pptx
+                             {viepilot-install}/templates/proposal/docx/{type}.docx
+```
+- Override chỉ ảnh hưởng project hiện tại
+- Stock templates ship theo npm package
+
+### D3: Proposal types (4 + 1 docx)
+| Type ID | Tên | Use case |
+|---------|-----|----------|
+| `project-proposal` | Project Proposal | Scope, timeline, budget cho khách hàng |
+| `tech-architecture` | Technical Architecture | Thiết kế hệ thống cho technical partner |
+| `product-pitch` | Product Pitch Deck | Investor / partner pitch |
+| `general` | General Proposal | Tổng quát, fallback |
+| `project-detail` (docx) | Project Detail Doc | Tài liệu chi tiết bổ sung cho tất cả loại trên |
+
+### D4: Output location
+```
+docs/proposals/
+├── {slug}-{date}.md          # Markdown source
+├── {slug}-{date}.pptx        # Presentation
+├── {slug}-{date}.docx        # Detail document
+└── {slug}-{date}-slides.txt  # Google Slides URL (nếu --slides)
+```
+
+### D5: Tech stack
+| Output | Package | Version | Downloads/wk |
+|--------|---------|---------|-------------|
+| `.pptx` | `pptxgenjs` | ^3.x | 1.8M |
+| `.docx` | `docx` | ^9.x | 3.5M |
+| Google Slides | `@googleapis/slides` | official | optional dep |
+
+### D6: Workflow integration
+- `c` — Context-aware: detect brainstorm session tự động OR standalone brief
+- Auto-detect: check `docs/brainstorm/session-*.md` → sort by date → load latest
+- User có thể override: `/vp-proposal --from session-2026-04-11.md`
+
+---
+
+## Architecture
+
+### New files
+```
+skills/vp-proposal/
+└── SKILL.md                          # Skill definition
+
+workflows/
+└── proposal.md                       # Step-by-step workflow
+
+lib/
+└── proposal-generator.cjs            # Core: template resolution + pptxgenjs + docx
+
+templates/proposal/
+├── pptx/
+│   ├── project-proposal.pptx         # ViePilot stock template
+│   ├── tech-architecture.pptx
+│   ├── product-pitch.pptx
+│   └── general.pptx
+└── docx/
+    └── project-detail.docx           # ViePilot stock .docx template
+```
+
+### Template resolution logic (lib/proposal-generator.cjs)
+```js
+function resolveTemplate(type, ext, projectRoot) {
+  const projectOverride = path.join(projectRoot, '.viepilot/proposal-templates', `${type}.${ext}`);
+  if (fs.existsSync(projectOverride)) return projectOverride;
+  return path.join(__dirname, '../templates/proposal', ext, `${type}.${ext}`);
+}
+```
+
+### Slide generation flow
+```
+/vp-proposal [--type project-proposal] [--slides]
+      │
+      ├─ 1. Load context (brainstorm session or user brief)
+      ├─ 2. AI structures content → JSON slide manifest
+      ├─ 3. resolveTemplate() → pick .pptx/.docx template
+      ├─ 4. pptxgenjs → write .pptx
+      ├─ 5. docx → write .docx
+      ├─ 6. Write .md summary
+      └─ 7. (--slides) Google Slides API upload → write URL
+```
+
+---
+
+## Open Questions
+
+- ~~OQ1~~: **Resolved** — Dark theme: navy/charcoal. Professional, tech feel.
+- ~~OQ2~~: **Resolved** — Flexible per type: project-proposal 10, tech-architecture 12, product-pitch 12, general 8.
+- ~~OQ3~~: **Resolved** — `optionalDependencies` — load on demand khi `--slides` flag, npm install không fail nếu thiếu.
+- ~~OQ4~~: **Resolved** — Skill-only `/vp-proposal`, nhất quán với các skill khác.
+
+---
+
+## Phases
+
+### Phase 1 — Core infrastructure
+- Add `pptxgenjs` + `docx` to `package.json` dependencies
+- `lib/proposal-generator.cjs`: template resolution + base pptx/docx writer
+- Unit tests: template resolution logic
+
+### Phase 2 — Skill + Workflow
+- `skills/vp-proposal/SKILL.md`
+- `workflows/proposal.md` — full step-by-step
+- Context detection: brainstorm session auto-load
+- 4 proposal types wired up
+
+### Phase 3 — Stock templates
+- Design + generate 4 stock `.pptx` templates (ViePilot branded)
+- 1 stock `.docx` template
+- Store in `templates/proposal/`
+
+### Phase 4 — Google Slides export (optional)
+- `--slides` flag
+- `@googleapis/slides` optional dependency
+- Service account auth guide in docs
+
+### Phase 5 — Tests + Docs
+- Jest contracts for proposal-generator
+- `docs/user/features/proposal.md`
+- Update `docs/skills-reference.md` + `README.md`
+
+---
+
+## Research Notes
+
+### pptxgenjs
+- MIT, zero runtime dependencies
+- Supports Slide Masters for branded templates
+- HTML-to-PPTX in 1 line
+- Template injection: load existing .pptx → inject content
+
+### docx (by Dolan Miu)
+- MIT, 3.5M downloads/week
+- Declarative API: `new Document({ sections: [...] })`
+- Supports tables, images, headings, lists
+- Version 9.6.1, actively maintained
+
+### Google Slides API
+- Official `@googleapis/slides` Node.js client
+- Service account = no browser auth for CLI
+- Template-based: create in Slides → replace placeholders via API
+- Optional: only needed for `--slides` flag
+
+---
+
+## Project meta intake (FEAT-009)
+Waiver — this is the ViePilot framework repo itself; profile binding already exists.
+
+---
+
+## Session Summary
+- **Feasibility**: HIGH ✅
+- **Dependencies**: 2 well-maintained npm packages (pptxgenjs + docx), both MIT
+- **Complexity**: Medium — template system + AI content structuring + 2 file formats
+- **Estimated phases**: 5
+- **Suggested ID**: FEAT-016
+- **Target version**: 2.5.0

package/docs/skills-reference.md

@@ -45,6 +45,10 @@ Complete reference for all ViePilot skills.
 - **Product horizon:** session file giữ **`## Product horizon`** (MVP / Post-MVP / Future tags, deferred capabilities, hoặc single-release statement) để `/vp-crystallize` không bỏ sót post-MVP — xem `workflows/brainstorm.md`.
 - UI Direction (optional): `.viepilot/ui-direction/{session-id}/` — legacy (`index.html`) hoặc multi-page (`pages/*.html` + hub + `## Pages inventory` trong `notes.md`). Chi tiết: [UI Direction](user/features/ui-direction.md).
 
+### Adapter-Aware Interactive Prompts (ENH-048)
+- **Claude Code (terminal)**: dùng `AskUserQuestion` tool — click-to-select UI cho session intent + landing page layout
+- **Cursor / Codex / Antigravity / other**: tự động fallback về text list — không cần cấu hình
+
 ---
 
 ## /vp-crystallize
@@ -101,6 +105,10 @@ LICENSE
 README.md
 ```
 
+### Adapter-Aware Interactive Prompts (ENH-048)
+- **Claude Code (terminal)**: dùng `AskUserQuestion` tool cho license selection, brownfield overwrite confirm, polyrepo prompt, UI direction gate, architect suggestion
+- **Cursor / Codex / Antigravity / other**: tự động fallback về text list — không cần cấu hình
+
 ---
 
 ## /vp-auto
@@ -313,6 +321,10 @@ CHANGELOG.md (updated)
 4. Add to backlog
 5. Offer routing options (fix now, add to phase, etc.)
 
+### Adapter-Aware Interactive Prompts (ENH-048)
+- **Claude Code (terminal)**: dùng `AskUserQuestion` tool cho request type detection, bug severity, feature priority
+- **Cursor / Codex / Antigravity / other**: tự động fallback về text list — không cần cấu hình
+
 ---
 
 ## /vp-debug
@@ -467,3 +479,49 @@ CHANGELOG.md (updated)
 ### Lưu ý
 - Trong repo **application** có `node_modules/viepilot`, update mặc định có thể target **local** — dùng **`--global`** nếu chỉ muốn global.
 - Luồng an toàn: `vp-tools update --dry-run` → sau đó `vp-tools update --yes` (hoặc `--global --yes`).
+
+---
+
+## /vp-proposal
+
+**Purpose**: Generate professional proposal packages (.pptx + .docx + .md) from brainstorm sessions or direct briefs.
+
+**Triggers**: "proposal", "pitch deck", "presentation", "tài liệu đề xuất"
+
+### Proposal Types
+| Type | Slides | Use case |
+|------|--------|----------|
+| `project-proposal` | 10 | Client delivery — scope, timeline, budget |
+| `tech-architecture` | 12 | Technical partners — system design |
+| `product-pitch` | 12 | Investors / partners — pitch |
+| `general` | 8 | Any audience — flexible |
+
+### Flags
+| Flag | Description |
+|------|-------------|
+| `--type <id>` | Proposal type ID. If omitted: guided menu. |
+| `--from <file>` | Explicit brainstorm session file to use |
+| `--slides` | Upload to Google Slides after generation (requires service account) |
+| `--dry-run` | Print slide manifest; no files written |
+
+### Output
+```
+docs/proposals/
+├── {slug}-{date}.md      Markdown source
+├── {slug}-{date}.pptx    Presentation
+├── {slug}-{date}.docx    Detailed document
+└── {slug}-{date}-slides.txt  Google Slides URL (--slides only)
+```
+
+### Template Override
+Place custom `.pptx`/`.docx` files in `.viepilot/proposal-templates/` to override stock ViePilot templates for a specific project.
+
+### Examples
+```
+/vp-proposal                              Auto-detect session + guided type selection
+/vp-proposal --type product-pitch         12-slide investor pitch
+/vp-proposal --type project-proposal --slides  + upload to Google Slides
+/vp-proposal --dry-run                    Preview manifest only
+```
+
+Full guide: `docs/user/features/proposal.md`