viepilot 2.12.0 → 2.15.0

package/CHANGELOG.md

@@ -7,6 +7,85 @@ 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)

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.5.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-17-purple.svg)](#skills-reference)
-[![Workflows](https://img.shields.io/badge/workflows-12-orange.svg)](#workflows)
+[![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,7 +28,7 @@ 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`) |
+| 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) |
@@ -61,11 +61,11 @@ Tổng thể / Overall:  ██████████████████
 | Lĩnh vực / Area | Trạng thái | Chi tiết |
 |-----------------|------------|----------|
 | 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 (12) | ✅ Hoàn thiện | Full step-by-step guides với success criteria |
+| 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 |
@@ -339,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
@@ -357,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
@@ -368,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/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

package/docs/user/features/interactive-prompts.md

@@ -0,0 +1,83 @@
+# Interactive Prompts (AskUserQuestion)
+
+> **ENH-048** — Introduced in v2.15.0
+
+ViePilot skills that ask user questions now use **adapter-aware interactive prompts**.
+In Claude Code (terminal), questions appear as structured click-to-select UI.
+All other adapters fall back to plain-text numbered lists automatically.
+
+---
+
+## How It Works
+
+When a vp-* skill needs input (e.g. "What type of request?"), it checks whether
+the `AskUserQuestion` tool is available in the current adapter:
+
+| Adapter | Experience |
+|---------|------------|
+| **Claude Code (terminal)** | Click-to-select options with descriptions, optional multi-select, preview panels |
+| **Claude Code (VS Code ext)** | Terminal mode — same as above (VS Code interactive UI pending [#12609](https://github.com/anthropics/claude-code/issues/12609)) |
+| **Cursor — Plan Mode** | `AskQuestion` available in Plan Mode only |
+| **Cursor — Agent/Skills** | Text fallback (AskQuestion not in Agent Mode) |
+| **Codex CLI** | Text fallback (native tool N/A) |
+| **Antigravity native** | Text fallback (Artifact model, no raw tool calls) |
+
+No configuration needed. The fallback is automatic.
+
+---
+
+## Affected Skills and Prompts
+
+### /vp-crystallize
+| Prompt | AUQ Options |
+|--------|-------------|
+| License selection | MIT / Apache-2.0 / GPL-3.0 / Proprietary |
+| Brownfield overwrite confirm | Yes, continue / No, abort |
+| Polyrepo related-repos | Yes, I'll list them / Skip for now |
+| UI direction gate | Return to brainstorm / Continue with assumptions |
+| Architect mode suggestion | Yes, architect mode / No, continue now |
+
+### /vp-brainstorm
+| Prompt | AUQ Options |
+|--------|-------------|
+| Session intent | Continue recent / Review specific / New session |
+| Landing page layout | Layout A (Hero) / Layout B (Problem-Solution) / Layout C (Storytelling) / Layout D (SaaS) |
+
+### /vp-request
+| Prompt | AUQ Options |
+|--------|-------------|
+| Request type | Bug / Feature / Enhancement / Tech Debt |
+| Bug severity | Critical / High / Medium / Low |
+| Feature priority | Must-have / Should-have / Nice-to-have |
+
+### /vp-evolve
+| Prompt | AUQ Options |
+|--------|-------------|
+| Evolve intent | Add Feature / New Milestone / Refactor |
+| Complexity | S (Small) / M (Medium) / L (Large) / XL (Extra Large) |
+| Brainstorm routing | Yes, brainstorm first / No, plan directly |
+
+---
+
+## AskUserQuestion Tool Constraints
+
+When using Claude Code, the tool has these constraints:
+- **1–4 questions** per call
+- **2–4 options** per question
+- Optional `multiSelect: true` for non-exclusive choices
+- Optional `preview` field for visual comparisons (code/layout mockups)
+- Automatic "Other" option always appended by the UI
+
+---
+
+## Research Notes (Adapter Support)
+
+Research conducted 2026-04-13 confirmed:
+
+- **Cursor Agent/Skills Mode** does not expose `AskQuestion` — it only works in Plan Mode
+  ([community request](https://forum.cursor.com/t/allow-askquestion-tool-calls-in-agent-mode-or-any-mode/152517))
+- **Codex CLI** `ask_user_question` is a community MCP skill, not a native tool
+  ([openai/codex#9926](https://github.com/openai/codex/issues/9926))
+- **Antigravity** uses an "Artifacts" model for agent output — no raw tool execution for interactive UI
+
+All non-Claude-Code adapters receive identical plain-text prompts as before ENH-048.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viepilot",
-  "version": "2.12.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": {

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

@@ -100,8 +100,21 @@ Scanner runs 12 signal categories across the existing codebase:
 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 (project_name, primary_language, ≥1 framework, current_version) block artifact generation until user fills interactively.
+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>
@@ -250,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-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

package/workflows/crystallize.md

@@ -2,6 +2,14 @@
 Convert brainstorm sessions into structured artifacts for autonomous AI execution.
 </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-*`.
@@ -80,7 +88,7 @@ Ask the user for project information:
 
 9. Lead developer email?
 
-10. GitHub username? (optional)
+10. Git remote host / username? (optional — e.g. github.com/johndoe, gitlab.com/org, bitbucket.org/team)
 ```
 
 ### Repository Info
@@ -92,6 +100,15 @@ Ask the user for project information:
 ```
 
 ### License & Year
+
+> **Adapter-aware prompt (question 13):**
+> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+>   - question: "Which license for this project?"
+>   - header: "License"
+>   - options: [{ label: "MIT", description: "Permissive — most common open-source choice" }, { label: "Apache-2.0", description: "Permissive with patent grant — preferred for enterprise OSS" }, { label: "GPL-3.0", description: "Copyleft — derivative works must stay open-source" }, { label: "Proprietary", description: "All rights reserved — no public redistribution" }]
+>   - multiSelect: false
+> - **Cursor / Codex / Antigravity / other:** use text list below
+
 ```
 13. License?
     Options: MIT, Apache-2.0, GPL-3.0, BSD-3-Clause, Proprietary
@@ -115,7 +132,16 @@ Store all metadata for template generation.
 
 **If brownfield triggered AND `.viepilot/` already exists:**
 - Warn: "`.viepilot/` already exists. Re-running brownfield mode will overwrite artifacts."
-- Ask: "Continue? (y/n)" — abort if n.
+
+> **Adapter-aware prompt:**
+> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+>   - question: "`.viepilot/` already exists. Re-running brownfield mode will overwrite artifacts. Continue?"
+>   - header: "Overwrite?"
+>   - options: [{ label: "Yes, continue", description: "Overwrite existing .viepilot/ artifacts with new scan results" }, { label: "No, abort", description: "Stop here — keep existing artifacts unchanged" }]
+>   - multiSelect: false
+> - **Cursor / Codex / Antigravity / other:** use text prompt below
+>
+> Ask: "Continue? (y/n)" — abort if n.
 
 **When brownfield mode is active:**
 1. Run the full 12-category codebase scanner (Signal Categories 1–12 below).
@@ -165,6 +191,64 @@ Probe the following files in order of priority (first match per language wins):
 
 If monorepo detected → scan each module separately; aggregate into `modules[]` in Scan Report.
 
+**Git Submodule Detection** (run after monorepo check):
+- Check for `.gitmodules` file at repo root
+- If present: parse all `[submodule "name"]` blocks → extract `name`, `path`, `url`
+- For each submodule path:
+  - If path exists on disk (initialized):
+    - Run Signal Cat 1 (manifest scan) on `{path}/`
+    - Run Signal Cat 2 (framework) on `{path}/`
+    - Run Signal Cat 4 (DB signals) on `{path}/`
+    - Record `initialized: true`
+  - If path absent (not initialized):
+    - Record `initialized: false`, `primary_language: MISSING`
+    - Add open question: "Submodule '{name}' not initialized — run `git submodule update --init {path}` to scan it"
+- Add each submodule to `modules[]` with `type: submodule`
+
+> **SAFETY RULE**: Never run `git submodule update`, `git submodule init`, or any git network command during scan. Read the local filesystem only.
+
+**Polyrepo / Multi-Repo Detection** (run after submodule check):
+
+Scan the following signals to determine if this repo is part of a larger multi-repo system:
+
+| Signal Source | Pattern | Interpretation |
+|--------------|---------|----------------|
+| `docker-compose.yml` / `docker-compose*.yml` | `build: ../path` or `context: ../path` (value starts with `../`) | Sibling repo used as build context |
+| `docker-compose.yml` | Multiple services with external `image:` and no local `build:` | External microservices — possible sibling repos |
+| `package.json` | `"dependencies"` or `"devDependencies"` value matching `"file:../..."` | Local `file:` sibling repo dependency |
+| `.github/workflows/*.yml` / `.gitlab-ci.yml` / `ci/*.yml` | `git clone` steps, or `uses: org/other-repo/.github/workflows/` referencing a different repo | CI clones or calls a sibling repo |
+| `README.md` / `CONTRIBUTING.md` | Lines containing a repo URL whose path differs from the current repo's remote | Related repo link in docs |
+| `Makefile` / `justfile` | Targets containing `cd ../` followed by build/test commands | Cross-repo build orchestration |
+
+For each match: record `{ source, hint, inferred_repo }` in `polyrepo_hints[]`.
+Deduplicate by `inferred_repo` name.
+If `polyrepo_hints` is empty → skip this section entirely (no empty array in clean single-repo Scan Reports).
+
+**Interactive prompt** (fire when `polyrepo_hints` non-empty):
+
+> **Adapter-aware prompt:**
+> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+>   - question: "Polyrepo signals detected — this repo may be part of a multi-repo system. Would you like to provide related repo URLs?"
+>   - header: "Polyrepo?"
+>   - options: [{ label: "Yes, I'll list them", description: "Provide sibling repo URLs — improves system-level context accuracy" }, { label: "Skip for now", description: "Continue without related repos — affected fields will be marked ASSUMED" }]
+>   - multiSelect: false
+> - **Cursor / Codex / Antigravity / other:** use text prompt below
+
+```
+⚠️ Polyrepo signals detected:
+  {list polyrepo_hints}
+
+This repo appears to be part of a multi-repo system.
+Would you like to list related repos? (optional — press Enter to skip)
+Format: one URL per line, e.g. https://github.com/org/api-service [backend]
+```
+- User-supplied repos → stored in `related_repos[]` as `{ url, role }`
+- If user skips → `related_repos: []`; system-level context fields set to **ASSUMED** tier
+
+**Gap-fill rule for polyrepo:**
+- `polyrepo_hints` non-empty AND `related_repos` empty → system-level fields (e.g. `deployment_topology`) = ASSUMED (not MISSING; single-repo scan is still valid)
+- `related_repos` populated → system-level fields = DETECTED for user-supplied context
+
 If no manifest found → `primary_language` = MISSING; user must provide.
 
 ---
@@ -487,8 +571,34 @@ frameworks:
 build_tool: string
 package_manager: string
 monorepo: bool
-modules: []                    # if monorepo
+gap_tier: DETECTED | ASSUMED | MISSING   # root rollup = worst tier across all modules
+modules:                       # if monorepo or submodules detected
+  - name: string               # workspace package name or submodule name
+    type: workspace | submodule | root   # workspace = monorepo member; submodule = git submodule
+    path: string               # repo-relative path
+    submodule_url: string | null         # remote URL from .gitmodules (null if not submodule)
+    initialized: bool          # true if path exists on disk (submodules only)
+    primary_language: string
+    framework: string | null
+    module_purpose: string     # inferred from dir name + manifest description
+    entry_point: string | null # main entry file path
+    gap_tier: DETECTED | ASSUMED | MISSING
+    must_detect_status:        # evidence record per MUST-DETECT field
+      primary_language: { value: string, source: string, tier: string }
+      framework:        { value: string, source: string, tier: string }
+      module_purpose:   { value: string, source: string, tier: string }
+      entry_point:      { value: string, source: string, tier: string }
+    open_questions: []         # per-module open questions
+polyrepo_hints:                # present only when polyrepo signals detected
+  - source: string             # e.g. docker-compose.yml
+    hint: string               # raw signal text
+    inferred_repo: string      # guessed sibling repo name
+related_repos:                 # present only when user supplied input after prompt
+  - url: string
+    role: string               # backend | frontend | shared-library | infra | etc.
 architecture_layers: []        # { layer, evidence_path }
+module_dependencies: []        # { from, to, type, evidence_path } — Gap D (Phase 78)
+dependency_cycles: []          # cycle paths detected — Gap D (Phase 78)
 database_signals: []           # { type, evidence_path, migration_tool }
 api_contracts: []              # { style, file_path }
 api_style: string              # REST | GraphQL | gRPC | mixed | unknown
@@ -505,7 +615,7 @@ repo_url: string
 top_contributors: []
 docs_extracted: []             # { file, summary, key_facts[] }
 language_distribution: {}      # { ts: 142, java: 38, ... }
-open_questions: []             # fields not resolved by user input
+open_questions: []             # root-level open questions (includes rollup from modules)
 ```
 
 ---
@@ -540,15 +650,73 @@ Every field in Scan Report is classified as:
 
 ---
 
+### Per-Module Gap Detection
+
+Applies to every entry in `modules[]` (monorepo workspace members, git submodules, and root if single-repo). Each module is assessed independently.
+
+**Per-module MUST-DETECT fields:**
+
+| Field | Source signals | Tier if absent |
+|-------|---------------|----------------|
+| `primary_language` | Manifest extension, file survey (Signal Cat 12), `tsconfig.json`, `pyproject.toml` | MISSING — must ask user |
+| `framework` | Signal Cat 2 dep patterns scanned on module path | ASSUMED if no dep match; MISSING if no manifest found |
+| `module_purpose` | Manifest `description` field, directory name convention, README first line | ASSUMED (infer from dir name); MISSING if none of the above |
+| `entry_point` | `main` in `package.json`; `src/index.*`; `cmd/main.go`; `*Application.java` | ASSUMED if standard path exists; MISSING otherwise |
+
+**Gap tier assignment per module:**
+```
+DETECTED  — all MUST-DETECT fields sourced directly from file evidence (no inference)
+ASSUMED   — ≥1 MUST-DETECT field inferred by convention (no direct file evidence, but plausible)
+MISSING   — ≥1 MUST-DETECT field has no evidence and cannot be inferred
+```
+
+**`must_detect_status` evidence conventions:**
+- `source: "tsconfig.json"` — read from a specific file
+- `source: "inferred"` — derived by directory name / naming convention (tier = ASSUMED)
+- `source: "absent"` — no evidence found (tier = MISSING)
+- `source: "user"` — provided by user during gap-filling (tier = DETECTED)
+
+**Root gap tier rollup:**
+```
+root gap_tier = worst tier across all modules
+Priority order: MISSING > ASSUMED > DETECTED
+```
+If any module is MISSING → root `gap_tier` = MISSING → artifact generation blocked until resolved.
+If all modules are DETECTED or ASSUMED → root `gap_tier` matches the worst module tier.
+
+**Scan summary printout** (show after all modules scanned):
+```
+Module scan summary:
+┌─────────────────┬──────────────────┬────────────┬──────────────┬───────────┐
+│ Module          │ Path             │ Language   │ Framework    │ Gap Tier  │
+├─────────────────┼──────────────────┼────────────┼──────────────┼───────────┤
+│ api-service     │ apps/api         │ TypeScript │ NestJS       │ DETECTED  │
+│ web-client      │ apps/web         │ TypeScript │ React        │ DETECTED  │
+│ shared-lib      │ libs/shared      │ TypeScript │ —            │ ASSUMED   │
+│ legacy-worker   │ services/worker  │ MISSING    │ MISSING      │ MISSING   │
+└─────────────────┴──────────────────┴────────────┴──────────────┴───────────┘
+Root gap tier: MISSING (worst across modules)
+```
+
+---
+
 ### Interactive Gap-Filling (Step 0-B-ii)
 
 After scanner completes:
 
 1. Display Scan Report summary table to user (field | value | status).
-2. For each MUST-DETECT field that is MISSING → **pause and ask user to provide value**. Do not proceed until all MUST-DETECT fields are filled.
-3. Present ASSUMED fields in a confirmation table → user may accept all with "y" or override individually.
-4. Capture all user responses; update Scan Report fields accordingly.
-5. All remaining unresolved items → `open_questions[]`.
+2. **Per-module MISSING fields** — for each module with `gap_tier: MISSING`, pause and ask per field:
+   ```
+   ⛔ Module '{name}' (path: {path}) has MISSING required fields:
+     - {field}: no evidence found
+   Please provide {field}:
+   ```
+   Record answer as `{ value: user_input, source: "user", tier: DETECTED }`.
+   Do NOT proceed to artifact generation until all MISSING module fields are filled.
+3. For each root-level MUST-DETECT field that is MISSING → **pause and ask user to provide value**.
+4. Present ASSUMED fields (root + per-module) in a confirmation table → user may accept all with "y" or override individually.
+5. Capture all user responses; update Scan Report fields accordingly.
+6. All remaining unresolved items → `open_questions[]` (roll up per-module `open_questions[]` into root).
 
 ---
 
@@ -673,6 +841,14 @@ Check if `.viepilot/ui-direction/` exists and contains any session artifacts.
 
 If `ui_scope_detected = true` **AND** artifacts are missing → **STOP** and present:
 
+> **Adapter-aware prompt:**
+> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+>   - question: "UI Direction artifacts missing. The brainstorm indicates UI scope but `.viepilot/ui-direction/` has no artifacts. How to proceed?"
+>   - header: "UI Direction"
+>   - options: [{ label: "Return to /vp-brainstorm --ui (Recommended)", description: "Create UI direction artifacts first for best results" }, { label: "Continue with assumptions", description: "Record assumptions in ARCHITECTURE.md and proceed without visual direction" }]
+>   - multiSelect: false
+> - **Cursor / Codex / Antigravity / other:** use text menu below
+
 ```
 ⚠️ UI Direction artifacts missing
 
@@ -838,6 +1014,15 @@ If `.viepilot/architect/` exists with at least one session directory:
 
 If `.viepilot/architect/` does **not** exist but brainstorm shows complex architecture (≥5 services/components detected):
 - Suggest (soft prompt — not a hard block):
+
+> **Adapter-aware prompt:**
+> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+>   - question: "Complex architecture detected (≥5 services/components). Would you like to create architecture visualizations first with /vp-brainstorm --architect?"
+>   - header: "Architect?"
+>   - options: [{ label: "Yes, go to architect mode", description: "Create visual architecture diagrams before crystallizing (recommended for complex systems)" }, { label: "No, continue now", description: "Continue crystallize with text-only brainstorm — no visual diagrams" }]
+>   - multiSelect: false
+> - **Cursor / Codex / Antigravity / other:** use text menu below
+
   ```
   💡 Would you like to return to /vp-brainstorm --architect to create visualizations first?
   1. Yes — return to architect mode

package/workflows/documentation.md

@@ -17,20 +17,35 @@ Generate comprehensive documentation from code and artifacts.
 Before generating any file, collect actual project context from the environment:
 
 ```bash
-# Get GitHub remote URL (supports both HTTPS and SSH formats)
+# Get Git remote URL (supports any forge: GitHub, GitLab, Bitbucket, Azure DevOps, Gitea, self-hosted)
 REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo "")
 
-# Extract owner/repo slug
-# https://github.com/0-CODE/viepilot.git → 0-CODE/viepilot
-# git@github.com:0-CODE/viepilot.git → 0-CODE/viepilot
-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)
+# Forge-agnostic remote URL parser
+# Handles SSH  : git@<host>:owner/repo.git
+# Handles HTTPS: https://<host>/owner/repo.git
+# Handles Azure DevOps: https://dev.azure.com/org/project/_git/repo
+if echo "$REMOTE_URL" | grep -q 'dev\.azure\.com'; then
+  # Azure DevOps: https://dev.azure.com/ORG/PROJECT/_git/REPO
+  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
+  # SSH format: git@host:owner/repo.git
+  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
+  # HTTPS format: https://host/owner/repo.git
+  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 if no remote
-if [ -z "$GITHUB_OWNER" ]; then
-  GITHUB_OWNER="{GITHUB_OWNER}"
-  GITHUB_REPO="{GITHUB_REPO}"
+if [ -z "$GIT_OWNER" ]; then
+  GIT_HOST="{GIT_HOST}"
+  GIT_OWNER="{GIT_OWNER}"
+  GIT_REPO="{GIT_REPO}"
 fi
 
 # Get project name from package.json or directory name
@@ -54,7 +69,7 @@ if [ -d "skills" ] && ls skills/vp-*/SKILL.md 2>/dev/null | head -1 > /dev/null;
 fi
 ```
 
-Use `$GITHUB_OWNER`, `$GITHUB_REPO` throughout all generated files.
+Use `$GIT_HOST`, `$GIT_OWNER`, `$GIT_REPO` throughout all generated files.
 For viepilot framework repos, also use `$ACTUAL_SKILLS`, `$ACTUAL_WORKFLOWS`.
 **Never hardcode** `your-org`, `YOUR_USERNAME`, `YOUR_ORG`, or static skill/workflow counts.
 

package/workflows/evolve.md

@@ -2,6 +2,14 @@
 Upgrade or expand the project: add features, start a new milestone, or refactor.
 </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-*`.
@@ -44,7 +52,17 @@ Determine:
  Version: {version}
 
 How would you like to evolve the project?
+```
+
+> **Adapter-aware prompt:**
+> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+>   - question: "How would you like to evolve the project?"
+>   - header: "Evolve mode"
+>   - options: [{ label: "Add Feature", description: "Add a new capability to the current milestone" }, { label: "New Milestone", description: "Archive current milestone and start a new scope" }, { label: "Refactor", description: "Improve existing code without adding new features" }]
+>   - multiSelect: false
+> - **Cursor / Codex / Antigravity / other:** use text menu below
 
+```
 1. Add Feature - Add new feature to current milestone
 2. New Milestone - Start a new milestone (archive current)
 3. Refactor - Improve existing code without new features
@@ -62,7 +80,25 @@ Describe the new feature:
 2. What does it do? (1-2 sentences)
 3. Which services/modules affected?
 4. Dependencies on existing code?
+
+> **Adapter-aware prompt (question 5 — complexity):**
+> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+>   - question: "Estimated implementation complexity?"
+>   - header: "Complexity"
+>   - options: [{ label: "S — Small", description: "Few hours — isolated change, 1 file" }, { label: "M — Medium", description: "1–2 days — 1–2 files, some integration" }, { label: "L — Large", description: "3–5 days — multiple modules affected" }, { label: "XL — Extra Large", description: "1+ week — architectural change or major feature" }]
+>   - multiSelect: false
+> - **Cursor / Codex / Antigravity / other:** use text below
+
 5. Estimated complexity? (S/M/L/XL)
+
+> **Adapter-aware prompt (question 6 — brainstorm routing):**
+> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+>   - question: "Does this feature need a brainstorm session first?"
+>   - header: "Brainstorm?"
+>   - options: [{ label: "Yes — go to /vp-brainstorm", description: "Research-heavy, UX-driven, or landing page feature — brainstorm first" }, { label: "No — plan directly", description: "Scope is clear — proceed to phase/task planning now" }]
+>   - multiSelect: false
+> - **Cursor / Codex / Antigravity / other:** use text below
+
 6. Need deep brainstorm? (landing page / UX / growth ideas / research-heavy)
 ```
 

package/workflows/request.md

@@ -2,6 +2,14 @@
 Create and manage project requests: bugs, features, enhancements, tech debt, and brainstorm continuation.
 </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-*`.
@@ -53,6 +61,15 @@ Parse `{{VP_ARGS}}` for type flag:
 - `--list` → List Requests
 
 If no flag, ask user:
+
+> **Adapter-aware prompt:**
+> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+>   - question: "What type of request would you like to create?"
+>   - header: "Request type"
+>   - options: [{ label: "🐛 Bug Report", description: "Something is broken — file a defect report" }, { label: "✨ Feature Request", description: "New functionality — add a capability that doesn't exist yet" }, { label: "🔧 Enhancement", description: "Improve existing feature — make something better" }, { label: "🧹 Technical Debt", description: "Code cleanup / refactor — no new behavior" }]
+>   - multiSelect: false
+> - **Cursor / Codex / Antigravity / other:** use text menu below (Brainstorm and List options remain text-only)
+
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  VIEPILOT ► REQUEST
@@ -117,6 +134,15 @@ Options:
    > 
 
 6. Severity?
+
+> **Adapter-aware prompt:**
+> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+>   - question: "What is the bug severity?"
+>   - header: "Severity"
+>   - options: [{ label: "Critical", description: "System down, data loss — needs immediate attention" }, { label: "High", description: "Major feature broken — significantly impacts users" }, { label: "Medium", description: "Feature impaired — workaround exists" }, { label: "Low", description: "Minor / cosmetic issue — no functional impact" }]
+>   - multiSelect: false
+> - **Cursor / Codex / Antigravity / other:** use text list below
+
    1. Critical - System down, data loss
    2. High - Major feature broken
    3. Medium - Feature impaired
@@ -191,6 +217,15 @@ Create `BUG-{N}.md`:
    > 
 
 5. Priority?
+
+> **Adapter-aware prompt:**
+> - **Claude Code (terminal):** use `AskUserQuestion` tool — spec:
+>   - question: "What is the feature priority?"
+>   - header: "Priority"
+>   - options: [{ label: "Must-have", description: "Critical for release — cannot ship without it" }, { label: "Should-have", description: "Important but not blocking — include if capacity allows" }, { label: "Nice-to-have", description: "Quality-of-life improvement — can defer to next milestone" }]
+>   - multiSelect: false
+> - **Cursor / Codex / Antigravity / other:** use text list below
+
    1. Must-have - Critical for release
    2. Should-have - Important but not blocking
    3. Nice-to-have - Can defer