viepilot 2.23.0 → 2.45.2

package/skills/vp-auto/SKILL.md

@@ -15,6 +15,43 @@ Output this banner as the **first** thing on every invocation — before questio
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 </greeting>
+<version_check>
+## Version Update Check (ENH-072)
+
+After displaying the greeting banner, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" check-update --silent
+```
+
+**If exit code = 1** (update available — new version printed to stdout):
+Display notice banner before any other output:
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ ✨ ViePilot {latest_version} available  (installed: {current})   │
+│    npm i -g viepilot && vp-tools install --target {adapter_id}   │
+└──────────────────────────────────────────────────────────────────┘
+```
+Replace `{latest_version}` with stdout from the command, `{current}` with the installed
+version, `{adapter_id}` with the active adapter (claude-code / cursor / antigravity / codex / copilot).
+
+**If exit code = 0 or command unavailable**: silent, continue.
+
+**Suppression rules:**
+- `--no-update-check` flag on skill invocation → skip this step entirely
+- `config.json` → `update.check: false` → skip this step entirely
+- Show at most once per session (`update_check_done` session guard)
+</version_check>
+<persona_context>
+## Persona Context Injection (ENH-073)
+At skill start, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona auto-switch
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona context
+```
+Inject the output as `## User Persona` context before any task execution.
+Silent if command unavailable or errors.
+</persona_context>
+
 
 <cursor_skill_adapter>
 ## A. Skill Invocation
@@ -267,3 +304,20 @@ Before the first interactive prompt, call `ToolSearch` with `query: "select:AskU
 - [ ] CHANGELOG updated for features/fixes
 - [ ] Clean stop with summary on pause/error
 </success_criteria>
+
+### Skill Context Execution (FEAT-020)
+
+At session start, vp-auto reads `PROJECT-CONTEXT.md ## Skills` (locked by `/vp-crystallize`
+Step 1E) and builds a `SKILL_CONTEXT_MAP`.
+
+During each task:
+- Required skills whose phases match the current task's phase are **silently** injected into the execution context
+- Best practices from matched skills appear as a silent checklist before implementation
+- Task output records `skills_applied: [id@version, ...]`
+
+**No prompts are shown** — all skill decisions are locked at crystallize time.
+`/vp-auto` is execution-only for skills.
+
+Install skills: `vp-tools install-skill <source>`
+Lock decisions: `/vp-crystallize` Step 1E
+Docs: `docs/user/features/skill-registry.md`

package/skills/vp-brainstorm/SKILL.md

@@ -15,6 +15,43 @@ Output this banner as the **first** thing on every invocation — before questio
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 </greeting>
+<version_check>
+## Version Update Check (ENH-072)
+
+After displaying the greeting banner, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" check-update --silent
+```
+
+**If exit code = 1** (update available — new version printed to stdout):
+Display notice banner before any other output:
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ ✨ ViePilot {latest_version} available  (installed: {current})   │
+│    npm i -g viepilot && vp-tools install --target {adapter_id}   │
+└──────────────────────────────────────────────────────────────────┘
+```
+Replace `{latest_version}` with stdout from the command, `{current}` with the installed
+version, `{adapter_id}` with the active adapter (claude-code / cursor / antigravity / codex / copilot).
+
+**If exit code = 0 or command unavailable**: silent, continue.
+
+**Suppression rules:**
+- `--no-update-check` flag on skill invocation → skip this step entirely
+- `config.json` → `update.check: false` → skip this step entirely
+- Show at most once per session (`update_check_done` session guard)
+</version_check>
+<persona_context>
+## Persona Context Injection (ENH-073)
+At skill start, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona auto-switch
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona context
+```
+Inject the output as `## User Persona` context before any task execution.
+Silent if command unavailable or errors.
+</persona_context>
+
 
 <cursor_skill_adapter>
 ## A. Skill Invocation
@@ -54,11 +91,18 @@ Supports:
 - **Phase assignment (ENH-030):** in every session, features/capabilities are assigned directly to Phase 1, Phase 2, Phase 3... — no MVP/Post-MVP/Future tiers. Session file stores assignments in the `## Phases` section.
 - **Project meta intake (FEAT-009):** after **scope locked**, **before** `Completed` / `/end`, if `.viepilot/META.md` (`viepilot_profile_id`) is missing — run **sequential** Q&A with proposals; read/write `~/.viepilot/profile-map.md`; create `~/.viepilot/profiles/<slug>.md` + binding per **`docs/dev/global-profiles.md`**. If a profile is already bound — skip intake by default (ask if change needed).
 - **UX walkthrough (FEAT-010 + ENH-019 + ENH-020):** in **`--ui`** mode, command **`/research-ui`** or **`/research ui`** runs 3 phases — simulates **end-user** (with **content stress pass** + **stress recipes by archetype** → **Stress findings**) → **UX designer + web research** → update `index.html` / `pages/*.html` / `style.css` and write **`## UX walkthrough log`** in `notes.md` (sync hub + **Pages inventory** for multi-page).
