viepilot 1.9.11 → 2.1.0

package/docs/user/features/architect-design-mode.md

@@ -0,0 +1,170 @@
+# Architect Design Mode (FEAT-011)
+
+`/vp-brainstorm --architect` bật chế độ brainstorm kiến trúc với live HTML generation — workspace trực quan để review, chỉnh sửa, và trình bày trước khi chạy `/vp-crystallize`.
+
+## Overview
+
+Architect Design Mode giải quyết gap: brainstorm architecture thông thường chỉ là text/markdown. Không có visualization trực quan → khó detect lỗi sớm, khó align với stakeholders.
+
+**Architect Mode tạo ra:**
+- HTML workspace với 7 sections (architecture, data-flow, decisions, tech-stack, tech-notes, feature-map)
+- Machine-readable `notes.md` với YAML schema (decisions, open_questions, tech_stack)
+- Mermaid.js diagrams tự động render trong browser
+- Incremental updates khi decisions thay đổi — không tái tạo toàn bộ workspace
+
+## Activation
+
+### Explicit flag
+```
+/vp-brainstorm --architect
+```
+Kích hoạt ngay khi bắt đầu phiên. ViePilot sẽ tạo workspace và bắt đầu generate HTML sau mỗi major decision.
+
+### Auto-activate heuristic
+Khi đang brainstorm thông thường, ViePilot theo dõi:
+- **Component/service mentions**: tên theo pattern `{capitalized} Service|API|Module|Layer|Server|Database`
+- **Stack mentions**: bất kỳ technology keyword nào (React, Node.js, PostgreSQL, Kafka, AWS, Docker, v.v.)
+
+Khi **≥3 components** hoặc **≥1 stack suggestion** → prompt:
+```
+🏗️ Tôi nhận thấy bạn đang thiết kế kiến trúc với nhiều components.
+Kích hoạt Architect Design Mode để tôi tạo HTML visualization không?
+1. Có — tạo workspace và generate initial HTML
+2. Không — tiếp tục text-only
+```
+
+## HTML Artifacts
+
+### Workspace layout
+
+```
+.viepilot/architect/{session-id}/
+  index.html         # Hub: sidebar nav → tất cả sections
+  architecture.html  # System diagram (Mermaid) + component table
+  data-flow.html     # Sequence/flow diagrams
+  decisions.html     # ADR log: Date | Decision | Options | Chosen | Rationale | Status
+  tech-stack.html    # Layer-by-layer: frontend, backend, infra, data, DevOps
+  tech-notes.html    # 3 columns: Assumptions | Risks | Open Questions
+  feature-map.html   # Features: layer, phase, MVP/Post-MVP/Future tags
+  style.css          # Shared: dark/light mode, .updated highlight, Mermaid container
+  notes.md           # Machine-readable YAML (xem Schema bên dưới)
+```
+
+### File descriptions
+
+| File | Nội dung | Diagram type |
+|------|----------|-------------|
+| `index.html` | Hub: card links tới 6 sections | — |
+| `architecture.html` | System components, service boundaries | `graph TD` hoặc `C4Context` |
+| `data-flow.html` | Request/event flows | `sequenceDiagram` hoặc `flowchart LR` |
+| `decisions.html` | ADR log với status badges | — |
+| `tech-stack.html` | Layer table + alternatives | — |
+| `tech-notes.html` | 3 cột: Assumptions, Risks, Open Questions | — |
+| `feature-map.html` | Feature list + mindmap | `mindmap` hoặc `quadrantChart` |
+
+### Opening the workspace
+Mở `index.html` trong browser để xem toàn bộ workspace. Các trang tự liên kết nhau qua sidebar nav.
+
+### Dark/light mode
+Mỗi trang có nút toggle dark/light. Mermaid diagrams tự điều chỉnh theme.
+
+## Dialogue Cadence
+
+Sau **mỗi major decision** trong Architect Mode:
+1. ViePilot cập nhật HTML section liên quan (chỉ section đó — không tái tạo toàn bộ)
+2. Thêm `class="updated"` + `data-updated="true"` → CSS highlight (yellow left border + "updated" badge)
+3. Update `notes.md` YAML (`updated` date + entry tương ứng)
+
+**Ví dụ luồng:**
+```
+User: "Chọn PostgreSQL cho database vì cần ACID compliance"
+→ AI update decisions.html (thêm row D001)
+→ AI update tech-stack.html (Database layer)
+→ AI update notes.md (decisions[] + tech_stack.database)
+→ Highlight các section đã thay đổi với .updated class
+```
+
+## `/review-arch` command
+
+Gõ `/review-arch` trong phiên Architect Mode để xem tóm tắt:
+
+```
+📊 Architecture Review
+
+Decisions so far:
+| ID   | Topic           | Chosen      | Status   |
+|------|-----------------|-------------|----------|
+| D001 | Database        | PostgreSQL  | decided  |
+| D002 | Caching layer   | Redis       | decided  |
+| D003 | Queue system    | —           | open     |
+
+Open Questions:
+- Q001: Caching layer Redis hay Memcached? (due: before crystallize)
+- Q002: Deploy ECS hay Kubernetes? (due: open)
+
+Tiếp tục brainstorm không?
+```
+
+## Crystallize Integration
+
+### Step 1D — Consume Architect Artifacts
+
+Khi chạy `/vp-crystallize`, Step 1D tự động đọc `.viepilot/architect/`:
+
+1. **decisions[]** → import vào `.viepilot/ARCHITECTURE.md` section `## Architecture Decisions (from Architect Mode)`
+2. **tech_stack{}** → dùng làm authoritative stack (override brainstorm text nếu conflict; khi có conflict → hỏi user)
+3. **open_questions[] status=open** → surface trước khi tiếp tục
+4. **feature-map.html** → cross-check với `## Product Horizon` trong brainstorm session
+
+**Soft suggestion** (không block) khi architect dir chưa có nhưng brainstorm có ≥5 services:
+```
+💡 Bạn muốn quay lại /vp-brainstorm --architect để tạo visualization trước không?
+1. Có — quay lại architect mode
+2. Không — tiếp tục crystallize với text-only brainstorm
+```
+
+## notes.md Schema
+
+File `notes.md` trong architect workspace là machine-readable YAML + Markdown:
+
+```yaml
+---
+session_id: {id}
+project: {name}
+created: {date}
+updated: {date}
+---
+## decisions
+- id: D001
+  topic: Database choice
+  options: [PostgreSQL, MongoDB, DynamoDB]
+  chosen: PostgreSQL
+  rationale: ACID compliance needed for financial data
+  status: decided  # decided | open | deferred
+
+## open_questions
+- id: Q001
+  question: Caching layer Redis hay Memcached?
+  context: High read traffic expected
+  due: before crystallize
+
+## tech_stack
+  frontend: React + TypeScript
+  backend: Node.js + Express
+  database: PostgreSQL
+  infra: AWS ECS + RDS
+  devops: GitHub Actions + Terraform
+```
+
+`crystallize` đọc file này trực tiếp — giữ schema nhất quán để import hoạt động đúng.
+
+## Tips & Best Practices
+
+1. **Bắt đầu với Architecture** — chốt component boundaries trước khi đi vào data-flow và decisions
+2. **Dùng `/review-arch` thường xuyên** — đặc biệt khi có nhiều open_questions; resolve trước khi crystallize
+3. **Decisions.html là lịch sử** — không xóa rows cũ; chỉ update `status` khi quyết định thay đổi
+4. **tech_stack{} là authoritative** — crystallize sẽ dùng đây làm stack chính; đảm bảo đúng trước khi `/vp-crystallize`
+5. **Mở index.html trong browser** — workspace được thiết kế để share với stakeholders trực tiếp từ file
+
+---
+_Cập nhật: 1.11.0 (FEAT-011 — Architect Design Mode)_

