viepilot 2.12.0 → 2.22.0

package/workflows/crystallize.md

@@ -2,6 +2,15 @@
 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 — **REQUIRED** | ❌ text fallback | ❌ text fallback | ❌ text fallback |
+
+**Claude Code (terminal):** Always call `AskUserQuestion` first. Only fall back to the plain-text menu below if the tool returns an error or is unavailable.
+**Cursor / Codex CLI / Antigravity / other adapters:** `AskUserQuestion` not available — use text menus below.
+
 ## ViePilot Skill Scope Policy (BUG-004)
 
 - Default behavior: only use and suggest skills under `vp-*`.
@@ -80,7 +89,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 +101,15 @@ Ask the user for project information:
 ```
 
 ### License & Year
+
+> **Adapter-aware prompt (question 13):**
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable. AUQ 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 +133,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) — REQUIRED:** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable. AUQ 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 +192,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) — REQUIRED:** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable. AUQ 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 +572,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 +616,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 +651,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).
 
 ---
 
@@ -618,6 +787,31 @@ When generating TRACKER.md in Step 9 (brownfield mode only), append:
 
 </step>
 
+<step name="brownfield_execution_path">
+## Brownfield Execution Path
+
+When `IS_BROWNFIELD=true`, the following table governs which steps execute:
+
+| Step | Name | Brownfield behavior | Rationale |
+|------|------|---------------------|-----------|
+| 0 | Collect metadata | **RUN** | Always needed |
+| 0-B | Brownfield scanner | **RUN** | Core brownfield step |
+| 0-C | Generate brainstorm stub | **RUN** | Creates `session-brownfield-import.md` |
+| 1 | Analyze brainstorm | **RUN (stub only)** | Reads brownfield stub; skips greenfield-only checks |
+| 1A | UI direction gate | **CONDITIONAL** — run if `.viepilot/ui-direction/` already exists in the project |
+| 1B | Stack research cache | **CONDITIONAL** — skip if brownfield scanner already populated stack cache |
+| 1C | Architect artifact consumption | **SKIP** — no architect HTML workspace in a brownfield import |
+| 1D | Architect auto-activate suggestion | **SKIP** — no scope brainstorm; architect mode not applicable |
+| 2+ | All subsequent steps | **RUN** — same as greenfield from Step 2 onward |
+
+> **Implementation note for AI agents:** When `IS_BROWNFIELD=true`, check each CONDITIONAL
+> step against the stated condition before executing. Do **not** skip Step 1 entirely —
+> read the brownfield stub to extract stack + gap data for Step 2 (AI-GUIDE.md generation).
+> For Step 1B: check `~/.viepilot/stacks/` for entries created during the Step 0-B scan;
+> if present and non-empty, skip the full research pass in 1B.
+
+</step>
+
 <step name="analyze_brainstorm">
 ## Step 1: Analyze Brainstorm
 
@@ -673,6 +867,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) — REQUIRED:** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable. AUQ 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 +1040,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) — REQUIRED:** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable. AUQ 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,15 @@
 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 — **REQUIRED** | ❌ text fallback | ❌ text fallback | ❌ text fallback |
+
+**Claude Code (terminal):** Always call `AskUserQuestion` first. Only fall back to the plain-text menu below if the tool returns an error or is unavailable.
+**Cursor / Codex CLI / Antigravity / other adapters:** `AskUserQuestion` not available — use text menus below.
+
 ## ViePilot Skill Scope Policy (BUG-004)
 
 - Default behavior: only use and suggest skills under `vp-*`.
@@ -44,7 +53,18 @@ Determine:
  Version: {version}
 
 How would you like to evolve the project?
+```
+
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable.
+> **Cursor / Codex / Antigravity:** use text menu below.
+> AUQ 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 +82,27 @@ Describe the new feature:
 2. What does it do? (1-2 sentences)
 3. Which services/modules affected?
 4. Dependencies on existing code?
+
+> **Claude Code (terminal) — REQUIRED (question 5 — complexity):** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable.
+> **Cursor / Codex / Antigravity:** use text menu below.
+> AUQ 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)
+
+> **Claude Code (terminal) — REQUIRED (question 6 — brainstorm routing):** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable.
+> **Cursor / Codex / Antigravity:** use text menu below.
+> AUQ 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)
 ```
 
@@ -252,13 +292,15 @@ Add to ROADMAP.md as phase {N+0.5} or insert between phases.
 <step name="update_version">
 ## 4. Update Version
 
-Based on changes:
+Apply the canonical bump rules from `.viepilot/SYSTEM-RULES.md → Version Bump Rules`.
+Precedence: MAJOR > MINOR > PATCH. Mixed phase → highest applicable bump wins.
 
-| Mode | Version Bump |
-|------|--------------|
-| Add Feature | MINOR (x.Y.z) |
-| New Milestone | MAJOR or MINOR |
-| Refactor | PATCH (x.y.Z) |
+Quick reference:
+- Add Feature → **MINOR**
+- Bug fix only → **PATCH**
+- Refactor (no behavior change) → **PATCH**
+- Mixed feature + fix → **MINOR**
+- Breaking change → **MAJOR**
 
 Update in:
 - TRACKER.md
@@ -269,6 +311,8 @@ Update in:
 <step name="confirm">
 ## 5. Confirm & Suggest Next
 
+Output the evolution summary banner:
+
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  VIEPILOT ► EVOLVE COMPLETE ✓
@@ -286,7 +330,32 @@ Update in:
  - Phase {N}: {name}
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Next: /vp-auto --from {new_phase}
+```
+
+Then — **Claude Code adapter (terminal): use AskUserQuestion**:
+
+```
+question: "Phase {N} planned. What would you like to do next?"
+options:
+  - label: "Execute now → /vp-auto"
+    description: "Start implementing Phase {N} immediately (Recommended)"
+  - label: "Create another request → /vp-request"
+    description: "Log more requests before implementing"
+  - label: "Done for now"
+    description: "Exit — run /vp-auto later to start implementation"
+```
+
+**On selection:**
+- "Execute now → /vp-auto": invoke `/vp-auto --from {new_phase}` skill
+- "Create another request → /vp-request": invoke `/vp-request` skill
+- "Done for now": print brief confirmation and exit
+
+**Text fallback (Cursor, Codex, Copilot, Antigravity — AUQ not available):**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Next:
+ - /vp-auto --from {new_phase}    Execute Phase {N}
+ - /vp-request                    Create another request
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 </step>

