viepilot 2.12.0 → 2.22.0

package/CHANGELOG.md

@@ -7,6 +7,209 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.22.0] - 2026-04-18
+
+### Added
+- **ENH-058**: Workflow continuation prompt — AskUserQuestion at vp-evolve and vp-request completion
+  - `workflows/evolve.md` Step 5: AUQ asks "Execute now / Create request / Done" — selecting Execute invokes `/vp-auto` immediately
+  - `workflows/request.md` Step 7: AUQ asks "Plan phase / Create another / Done" — selecting Plan invokes `/vp-evolve` immediately
+  - Text fallback for Cursor / Codex / Copilot / Antigravity adapters (static list preserved)
+  - `skills/vp-evolve/SKILL.md` + `skills/vp-request/SKILL.md` AUQ prompt tables updated
+
+## [2.21.0] - 2026-04-18
+
+### Added
+- **FEAT-019: GitHub Copilot Adapter** — install and run vp-* skills inside VS Code Copilot Chat and GitHub Copilot CLI
+  - `lib/adapters/copilot.cjs` — adapter definition with `~/.config/gh-copilot/` config home
+  - Auto-detect via `~/.config/gh-copilot/` directory or `gh` CLI binary presence
+  - Skill invocation: `/vp-status`, `/vp-auto`, etc. (same slash syntax as Claude Code / Cursor)
+  - Install command: `viepilot install --target copilot`
+  - 4 adapter-table SKILL.md files updated with GitHub Copilot row
+  - `docs/user/features/adapters.md` — Copilot section with surface matrix, prerequisites, limitations
+
+## [2.20.0] - 2026-04-18
+
+### Added
+- **ENH-057: ViePilot Agents System** — 6 dedicated sub-agents for repetitive/parallelizable skill tasks:
+  - `tracker-agent`: TRACKER.md read/write delegation (phase status, task status, decision log)
+  - `research-agent`: WebSearch + WebFetch feasibility studies (auto-triggered in request.md Step 2B)
+  - `file-scanner-agent`: Glob + Grep repo-wide scanning (Explore subagent on Claude Code)
+  - `changelog-agent`: atomic CHANGELOG + version bump — single authority (resolves ENH-053)
+  - `test-generator-agent`: contract test scaffolding + run from acceptance criteria
+  - `doc-sync-agent`: bulk multi-file `.md` updates (≥5 files → 1 agent call)
+- `agents/` directory with 6 agent definition files (`agents/*-agent.md`)
+- Research-agent feasibility gate in `workflows/request.md` Step 2B — auto-triggered for Feature/platform requests
+- Bulk-edit task detection in `workflows/autonomous.md` — doc-sync-agent invoked when ≥5 identical file types in task Paths
+- Agent delegation table + invoke-agent patterns in `workflows/autonomous.md`
+- `docs/dev/agents.md` — developer reference for agents layer architecture and invocation
+
+### Fixed
+- **ENH-053**: Version bump authority unified in `changelog-agent` — `autonomous.md` and `evolve.md` both invoke it; no more inline duplication
+
+## [2.19.0] - 2026-04-18
+
+### Added
+- **ENH-056: Skill invocation greeting banner** — all 17 `vp-*` skills now output
+  a version banner as the very first output on invocation:
+  ```
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   VIEPILOT ► VP-AUTO  v0.2.2 (fw 2.19.0)
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ```
+  Addresses Claude Code UI change where skill-load indicators are no longer shown;
+  users can now confirm which skill version is running. 119 contract tests added.
+
+## [2.18.0] - 2026-04-18
+
+### Fixed
+- **vp-rollback** (BUG-014): `rollback.md` Step 7 now parses enriched tag format
+  `{project}-{branch}-{version}-vp-p{N}-t{M}` introduced by ENH-050. Rollback to
+  any Phase 57+ checkpoint correctly restores HANDOFF.json phase/task state.
+  All 3 formats (legacy, project-scoped, enriched) handled via `grep -oE vp-p[0-9]+`.
+
+### Changed
+- **vp-crystallize** (ENH-051): Added "Brownfield Execution Path" table clarifying
+  which sub-steps (1A–1D) run, skip, or are conditional in brownfield mode.
+  Steps 1A/1B CONDITIONAL; Steps 1C/1D SKIP with rationale.
+- **vp-brainstorm** (ENH-052): Step 6 now validates phase assignment before saving.
+  Scope-locked sessions with features but no phase assignments are blocked with
+  actionable message. Exploratory sessions and brownfield stubs bypass the gate.
+- **Version bump rules** (ENH-053): Consolidated into `.viepilot/SYSTEM-RULES.md`
+  as single canonical table with precedence rule (MAJOR > MINOR > PATCH) and
+  mixed-phase handling. `evolve.md` and `autonomous.md` reference this table
+  instead of defining rules inline.
+- **vp-audit post-phase hook** (ENH-054): Auto-hook integration upgraded from
+  conceptual note to concrete `<step name="post_phase_audit">` block in
+  `autonomous.md`. Runs 3 fast Tier 1+2 checks after every phase-complete event;
+  completely silent when no issues found; y/n prompt when issues detected.
+- **AskUserQuestion enforcement** (ENH-055): All 13 AUQ prompt blocks across 4
+  workflows (evolve, request, brainstorm, crystallize) now explicitly mark Claude
+  Code adapter as REQUIRED. Plain-text menus remain as fallback for non-Claude-Code
+  adapters only. `vp-evolve/SKILL.md` gains new Adapter Compatibility section.
+
+### Files
+- `workflows/rollback.md` — Step 7: 3-format tag parse with `grep -oE`
+- `workflows/crystallize.md` — Brownfield Execution Path table (Step 0-C → Step 1)
+- `workflows/brainstorm.md` — Pre-save phase validation gate in Step 6
+- `.viepilot/SYSTEM-RULES.md` — Canonical Version Bump Rules table
+- `workflows/evolve.md` — Version bump ref → SYSTEM-RULES.md; AUQ REQUIRED
+- `workflows/autonomous.md` — Version bump ref + `post_phase_audit` step (5c)
+- `workflows/audit.md` — Auto-hook: concrete integration spec replaces conceptual note
+- `workflows/request.md`, `brainstorm.md`, `crystallize.md` — AUQ REQUIRED
+- `skills/vp-evolve/SKILL.md` — New Adapter Compatibility section
+- `skills/vp-request`, `vp-brainstorm`, `vp-crystallize` SKILL.md — AUQ REQUIRED
+- `tests/unit/vp-workflow-consistency.test.js` — 35 contract tests
+
+## [2.17.0] - 2026-04-17
+
+### Changed
+- **vp-auto** git tags now include active branch and package version for full
+  traceability. New format: `{prefix}-{branch}-{version}-vp-p{n}-t{n}`. (ENH-050)
+  - Branch resolved via `git rev-parse --abbrev-ref HEAD` (sanitized: `/` → `-`)
+  - Version resolved from `package.json` (fallback: `0.0.0`)
+  - Legacy tags (`{prefix}-vp-p{n}-*`) continue to be recognized by audit + rollback
+
+### Files
+- `workflows/autonomous.md` — `TAG_PREFIX` resolution block (BRANCH_SAFE + VERSION);
+  task start, task done, and phase complete tag patterns updated to enriched format
+- `workflows/audit.md` — `COMPLETE_TAGS` regex: added third alternative for enriched
+  format; `PREV_TAG` grep: extended char class to include `.` for version strings
+- `workflows/rollback.md` — tag grep char class extended to include `.` for version strings
+- `tests/unit/vp-enh050-git-tag-format.test.js` — 16 contract tests
+
+## [2.16.0] - 2026-04-17
+
+### Changed
+- **vp-audit** Tier 4 (Framework Integrity) now runs silently — output is suppressed
+  when the check passes (✅) or is skipped (non-framework repo). Tier 4 is only
+  surfaced in the audit report when issues (⚠️) are found. (ENH-049)
+
+### Files
+- `workflows/audit.md` — Step 4 skip: removed `echo "→ Tier 4 skipped"` message;
+  Step 4f report block wrapped in `TIER4_ISSUES > 0` guard; All Clear banner Tier 4
+  line removed; Issues Found banner Tier 4 line rendered only when `TIER4_ISSUES > 0`
+- `skills/vp-audit/SKILL.md` — documented silent-by-default Tier 4 behavior (ENH-049)
+- `tests/unit/vp-enh049-audit-tier4-silent.test.js` — 13 contract tests
+
+## [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.22.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-1140%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.19.0** is the **ViePilot framework SemVer** tracked in `.viepilot/TRACKER.md` and `CHANGELOG.md`. The npm `package.json` field `version` (**2.19.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/dev/agents.md