-- **Background UI extraction (ENH-026):** automatically detects UI signal keywords in every brainstorm session (no `--ui` flag required); silent accumulation buffer; surfaces for confirmation when topic ends, `/save`, or ≥5 signals — does not interrupt the main conversation.
+- **Background UI extraction (ENH-026 + ENH-060):** automatically detects UI signal keywords in every brainstorm session (no `--ui` flag required). **Auto-suggests itself (ENH-060):** if the initial message contains ≥1 UI keyword, shows a proactive 🎨 banner immediately — mirrors Architect Design Mode's 🏗️ proactive activation. Accumulation starts at ≥1 signal (was ≥3); surfaces for confirmation when topic ends, `/save`, or **≥2 unique signals** accumulated (was ≥5) — does not interrupt the main conversation.
+- **Idea → Architecture breakdown loop (ENH-061):** structured 8-step flow from free idea collection → scope lock → **Feature → Coverage mapping** (maps each Phase 1 feature to an architect page + UI screen, outputs `## Coverage` matrix in `notes.md`) → Architect Design → **`arch_to_ui_sync`** reverse sync (surfaces UI implications of architectural decisions; `/sync-ui` command) → UI Direction → **completeness gate** (CHECK 4: warns if any Phase 1 feature has no coverage in either mode, non-blocking). See `Recommended Breakdown Ordering` section in `workflows/brainstorm.md`.
+- **Unified workspace mode selection (BUG-018):** after scope lock, before any design workspace is created, an AUQ prompt offers: Both / Architect only / UI Direction only / Neither. Architect auto-activate heuristic is deferred until after this selection; suppressed if user selects "Neither" or "UI Direction only".
+- **Admin & Governance coverage (ENH-063):** Topic 6 in brainstorm template; proactive 🔐 heuristic fires on admin/governance keywords; admin coverage gate before /save for multi-user/SaaS/compliance projects; `admin.html` added to Architect workspace when applicable; `notes.md ## admin` YAML exported via crystallize.
+- **Content Management coverage (ENH-065):** Topic 7 in brainstorm template; proactive 🗂️ heuristic fires on content-type/media/SEO keywords; content coverage gate before /save for projects with content layer; `content.html` added to Architect workspace; `notes.md ## content` YAML exported via crystallize.
+- **Admin Entity Management coverage (ENH-068):** Topic 7 in brainstorm template; proactive 🗄️ heuristic fires on CRUD/entity/admin panel keywords; entity management coverage gate before /save for projects with DB entities (cross-references ERD); `entity-mgmt.html` added to Architect workspace; `notes.md ## entity_mgmt` YAML exported via crystallize.
+- **User Data Management coverage (ENH-066):** Topic 9 in brainstorm template; proactive 👤 heuristic fires on user-account/privacy/auth keywords; user data coverage gate before /save for B2C/SaaS/GDPR projects; `user-data.html` added to Architect workspace; `notes.md ## user_data` YAML exported via crystallize.
 - **Architect Design Mode (FEAT-011):** `/vp-brainstorm --architect` or auto-activate when ≥3 components/services detected; generate HTML workspace (architecture, data-flow, decisions, tech-stack, tech-notes, feature-map) with Mermaid diagrams; incremental update per decision; `/review-arch` command; machine-readable `notes.md` YAML schema.
 - **ERD page (ENH-027):** Architect workspace includes `erd.html` — Mermaid `erDiagram`, entity list table, relationship summary; triggered by DB/entity/table/relationship keywords; notes.md `## erd` YAML section exported to ARCHITECTURE.md `## Database Schema` via crystallize Step 1D.
 - **User Use Cases page (ENH-028):** Architect workspace includes `user-use-cases.html` — actor/use-case diagram (Mermaid flowchart), use case table; triggered by user/role/actor/story keywords; notes.md `## use_cases` YAML section exported to PROJECT-CONTEXT.md `## User Stories & Use Cases` via crystallize Step 1D.
 - **C4Context/Sequence/Deployment/APIs pages (ENH-029, 12-page workspace):** Architect workspace expanded to 12 pages — `sequence-diagram.html` (per-scenario sequenceDiagram), `deployment.html` (infra graph + environments + CI/CD pipeline), `apis.html` (endpoint tables with HTTP method badges); page boundary rules table; trigger keywords for sequence/deploy/API; notes.md `## apis` YAML section; deployment+APIs exported to ARCHITECTURE.md via crystallize Step 1D (sequence excluded — scenario docs are not architecture artifacts).