package/workflows/request.md

@@ -2,6 +2,15 @@
 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 — **REQUIRED** | ❌ text fallback | ❌ text fallback | ❌ text fallback |
+
+**Claude Code (terminal):** Always call `AskUserQuestion` first. Only fall back to the plain-text menu below if the tool returns an error or is unavailable.
+**Cursor / Codex CLI / Antigravity / other adapters:** `AskUserQuestion` not available — use text menus below.
+
 ## ViePilot Skill Scope Policy (BUG-004)
 
 - Default behavior: only use and suggest skills under `vp-*`.
@@ -53,6 +62,15 @@ Parse `{{VP_ARGS}}` for type flag:
 - `--list` → List Requests
 
 If no flag, ask user:
+
+> **Adapter-aware prompt:**
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable. AUQ 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
@@ -69,6 +87,39 @@ What type of request?
 ```
 </step>
 
+<step name="feasibility_gate">
+## 2B. Feasibility Gate — research-agent (ENH-057)
+
+**Trigger**: auto-activate for **Feature** and **Enhancement** requests when any of:
+- User description mentions a new platform, IDE, API, protocol, or SDK
+- User asks "is this possible?", "how does X work?", "feasibility of X"
+- Request type = Feature AND subject is an external integration
+
+**Skip for**: Bug reports, internal refactors, Enhancement requests on known code.
+
+If triggered:
+
+**Claude Code (terminal) — invoke research-agent:**
+```
+Agent({
+  subagent_type: "general-purpose",
+  description: "research-agent: feasibility study for {topic}",
+  prompt: `
+    Load agents/research-agent.md for full spec.
+    Topic: {extracted from user description}
+    Questions: ["What SDK/API exists?", "What are integration points?", "What config dir/convention?", "Feasibility rating?"]
+    Return a ## Research Findings section + ## Sources.
+  `
+})
+```
+
+**Non-Claude Code**: if web search available, perform inline research. Otherwise note "manual research needed" and continue gathering details.
+
+**Output**: embed research-agent findings in the `## Research Findings` section of the request file.
+
+> This gate made FEAT-019 (Copilot adapter) research systematic — apply it to all future platform/API feature requests.
+</step>
+
 <step name="list_requests">
 ## 3. List Requests (if --list)
 
@@ -117,6 +168,15 @@ Options:
    > 
 
 6. Severity?
+
+> **Adapter-aware prompt:**
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable. AUQ 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 +251,15 @@ Create `BUG-{N}.md`:
    > 
 
 5. Priority?
+
+> **Adapter-aware prompt:**
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion` tool. Only fall back to text menu if the tool errors or is unavailable. AUQ 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
@@ -221,6 +290,9 @@ Create `FEAT-{N}.md`:
 ## Summary
 {TITLE}
 
+## Research Findings
+{Populated by research-agent if feasibility gate triggered (Step 2B); omit section if not applicable}
+
 ## Problem Statement
 {PROBLEM}
 
@@ -509,6 +581,8 @@ git push
 <step name="confirm">
 ## 7. Confirm
 
+Output the request summary banner:
+
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  VIEPILOT ► REQUEST CREATED ✓
@@ -523,15 +597,33 @@ git push
  File: .viepilot/requests/{TYPE}-{N}.md
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Next Steps
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Then — **Claude Code adapter (terminal): use AskUserQuestion**:
 
- /vp-request --list    View all requests
- /vp-evolve            ROADMAP + phase/tasks (before code)
- /vp-auto              Implement theo task plan (sau evolve)
- /vp-request           Create another request
- /vp-status            See overall progress
+```
+question: "Request {TYPE}-{N} logged. What would you like to do next?"
+options:
+  - label: "Plan phase + tasks → /vp-evolve"
+    description: "Create ROADMAP entry, phase dir, and task files now (Recommended)"
+  - label: "Create another request → /vp-request"
+    description: "Log more requests before planning"
+  - label: "Done for now"
+    description: "Exit — request is saved in backlog"
+```
 
+**On selection:**
+- "Plan phase + tasks → /vp-evolve": invoke `/vp-evolve` skill
+- "Create another request → /vp-request": invoke `/vp-request` skill
+- "Done for now": print brief confirmation and exit
+
+**Text fallback (Cursor, Codex, Copilot, Antigravity — AUQ not available):**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ Next:
+ - /vp-evolve            Plan phase/tasks + ROADMAP
+ - /vp-request           Create another request
+ - /vp-request --list    View all requests
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 </step>