viepilot 1.9.1 → 1.9.4

package/CHANGELOG.md

@@ -15,6 +15,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - None yet.
 
+### Changed
+
+- None yet.
+
+## [1.9.4] - 2026-04-02
+
+### Fixed
+
+- **Installer / Claude Code** — `npx viepilot install --target claude-code` giờ **copy** (hoặc symlink nếu `VIEPILOT_SYMLINK_SKILLS=1`) toàn bộ `skills/vp-*` vào **`~/.claude/skills/`**, không chỉ `~/.cursor/skills/`. `uninstall --target claude-code` gỡ `~/.claude/skills/vp-*`. (`lib/viepilot-install.cjs`, `bin/viepilot.cjs`; tests + `docs/user/claude-code-setup.md`, FAQ).
+
+## [1.9.3] - 2026-04-02
+
+### Added
+
+- **M1.29 / Phase 34 (FEAT-001)** — Hướng dẫn ViePilot trên **Claude Code**: `docs/user/claude-code-setup.md` (installer `npx viepilot install --target claude-code`, map `vp-*` → `~/.claude/skills`, `vp-tools info`, chuỗi request → evolve → auto); cross-links trong `docs/getting-started.md`, `docs/user/quick-start.md`, `docs/user/faq.md`, `docs/README.md`; `tests/unit/vp-feat001-claude-code-docs-contracts.test.js`; README test metrics **299** / **15** suites.
+
+## [1.9.2] - 2026-04-03
+
+### Changed
+
+- **ENH-019** — `/research-ui`: Phase 1 thêm **content stress pass** (copy dài, khối lượng, validation, viewport…) và **Stress findings**; log + designer pass cập nhật tương ứng (`workflows/brainstorm.md`, `vp-brainstorm` 0.6.1 → **0.6.3** theo bản ship).
+- **ENH-020** — `/research-ui`: bảng **stress recipes theo archetype** (landing, SaaS admin, form/wizard, reader, commerce/booking) + hybrid.
+- **ENH-021** — **Implementation routing guard**: `vp-request` / `vp-evolve` / `vp-debug` không implement shipping mặc định; chuỗi **`/vp-evolve` → `/vp-auto`**; cả **16** `skills/vp-*/SKILL.md` + `workflows/request.md`, `evolve.md`, `debug.md`, `autonomous.md`; `docs/skills-reference.md`; `tests/unit/vp-en021-implementation-routing-contracts.test.js`; README test metrics **297**.
+
 ## [1.9.1] - 2026-04-02
 
 ### Added