package/docs/user/features/hooks.md

@@ -0,0 +1,93 @@
+# ViePilot Hooks
+
+ViePilot integrates with Claude Code's hook system to automate actions after each AI response. Hooks are shell commands that fire at specific Claude Code events — no manual typing required.
+
+## Brainstorm Staleness Hook
+
+**Event**: `Stop` (fires after each Claude response)  
+**Script**: `~/.viepilot/hooks/brainstorm-staleness.cjs`  
+**Config**: `~/.claude/settings.json`
+
+### What it does
+
+After each exchange in a `vp-brainstorm` session, the hook automatically:
+
+1. Finds the most recently modified brainstorm session file (`notes.md` or `session-*.md`)
+2. Scans session content for keywords that match architect HTML pages
+3. Marks relevant architect items with `data-arch-stale="true"` — rendered as an amber "⚠ gap" badge in the browser
+4. Exits cleanly — if it fails or finds nothing, your session continues normally
+
+This is **flag-only** (Option A) — the hook does not rewrite architect HTML content, only marks items for review. Use `/sync-arch` to perform a full content sync.
+
+### Install
+
+Run once per machine:
+
+```bash
+node bin/vp-tools.cjs hooks install
+# or if installed globally:
+vp-tools hooks install
+```
+
+This writes the hook entry into `~/.claude/settings.json`. Running it again is safe (idempotent).
+
+To verify the install:
+
+```bash
+cat ~/.claude/settings.json | grep brainstorm-staleness
+```
+
+### Preview (scaffold)
+
+To see what will be written without installing:
+
+```bash
+node bin/vp-tools.cjs hooks scaffold
+```
+
+### Cursor users
+
+Cursor does not support `settings.json` hook events. Use `/sync-arch` manually within the brainstorm session to trigger architect delta sync (ENH-034).
+
+---
+
+## Adapter support
+
+Hook behavior is adapter-dependent:
+
+| Adapter | Config file | Programmatic events |
+|---------|-------------|---------------------|
+| `claude-code` | `~/.claude/settings.json` | Stop, PreToolUse, PostToolUse, UserPromptSubmit, … |
+| `cursor` | `.cursorrules` / MDC | None (no programmatic hook events) |
+
+Check your adapter's supported events:
+
+```bash
+node bin/vp-tools.cjs hooks scaffold --adapter claude-code
+```
+
+---
+
+## Adding custom hooks
+
+1. Create your hook script in `~/.viepilot/hooks/` (or anywhere accessible)
+2. Get the config format: `vp-tools hooks scaffold`
+3. Add your command to the relevant event array in `~/.claude/settings.json`
+
+Claude Code passes a JSON payload on stdin with `session_id`, `cwd`, `transcript_path`, and event-specific data. Your hook script should read from stdin and always exit 0.
+
+---
+
+## Troubleshooting
+
+**Hook not firing**  
+- Confirm `~/.claude/settings.json` has a `Stop` entry: `vp-tools hooks install` (idempotent)
+- Restart your Claude Code session after modifying `settings.json`
+
+**No stale badges appearing**  
+- The hook only marks stale if session content matches architect keyword triggers
+- Check that the brainstorm session notes file exists in `.viepilot/ui-direction/` or `docs/brainstorm/`
+- The architect HTML files must exist at `templates/architect/` (repo) or `~/.claude/viepilot/templates/architect/` (installed)
+
+**Hook error messages**  
+Hook errors appear on stderr (not in Claude's response). Check terminal output or Claude Code logs.

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

@@ -84,12 +84,85 @@ Gợi ý: kèm tên sản phẩm hoặc ngữ cảnh trong cùng tin nhắn (vd.
 
 **Khác `/research {chủ đề}`**: lệnh tự do chỉ cần research ngắn và quay lại topic; **`/research-ui`** bắt buộc 3 phase + log + chỉnh prototype khi phù hợp.
 
+## Background Extraction (ENH-026)
+
+Kể từ **1.10.0**, bạn **không cần** gọi `--ui` để thu thập ý tưởng UI — `/vp-brainstorm` tự động nhận diện tín hiệu UI trong mọi phiên.
+
+### Cách hoạt động
+
+| Bước | Mô tả |
+|------|-------|
+| **1. Silent detection** | AI theo dõi các keyword UI (`màu`, `layout`, `page`, `button`, `giao diện`, v.v.) trong suốt hội thoại — không interrupt |
+| **2. Accumulation** | Khi ≥3 keyword xuất hiện, ý tưởng UI được ghi vào buffer ngầm (`ui_idea_buffer`) |
+| **3. Surface** | Khi topic kết thúc, bạn gõ `/save`/`/review`, hoặc ≥5 signals tích luỹ → AI đề xuất lưu |
+
+### Ví dụ thực tế
+
+Bạn đang brainstorm về tính năng đặt vé và nhắc đến:
+
+> "tôi muốn **nút** màu **xanh**, **màn hình** danh sách vé cần rõ ràng, và **form** thanh toán đơn giản"
+
+→ 3 keywords (`nút`, `màn hình`, `form`) → threshold đạt → buffer bắt đầu tích luỹ im lặng.
+
+Khi topic kết thúc, AI hỏi:
+
+```
+💡 Tôi phát hiện một số ý tưởng UI trong phiên này:
+- Nút màu xanh (CTA)
+- Màn hình danh sách vé — yêu cầu layout rõ ràng
+- Form thanh toán — thiết kế đơn giản
+
+Bạn muốn:
+1. Lưu vào ui-direction/notes.md (background extraction)
+2. Lưu + kích hoạt UI Direction Mode để generate HTML direction
+3. Bỏ qua, tiếp tục brainstorm
+```
+
+### Khác biệt với `--ui` mode
+
+| | Background Extraction | UI Direction Mode (`--ui`) |
+|---|---|---|
+| **Kích hoạt** | Tự động (silent) | Chủ động (`--ui` hoặc chọn Option 2) |
+| **Artifact tạo ra** | `notes.md` (`## Background extracted ideas`) | `index.html`, `style.css`, `notes.md` |
+| **Gián đoạn brainstorm?** | Không (non-blocking) | Có thể (chuyển sang UI mode) |
+| **Dùng khi** | UI là phụ, main focus là domain/arch | UI là trọng tâm phiên |
+
+## Crystallize Integration
+
+`/vp-crystallize` đọc `notes.md` trước, sau đó `index.html`, `style.css`, và **từng** `pages/*.html` (nếu có) để lên kiến trúc UI đủ page.
+
+### Hard gate (ENH-026)
+
+Kể từ **1.10.0**, Step 1A áp dụng **hard gate** khi phát hiện UI scope trong brainstorm nhưng thiếu artifacts:
+
+```
+⚠️ UI Direction artifacts missing
+
+Phiên brainstorm cho thấy dự án có UI scope nhưng `.viepilot/ui-direction/` chưa có artifacts.
+
+1. Quay lại /vp-brainstorm --ui để tạo direction trước (khuyến nghị)
+2. Tiếp tục với assumptions — ghi vào ARCHITECTURE.md và proceed
+```
+
+**Option 1** (khuyến nghị): quay lại brainstorm và tạo direction trước — đảm bảo UI vision được capture đầy đủ.
+
+**Option 2** (bypass): crystallize tiếp tục nhưng ghi block `## UI Direction Assumptions` vào `.viepilot/ARCHITECTURE.md`:
+
+```markdown
+## UI Direction Assumptions
+> Auto-generated by crystallize (ENH-026 gate bypassed by user)
+- UI scope detected in brainstorm but no ui-direction artifacts present
+- Proceeding without visual direction; architecture decisions may need UI review later
+```
+
+Gate **chỉ kích hoạt** khi `ui_scope_detected = true` (≥3 UI signals trong brainstorm sessions). Dự án không có UI scope đi qua bình thường.
+
 ## Flow khuyến nghị
-1. `/vp-brainstorm --ui`
-2. Chọn legacy hoặc multi-page theo số màn hình.
+1. `/vp-brainstorm` (mọi phiên — background extraction hoạt động im lặng)
+2. Hoặc `/vp-brainstorm --ui` nếu UI là trọng tâm.
 3. (Optional) `/research-ui` để chạy walkthrough và nâng cấp prototype + `notes.md`.
 4. Mỗi thay đổi page → cập nhật HTML + **hub + `## Pages inventory`** trong cùng một lượt.
-5. `/vp-crystallize` đọc `notes.md` trước, sau đó `index.html`, `style.css`, và **từng** `pages/*.html` (nếu có) để lên kiến trúc UI đủ page.
+5. `/vp-crystallize` — Step 1A hard gate kiểm tra artifacts trước khi tiến hành.
 
 ## Kiểm tra nhanh (optional)
 
@@ -98,3 +171,6 @@ node scripts/verify-ui-direction-pages.cjs
 ```
 
 Script báo lỗi nếu có session có `pages/*.html` nhưng thiếu `## Pages inventory` hoặc thiếu tên file page trong `notes.md`.
+
+---
+_Cập nhật: 1.10.0 (ENH-026 — background extraction + crystallize hard gate)_

package/lib/adapters/claude-code.cjs

@@ -0,0 +1,42 @@
+'use strict';
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+module.exports = {
+  id: 'claude-code',
+  name: 'Claude Code',
+  // Paths (home-relative; resolved at install time)
+  skillsDir:   (home) => path.join(home, '.claude', 'skills'),
+  viepilotDir: (home) => path.join(home, '.claude', 'viepilot'),
+  // execution_context base for skill .md files
+  executionContextBase: '.claude/viepilot',
+  // Path rewrite rule: when mirroring skills, rewrite from → to in *.md files
+  pathRewrite: { from: '.cursor/viepilot', to: '.claude/viepilot' },
+  // Hooks configuration (Claude Code settings.json)
+  hooks: {
+    configFile: (home) => path.join(home, '.claude', 'settings.json'),
+    schema: 'claude-code',
+    supportedEvents: [
+      'SessionStart', 'SessionEnd', 'Stop', 'StopFailure',
+      'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'PostToolUseFailure',
+      'FileChanged', 'SubagentStart', 'SubagentStop',
+      'TaskCreated', 'TaskCompleted', 'PreCompact', 'PostCompact'
+    ]
+  },
+  // Files/dirs to install into viepilotDir
+  installSubdirs: [
+    'workflows',
+    path.join('templates', 'project'),
+    path.join('templates', 'phase'),
+    path.join('templates', 'architect'),
+    'bin',
+    'lib',
+    'ui-components'
+  ],
+  // Detection: is this platform available on the current machine?
+  isAvailable: (home) => {
+    const h = home || os.homedir();
+    return fs.existsSync(path.join(h, '.claude'));
+  }
+};

package/lib/adapters/cursor.cjs

@@ -0,0 +1,31 @@
+'use strict';
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+module.exports = {
+  id: 'cursor',          // maps to cursor-agent and cursor-ide (same paths)
+  name: 'Cursor',
+  skillsDir:   (home) => path.join(home, '.cursor', 'skills'),
+  viepilotDir: (home) => path.join(home, '.cursor', 'viepilot'),
+  executionContextBase: '.cursor/viepilot',
+  pathRewrite: null,     // no rewrite needed (source is cursor-first)
+  hooks: {
+    configFile: null,    // Cursor uses .cursorrules/MDC, not settings.json hooks
+    schema: 'cursor',
+    supportedEvents: []  // no programmatic hook events
+  },
+  installSubdirs: [
+    'workflows',
+    path.join('templates', 'project'),
+    path.join('templates', 'phase'),
+    path.join('templates', 'architect'),
+    'bin',
+    'lib',
+    'ui-components'
+  ],
+  isAvailable: (home) => {
+    const h = home || os.homedir();
+    return fs.existsSync(path.join(h, '.cursor'));
+  }
+};

package/lib/adapters/index.cjs

@@ -0,0 +1,26 @@
+'use strict';
+const adapters = {
+  'claude-code':  require('./claude-code.cjs'),
+  'cursor':       require('./cursor.cjs'),
+  'cursor-agent': require('./cursor.cjs'),  // alias
+  'cursor-ide':   require('./cursor.cjs'),  // alias
+};
+
+/**
+ * Get adapter by id. Throws if unknown.
+ * @param {string} id
+ */
+function getAdapter(id) {
+  const a = adapters[id];
+  if (!a) throw new Error(`Unknown adapter: "${id}". Known: ${Object.keys(adapters).join(', ')}`);
+  return a;
+}
+
+/**
+ * List unique adapters (deduplicated — aliases share the same object).
+ */
+function listAdapters() {
+  return [...new Set(Object.values(adapters))];
+}
+
+module.exports = { getAdapter, listAdapters, adapters };