@@ -0,0 +1,131 @@
+# ViePilot Agents Layer
+
+Developer reference for the agents system introduced in ENH-057 (v2.20.0).
+
+## Why Agents?
+
+Before v2.20.0, vp-* skills handled everything inline: research web fetches, TRACKER.md
+updates, CHANGELOG writes, file scans, test generation, and doc updates all ran
+sequentially in the main LLM context. This caused:
+
+1. **Context bloat** — long skill runs exhausted context with intermediate data
+2. **Sequential bottleneck** — research + write + verify ran one-at-a-time
+3. **Skill coupling** — each skill re-implemented the same patterns (tracker update, version bump)
+4. **No parallelism** — vp-auto tasks that could run concurrently didn't
+
+The agents layer delegates these operations to dedicated sub-agents — isolated contexts
+that run in parallel or in sequence without polluting the calling skill's conversation.
+
+## Architecture
+
+```
+vp-* skill (orchestrator)
+    │
+    ├── tracker-agent      ← .viepilot/TRACKER.md read/write
+    ├── research-agent     ← WebSearch + WebFetch (isolated context)
+    ├── file-scanner-agent ← Glob + Grep (repo-wide scanning)
+    ├── changelog-agent    ← CHANGELOG + version bump (single authority)
+    ├── test-generator-agent ← tests/*.test.js generation + run
+    └── doc-sync-agent     ← skills/*/SKILL.md bulk update
+```
+
+Agent definitions live in `agents/` at the repo root. They are installed to
+`{viepilotDir}/agents/` alongside workflows and templates.
+
+## Agent Catalog
+
+### tracker-agent
+**File**: `agents/tracker-agent.md`
+**Purpose**: Read/write TRACKER.md — phase status, task status, decision log, request table.
+**When to invoke**: vp-auto (task start/complete/phase complete), vp-request (Step 5), vp-evolve (phase creation).
+**Claude Code subagent_type**: `general-purpose`
+
+### research-agent
+**File**: `agents/research-agent.md`
+**Purpose**: WebSearch + WebFetch + summarize for feasibility studies and tech research.
+**When to invoke**: vp-request (Step 2B — auto-triggered for Feature/platform requests), vp-brainstorm (external validation).
+**Claude Code subagent_type**: `general-purpose`
+
+### file-scanner-agent
+**File**: `agents/file-scanner-agent.md`
+**Purpose**: Glob + Grep across repo to find affected files, detect stale refs.
+**When to invoke**: vp-audit (Tier 1–4), vp-evolve (impact analysis), vp-rollback (state restore).
+**Claude Code subagent_type**: `Explore` (specialized for codebase scanning)
+
+### changelog-agent
+**File**: `agents/changelog-agent.md`
+**Purpose**: Atomically append CHANGELOG entry + bump package.json version.
+**When to invoke**: vp-auto post-phase (last task), vp-evolve (milestone ship).
+**Claude Code subagent_type**: `general-purpose`
+**Note**: Single authority for version bumps — resolves ENH-053.
+
+### test-generator-agent
+**File**: `agents/test-generator-agent.md`
+**Purpose**: Generate contract tests from acceptance criteria, run suite, report pass/fail.
+**When to invoke**: Last task of each phase (the `N.last` contract-test task pattern).
+**Claude Code subagent_type**: `general-purpose`
+
+### doc-sync-agent
+**File**: `agents/doc-sync-agent.md`
+**Purpose**: Bulk-apply the same change to ≥5 `.md` files (adapter rows, banners, etc.).
+**When to invoke**: Auto-triggered by autonomous.md when task Paths block has ≥5 identical file types.
+**Claude Code subagent_type**: `general-purpose`
+
+## Invocation Patterns
+
+### Claude Code (terminal)
+
+Use the `Agent` tool with the appropriate `subagent_type`:
+
+```js
+Agent({
+  subagent_type: "general-purpose",  // or "Explore" for file-scanner
+  description: "{agent-name}: {operation-summary}",
+  prompt: `
+    Load agents/{agent-name}.md for the full specification.
+    Execute operation: {operation}
+    Inputs: {inputs}
+  `
+})
+```
+
+### Cursor / Codex / Antigravity
+
+Execute the equivalent operation inline in the same session. The agent `.md` file
+describes the exact steps — follow them as a scoped sub-prompt.
+
+## Adapter Behavior Table
+
+| Agent | Claude Code | Cursor | Codex | Antigravity |
+|-------|------------|--------|-------|-------------|
+| tracker-agent | Subagent (general-purpose) | Inline | Inline | Inline |
+| research-agent | Subagent (general-purpose) | Inline if web available | Inline if web available | Inline if web available |
+| file-scanner-agent | Subagent (Explore) | Inline | Inline | Inline |
+| changelog-agent | Subagent (general-purpose) | Inline | Inline | Inline |
+| test-generator-agent | Subagent (general-purpose) | Inline | Inline | Inline |
+| doc-sync-agent | Subagent (general-purpose) | Sequential inline | Sequential inline | Sequential inline |
+
+## Adding a New Agent
+
+1. Create `agents/{name}-agent.md` with all required sections:
+   - `## Purpose`
+   - `## Inputs`
+   - `## Outputs`
+   - `## Invocation Pattern` (Claude Code + text fallback)
+   - `## Adapter Behavior` (table covering all 4 adapters)
+   - `## Notes`
+
+2. Add the agent to the delegation table in `workflows/autonomous.md`
+   under `## Agent Delegation`.
+
+3. Wire invocation into the relevant workflow steps.
+
+4. Add to `installSubdirs` in the adapter that should include `agents/`.
+
+5. Write a contract test in `tests/unit/` verifying the file exists and has required sections.
+
+## Naming Conventions
+
+- File: `agents/{name}-agent.md` (kebab-case, always ends in `-agent`)
+- Reference: `{name}-agent` (e.g., `tracker-agent`, not `tracker`)
+- Invocation: `Load agents/{name}-agent.md for full spec.`

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/adapters.md