+- **Embedded Domain Mode (ENH-071):** Activated when ≥2 embedded trigger keywords detected (MCU families: STM32/ESP32/nRF52/AVR/RISC-V/RP2040; concepts: firmware/bare-metal/GPIO/interrupt/HAL/bootloader/RTOS) OR `--domain embedded` flag. Adds 6 Architect workspace pages for embedded hardware artifacts, injects domain-specific topic probes, suppresses web-UI false-positives for hardware display keywords, and offers a firmware phase ordering template. crystallize exports 8 YAML sections to ARCHITECTURE.md hardware sections.
 
 **Creates/Updates:**
 - `docs/brainstorm/session-{YYYY-MM-DD}.md`
@@ -70,6 +114,16 @@ Supports:
 - `BRAINSTORM_LANG` is used for brainstorm file storage and generated content.
 - User session language takes precedence over config if different.
 - Configure via: `vp-tools config set language.document vi`
+
+**Workflow version stamps (ENH-067):**
+- Session files record `workflow_version` (current ViePilot semver) at create/save time.
+- `upgrade_supplement_version` stamped after gap-detection supplement completes (idempotency guard).
+
+**Upgrade gap detection (ENH-067):**
+- On `--continue`, compares session `workflow_version` vs. current Topics Template to detect missing topics.
+- Proactive 🔄 upgrade banner (AUQ) lists missing topics; user can discuss inline, defer to /save, or skip.
+- Inline supplement appended as `## Upgrade supplement (vX → vY)` section; `upgrade_supplement_version` stamped for idempotency.
+- After supplement: suggests `/vp-crystallize --upgrade` to patch project artifacts.
 </objective>
 
 <execution_context>
@@ -83,9 +137,53 @@ Optional flags:
 - `--list` : List all sessions
 - `--landing` : Prioritize the Landing Page layout discovery flow
 - `--research` : Enable proactive research suggestions during the session
-- `--ui` : Enable UI Direction mode (live HTML/CSS direction artifacts)
+- `--ui` : Enable UI Direction mode (live HTML/CSS direction artifacts + auto-generates `design.md` when design keywords present — ENH-076)
+- `--domain embedded` : Force-activate Embedded Domain Mode (hardware topology, RTOS, pin map, memory layout, protocol matrix, power budget pages + topic probes)
 </context>
 