@@ -310,7 +334,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-[Unreleased]: https://github.com/0-CODE/viepilot/compare/v1.9.1...HEAD
+[Unreleased]: https://github.com/0-CODE/viepilot/compare/v1.9.2...HEAD
+[1.9.2]: https://github.com/0-CODE/viepilot/compare/v1.9.1...v1.9.2
 [1.9.1]: https://github.com/0-CODE/viepilot/compare/v1.9.0...v1.9.1
 [1.9.0]: https://github.com/0-CODE/viepilot/compare/v1.8.1...v1.9.0
 [1.8.1]: https://github.com/0-CODE/viepilot/compare/v1.8.0...v1.8.1

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-1.9.1-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-1.9.4-blue.svg)](CHANGELOG.md)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-16-purple.svg)](#skills-reference)
 [![Workflows](https://img.shields.io/badge/workflows-12-orange.svg)](#workflows)
 [![Templates](https://img.shields.io/badge/templates-17-cyan.svg)](#templates)
-[![Tests](https://img.shields.io/badge/tests-294%20passing-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-304%20passing-brightgreen.svg)](tests/)
 [![GitHub](https://img.shields.io/github/stars/0-CODE/viepilot?style=social)](https://github.com/0-CODE/viepilot)
 
-**Versioning:** Shield **1.9.1** is the **ViePilot framework SemVer** tracked in `.viepilot/TRACKER.md` and `CHANGELOG.md`. The npm `package.json` field `version` (**1.9.1**) is the Node package identifier for this repo; use the framework version for milestone releases and docs.
+**Versioning:** Shield **1.9.4** is the **ViePilot framework SemVer** tracked in `.viepilot/TRACKER.md` and `CHANGELOG.md`. The npm `package.json` field `version` (**1.9.4**) 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,13 +28,13 @@ 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 | **~27,113+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
+| Total LOC | **~27,779+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
 | Skills | **16** |
 | Workflows | **12** |
 | Templates | **17** (Project: 12, Phase: 5) |
 | CLI Commands | **18** (`vp-tools` 17 subcommands + `viepilot` installer) |
-| Tests | **294** (13 suites: unit + integration + AI compat + README metrics + UI direction + ENH contracts + scope policy + FEAT-009 + FEAT-010 + viepilot-info/update/install) |
-| ViePilot phases (local `.viepilot`) | **32** phase cycles — **M1.28** (**v1.9.1** FEAT-010); **M1.27** (**v1.9.0** FEAT-009); xem `CHANGELOG.md` |
+| Tests | **304** (15 suites: unit + integration + AI compat + README metrics + UI direction + ENH contracts + scope policy + FEAT-009 + FEAT-010 + ENH-021 routing + FEAT-001 Claude Code docs + viepilot-info/update/install) |
+| ViePilot phases (local `.viepilot`) | **34** phase cycles — **M1.29** FEAT-001 (**v1.9.3** doc); patch **v1.9.4** (Claude installer); **M1.28** FEAT-010 (**v1.9.1**); **v1.9.2** (ENH-019~021); **M1.27** (**v1.9.0** FEAT-009); xem `CHANGELOG.md` |
 | Standards | 5 (SemVer, Commits, Changelog, Comments, Contributors) |
 
 > Metric `Total LOC` có thể được refresh tự động bằng `npm run readme:sync` (dùng `cloc`; nếu thiếu `cloc` script sẽ fallback an toàn).
@@ -48,14 +48,14 @@ Nếu ViePilot giúp ích cho bạn, bạn có thể ủng hộ một ly cafe:
 | Project Templates | 12 | AI-GUIDE, ARCHITECTURE, VIEPILOT-META, README, SYSTEM-RULES, etc. |
 | Phase Templates | 5 | SPEC, PHASE-STATE, TASK, VERIFICATION, SUMMARY |
 | CLI Tools | 2 | vp-tools.cjs (**17** subcommands) + viepilot.cjs (guided installer) |
-| Test Files | 13 | Jest: 12 unit + 1 integration (contracts, installer, info/update, FEAT-009, FEAT-010, scope policy, …) |
+| Test Files | 15 | Jest: 14 unit + 1 integration (contracts, installer + Claude paths, info/update, FEAT-009, FEAT-010, FEAT-001, ENH-021, scope policy, …) |
 
 ---
 
 ## Độ hoàn thiện / Completion Status
 
 ```
-Tổng thể / Overall:  ████████████████████  ~98% ✅ Latest **v1.9.1** (M1.28 FEAT-010 — `/research-ui`); prior **v1.9.0** FEAT-009; **v1.8.1** BUG-004
+Tổng thể / Overall:  ████████████████████  ~98% ✅ Latest **v1.9.4** (Claude Code **installer** ~/.claude/skills); **v1.9.3** FEAT-001 doc; **v1.9.2** (ENH-019~021); **v1.9.1** FEAT-010; **v1.9.0** FEAT-009
 ```
 
 | Lĩnh vực / Area | Trạng thái | Chi tiết |
@@ -65,7 +65,7 @@ Tổng thể / Overall:  ██████████████████
 | 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 (294) | ✅ Hoàn thiện | Unit, integration, AI compat, workflow contracts, installer, scope policy, FEAT-009/010, info/update |
+| Tests (304) | ✅ Hoàn thiện | Unit, integration, AI compat, workflow contracts, installer, scope policy, FEAT-009/010/001, ENH-021, info/update |
 | 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 |

package/bin/viepilot.cjs

@@ -32,14 +32,14 @@ Usage:
   viepilot --list-targets
 
 Install options:
-  --target <id|id,id|all>   Target profile(s): claude-code,cursor-agent,cursor-ide
+  --target <id|id,id|all>   Target profile(s): claude-code (mirrors vp-* to ~/.claude/skills), cursor-agent, cursor-ide
   --yes                      Non-interactive mode (skip confirmations)
   --dry-run                  Print actions only (Node installer; no bash)
   --list-targets             Print supported targets and exit
   --help                     Show help
 
 Uninstall options:
-  --target <id|id,id|all>   Remove installed assets for selected profile(s)
+  --target <id|id,id|all>   Remove assets (claude-code: ~/.claude/skills/vp-*; cursor-*: ~/.cursor/skills/vp-*; shared: ~/.cursor/viepilot)
   --yes                     Non-interactive mode (skip confirmations)
   --dry-run                 Print actions only, do not remove files
 `);
@@ -246,7 +246,7 @@ async function interactiveTargetSelection() {
 }
 
 /**
- * One install applies the same file bundle for every target id (profiles are informational).
+ * Core bundle (workflows, bin, ~/.cursor/viepilot) is shared; `claude-code` additionally mirrors vp-* skills into ~/.claude/skills.
  * @param {string[]} selectedTargets
  * @param {boolean} dryRun
  * @returns {{ ok: boolean, code: number }}
@@ -264,7 +264,7 @@ function runInstallViaNode(selectedTargets, dryRun) {
 
   let plan;
   try {
-    plan = buildInstallPlan(pkgRoot, env, { wantPathShim });
+    plan = buildInstallPlan(pkgRoot, env, { wantPathShim, installTargets: selectedTargets });
   } catch (err) {
     console.error(err.message);
     return { ok: false, code: 1 };
@@ -273,7 +273,10 @@ function runInstallViaNode(selectedTargets, dryRun) {
   console.log('');
   console.log('ViePilot install (Node — no bash required)');
   console.log(`  Package: ${pkgRoot}`);
-  console.log(`  Targets (informational): ${selectedTargets.join(', ')}`);
+  console.log(`  Targets: ${selectedTargets.join(', ')}`);
+  if (selectedTargets.includes('claude-code')) {
+    console.log('  (claude-code → also ~/.claude/skills/vp-*)');
+  }
 
   const applied = applyInstallPlan(plan, { dryRun });
   if (applied.logs.length > 0) {
@@ -332,7 +335,8 @@ async function installCommand(rawArgs) {
     else console.log(`- ${r.target}: failed (exit ${r.code})`);
   }
   console.log('\nNext actions:');
-  console.log('- Open project in Cursor/Claude and run /vp-status');
+  console.log('- Cursor: open project and run /vp-status');
+  console.log('- Claude Code: restart session if needed so ~/.claude/skills/vp-* is picked up; then /vp-status');
   console.log('- If needed, run /vp-brainstorm then /vp-crystallize');
 
   return failed.length === 0 ? 0 : 1;
@@ -356,6 +360,17 @@ function computeUninstallPaths(targets) {
     }
   }
 
+  if (targets.some((t) => t === 'claude-code')) {
+    const claudeSkills = path.join(home, '.claude', 'skills');
+    if (fs.existsSync(claudeSkills)) {
+      for (const entry of fs.readdirSync(claudeSkills)) {
+        if (entry.startsWith('vp-')) {
+          paths.push(path.join(claudeSkills, entry));
+        }
+      }
+    }
+  }
+
   paths.push(vpRoot);
   paths.push('/usr/local/bin/vp-tools');
   paths.push('/usr/local/bin/viepilot');

package/docs/README.md

@@ -22,6 +22,7 @@
 | Document | Description |
 |----------|-------------|
 | [Quick Start](user/quick-start.md) | Install, brainstorm, crystallize, auto — 5 min guide |
+| [Claude Code setup](user/claude-code-setup.md) | Cài ViePilot trên Claude Code (`~/.claude/skills`, CLI, workflows) |
 | [FAQ](user/faq.md) | Frequently asked questions |
 
 #### Features
@@ -116,9 +117,9 @@
 | `/vp-status` | "status", "tiến độ" | Progress dashboard |
 | `/vp-info` | "version", "phiên bản" | Bundle version, npm latest, inventory |
 | `/vp-update` | "upgrade viepilot", "npm" | Upgrade ViePilot via npm |
-| `/vp-request` | "request", "feature", "bug" | Add feature/bug |
+| `/vp-request` | "request", "feature", "bug" | Log backlog; sau đó evolve + auto (ENH-021) |
 | `/vp-ui-components` | "ui components", "21st.dev" | Curate and reuse UI component library |
-| `/vp-evolve` | "evolve", "milestone mới" | New milestone |
+| `/vp-evolve` | "evolve", "milestone mới" | Planning (ROADMAP/phase); implement bằng `/vp-auto` |
 | `/vp-docs` | "docs", "documentation" | Generate docs |
 | `/vp-task` | "task", "manual" | Manual task control |
 | `/vp-debug` | "debug", "investigate" | Debug issues |
@@ -127,4 +128,4 @@
 
 ---
 
-*Last updated: 2026-04-01 — ViePilot framework **v1.9.0** (M1.27 FEAT-009: global profiles + docs workflow §0A); see `CHANGELOG.md` and `docs/dev/global-profiles.md`.*
+*Last updated: 2026-04-02 — ViePilot framework **v1.9.4** (Claude Code installer → `~/.claude/skills`; FEAT-001 doc v1.9.3; ENH-021 routing; M1.27 FEAT-009 profiles); see `CHANGELOG.md`, [Claude Code setup](user/claude-code-setup.md), `docs/user/features/autonomous-mode.md`.*

package/docs/getting-started.md

@@ -27,6 +27,10 @@ cd viepilot
 ./install.sh
 ```
 
+### Claude Code
+
+Nếu bạn dùng **Claude Code** thay vì Cursor, làm theo [ViePilot trên Claude Code](user/claude-code-setup.md) (skills trong `~/.claude/skills`, installer `npx viepilot install --target claude-code`, và verify `vp-tools info`).
+
 ## Step 2: Brainstorm Your Project
 
 Start a new project by brainstorming:

package/docs/skills-reference.md

@@ -10,6 +10,10 @@ Complete reference for all ViePilot skills.
 - **Routing fallback**: if an external skill is mentioned accidentally, prefer the closest built-in `vp-*` command instead.
 - **Opt-in example**: "Trong bước này, cho phép dùng thêm external skills ngoài ViePilot để tham khảo."
 
+### Implementation routing (ENH-021)
+
+- **`/vp-request`** và **`/vp-evolve`** **không** implement mã shipping mặc định — chỉ backlog / plan (ROADMAP, phase, tasks). **`/vp-auto`** là lane implement sau khi có task plan (doc-first **BUG-001**). Mọi `skills/vp-*/SKILL.md` có block `<implementation_routing_guard>`; normative: `workflows/request.md`, `workflows/evolve.md`, `workflows/debug.md`, `workflows/autonomous.md`.
+
 ---
 
 ## /vp-brainstorm
@@ -32,7 +36,7 @@ Complete reference for all ViePilot skills.
 | `/end` | Kết thúc và lưu (sau **Project meta intake** nếu thiếu `.viepilot/META.md` / `viepilot_profile_id` — FEAT-009) |
 | `/questions` | Xem open questions |
 | `/research {topic}` | Research nhanh trong phiên, quay lại topic hiện tại |
-| `/research-ui` | **UI Direction (FEAT-010)**: mô phỏng user → designer + web research → cập nhật HTML/CSS + **`## UX walkthrough log`** trong `notes.md` |
+| `/research-ui` | **UI Direction (FEAT-010, ENH-019, ENH-020)**: scenarios + stress pass + **archetype recipes** → designer + research → HTML/CSS + **`## UX walkthrough log`** |
 | `/research ui` | Alias của `/research-ui` |
 
 ### Output
@@ -197,7 +201,7 @@ AI pauses for user input when:
 
 ## /vp-evolve
 
-**Purpose**: Nâng cấp hoặc mở rộng dự án
+**Purpose**: Nâng cấp hoặc mở rộng dự án (**planning** — ROADMAP, phase, tasks; implement sau bằng **`/vp-auto`**; xem **Implementation routing (ENH-021)** ở đầu file).
 
 ### Modes
 | Mode | Description |
@@ -274,7 +278,7 @@ CHANGELOG.md (updated)
 
 ## /vp-request
 
-**Purpose**: Tạo và quản lý requests (Bug, Feature, Enhancement, Tech Debt, Brainstorm tiếp)
+**Purpose**: Tạo và quản lý requests (Bug, Feature, Enhancement, Tech Debt, Brainstorm tiếp). **Không** thay **`/vp-evolve`** (plan) hay **`/vp-auto`** (implement); chuỗi khuyến nghị: request → evolve → auto (**ENH-021**).
 
 ### Flags
 | Flag | Description |

package/docs/user/claude-code-setup.md

@@ -0,0 +1,144 @@
+# ViePilot trên Claude Code
+
+Hướng dẫn cài đặt và kiểm tra ViePilot khi bạn dùng **Claude Code** (CLI/IDE), bổ sung cho [Quick Start](quick-start.md) và [Getting Started](../getting-started.md).
+
+## Claude Code vs Cursor (đường dẫn skills)
+
+| | **Cursor** | **Claude Code** |
+|---|------------|-----------------|
+| Skills (global) | `~/.cursor/skills/<id>/SKILL.md` | `~/.claude/skills/<id>/SKILL.md` |
+| Skills (project) | Rules / project config tùy Cursor | `.claude/skills/<id>/SKILL.md` trong repo |
+| Tài liệu chính thức | — | [Extend Claude with skills](https://code.claude.com/docs/en/skills), [Explore the .claude directory](https://code.claude.com/docs/en/claude-directory) |
+
+Bundled skill ViePilot dùng frontmatter `name: vp-*` — trên Claude Code bạn gọi tương đương **`/vp-auto`**, **`/vp-request`**, … như trong [Skills Reference](../skills-reference.md).
+
+**Lưu ý:** Nội dung skill hiện nhắc tới công cụ kiểu Cursor (`ReadFile`, `ApplyPatch`, …). Trên Claude Code, agent sẽ map sang tool tương đương (đọc/ghi file, terminal, …). Phần **workflow** và **chuỗi lệnh** (`/vp-evolve` → `/vp-auto`) vẫn giữ nguyên ý nghĩa.
+
+## Bước 1 — Cài bundle ViePilot (CLI)
+
+Với **`--target claude-code`**, installer (ViePilot **≥ 1.9.4**) **tự copy** toàn bộ `skills/vp-*` vào **`~/.claude/skills/`** (Claude Code mới thấy lệnh `/vp-*`). Đồng thời vẫn mirror vào **`~/.cursor/skills/`** và **`~/.cursor/viepilot/`** (workflows, bin) như trước.
+
+```bash
+npx viepilot install --target claude-code --yes
+```
+
+Hoặc clone repo và chạy từ thư mục gốc package:
+
+```bash
+git clone https://github.com/0-CODE/viepilot.git
+cd viepilot
+npx viepilot install --target claude-code --yes
+```
+
+Kết quả điển hình:
+
+- **`~/.claude/skills/vp-*/SKILL.md`** — dùng trực tiếp trong Claude Code
+- **`~/.cursor/skills/vp-*/`** — giữ cho Cursor / tương thích
+- Workflows, templates, `bin/*.cjs` tới **`~/.cursor/viepilot/`**
+- Seed **`~/.viepilot/profiles/`** và `~/.viepilot/profile-map.md` (xem [Global profiles](../dev/global-profiles.md))
+
+Sau khi cài: **khởi động lại / mở session Claude Code mới** nếu menu `/` chưa thấy `vp-*`.
+
+**Cập nhật sau này:** chạy lại `npx viepilot install --target claude-code --yes` từ bản npm/git mới để refresh cả hai cây skills.
+
+## Bước 2 — Tuỳ chọn: symlink / copy thủ công (bản cũ hoặc chỉ Cursor)
+
+Nếu bạn dùng ViePilot **&lt; 1.9.4** hoặc đã cài **`--target cursor-*`** mà **không** gồm `claude-code`, Claude Code **không** đọc `~/.cursor/skills` — khi đó đồng bộ thủ công vào **`~/.claude/skills/<tên-thư-mục>/SKILL.md`**.
+
+### Cách A — Symlink (khuyến nghị cho máy cá nhân)
+
+```bash
+mkdir -p ~/.claude/skills
+for d in ~/.cursor/skills/vp-*; do
+  [ -d "$d" ] || continue
+  name=$(basename "$d")
+  ln -sfn "$d" "$HOME/.claude/skills/$name"
+done
+```
+
+### Cách B — Copy (ổn cho máy không dùng symlink)
+
+```bash
+mkdir -p ~/.claude/skills
+for d in ~/.cursor/skills/vp-*; do
+  [ -d "$d" ] || continue
+  name=$(basename "$d")
+  rm -rf "$HOME/.claude/skills/$name"
+  cp -R "$d" "$HOME/.claude/skills/$name"
+done
+```
+
+Sau mỗi lần `npm update -g viepilot` hoặc reinstall: với **copy** cần chạy lại lệnh copy; với **symlink** chỉ cần cập nhật phía `~/.cursor/skills`.
+
+### Cách C — Skills chỉ trong một project
+
+Trong repo của bạn:
+
+```bash
+mkdir -p .claude/skills
+# symlink hoặc copy từng vp-* từ clone viepilot hoặc từ ~/.cursor/skills
+```
+
+Commit `.claude/skills/` nếu team cần dùng chung (xì [Where skills live](https://code.claude.com/docs/en/skills#where-skills-live)).
+
+## Bước 3 — Workflows và `execution_context`
+
+Nhiều skill trỏ tới workflow qua đường dẫn kiểu **`~/.cursor/viepilot/workflows/...`**. Sau `npx viepilot install`, thư mục này đã có bản mirror — **giữ nguyên** và đảm bảo skill không bị sandbox chặn đọc `$HOME`.
+
+Nếu bạn **không** dùng installer: từ clone, có thể đọc trực tiếp `workflows/*.md` trong repo hoặc tự mirror sang `~/.cursor/viepilot/workflows/` cho khớp văn bản skill.
+
+## Bước 4 — `vp-tools` trên PATH
+
+**Sau installer**, thử:
+
+```bash
+~/.cursor/viepilot/bin/vp-tools.cjs info
+# hoặc nếu đã thêm vào PATH:
+vp-tools info
+vp-tools info --json
+```
+
+**npm global:**
+
+```bash
+npm i -g viepilot
+vp-tools info
+```
+
+**Chỉ có clone, không cài global:**
+
+```bash
+node /đường-dẫn/tới/viepilot/bin/vp-tools.cjs info --json
+```
+
+Chi tiết lệnh: [CLI Reference](../dev/cli-reference.md).
+
+## Bước 5 — Bootstrap `.viepilot/` cho project đích
+
+Trong thư mục project (không nhất thiết là repo `viepilot`):
+
+1. Mở project trong Claude Code.
+2. Chạy **`/vp-crystallize`** (hoặc tương đương theo skill) để sinh `.viepilot/` — hoặc copy thủ công từ [`templates/project/`](../../templates/project/) theo [Getting Started](../getting-started.md).
+
+Một số repo framework **gitignore** `.viepilot/`; với **ứng dụng của bạn** thường nên **commit** để cả team (và agent) cùng thấy ROADMAP/TRACKER.
+
+## Kiểm tra nhanh
+
+| Bước | Lệnh / hành động | Kỳ vọng |
+|------|------------------|---------|
+| CLI | `vp-tools info` hoặc `node .../vp-tools.cjs info` | In `installedVersion`, `skills[]` |
+| Claude | Gõ `/` trong Claude Code | Thấy các skill `vp-*` đã cài |
+| Project | Có `.viepilot/TRACKER.md` sau crystallize | Theo [FAQ](faq.md) |
+
+## Windows
+
+- Symlink có thể cần quyền Developer Mode hoặc chạy terminal elevated; nếu không, dùng **copy** (cách B).
+- `path_shim` tới `/usr/local/bin` chỉ phù hợp Unix; trên Windows dùng `node ...\vp-tools.cjs` hoặc thêm thư mục chứa `vp-tools.cjs` vào **PATH** thủ công.
+
+## Chuỗi làm việc gợi ý (ENH-021)
+
+1. **`/vp-request`** — ghi yêu cầu  
+2. **`/vp-evolve`** — lên ROADMAP / phase  
+3. **`/vp-auto`** — thực thi task có plan  
+
+Xem thêm: [Autonomous mode](features/autonomous-mode.md), [Troubleshooting](../troubleshooting.md).

package/docs/user/faq.md

@@ -14,6 +14,12 @@ A: Skills được thiết kế cho Cursor IDE. Tuy nhiên, workflows và CLI (`
 
 ---
 
+### Q: Làm sao dùng ViePilot với Claude Code?
+
+A: Chạy `npx viepilot install --target claude-code --yes` (ViePilot **≥ 1.9.4**): installer **tự copy** `vp-*` vào **`~/.claude/skills/`**. Với bản cũ hoặc chỉ target Cursor, symlink/copy thủ công từ `~/.cursor/skills/`. Chi tiết, verify `vp-tools info`, và chuỗi **`/vp-request` → `/vp-evolve` → `/vp-auto`**: xem [ViePilot trên Claude Code](claude-code-setup.md).
+
+---
+
 ### Q: Tôi có cần biết code để dùng ViePilot không?
 
 A: Không nhất thiết. ViePilot giúp AI code cho bạn. Tuy nhiên, để review code và approve control points, hiểu biết cơ bản về programming sẽ hữu ích.
@@ -106,12 +112,13 @@ A: Dùng `/vp-resume` để tiếp tục từ điểm dừng. Nếu có lỗi, d
 
 ### Q: Làm sao thêm feature mới khi project đang chạy?
 
-A: Dùng `/vp-request --feature` — ViePilot sẽ insert phase mới vào roadmap mà không disrupt phases hiện tại.
+A: **`/vp-request --feature`** để **log** yêu cầu (file request + backlog). **`/vp-evolve`** (Add feature / New milestone) để **thêm phase + tasks** trên ROADMAP. **`/vp-auto`** để **implement** theo task plan. (ENH-021: không implement trực tiếp trong thread request/evolve trừ khi bạn explicit bypass.)
 
 ---
 
 ### Q: Khi nào nên dùng `/vp-evolve` vs `/vp-request`?
 
-A: 
-- `/vp-request --feature` — Thêm feature nhỏ vào milestone hiện tại
-- `/vp-evolve` — Bắt đầu milestone mới (M2, M3) với scope lớn hơn
+A:
+- **`/vp-request`** — Ghi nhận bug/feature/enhancement vào `.viepilot/requests/*` + TRACKER; **không** thay thế bước plan/implement.
+- **`/vp-evolve`** — **Planning**: thêm phase trên ROADMAP, tạo `SPEC`/tasks, cập nhật milestone; sau đó gọi **`/vp-auto`**.
+- Milestone **mới** (M2, M3…) hoặc scope lớn → thường bắt đầu bằng **`/vp-evolve`**; ý tưởng rời rạc → có thể **`/vp-request`** trước rồi evolve.

package/docs/user/features/autonomous-mode.md

@@ -36,6 +36,13 @@ Mỗi task:
 - Nếu môi trường runtime có skills ngoài framework, workflow sẽ bỏ qua và ưu tiên skill ViePilot tương đương.
 - Chỉ khi bạn ghi rõ yêu cầu mở rộng (explicit opt-in), agent mới được phép dùng external skills.
 
+### Implementation routing (ENH-021)
+
+- **`/vp-auto`** là **lane mặc định** để **implement** mã shipping sau khi đã có **phase/task plan** trên ROADMAP.
+- **`/vp-request`** chỉ **ghi backlog** (`.viepilot/requests/*`, TRACKER) — **không** thay evolve + auto.
+- **`/vp-evolve`** chỉ **planning** (ROADMAP, thư mục phase, SPEC/tasks) — **không** implement thay `/vp-auto`.
+- **Chuỗi khuyến nghị:** `vp-request` → `vp-evolve` → **`vp-auto`**. Ngoại lệ: user **explicit** (*hotfix*, *sửa trong chat này*) — phải nêu rõ bypass.
+
 ### Doc-first gate (v0.8.2 / BUG-001)
 
 Workflow `autonomous.md` yêu cầu **ghi nhận kế hoạch trong file task** và **`PHASE-STATE` → `in_progress`** trước khi chỉnh sửa deliverable. Xem `workflows/autonomous.md` — *Pre-execution documentation gate*.

package/docs/user/features/ui-direction.md

@@ -76,9 +76,9 @@ Sau khi có prototype trong `.viepilot/ui-direction/{session-id}/`, bạn có th
 
 **Pipeline (3 phase)** — normative: `workflows/brainstorm.md` (mục *UI Direction — UX walkthrough & upgrade*):
 
-1. **End-user simulation** — AI đóng vai người dùng cuối: đi qua 3–8 scenario trên UI hiện tại, ghi pain (mơ hồ, thiếu feedback, quá nhiều bước, …) và mức độ.
-2. **Designer + research** — Đổi vai UX/UI designer: ưu tiên P0/P1/P2, **web search** khi cần benchmark/pattern, đề xuất cải tiến theo từng page/slug.
-3. **Cập nhật artifact** — Sửa HTML/CSS, và trong **`notes.md`** thêm section **`## UX walkthrough log`** (entry: ngày, scenario, pain, link research, tóm tắt thay đổi). Multi-page: vẫn giữ **hub** + **`## Pages inventory`** khớp `pages/*`.
+1. **End-user simulation** — AI đóng vai người dùng cuối: đi qua 3–8 scenario trên UI hiện tại, ghi pain (mơ hồ, thiếu feedback, quá nhiều bước, …) và mức độ. **Sau đó** chạy **content stress pass** (ENH-019): copy dài, list/grid đầy, số & validation dài, empty vs max, viewport hẹp/rộng — phát hiện tràn layout / ellipsis / scroll / overlap; ghi **Stress findings** (có thể mô tả giả định nếu prototype chưa có data thật). **ENH-020:** chọn **archetype** (landing, SaaS admin, form/wizard, reader, commerce/booking) và áp **≥2 recipe** từ bảng trong `workflows/brainstorm.md` cho mỗi archetype đã chọn.
+2. **Designer + research** — Đổi vai UX/UI designer: ưu tiên P0/P1/P2 (**P0** nếu stress nội dung làm hỏng luồng), **web search** khi cần benchmark/pattern, đề xuất cải tiến theo từng page/slug.
+3. **Cập nhật artifact** — Sửa HTML/CSS, và trong **`notes.md`** thêm section **`## UX walkthrough log`** (entry: ngày, scenario, pain, **Stress findings**, link research, tóm tắt thay đổi; tùy chọn placeholder dài để minh họa). Multi-page: vẫn giữ **hub** + **`## Pages inventory`** khớp `pages/*`.
 
 Gợi ý: kèm tên sản phẩm hoặc ngữ cảnh trong cùng tin nhắn (vd. “Trips — ưu tiên luồng đặt chuyến”).
 

package/docs/user/quick-start.md

@@ -31,6 +31,8 @@ Chọn profile cài đặt trong wizard (arrow keys + space + enter):
 - `cursor-agent`
 - `cursor-ide`
 
+Hướng dẫn đầy đủ cho **Claude Code** (symlink/copy skills sang `~/.claude/skills`, PATH, kiểm tra CLI): [ViePilot trên Claude Code](claude-code-setup.md).
+
 Non-interactive:
 ```bash
 npx viepilot install --target cursor-agent --yes

package/lib/viepilot-install.cjs

@@ -76,7 +76,7 @@ function listDirEntries(packageRoot, subdir) {
  *
  * @param {string} packageRoot - absolute viepilot package root
  * @param {Record<string, string | undefined>} [envSource] - defaults to process.env
- * @param {{ wantPathShim?: boolean, overrideHomedir?: string }} [opts] - `overrideHomedir`: absolute fake home for tests only. `wantPathShim`: append /usr/local/bin steps (skipped on Windows at apply time).
+ * @param {{ wantPathShim?: boolean, overrideHomedir?: string, installTargets?: string[] }} [opts] - `overrideHomedir`: absolute fake home for tests only. `wantPathShim`: append /usr/local/bin steps (skipped on Windows at apply time). `installTargets`: when it includes `claude-code`, also mirror `skills/vp-*` into `~/.claude/skills/` (Claude Code discovery).
  * @returns {{ version: number, packageRoot: string, env: ReturnType<typeof normalizeInstallEnv>, home: string, paths: object, steps: object[] }}
  */
 function buildInstallPlan(packageRoot, envSource = process.env, opts = {}) {
@@ -91,6 +91,10 @@ function buildInstallPlan(packageRoot, envSource = process.env, opts = {}) {
   const viepilotProfilesDir = path.join(viepilotUserDataDir, 'profiles');
   const viepilotProfileMapPath = path.join(viepilotUserDataDir, 'profile-map.md');
 
+  const installTargets = Array.isArray(opts.installTargets) ? opts.installTargets : [];
+  const installClaudeSkills = installTargets.includes('claude-code');
+  const claudeSkillsDir = installClaudeSkills ? path.join(home, '.claude', 'skills') : null;
+
   let wantPathShim = opts.wantPathShim;
   if (wantPathShim === undefined) {
     wantPathShim = env.autoYes && env.addPath;
@@ -133,6 +137,23 @@ function buildInstallPlan(packageRoot, envSource = process.env, opts = {}) {
     }
   }
 
+  if (installClaudeSkills && claudeSkillsDir) {
+    steps.push({ kind: 'mkdir', path: claudeSkillsDir });
+    for (const name of listSkillDirNames(root)) {
+      const src = path.join(root, 'skills', name);
+      const dest = path.join(claudeSkillsDir, name);
+      if (env.symlinkSkills) {
+        steps.push({
+          kind: 'symlink_dir',
+          target: dest,
+          sourceAbsolute: path.resolve(src),
+        });
+      } else {
+        steps.push({ kind: 'copy_dir', from: src, to: dest });
+      }
+    }
+  }
+
   for (const ent of listDirEntries(root, 'workflows')) {
     const src = path.join(root, 'workflows', ent.name);
     const dest = path.join(viepilotDir, 'workflows', ent.name);
@@ -223,6 +244,7 @@ function buildInstallPlan(packageRoot, envSource = process.env, opts = {}) {
     home,
     paths: {
       cursorSkillsDir,
+      claudeSkillsDir,
       viepilotDir,
       viepilotUserDataDir,
       viepilotProfilesDir,
@@ -241,8 +263,11 @@ function formatPlanLines(plan) {
   const lines = [];
   lines.push('ViePilot install plan (dry-run)');
   lines.push(`  packageRoot: ${plan.packageRoot}`);
-  lines.push(`  profile: ${plan.env.profile} (informational; same file set as install.sh)`);
-  lines.push(`  skills: ${plan.paths.cursorSkillsDir}`);
+  lines.push(`  profile: ${plan.env.profile} (informational; Cursor paths always; Claude Code skills when target includes claude-code)`);
+  lines.push(`  skills (Cursor): ${plan.paths.cursorSkillsDir}`);
+  if (plan.paths.claudeSkillsDir) {
+    lines.push(`  skills (Claude Code): ${plan.paths.claudeSkillsDir}`);
+  }
   lines.push(`  viepilot: ${plan.paths.viepilotDir}`);
   if (plan.paths.viepilotUserDataDir) {
     lines.push(`  userData (~/.viepilot): ${plan.paths.viepilotUserDataDir}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viepilot",
-  "version": "1.9.1",
+  "version": "1.9.4",
   "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-audit/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-audit
 description: "Audit state, docs drift, and stack best-practice compliance — works on any project"
-version: 0.3.0
+version: 0.3.1
 ---
 
 <cursor_skill_adapter>
@@ -22,6 +22,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- **Báo cáo / gap** — **không** fix shipping mặc định; route **`/vp-request`** → **`/vp-evolve`** → **`/vp-auto`** hoặc user explicit. Xem `workflows/request.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Audit ViePilot project state và documentation để phát hiện drift.

package/skills/vp-auto/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-auto
 description: "Autonomous execution loop với control points và recovery"
-version: 0.2.1
+version: 0.2.2
 ---
 
 <cursor_skill_adapter>
@@ -25,6 +25,12 @@ Use `Task(subagent_type="generalPurpose", ...)` for parallel execution.
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Primary implementation lane (ENH-021)
+
+- **`/vp-auto`** + `workflows/autonomous.md` là **lane mặc định** để **implement** work đã có **phase/task plan** (doc-first **BUG-001**, git persistence **BUG-003**). **`/vp-request`** và **`/vp-evolve`** **không** thay thế lane này trừ user **explicit** override.
+</implementation_routing_guard>
+
 
 <objective>
 Autonomous execution của project phases. Cho mỗi phase: analyze → plan → execute → verify → iterate.

package/skills/vp-brainstorm/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-brainstorm
 description: "Brainstorm session để thu thập ý tưởng, quyết định cho dự án"
-version: 0.6.0
+version: 0.6.3
 ---
 
 <cursor_skill_adapter>
@@ -22,6 +22,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- Trong phạm vi **session** (`docs/brainstorm/*`, `.viepilot/ui-direction/*`). **Không** implement thay **`/vp-auto`** cho `lib/`, `tests/`, thay đổi framework `workflows/`/`skills/` — sau brainstorm dùng **`/vp-crystallize`** / **`/vp-evolve`** → **`/vp-auto`** tùy giai đoạn. Override explicit — nêu rõ trong chat.
+</implementation_routing_guard>
+
 
 <objective>
 Thu thập ý tưởng, requirements, quyết định kiến trúc cho dự án thông qua interactive Q&A.
@@ -35,7 +41,7 @@ Hỗ trợ:
 - UI Direction mode: tạo/cập nhật HTML prototype + notes trong `.viepilot/ui-direction/{session-id}/` — hỗ trợ **multi-page** (`pages/{slug}.html` + hub `index.html`) và hook **`## Pages inventory`** trong `notes.md` khi có `pages/` (FEAT-007)
 - **Product horizon (ENH-014):** mọi session phải duy trì **`## Product horizon`** khi thảo luận capability/milestone — tier tags `(MVP)` / `(Post-MVP)` / `(Future)`, non-goals, deferred capabilities; hoặc ghi rõ **single-release / no deferred epics** (contract: `workflows/brainstorm.md`)
 - **Project meta intake (FEAT-009):** sau khi **scope locked**, **trước** `Completed` / `/end`, nếu thiếu `.viepilot/META.md` (`viepilot_profile_id`) — chạy Q&A **tuần tự** có proposal; đọc/ghi `~/.viepilot/profile-map.md`; tạo `~/.viepilot/profiles/<slug>.md` + binding theo **`docs/dev/global-profiles.md`**. Nếu đã có profile bound — skip intake mặc định (hỏi đổi nếu cần).
-- **UX walkthrough (FEAT-010):** trong **`--ui`**, lệnh **`/research-ui`** hoặc **`/research ui`** chạy 3 phase — mô phỏng **end-user** → **UX designer + web research** → chỉnh `index.html` / `pages/*.html` / `style.css` và ghi **`## UX walkthrough log`** trong `notes.md` (đồng bộ hub + **Pages inventory** khi multi-page).
+- **UX walkthrough (FEAT-010 + ENH-019 + ENH-020):** trong **`--ui`**, lệnh **`/research-ui`** hoặc **`/research ui`** chạy 3 phase — mô phỏng **end-user** (kèm **content stress pass** + **stress recipes theo archetype** → **Stress findings**) → **UX designer + web research** → chỉnh `index.html` / `pages/*.html` / `style.css` và ghi **`## UX walkthrough log`** trong `notes.md` (đồng bộ hub + **Pages inventory** khi multi-page).
 
 **Creates/Updates:**
 - `docs/brainstorm/session-{YYYY-MM-DD}.md`
@@ -85,7 +91,7 @@ Key steps:
 - [ ] Research can be executed inside the same brainstorm session
 - [ ] UI Direction artifacts created/updated when UI mode is active
 - [ ] Multi-page sessions: hub links + `## Pages inventory` stay in sync with `pages/*.html`
-- [ ] **FEAT-010**: `/research-ui` (khi `--ui`) chạy đủ 3 phase + **`## UX walkthrough log`** khi có chỉnh prototype
+- [ ] **FEAT-010 + ENH-019 + ENH-020**: `/research-ui` (khi `--ui`) chạy đủ 3 phase, gồm **content stress pass** + **archetype recipes** + **`## UX walkthrough log`** (có **Stress findings**) khi có chỉnh prototype
 - [ ] `## Product horizon` present với MVP / Post-MVP / Future (hoặc explicit single-release statement) khi scope được thảo luận
 - [ ] **FEAT-009**: intake hoàn tất hoặc binding đã có **hoặc** waiver có lý do trước Completed; session ghi **`## Project meta intake (FEAT-009)`**
 - [ ] Next steps suggested

package/skills/vp-crystallize/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-crystallize
 description: "Chuyển đổi brainstorm thành executable artifacts"
-version: 0.5.0
+version: 0.5.1
 ---
 
 <cursor_skill_adapter>
@@ -22,6 +22,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- Tạo **artifact** trong `.viepilot/` (và template copy) từ brainstorm — **không** thay **`/vp-auto`** để implement mã ứng dụng / framework shipping. Backlog feature code: **`/vp-evolve`** + **`/vp-auto`**. Xem `workflows/request.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Chuyển đổi brainstorm sessions thành structured artifacts để AI có thể autonomous execution.

package/skills/vp-debug/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-debug
 description: "Systematic debugging with persistent state tracking across sessions"
-version: 0.1.0
+version: 0.2.0
 ---
 
 <cursor_skill_adapter>
@@ -22,6 +22,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- **Điều tra + log** session; **không** merge fix shipping mặc định cho đến khi user **explicit** (*sửa luôn*, *hotfix*) hoặc route **`/vp-request` → `/vp-evolve` → `/vp-auto`**. Patch nhỏ chỉ để **reproduce** OK nếu user đồng ý. Xem `workflows/debug.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Systematic debugging với persistent state tracking. Giúp track vấn đề qua nhiều sessions.

package/skills/vp-docs/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-docs
 description: "Generate comprehensive documentation cho dự án"
-version: 0.2.0
+version: 0.2.1
 ---
 
 <cursor_skill_adapter>
@@ -22,6 +22,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- Skill này sửa **`docs/`**, index, README liên quan doc — **không** implement **`lib/`**, **`tests/`**, logic product mặc định; việc đó là **`/vp-auto`**. Override explicit. Xem `workflows/request.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Generate comprehensive documentation từ code và artifacts.

package/skills/vp-evolve/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-evolve
 description: "Nâng cấp, thêm features, hoặc bắt đầu milestone mới"
-version: 0.2.0
+version: 0.3.0
 ---
 
 <cursor_skill_adapter>
@@ -22,6 +22,14 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- Skill này chỉ **planning**: ROADMAP, phase dir, SPEC/tasks, TRACKER, ghi chú version/CHANGELOG khi workflow quy định — **không** implement mã shipping mặc định (`lib/`, `tests/`, `bin/`, sửa lớn `workflows/`/`skills/` ngoài plan artifact).
+- **Bước tiếp:** **`/vp-auto`**. Xem `workflows/evolve.md`.
+- **Ngoại lệ:** User **explicit** bypass — nêu rõ trong chat.
+</implementation_routing_guard>
+
 
 <objective>
 Nâng cấp hoặc mở rộng dự án sau khi hoàn thành milestone hoặc cần thêm features.

package/skills/vp-info/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-info
 description: "Hiển thị phiên bản ViePilot, npm latest, danh sách skills/workflows qua vp-tools"
-version: 0.1.0
+version: 0.1.1
 ---
 
 <cursor_skill_adapter>
@@ -19,6 +19,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- **Inventory / version info** — không implement shipping; implement qua **`/vp-auto`**. Xem `workflows/request.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Chạy **`vp-tools info`** để lấy metadata bundle ViePilot (không cần `.viepilot/` trong project đích).

package/skills/vp-pause/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-pause
 description: "Pause work với context preservation để resume sau"
-version: 0.1.0
+version: 0.1.1
 ---
 
 <cursor_skill_adapter>
@@ -22,6 +22,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- **Handoff state** — không implement shipping; resume với **`/vp-resume`** rồi **`/vp-auto`** theo plan. Xem `workflows/request.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Save complete work state để có thể resume từ bất kỳ context nào.

package/skills/vp-request/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-request
 description: "Tạo request mới: feature, bug fix, enhancement, hoặc brainstorm tiếp"
-version: 0.1.0
+version: 0.2.0
 ---
 
 <cursor_skill_adapter>
@@ -22,6 +22,15 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- Skill này chỉ **tạo request**, **backlog**, **triage** (`.viepilot/requests/*`, `TRACKER`, đôi khi gợi ý ROADMAP) — **không** implement mã shipping mặc định (`lib/`, `tests/`, `bin/`, `workflows/`, `skills/` của repo, v.v.).
+- **Sau request:** **`/vp-evolve`** (ROADMAP + phase + tasks + plan) → **`/vp-auto`** (thực thi). Xem `workflows/request.md`.
+- **Ngoại lệ:** User **explicit** (*hotfix ngay*, *sửa trong chat này*, *bypass planning*) — phải **nêu rõ** bypass trong chat.
+- **Không** đề xuất *“Start working now”* như implement trực tiếp trong thread này; thay bằng evolve → auto.
+</implementation_routing_guard>
+
 
 <objective>
 Tạo và quản lý requests cho dự án đang phát triển:
@@ -199,7 +208,7 @@ Options:
 1. Add to current milestone backlog
 2. Brainstorm in detail first
 3. Schedule for next milestone
-4. Start working now
+4. Plan then execute: `/vp-evolve` → `/vp-auto` (not direct implement here unless explicit override)
 ```
 
 **Tech Debt:**
@@ -242,7 +251,8 @@ Update `.viepilot/TRACKER.md`:
 
  Next:
  - /vp-request --list    View all requests
- - /vp-auto              Start working on it
+ - /vp-evolve            Plan phase/tasks + ROADMAP (before code)
+ - /vp-auto              Implement per task plan (after evolve)
  - /vp-request           Create another request
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```

package/skills/vp-resume/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-resume
 description: "Resume work từ previous session với full context restoration"
-version: 0.1.0
+version: 0.1.1
 ---
 
 <cursor_skill_adapter>
@@ -22,6 +22,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- **Khôi phục context** — không implement shipping mặc định; tiếp tục **`/vp-auto`** khi có task plan. Xem `workflows/request.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Restore complete project context và resume work seamlessly.

package/skills/vp-rollback/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-rollback
 description: "Rollback to any checkpoint safely with state preservation"
-version: 0.1.0
+version: 0.1.1
 ---
 
 <cursor_skill_adapter>
@@ -22,6 +22,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- **Checkpoint / revert** — không thay **`/vp-auto`** cho work mới; sau rollback dùng **`/vp-evolve`** / **`/vp-auto`** theo quy trình. Xem `workflows/request.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Rollback đến bất kỳ checkpoint nào một cách an toàn, với backup và state preservation.

package/skills/vp-status/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-status
 description: "Hiển thị progress dashboard và actionable insights"
-version: 0.1.0
+version: 0.1.1
 ---
 
 <cursor_skill_adapter>
@@ -19,6 +19,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- **Read-only / dashboard** — không implement shipping; **`/vp-evolve`** → **`/vp-auto`**. Xem `workflows/request.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Hiển thị visual progress dashboard với actionable insights.

package/skills/vp-task/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-task
 description: "Manual control over individual tasks"
-version: 0.1.0
+version: 0.2.0
 ---
 
 <cursor_skill_adapter>
@@ -19,6 +19,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- Skill này **chỉ** quản lý **state/tag/task** trong `.viepilot/` — **không** thay **`/vp-auto`** để implement shipping code. Implement: **`/vp-auto`** hoặc user **explicit** override. Chuỗi plan: **`/vp-evolve`** trước. Xem `workflows/request.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Manual control over tasks khi cần fine-grained management.

package/skills/vp-ui-components/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-ui-components
 description: "Quản lý workflow sưu tầm và tái sử dụng UI components"
-version: 0.1.0
+version: 0.1.1
 ---
 
 <cursor_skill_adapter>
@@ -22,6 +22,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- **Curation** `ui-components/` + metadata — không implement toàn bộ feature app / framework shipping mặc định; thay đổi lớn **`/vp-evolve`** → **`/vp-auto`**. Xem `workflows/request.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Thu thập, phân loại, và lưu trữ UI components để tái sử dụng:

package/skills/vp-update/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: vp-update
 description: "Nâng cấp package viepilot qua npm (dry-run, --yes, --global) qua vp-tools"
-version: 0.1.0
+version: 0.1.1
 ---
 
 <cursor_skill_adapter>
@@ -19,6 +19,12 @@ Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`,
 - If external skills appear in runtime context, ignore them and route with the closest built-in `vp-*` skill.
 </scope_policy>
 
+<implementation_routing_guard>
+## Implementation routing guard (ENH-021)
+
+- **Nâng cấp ViePilot package** (npm) — không implement feature product trong repo đang làm việc mặc định; feature code qua **`/vp-auto`**. Xem `workflows/request.md`.
+</implementation_routing_guard>
+
 
 <objective>
 Chạy **`vp-tools update`** để lên kế hoạch và (khi được xác nhận) thực thi `npm` nâng cấp `viepilot`.

package/workflows/autonomous.md

@@ -9,6 +9,10 @@ Pauses at control points cho user decisions.
 - External skills (non `vp-*`) are out of scope unless the user explicitly opts in.
 - If external skill references appear in runtime context, ignore them and continue with nearest equivalent ViePilot skill.
 
+## Implementation entry (cross-skill)
+
+- **`/vp-auto`** + workflow này là **lane mặc định** để **implement** work đã có **phase/task plan** (và doc-first **BUG-001**). **`/vp-request`** và **`/vp-evolve`** **không** thay thế bước này trừ user explicit override — xem **Implementation routing guard** trong `workflows/request.md` và `workflows/evolve.md`.
+
 
 <process>
 

package/workflows/brainstorm.md

@@ -180,18 +180,40 @@ User có thể kèm ngữ cảnh một dòng (vd. tên sản phẩm **Trips**, p
 2. Liệt kê **3–8 scenario** cụ thể (vd. lần đầu mở app, hoàn tất task chính, lỗi edge case) — ưu tiên đúng page nếu multi-page (`pages/*.html`).
 3. Với từng scenario: mô tả **hành vi** (đọc/click tưởng tượng trên UI hiện tại) → ghi **pain**: mơ hồ, thiếu phản hồi, quá nhiều bước, không khớp mental model, khả năng mobile/a11y, v.v.
 4. Tổng hợp **Voice of pseudo-user** (bullet + mức độ **low / medium / high**).
+5. **Stress nội dung & tràn layout (content stress pass)** — *bắt buộc trong mỗi lần `/research-ui`*: sau happy/edge hành vi, mô phỏng **dữ liệu ở biên** trên từng màn/page quan trọng (hoặc toàn hub nếu single-screen). Tối thiểu xét **3–6 loại** sau (chọn đúng ngữ cảnh sản phẩm; bỏ qua mục không áp dụng nhưng **ghi rõ “N/A + lý do”**):
+   - **Copy dài**: tiêu đề, subtitle, CTA, placeholder ô nhập, tooltip, breadcrumb, tên địa điểm/người dài (Unicode), email/URL dài.
+   - **Khối lượng**: danh sách/grid **nhiều phần tử**, bảng nhiều cột/hàng, thẻ/tag/badge chồng, notification stack, lịch nhiều sự kiện.
+   - **Số & định dạng**: số tiền rất lớn/nhỏ, đơn vị dài, múi giờ/ngôn ngữ (nếu product có).
+   - **Trạng thái lỗi / validation**: message lỗi dài, nhiều lỗi cùng lúc, inline + banner.
+   - **Empty vs cực đầy**: không dữ liệu vs max items; skeleton vs flash of long content.
+   - **Viewport**: cùng stress trên **hẹp** (mobile) và **rộng** (desktop) nếu prototype nhắm đa kích thước.
+
+   **Stress recipes theo archetype (ENH-020)** — sau khi áp checklist trên, **chốt 1–2 archetype** khớp sản phẩm (từ `notes.md` / HTML / user) và áp **ít nhất hai recipe** trong mỗi hàng đã chọn (có thể diễn đạt lại bằng ngôn ngữ session; **ghi rõ archetype** trong Stress findings):
+
+   | Archetype | Ưu tiên stress (recipe gợi ý) | Ghi chú |
+   |-----------|------------------------------|---------|
+   | **Landing / marketing** | Hero **headline** cực ngắn vs cực dài; **pricing** 3–5 tier + feature list dài mỗi tier; **FAQ** 10–20 mục (accordion/stack); **logo / social proof** hàng 8–15 logo + tên dài | Sticky CTA vs nội dung dài; section order khi overflow |
+   | **App shell / SaaS admin** | **Bảng** nhiều cột + nhiều hàng; **filter bar** chip + dropdown tràn; **sidebar** nhiều cấp; **notification** stack / toast chồng | Trạng thái dense vs comfortable; frozen column |
+   | **Form-heavy / wizard** | **Label + hint** dài; **multi-step** 5–7 bước + breadcrumb dài; **lỗi** inline từng field + banner tổng; khối **optional fields** mở rộng | Tab order, submit disabled ambiguity |
+   | **Content / reader** | **Bài** cực dài; **code block** rộng; **TOC** 20–40 heading; **related** 8–15 thẻ | Max line length, sidenote, mobile đọc |
+   | **Commerce / booking / marketplace** | **Kết quả tìm** grid dày; **giá** + đơn vị + discount dài; **ngày giờ** + múi giờ + DST; **đặt chỗ** (ghế, phòng) + availability text dài | Giỏ / summary trên mobile |
+
+   Hybrid (vd. marketing + app): **gộp recipe** từ các hàng liên quan; tránh lặp cùng một stress vô nghĩa trên hai màn giống nhau.
+
+   Với prototype chỉ có nội dung mẫu ngắn: **không bắt buộc** sửa file ngay ở Phase 1 — hãy **mô tả giả định** (“nếu title 120 ký tự thì…”) và UI sẽ **tràn, ellipsis, scroll, overlap, wrap xấu** thế nào.
+6. Tổng hợp thêm **Stress findings** (bullet: loại stress → quan sát → severity **low/medium/high**) và merge vào tổng kết Phase 1 cho Phase 2.
 
 #### Phase 2 — UX designer + research
 
-1. Đổi vai: **UX/UI designer** nhận feedback từ Phase 1.
-2. Map pain → **nguyên nhân thiết kế** (heuristic ngắn, pattern thiếu/sai); **ưu tiên hóa** P0 / P1 / P2.
+1. Đổi vai: **UX/UI designer** nhận feedback từ Phase 1 (**gồm cả Stress findings**).
+2. Map pain → **nguyên nhân thiết kế** (heuristic ngắn, pattern thiếu/sai); **ưu tiên hóa** P0 / P1 / P2 — **ưu tiên P0** nếu stress nội dung gây **mất thông tin, click sai, hoặc không dùng được** (overflow che CTA, text cắt nghĩa, bảng tràn không đọc được).
 3. **Web research**: khi cần benchmark hoặc pattern chuẩn ngành, chạy **1–3 truy vấn** (search) → tóm tắt nguồn, takeaway, trade-off.
 4. **Đề xuất cải tiến** cụ thể (thành phần UI, copy, layout, luồng) gắn với file/page (`slug` nếu multi-page).
 
 #### Phase 3 — Cập nhật artifact
 
 1. Sửa **`index.html`**, **`pages/*.html`**, **`style.css`** theo P0 → P1 trong phạm vi phiên (prototype direction, không ép production).
-2. Trong **`notes.md`**, thêm hoặc append section **`## UX walkthrough log`** (một entry mỗi lần chạy lệnh): ngày/scenario đã mô phỏng, pain chính, link research (nếu có), **diff ý định** (bullet), file đã đổi.
+2. Trong **`notes.md`**, thêm hoặc append section **`## UX walkthrough log`** (một entry mỗi lần chạy lệnh): ngày/scenario đã mô phỏng, pain chính, **Stress findings** (tóm tắt), link research (nếu có), **diff ý định** (bullet), file đã đổi. *Tùy chọn:* chỉnh HTML với **placeholder/copy dài** hoặc thêm **demo row** để minh họa stress đã bàn (ghi trong log).
 3. **Multi-page**: sau chỉnh sửa page, giữ **`## Pages inventory`** và **hub** khớp 100% file trong `pages/*` (hook FEAT-007).
 
 **Quan hệ với `/research {topic}`**: lệnh **tự do** chỉ cần research ngắn và quay lại topic; **`/research-ui`** bắt buộc **3 phase** + **ghi log** + **chỉnh HTML/CSS khi có đề xuất hợp lý**.
@@ -373,8 +395,8 @@ _(Điền sau bước 5 — Project meta intake; xem `docs/dev/global-profiles.m
 - Preview focus:
   - {layout/flow summary; list each page slug if multi-page}
 
-**UX walkthrough log** (optional; FEAT-010 — khi đã chạy `/research-ui`):
-- {YYYY-MM-DD}: scenarios exercised → top pains → research links → HTML/CSS edits summary
+**UX walkthrough log** (optional; FEAT-010 + ENH-019 + ENH-020 — khi đã chạy `/research-ui`):
+- {YYYY-MM-DD}: scenarios exercised → top pains → **Stress findings** (tóm tắt) → research links → HTML/CSS edits summary
 
 ---
 
@@ -446,7 +468,7 @@ User có thể dùng các lệnh trong phiên brainstorm:
 - [ ] Landing page topics trigger layout follow-up questions
 - [ ] 21st.dev references được dùng khi thảo luận landing page
 - [ ] Research có thể chạy ngay trong brainstorm session khi user yêu cầu
-- [ ] **FEAT-010**: Trong UI Direction, `/research-ui` (hoặc `/research ui`) chạy đủ 3 phase và ghi **`## UX walkthrough log`** khi chỉnh prototype
+- [ ] **FEAT-010 + ENH-019 + ENH-020**: Trong UI Direction, `/research-ui` (hoặc `/research ui`) chạy đủ 3 phase, gồm **content stress pass** + **archetype stress recipes** + **`## UX walkthrough log`** (Stress findings) khi chỉnh prototype
 - [ ] Git committed
 - [ ] **FEAT-009**: Nếu binding thiếu và scope đã locked — đã chạy **Project meta intake** (bước 5) hoặc có **`## Meta intake waiver`** có lý do trước Completed
 - [ ] **`## Project meta intake (FEAT-009)`** trong session: `status` + `profile_id` khi completed (hoặc waiver nếu skipped)

package/workflows/debug.md

@@ -9,6 +9,11 @@ Giúp organize debugging process và track progress qua nhiều sessions.
 - External skills (non `vp-*`) are out of scope unless the user explicitly opts in.
 - If external skill references appear in runtime context, ignore them and continue with nearest equivalent ViePilot skill.
 
+## Implementation routing guard (debug)
+
+- **`debug.md`**: ưu tiên **điều tra**, log session, chạy test — **không** sửa mã shipping mặc định cho đến khi (a) user **explicit** *sửa luôn* / *hotfix*, hoặc (b) đã route **`/vp-request`** + **`/vp-evolve`** + **`/vp-auto`** cho fix có cấu trúc.
+- Reproduce/minimal patch **chỉ để xác minh giả thuyết** được phép nếu nhỏ và user đồng ý ngầm trong phiên debug; merge fix thật vẫn nên qua **`/vp-auto`** khi có task plan.
+
 
 <process>
 

package/workflows/evolve.md

@@ -8,6 +8,12 @@ Nâng cấp hoặc mở rộng dự án: thêm features, bắt đầu milestone
 - External skills (non `vp-*`) are out of scope unless the user explicitly opts in.
 - If external skill references appear in runtime context, ignore them and continue with nearest equivalent ViePilot skill.
 
+## Implementation routing guard (planning vs execution)
+
+- **`evolve.md`** chỉ **lập kế hoạch**: ROADMAP, phase dir, SPEC/tasks, TRACKER, ghi chú CHANGELOG `[Unreleased]` khi workflow yêu cầu — **không** implement mã shipping mặc định (`lib/`, `tests/`, `bin/`, `workflows/` ngoài plan, v.v.).
+- **Bước tiếp:** **`/vp-auto`** sau khi task/phase có plan (doc-first **BUG-001**).
+- **Ngoại lệ:** User **explicit** bypass — phải nêu rõ trong chat.
+
 
 <process>
 

package/workflows/request.md

@@ -8,6 +8,12 @@ Tạo và quản lý requests cho dự án: bugs, features, enhancements, tech d
 - External skills (non `vp-*`) are out of scope unless the user explicitly opts in.
 - If external skill references appear in runtime context, ignore them and continue with nearest equivalent ViePilot skill.
 
+## Implementation routing guard (planning vs execution)
+
+- Workflow **`request.md`** chỉ **ghi nhận, backlog, triage** — **không** là lane mặc định để **implement** mã shipping (`lib/`, `tests/`, `bin/`, `src/` app, `workflows/`, `skills/` trong repo framework, v.v.).
+- **Chuỗi khuyến nghị sau khi có request:** `/vp-evolve` (ROADMAP, phase, SPEC/tasks, task plan; doc-first **BUG-001** khi áp dụng) → **`/vp-auto`** (thực thi + verify + git persistence **BUG-003**).
+- **Ngoại lệ:** User **explicit** (vd. *hotfix ngay*, *sửa file X trong chat này*, *bypass planning*) → được implement trực tiếp; assistant **phải nêu rõ** đang bypass guard.
+
 
 <process>
 
@@ -449,8 +455,8 @@ Current task: {task}
 
 If option 1:
 - Save current state (like /vp-pause)
-- Create emergency fix phase
-- Route to /vp-auto
+- Create emergency fix phase (minimal SPEC/tasks) **hoặc** user explicit hotfix
+- Route to **`/vp-auto`** — vẫn qua task plan ngắn khi có thể; **không** implement lặng trong thread `/vp-request` trừ user explicit bypass
 
 ### High Priority Feature
 ```
@@ -460,7 +466,7 @@ Options:
 1. Add to current milestone
 2. Brainstorm more first
 3. Schedule for next milestone
-4. Start working now
+4. **Plan then execute:** `/vp-evolve` → `/vp-auto` (không implement trực tiếp trong thread `/vp-request` trừ user explicit override)
 ```
 
 ### Regular Request
@@ -521,7 +527,8 @@ git push
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
  /vp-request --list    View all requests
- /vp-auto              Start working on requests
+ /vp-evolve            ROADMAP + phase/tasks (trước code)
+ /vp-auto              Implement theo task plan (sau evolve)
  /vp-request           Create another request
  /vp-status            See overall progress