@@ -10,6 +10,7 @@ ViePilot supports multiple AI coding platforms via its adapter system (FEAT-013)
 | `cursor-agent` / `cursor-ide` | Cursor | `~/.cursor/skills/` | `~/.cursor/viepilot/` | — | `/vp-status` |
 | `antigravity` | Google Antigravity | `~/.antigravity/skills/` | `~/.antigravity/viepilot/` | — | `/vp-status` |
 | `codex` | OpenAI Codex CLI | `~/.codex/skills/` | `~/.codex/viepilot/` | — | `$vp-status` |
+| `copilot` | GitHub Copilot | `~/.config/gh-copilot/skills/` | `~/.config/gh-copilot/viepilot/` | — | `/vp-status` |
 
 > **Note — Codex invocation syntax:** OpenAI Codex CLI uses `$skill-name` to invoke skills (e.g. `$vp-status`, `$vp-brainstorm`). The `/command` prefix is reserved for Codex built-in controls (`/plan`, `/clear`, `/diff`, etc.). SKILL.md file format is fully compatible — no changes needed to skill content.
 
@@ -28,6 +29,9 @@ viepilot install --target antigravity
 # OpenAI Codex CLI
 viepilot install --target codex
 
+# GitHub Copilot
+viepilot install --target copilot
+
 # Multiple targets at once
 viepilot install --target claude-code,antigravity
 ```
@@ -45,6 +49,53 @@ At install time, `{envToolDir}` is replaced with each adapter's `executionContex
 - `cursor` → `.cursor/viepilot`
 - `antigravity` → `.antigravity/viepilot`
 - `codex` → `.codex/viepilot`