+### Embedded Domain Mode (ENH-071)
+
+**Activation**: Automatically when ≥2 embedded keywords detected, or via `--domain embedded` flag. One-time `🔌 Embedded Domain Mode activated` banner shown.
+
+**Topic probes injected when `embedded_domain: true`:**
+- **MCU/Toolchain** (Gap 2): MCU family, toolchain (GCC-ARM/Keil/IAR), build system (CMake/PlatformIO/West), debug interface (SWD/JTAG), flasher, SDK/HAL
+- **RTOS/Scheduling** (Gap 3): bare-metal vs RTOS choice, task list, ISR table, resource protection strategy
+- **Power Budget** (Gap 7): supply type, sleep modes, current targets, battery life (triggered by battery/power/sleep keywords)
+- **Safety/Compliance** (Gap 10): IEC 61508/ISO 26262/DO-178C, watchdog, fault handlers (triggered by safety/SIL/ASIL keywords)
+- **Firmware Phase Template** (Gap 9): Board Bring-Up → Drivers → RTOS → Middleware → Application → Integration Test → OTA
+
+**6 new Architect workspace pages** (in `.viepilot/architect/{session-id}/`):
+
+| Page | Trigger | Content |
+|------|---------|---------|
+| `hw-topology.html` | Always in embedded domain | MCU block diagram (Mermaid graph TD) + component/bus/power-rail tables |
+| `pin-map.html` | GPIO/pin/pinout keywords | Pin assignment table (Pin# / GPIO / Function / Peripheral / Direction / Pull / Voltage) |
+| `memory-layout.html` | Flash/RAM/linker/bootloader/OTA keywords | Flash + RAM regions tables + linker constraint notes |
+| `protocol-matrix.html` | CAN/I2C/SPI/BLE/LoRa/MQTT/Modbus keywords | Bus protocol + wireless connectivity tables (distinct from `apis.html` HTTP REST) |
+| `rtos-scheduler.html` | RTOS/FreeRTOS/task/ISR/scheduler keywords | Task priority table + ISR table + state diagram (≤5 tasks) |
+| `power-budget.html` | Battery/sleep/power/µA/mAh keywords | Power modes table + battery life estimate |
+
+Pages linked in `index.html` under an **Embedded** nav section.
+
+**UI Direction false-positive suppression** (Gap 6):
+- `LCD` / `OLED` / `TFT` / `display` / `screen` in hardware context → routed to `hw-topology` peripherals, NOT UI Direction buffer
+- Hardware context confirmed by: GPIO / SPI / I2C / driver / framebuffer / ILI9341 / SSD1306 / LVGL / u8g2 keywords
+- `🎨 UI Direction Mode?` banner suppressed when all display signals have hardware context
+
+**notes.md YAML sections written:** `## hw_topology`, `## pin_map`, `## memory_layout`, `## protocols`, `## rtos_config`, `## embedded_toolchain`, `## power_budget`, `## safety_config`
+
+**crystallize Step 1D item 13 exports:**
+- `## Hardware Architecture` (from `hw_topology`)
+- `## Hardware Interface` (from `pin_map`)
+- `## Memory Map` (from `memory_layout`)
+- `## Communication Protocols` (from `protocols`) — distinct from `## APIs`
+- `## RTOS & Task Model` (from `rtos_config`)
+- `## Toolchain & Build System` (from `embedded_toolchain`)
+- `## Power Budget` (from `power_budget`)
+- `## Safety & Reliability` (from `safety_config`)
+- `## Embedded Domain: true` + MCU family written to `PROJECT-CONTEXT.md`
+- UI Coverage Gate skipped; Hardware Coverage Check (driver-task completeness, non-blocking) applied instead
+
 <process>
 Execute workflow from `@$HOME/{envToolDir}/workflows/brainstorm.md`
 
@@ -117,6 +215,7 @@ Key steps:
 - [ ] **FEAT-010 + ENH-019 + ENH-020**: `/research-ui` (when `--ui`) runs all 3 phases, including **content stress pass** + **archetype recipes** + **`## UX walkthrough log`** (with **Stress findings**) when prototype is updated
 - [ ] `## Phases` present with Phase 1 having real content when scope is discussed
 - [ ] **FEAT-009**: intake completed, binding already present, **or** waiver with reason before Completed; session records **`## Project meta intake (FEAT-009)`**
+- [ ] **ENH-076**: `design.md` generated in session directory when UI mode active and ≥2 design keywords present; `notes.md ## design_tokens` populated
 - [ ] Next steps suggested
 </success_criteria>
 
@@ -144,3 +243,26 @@ plain-text numbered list prompts — no configuration required.
 **Prompts using AskUserQuestion in this skill:**
 - Session intent (continue / review / new — Step 2)
 - Landing page layout selection (Step 4 — Layout A/B/C/D)
+- Mid-session structured choices (≥2 discrete named options — BUG-022): topic direction,
+  section priority, angle selection, and any numbered decision with enumerable options
+- Session-transition/next-steps prompt (session-flow choices: save/crystallize, update UI
+  artifacts, continue discussing — BUG-023)
+
+
+### Skill Registry Integration (FEAT-020)
+
+When UI Direction Mode is active, vp-brainstorm automatically:
+1. Loads `~/.viepilot/skill-registry.json` (written by `vp-tools scan-skills`)
+2. Matches installed skills by `capabilities` to current UI signals
+3. **Silently** applies matched skill `best_practices` to HTML generation
+4. Records matched skills in `notes.md ## skills_used`
+
+**No prompt is shown** — integration is transparent. Skills with relevant
+capabilities (e.g., `ui-generation`, `component-design`, `responsive-layout`)
+are detected automatically.
+
+Skill decisions are **locked at crystallize time** (see `/vp-crystallize`).
+`/vp-auto` executes with those locked decisions — no re-asking.
+
+Install skills via `vp-tools install-skill <source>`.
+See: `docs/user/features/skill-registry.md`

package/skills/vp-crystallize/SKILL.md

@@ -15,6 +15,43 @@ Output this banner as the **first** thing on every invocation — before questio
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 </greeting>
+<version_check>
+## Version Update Check (ENH-072)
+
+After displaying the greeting banner, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" check-update --silent
+```
+
+**If exit code = 1** (update available — new version printed to stdout):
+Display notice banner before any other output:
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ ✨ ViePilot {latest_version} available  (installed: {current})   │
+│    npm i -g viepilot && vp-tools install --target {adapter_id}   │
+└──────────────────────────────────────────────────────────────────┘
+```
+Replace `{latest_version}` with stdout from the command, `{current}` with the installed
+version, `{adapter_id}` with the active adapter (claude-code / cursor / antigravity / codex / copilot).
+
+**If exit code = 0 or command unavailable**: silent, continue.
+
+**Suppression rules:**
+- `--no-update-check` flag on skill invocation → skip this step entirely
+- `config.json` → `update.check: false` → skip this step entirely
+- Show at most once per session (`update_check_done` session guard)
+</version_check>
+<persona_context>
+## Persona Context Injection (ENH-073)
+At skill start, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona auto-switch
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona context
+```
+Inject the output as `## User Persona` context before any task execution.
+Silent if command unavailable or errors.
+</persona_context>
+
 
 <cursor_skill_adapter>
 ## A. Skill Invocation
@@ -84,6 +121,35 @@ Convert brainstorm sessions into structured artifacts for autonomous AI executio
 **Architect artifacts consumption (FEAT-011):**
 - Step 1D reads `.viepilot/architect/{session}/notes.md` YAML — imports `decisions[]` → ARCHITECTURE.md, uses `tech_stack{}` as authoritative stack (conflict → ask user), surfaces `open_questions[]` with `status: open`. Soft suggestion (not hard block) when architect dir missing but ≥5 services detected.
 
+**Admin & Governance Export (ENH-063):**
+- Step 1D item 7: if `admin.html` or `notes.md ## admin` exists in architect workspace → append `## Admin & Governance` table to `.viepilot/PROJECT-CONTEXT.md` (columns: Capability | Required | Phase | Notes) + Admin Personas table. Records `admin_imported` and `admin_capabilities_count` in working notes.
+
+**Content Management Export (ENH-065):**
+- Step 1D item 8: if `content.html` or `notes.md ## content` exists in architect workspace → append `## Content Management` table to `.viepilot/PROJECT-CONTEXT.md` (columns: Content Type | Created By | Lifecycle | Key Fields | Phase) + Media/Storage and Localization sub-tables. Records `content_imported` and `content_types_count` in working notes.
+
+**Admin Entity Management Export (ENH-068):**
+- Step 1D item 10: if `entity-mgmt.html` or `notes.md ## entity_mgmt` exists in architect workspace → append `## Admin Entity Management` table to `.viepilot/PROJECT-CONTEXT.md` (columns: Entity | CRUD Ops | Soft Delete | Bulk Actions | Audit Trail | Scope) + Import/Export sub-table. Records `entity_mgmt_imported` and `entity_mgmt_entity_count` in working notes.
+
+**User Data Management Export (ENH-066):**
+- Step 1D item 9: if `user-data.html` or `notes.md ## user_data` exists in architect workspace → append `## User Data Management` table to `.viepilot/PROJECT-CONTEXT.md` (columns: Capability | Supported | Notes) with 8 capability rows (profile editing, notification prefs, privacy settings, data export, right to erasure, connected accounts, session management, 2FA). Records `user_data_imported` and `user_data_capabilities_count` in working notes.
+
+**Crystallize version stamps (ENH-067):**
+- Generated `PROJECT-CONTEXT.md` includes `<!-- crystallize_version: {semver} -->` as its first line.
+- `HANDOFF.json` records `crystallize_version` and `crystallized_at` fields.
+- Used by `--upgrade` re-scan mode to compute delta on future runs.
+
+**Upgrade re-scan mode (`--upgrade`) (ENH-067):**
+- Detects `crystallize_version` delta; lists missing PROJECT-CONTEXT.md sections.
+- **Patch mode:** appends only missing sections non-destructively; re-stamps `crystallize_version`.
+- **Full re-generate:** backs up `.viepilot/` → regenerates all artifacts using existing sessions.
+- Integrates brainstorm `## Upgrade supplement` sections when present.
+
+**Mandatory Workspace Read Gates (ENH-064):**
+- **Architect workspace (Step 1D):** if `.viepilot/architect/` exists → reads ALL 12 pages front-to-back before any extraction. `architect_read_complete: true` required. Missing `notes.md` → STOP.
+- **UI Direction workspace (Step 1A strengthened):** if `.viepilot/ui-direction/` exists → reads ALL pages/*.html + ALL notes.md sections. `ui_direction_read_complete: true` required. Pages inventory mismatch → STOP.
+- **Cross-reference gate (Step 1F):** when both workspaces present → validates coverage matrix; warns on Phase 1 features with no architect OR UI coverage.
+- **No silent skip**: any workspace that exists MUST be fully read. Partial reads are not allowed.
+
 **Language configuration (ENH-032):**
 - Step 0-A reads `~/.viepilot/config.json` → `DOCUMENT_LANG` (default: `en`) and `COMMUNICATION_LANG` (default: `en`).
 - `DOCUMENT_LANG` controls content language for all generated files (ROADMAP, TRACKER, ARCHITECTURE, etc.).
@@ -303,3 +369,19 @@ plain-text numbered list prompts — no configuration required.
 - Polyrepo related-repos prompt (Step 0-B)
 - UI direction gate choice (Step 1A)
 - Architect mode suggestion (Step 1D)
+
+### Step 1E — Skill Decision Gate (FEAT-020)
+
+After scope lock, before SPEC generation, crystallize checks for `## skills_used`
+in the brainstorm session's notes.md:
+
+- **No skills_used found** → step silently skipped
+- **Skills found** → AUQ presents each skill (required / optional / exclude)
+- **Decision written** to `PROJECT-CONTEXT.md ## Skills`
+
+The `## Skills` decision is **final** — `/vp-auto` reads it at execution time
+and injects skill best practices per task without re-prompting.
+
+Install skills: `vp-tools install-skill <source>`
+Registry: `vp-tools scan-skills`
+Docs: `docs/user/features/skill-registry.md`

package/skills/vp-debug/SKILL.md

@@ -15,6 +15,43 @@ Output this banner as the **first** thing on every invocation — before questio
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 </greeting>
+<version_check>
+## Version Update Check (ENH-072)
+
+After displaying the greeting banner, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" check-update --silent
+```
+
+**If exit code = 1** (update available — new version printed to stdout):
+Display notice banner before any other output:
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ ✨ ViePilot {latest_version} available  (installed: {current})   │
+│    npm i -g viepilot && vp-tools install --target {adapter_id}   │
+└──────────────────────────────────────────────────────────────────┘
+```
+Replace `{latest_version}` with stdout from the command, `{current}` with the installed
+version, `{adapter_id}` with the active adapter (claude-code / cursor / antigravity / codex / copilot).
+
+**If exit code = 0 or command unavailable**: silent, continue.
+
+**Suppression rules:**
+- `--no-update-check` flag on skill invocation → skip this step entirely
+- `config.json` → `update.check: false` → skip this step entirely
+- Show at most once per session (`update_check_done` session guard)
+</version_check>
+<persona_context>
+## Persona Context Injection (ENH-073)
+At skill start, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona auto-switch
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona context
+```
+Inject the output as `## User Persona` context before any task execution.
+Silent if command unavailable or errors.
+</persona_context>
+
 
 <cursor_skill_adapter>
 ## A. Skill Invocation

package/skills/vp-design/SKILL.md

@@ -0,0 +1,219 @@
+<greeting>
+## Invocation Banner
+
+Output this banner as the **first** thing on every invocation — before questions, work, or any other output:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ VIEPILOT ► VP-DESIGN  v1.0.0 (fw 2.45.0)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+</greeting>
+<version_check>
+## Version Update Check (ENH-072)
+
+After displaying the greeting banner, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" check-update --silent
+```
+
+**If exit code = 1** (update available — new version printed to stdout):
+Display notice banner before any other output:
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ ✨ ViePilot {latest_version} available  (installed: {current})   │
+│    npm i -g viepilot && vp-tools install --target {adapter_id}   │
+└──────────────────────────────────────────────────────────────────┘
+```
+Replace `{latest_version}` with stdout from the command, `{current}` with the installed
+version, `{adapter_id}` with the active adapter (claude-code / cursor / antigravity / codex / copilot).
+
+**If exit code = 0 or command unavailable**: silent, continue.
+
+**Suppression rules:**
+- `--no-update-check` flag on skill invocation → skip this step entirely
+- `config.json` → `update.check: false` → skip this step entirely
+- Show at most once per session (`update_check_done` session guard)
+</version_check>
+<persona_context>
+## Persona Context Injection (ENH-073)
+At skill start, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona auto-switch
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona context
+```
+Inject the output as `## User Persona` context before any task execution.
+Silent if command unavailable or errors.
+</persona_context>
+
+<cursor_skill_adapter>
+## A. Skill Invocation
+- Skill is triggered when user mentions `vp-design`, `/vp-design`, "design system", "design.md", "sync tokens", "audit design"
+- Treat all user text after the skill mention as `{{VP_ARGS}}`
+
+## B. User Prompting
+Prompt user conversationally with numbered list options at control points.
+
+## C. Tool Usage
+Use Cursor tools: `Shell`, `ReadFile`, `Glob`, `rg`, `ApplyPatch`, `WebSearch`, `WebFetch`, `Subagent`
+</cursor_skill_adapter>
+
+<scope_policy>
+## ViePilot Namespace Guard (BUG-004)
+- Default mode: only use and reference `vp-*` skills in ViePilot workflows.
+- External skills (`non vp-*`) are out of framework scope unless user explicitly opts in.
+- 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)
+
+- This skill manages **design system files** (`design.md`, stylesheet token sync, compliance audit).
+- Does **not** implement application features or replace **`/vp-auto`** for shipping code.
+- After creating/updating `design.md`, run **`/vp-design --sync`** to apply tokens, then continue with **`/vp-auto`** for feature work.
+</implementation_routing_guard>
+
+<objective>
+Manage Design.MD design system files for the project (ENH-076).
+
+Implements the [Design.MD v1 spec](https://github.com/google-labs-code/design.md) —
+a Google Labs open standard (Apache 2.0) for describing visual design systems to AI coding agents.
+
+**Commands:**
+- `--init` : Create `design.md` from scratch via Q&A, or import from awesome-design-md community library (55+ brand examples)
+- `--sync` : Sync design.md tokens → Tailwind config / CSS custom properties / SCSS variables
+- `--audit` : Scan project HTML/CSS files for compliance; report deviations (❌ / ⚠️ / ✅)
+- `--import [brand]` : Fetch community template from awesome-design-md (Linear, Notion, Stripe, Vercel, Figma...)
+
+**Creates/Updates:**
+- `design.md` (project root)
+- `tailwind.config.js` / `style.css` / `_variables.scss` (via `--sync`)
+
+**Reads:**
+- `design.md` (project root or session directory)
+- HTML/CSS/SCSS files (via `--audit`)
+
+**After:** `design.md` is ready for `/vp-crystallize` (Step 1D.14 export) and
+`/vp-auto` (Preflight 5.5 token injection into UI tasks)
+</objective>
+
+<execution_context>
+@$HOME/.claude/viepilot/workflows/design.md
+</execution_context>
+
+<context>
+**Commands:**
+- `--init` : Create new design.md (Q&A or awesome-design-md import)
+- `--sync` : Sync tokens to project stylesheets (auto-detects Tailwind / CSS vars / SCSS)
+- `--audit` : Compliance report — scan all HTML/CSS vs design.md spec
+- `--import [brand]` : Import community template (omit brand for interactive catalog picker)
+
+**Examples:**
+```bash
+/vp-design --init                    # Q&A flow to create design.md
+/vp-design --init --import           # Import from awesome-design-md catalog
+/vp-design --sync                    # Sync tokens → detected stylesheet target
+/vp-design --audit                   # Full compliance report
+/vp-design --import linear           # Import Linear design system directly
+/vp-design --import notion           # Import Notion design system
+```
+</context>
+
+<process>
+Execute workflow from `@$HOME/.claude/viepilot/workflows/design.md`
+
+### --init flow (Q&A from scratch)
+
+1. **Brand identity:**
+   - Brand name?
+   - Core personality (3 words — AI suggests: minimal/bold/playful/enterprise/warm/technical)
+   - Primary color (hex or describe, AI suggests 4 palette options)
+
+2. **Typography:**
+   - Font family (AI suggests: Inter / Geist / Plus Jakarta Sans / Custom)
+   - Heading scale (tight compact / balanced standard / spacious editorial)
+
+3. **Spacing & Shape:**
+   - Spacing base (4px atomic / 8px standard — Recommended / custom)
+   - Corner radius (sharp 0px / subtle 4px / rounded 8px / pill 16px+)
+
+4. **Auto-generate semantic colors** from primary (surface, error, success, warning)
+5. **Write** `design.md` at project root
+
+### --init flow (awesome-design-md import mode)
+
+When user says "import" or triggers `--import`:
+1. AUQ catalog picker by category (Productivity / Developer / Commerce / Enterprise / Creative)
+2. Preview selected brand tokens (text table)
+3. AUQ: Apply as-is / Customize tokens / Use as reference only
+
+### --sync flow
+
+1. Parse `design.md` YAML front matter → TOKEN_MAP
+2. Detect stack:
+   - `tailwind.config.js` exists → Tailwind mode
+   - `style.css` only → CSS custom properties mode
+   - `*.scss` files → SCSS mode
+   - Multiple targets found → AUQ: which target?
+3. Generate/update target with tokens:
+   - **Tailwind:** `theme.extend.colors`, `theme.fontFamily`, `theme.spacing`, `theme.borderRadius`
+   - **CSS vars:** `:root { --color-primary: {hex}; --font-sans: {font}; --spacing-base: {n}px; }`
+   - **SCSS:** `$color-primary: {hex}; $font-sans: '{font}'; $spacing-base: {n}px;`
+4. Conflict resolution: AUQ per conflicting token (Override / Merge / Skip)
+5. Report: "Synced N tokens to {target file}"
+
+### --audit flow
+
+1. Discover all `.html` + `.css` + `.scss` files (exclude `node_modules`, `.git`)
+2. For each file: extract color/font references → compare vs TOKEN_MAP
+3. Categorize deviations:
+   - **❌ Critical:** wrong font-family, wrong primary/surface color hex
+   - **⚠️ Minor:** hardcoded value instead of CSS var (e.g. `#6366f1` instead of `var(--color-primary)`)
+   - **✅ Compliant:** uses correct var or correct hex
+4. Generate report table:
+   ```
+   | File | Colors | Typography | Spacing | Status |
+   | index.html | ✅ | ⚠️ 1 | ✅ | Partial |
+   ```
+5. Summary + suggestion: "Run /vp-design --sync to auto-fix"
+
+### --import [brand] flow
+
+1. Resolve brand:
+   - If arg provided → search awesome-design-md catalog for match
+   - If no arg → AUQ catalog picker
+2. Fetch template (runtime from awesome-design-md GitHub raw content)
+3. Preview: show token table (colors/typography/spacing)
+4. AUQ: Apply as-is / Customize before applying / Use as reference only
+</process>
+
+<success_criteria>
+- [ ] `design.md` created/updated at project root
+- [ ] `--init` produces valid Design.MD v1 spec YAML front matter
+- [ ] `--sync` updates correct target file based on stack detection
+- [ ] `--audit` produces severity-categorized compliance report
+- [ ] `--import` fetches community template and applies per user choice
+- [ ] AUQ used for catalog picker, conflict resolution, apply mode
+</success_criteria>
+
+## Adapter Compatibility
+
+### AskUserQuestion Tool (ENH-059)
+
+| Adapter | Interactive Prompts | Notes |
+|---------|---------------------|-------|
+| Claude Code (terminal) | ✅ `AskUserQuestion` — **REQUIRED** | Preload via ToolSearch before first prompt |
+| Cursor / Codex / Antigravity / Copilot | ❌ Text fallback | Plain numbered list |
+
+**Claude Code (terminal) — AUQ preload required (ENH-059):**
+Call `ToolSearch` with `query: "select:AskUserQuestion"` before first interactive prompt.
+
+**Prompts using AskUserQuestion in this skill:**
+- `--init`: primary color palette selection, font family selection
+- `--init --import`: awesome-design-md catalog picker, apply mode (as-is/customize/reference)
+- `--sync`: conflict resolution per token (Override/Merge/Skip), multi-target selection
+- `--audit`: (report only — no AUQ)
+- `--import`: catalog picker, apply mode
+- Workflow continuation after command completes
+</content>
+</invoke>

package/skills/vp-docs/SKILL.md

@@ -15,6 +15,43 @@ Output this banner as the **first** thing on every invocation — before questio
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 </greeting>
+<version_check>
+## Version Update Check (ENH-072)
+
+After displaying the greeting banner, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" check-update --silent
+```
+
+**If exit code = 1** (update available — new version printed to stdout):
+Display notice banner before any other output:
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ ✨ ViePilot {latest_version} available  (installed: {current})   │
+│    npm i -g viepilot && vp-tools install --target {adapter_id}   │
+└──────────────────────────────────────────────────────────────────┘
+```
+Replace `{latest_version}` with stdout from the command, `{current}` with the installed
+version, `{adapter_id}` with the active adapter (claude-code / cursor / antigravity / codex / copilot).
+
+**If exit code = 0 or command unavailable**: silent, continue.
+
+**Suppression rules:**
+- `--no-update-check` flag on skill invocation → skip this step entirely
+- `config.json` → `update.check: false` → skip this step entirely
+- Show at most once per session (`update_check_done` session guard)
+</version_check>
+<persona_context>
+## Persona Context Injection (ENH-073)
+At skill start, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona auto-switch
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona context
+```
+Inject the output as `## User Persona` context before any task execution.
+Silent if command unavailable or errors.
+</persona_context>
+
 
 <cursor_skill_adapter>
 ## A. Skill Invocation