+- `copilot` → `.config/gh-copilot/viepilot`
+
+## GitHub Copilot
+
+GitHub Copilot adapter (FEAT-019) enables vp-* skills to run inside VS Code Copilot Chat and the GitHub Copilot CLI.
+
+### Surface support
+
+| Surface | Status | Notes |
+|---------|--------|-------|
+| VS Code Copilot Chat | ✅ Supported | Invoke with `/vp-status`, `/vp-auto`, etc. |
+| GitHub Copilot CLI | ✅ Supported | Invoke with `/vp-status` in CLI chat |
+| Copilot Cloud Agents | ⚠️ Preview | GitHub Copilot Extensions (Public Preview); subject to change |
+| JetBrains Copilot | ⚠️ Pending | Copilot Chat for JetBrains — skills not yet validated |
+
+### Prerequisites
+
+- **gh CLI** installed (`brew install gh` or [cli.github.com](https://cli.github.com))
+- **GitHub Copilot subscription** (Individual, Business, or Enterprise)
+- **GitHub Copilot extension** for VS Code (marketplace ID: `GitHub.copilot-chat`)
+
+### Installation
+
+```bash
+npx viepilot install --target copilot
+```
+
+Files are installed to:
+- Skills: `~/.config/gh-copilot/skills/`
+- Workflows + lib: `~/.config/gh-copilot/viepilot/`
+
+After install, open VS Code, open Copilot Chat (`Ctrl+Shift+I` / `Cmd+Shift+I`), and type `/vp-status`.
+
+### Availability detection
+
+The installer detects Copilot by checking (in order):
+
+1. `~/.config/gh-copilot/` directory exists (primary)
+2. `gh` binary found at `/usr/local/bin/gh`, `/opt/homebrew/bin/gh`, or `~/.local/bin/gh` (secondary)
+
+### Known limitations
+
+| Feature | Status |
+|---------|--------|
+| `AskUserQuestion` interactive prompts | ❌ Not available — skills use text-based menus |
+| Hooks (PreToolUse, Stop, etc.) | ❌ Copilot uses `.agent.md` convention, not programmatic hooks |
+| MCP server integration | 🔜 Planned for Phase 2 |
 
 ## Adding a new adapter
 

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/lib/adapters/antigravity.cjs

@@ -24,7 +24,8 @@ module.exports = {
     path.join('templates', 'architect'),
     'bin',
     'lib',
-    'ui-components'
+    'ui-components',
+    'agents'
   ],
   isAvailable: (home) => {
     const h = home || os.homedir();

package/lib/adapters/claude-code.cjs

@@ -32,7 +32,8 @@ module.exports = {
     path.join('templates', 'architect'),
     'bin',
     'lib',
-    'ui-components'
+    'ui-components',
+    'agents'
   ],
   // Detection: is this platform available on the current machine?
   isAvailable: (home) => {

package/lib/adapters/codex.cjs

@@ -25,7 +25,8 @@ module.exports = {
     path.join('templates', 'architect'),
     'bin',
     'lib',
-    'ui-components'
+    'ui-components',
+    'agents'
   ],
   isAvailable: (home) => {
     const h = home || os.homedir();