viepilot 2.41.0 → 2.45.3

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

@@ -41,6 +41,16 @@ version, `{adapter_id}` with the active adapter (claude-code / cursor / antigrav
 - `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>

package/skills/vp-update/SKILL.md

@@ -41,6 +41,16 @@ version, `{adapter_id}` with the active adapter (claude-code / cursor / antigrav
 - `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>

package/workflows/autonomous.md

@@ -61,6 +61,16 @@ cat .viepilot/ROADMAP.md
 Read `~/.viepilot/config.json` → `COMMUNICATION_LANG` (default: `en`).
 Use `COMMUNICATION_LANG` for all banners, control-point messages, and user-facing output in this session.
 
+### Persona Context (ENH-073)
+After loading AI-GUIDE.md and TRACKER.md, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona auto-switch
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona context
+```
+Inject output as `## User Persona` block into each task's execution context.
+Use `persona.stacks` for stack preflight matching (prefer persona stacks over generic detection).
+Silent if command unavailable or errors — do not fail the phase.
+
 ### Skill Context Load (FEAT-020)
 
 After loading context files, load the project's skill decisions:
@@ -300,6 +310,55 @@ If stack cache is missing:
 - warn and optionally run quick research
 - then continue with explicit assumptions noted in task logs
 
+#### Preflight 5.5 — Design.MD Token Injection (ENH-076)
+
+After Stack Preflight, if `design.md` exists at project root (or nearest parent directory):
+
+**Step A — Build TOKEN_MAP** (parse YAML front matter):
+- `TOKEN_MAP.colors.*` — primary, surface, accent, error, success, warning
+- `TOKEN_MAP.typography.*` — fontFamily, fontSize, fontWeight, lineHeight
+- `TOKEN_MAP.spacing.*` — base, scale
+- `TOKEN_MAP.rounded.*` — sm, md, lg, full
+
+**Step B — UI task detection** (check task title + file paths + objective text):
+```
+UI_KEYWORDS = [
+  html, css, style, component, tailwind, layout, button, card,
+  form, page, ui, frontend, color, font, typography, responsive, design
+]
+```
+If NO UI_KEYWORDS matched → skip Design.MD injection entirely for this task.
+
+**Step C — Injection levels (when UI task detected):**
+
+- **Level 1 — Silent context injection (always):**
+  Token map injected as implicit constraint in execution context.
+  AI naturally applies brand tokens when generating HTML/CSS.
+  No output shown to user.
+
+- **Level 2 — Checklist items (when task has explicit UI acceptance criteria):**
+  Auto-append to task checklist:
+  ```
+  - [ ] Primary color uses TOKEN_MAP.colors.primary (or var(--color-primary))
+  - [ ] Font family matches TOKEN_MAP.typography.fontFamily
+  - [ ] Spacing follows TOKEN_MAP.spacing.base unit
+  ```
+
+- **Level 3 — Post-task design audit (when task output includes .html or .css files):**
+  After generating output: scan for token deviations.
+  Auto-fix: obvious wrong fonts or exact hex mismatches.
+  AUQ on Claude Code terminal when judgment call required.
+  Report:
+  ```
+  🎨 Design.MD check: ✅ Colors  ✅ Typography  ⚠️ 1 spacing deviation (auto-fixed)
+  ```
+
+**Edge cases:**
+- Backend-only task (no UI_KEYWORDS) → skip entirely
+- design.md missing a token → inject only present tokens, no fail
+- Monorepo → nearest `design.md` wins (task dir → parent → project root)
+- Token conflict with Tailwind config → AUQ: Use design.md / Use Tailwind config / Update both
+
 #### Scaffold-First Gate (BUG-020)
 
 When the stack preflight identifies a **framework stack** AND the current task is a **project setup / init task** (keywords in title or objective: "set up", "initialize", "create project", "scaffold", "bootstrap", "new project", "install Laravel/Next/Nest/Rails/Django"):

package/workflows/brainstorm.md

@@ -32,8 +32,33 @@ If the user writes in a different language during the session, that takes preced
 If `~/.viepilot/config.json` is absent, default to `en` — do not fail.
 </step>
 
+<step name="persona_domain_pack">
+## 0B. Persona Domain Pack Integration (ENH-073)
+
+At session start, before presenting topics, run:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona auto-switch
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona context
+```
+
+Store the result as `PERSONA_CONTEXT`. If command unavailable or errors → `PERSONA_CONTEXT = null`, continue silently.
+
+**If `PERSONA_CONTEXT` is available:**
+1. Read `persona.domain` — load corresponding `lib/domain-packs/{domain}.json`
+   - If domain is array (merged persona): load all packs and union their fields
+2. Apply to topic list:
+   - Prepend `extra_topics` not already in template (injected before session topics)
+   - Reorder template topics by `topic_priority` (matching topics float to top)
+   - Remove topics whose id is in `persona.brainstorm.topic_skip`
+3. When phase discussion begins: suggest `phase_template.phases` from domain pack as default ordering
+4. When Architect Design Mode activates: add domain pack `architect_pages` to workspace
+5. If `persona.confidence < 0.6`: add inline note "(persona auto-detected, may be inaccurate — run /vp-persona to refine)" — not a blocking prompt
+
+**Persona context is silently injected into the session — no banner, no AUQ.**
+</step>
+
 <step name="detect_embedded_domain">
-## 0B. Detect Embedded Domain (ENH-071)
+## 0C. Detect Embedded Domain (ENH-071)
 
 Scan the user's **initial message** (and, on `--continue`, the prior session content) for embedded trigger keywords.
 
@@ -403,6 +428,46 @@ For each topic:
 4. Suggest alternatives if needed
 5. Record decisions
 
+### Mid-session Structured Choice Rule (BUG-022)
+
+When presenting a decision with **≥2 discrete named options** during Q&A (e.g. "Hero first
+or Features section?", "lean into multi-adapter or persona angle?", any numbered choice set),
+use adapter-aware prompts:
+
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion`. AUQ spec:
+>   - question: "{The direction/decision question}"
+>   - header: "{short label, ≤12 chars}"
+>   - options: one entry per discrete choice (2–4 options per AUQ call)
+>   - multiSelect: false (unless user explicitly wants multi-select)
+> **Cursor / Codex / Antigravity / Copilot:** present as plain numbered list.
+
+**Exempt from AUQ** (remain plain conversational text):
+- Open-ended questions with no discrete choices ("Anything else you'd like to add?")
+- Follow-up clarification questions ("Tell me more about X")
+- Questions where the expected answer is a free-form description
+
+**AUQ per decision, not per topic:** One AUQ call per structured decision point.
+Do not bundle multiple unrelated decisions into a single AUQ call.
+
+### Mid-session Transition Prompt Rule (BUG-023)
+
+When the AI offers **session-flow choices** at a section or topic boundary — after presenting
+a table, completing an analysis, or finishing a discussion topic — use adapter-aware prompts:
+
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion`. Canonical AUQ spec:
+>   - question: "What would you like to do next?"
+>   - header: "Next step"
+>   - options (vary by context; always ≥2):
+>     - label: "Save session → /vp-crystallize", description: "Generate implementation specs"
+>     - label: "Update UI Direction artifacts", description: "Update index.html/notes.md now"
+>     - label: "Continue discussing", description: "Explore another section or topic"
+>   - multiSelect: false
+> **Cursor / Codex / Antigravity / Copilot:** present as plain numbered list.
+
+**Scope:** session-FLOW control choices only — distinct from BUG-022 (Q&A content/direction
+decisions during Q&A). Triggered when offering: save/crystallize, update artifacts, or
+continue/discuss more. NOT triggered for content questions about what to build or design.
+
 ### Landing Page Deep-Dive (activated contextually)
 If the user is brainstorming a landing page / homepage / marketing page:
 
@@ -458,6 +523,71 @@ If the user is brainstorming a project with UI/UX or requests a visual design:
    - Update HTML/CSS direction directly
    - Record decision + rationale in `notes.md` (single source of truth for design intent)
 
+### Design Token Extraction (ENH-076)
+
+**Trigger:** UI Direction Mode active (`--ui` flag) OR ≥2 design keywords detected in session:
+`color` / `font` / `brand` / `spacing` / `typography` / `palette` / `theme` / `style`
+
+**Extraction process:**
+During Q&A, AI tracks design decisions and maps them to a TOKEN_MAP:
+- Color mentions → `tokens.colors.*` (primary, surface, accent, error, success, warning)
+- Font/typeface mentions → `tokens.typography.fontFamily`, `fontSize`
+- Size/scale/rhythm mentions → `tokens.spacing.base`, `tokens.spacing.scale`
+- Roundness/corner mentions → `tokens.rounded.*` (sm/md/lg/full)
+
+**Output — `.viepilot/ui-direction/{session-id}/design.md`** (Design.MD v1 spec):
+```yaml
+---
+name: "{project-name}"
+description: "{one-line brand description from session}"
+colors:
+  primary: "{hex}"
+  surface: "{hex}"
+  accent: "{hex}"
+typography:
+  fontFamily: "{font}, sans-serif"
+  fontSize:
+    base: 16
+spacing:
+  base: 8
+  scale: [4, 8, 16, 24, 32, 48]
+rounded:
+  sm: 4px
+  md: 8px
+---
+
+## Overview
+{Brand personality extracted from session}
+
+## Colors
+{Color rationale from session decisions}
+
+## Typography
+{Font rationale from session decisions}
+```
+
+**notes.md section added** (append to session notes.md):
+```yaml
+## design_tokens
+colors:
+  primary: "{hex}"
+typography:
+  fontFamily: "{font}"
+spacing_base: 8
+design_md_path: .viepilot/ui-direction/{session-id}/design.md
+design_md_generated: true
+```
+
+**After generation:** Show inline summary:
+```
+🎨 Design.MD generated: primary={hex} | font={font} | spacing={n}px
+   Path: .viepilot/ui-direction/{session-id}/design.md
+```
+
+**Incremental updates:** If user refines a color or font later in the session, update
+`design.md` and `notes.md ## design_tokens` in place (same as how `index.html` is updated
+incrementally as design decisions evolve).
+
 ### Skill Registry Integration (FEAT-020)
 
 **Trigger**: UI Direction Mode is active (at least one HTML file being generated or updated).
@@ -671,6 +801,23 @@ Activate Architect Design Mode so I can create an HTML visualization?
 | `entity-mgmt.html` | Admin entity CRUD matrix: entity name, admin ops (C/R/U/D), soft delete flag, bulk actions, audit trail, multi-tenant scope; import/export summary table (ENH-068) |
 | `content.html` | Content types, lifecycle states, creator permission matrix, taxonomy tree, media storage config, SEO field schema |
 | `user-data.html` | User-owned data: profile field list, privacy rights matrix (export/erasure), connected OAuth providers, session/device management, 2FA config, consent log schema |
+| `design.html` | Design system visual reference: color swatches grid, typography scale table, spacing grid, border-radius samples, component token table (ENH-076) |
+
+**design.html trigger:** Architect Mode active AND (`design.md` present in session dir OR `## design_tokens` in `notes.md`).
+
+**design.html content sections:**
+
+1. **Color Palette** — swatch grid: colored square + hex value + semantic label, grouped as Brand (primary/accent) | Neutral (surface/muted) | Semantic (error/success/warning)
+2. **Typography Scale** — table: Level | Font Family | Size | Weight | Line Height | Example text (H1 → H2 → H3 → Body → Caption → Code)
+3. **Spacing Grid** — visual row of boxes with increasing widths (4px, 8px, 16px, 24px, 32px, 48px), labeled spacing-1 through spacing-12
+4. **Shape / Border Radius** — 4 visual boxes showing sharp/subtle/rounded/pill radii with CSS var labels (`--rounded-sm` → `--rounded-full`)
+5. **Component Tokens** — table: Component | Token | Value (rendered only if `components:` section exists in design.md)
+
+**Sync rule:** When `notes.md ## design_tokens` is updated (e.g. via new UI direction keywords), regenerate `design.html` sections — same incremental update pattern as other Architect pages.
+
+**Hub nav:** Add `<a href="design.html">🎨 Design System</a>` to `index.html` nav when `design.html` is created. Update `## Pages inventory` in `notes.md`.
+
+**Format:** Pure HTML + inline `<style>`, no external CSS/JS dependencies — consistent with all other Architect workspace pages.
 
 #### Admin & Governance Detection (ENH-063)
 

package/workflows/crystallize.md

@@ -907,6 +907,20 @@ When `IS_BROWNFIELD=true`, the following table governs which steps execute:
 </step>
 
 <step name="analyze_brainstorm">
+## Step 0C: Persona output_style adaptation (ENH-073)
+
+Read active persona via:
+```bash
+node "$HOME/.claude/viepilot/bin/vp-tools.cjs" persona get
+```
+
+Apply `output_style` to document generation in Steps 1D and 1E:
+- `lean` → concise docs: summary sections, skip boilerplate headers, short descriptions
+- `balanced` → standard docs (default if persona unavailable)
+- `enterprise` → full docs: compliance sections, decision rationale appendix, detailed risk notes
+
+Silent if persona unavailable → use `balanced` default.
+
 ## Step 1: Analyze Brainstorm
 
 ```bash
@@ -1397,6 +1411,103 @@ If notes.md contains any of: `## hw_topology`, `## pin_map`, `## memory_layout`,
 
 ---
 
+### Step 1D.14 — Design.MD Export (ENH-076)
+
+**Trigger (gate fires when ANY of):**
+- `design.md` exists in `.viepilot/ui-direction/{session-id}/`
+- `notes.md` contains `## design_tokens` section
+- Brainstorm session text contains ≥3 design keywords: `color` / `font` / `brand` / `spacing` / `typography` / `palette` / `theme` / `rounded` / `style`
+
+**Skip conditions (gate does NOT fire when ANY of):**
+- `notes.md` has `design_md_status: skipped` (idempotent — user already skipped this session)
+- `notes.md` has `design_md_status: exported` (already exported this session)
+- Session has no UI components and no design keywords
+
+**Gate — AUQ (mandatory-acknowledge — user must select one option):**
+
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion`:
+>   - question: "Design tokens found in this session. What would you like to do with design.md?"
+>   - header: "design.md"
+>   - options:
+>     - label: "Export to project root" (Recommended)
+>       description: "Copy design.md, update ARCHITECTURE.md + PROJECT-CONTEXT.md"
+>     - label: "Finalize & export"
+>       description: "Complete any missing tokens via Q&A, then export"
+>     - label: "Skip this time"
+>       description: "Note: vp-auto will not apply brand tokens to UI tasks"
+> **Cursor / Codex / Antigravity / Copilot:** present as plain numbered list.
+
+**Export pipeline (options 1 + 2):**
+
+1. **Source:** `.viepilot/ui-direction/{session-id}/design.md`
+2. **Destination:** `{project-root}/design.md`
+   - If `design.md` already exists at project root → AUQ (or plain numbered list on non-terminal):
+     Override with new tokens / Merge (new fills gaps, existing takes precedence) / Keep existing / View diff
+3. **Update `ARCHITECTURE.md`** — append `## Design System` section:
+   ```markdown
+   ## Design System
+
+   > Generated from Design.MD spec (v1)
+   > Source: `.viepilot/ui-direction/{session-id}/design.md`
+   > Last updated: {crystallize-date}
+
+   | Category | Token | Value |
+   |----------|-------|-------|
+   | Colors | primary | {hex} |
+   | Colors | surface | {hex} |
+   | Typography | fontFamily | {font} |
+   | Spacing | base | {n}px |
+
+   **Full spec:** See `design.md` at project root.
+   ```
+4. **Update `PROJECT-CONTEXT.md`** — add field:
+   ```
+   design_md: true
+   ```
+5. **Update `notes.md`** — set:
+   ```yaml
+   design_md_status: exported
+   design_md_exported_at: {timestamp}
+   ```
+
+**Skip pipeline (option 3):**
+- Write to `notes.md`:
+  ```yaml
+  design_md_status: skipped
+  design_md_skipped_at: {timestamp}
+  ```
+- Show warning: `⚠️  design.md skipped — vp-auto will not apply brand tokens to UI tasks`
+
+**Post-Export Handoff: vp-design --sync (ENH-077)**
+
+After **successful export** (export pipeline steps 1–5 complete), offer sync handoff:
+
+**Skip condition:** If no stylesheet target detected (no `tailwind.config.js`, no `.css`, no `.scss` files in project) → skip AUQ silently. Print:
+> `Note: no stylesheet target detected. Run /vp-design --sync after adding your stylesheets.`
+
+Otherwise:
+
+> **Claude Code (terminal) — REQUIRED:** Call `AskUserQuestion`:
+>   - question: "design.md exported to project root. Sync design tokens to your stylesheets now?"
+>   - header: "Sync tokens?"
+>   - options:
+>     - label: "Run /vp-design --sync now (Recommended)"
+>       description: "Auto-applies tokens to Tailwind / CSS vars / SCSS — stack auto-detected"
+>     - label: "Skip — run manually later"
+>       description: "Run /vp-design --sync yourself when ready"
+>
+> **Cursor / Codex / Antigravity / Copilot:** Text fallback:
+> ```
+> design.md exported. Next step:
+>   /vp-design --sync    Apply tokens to Tailwind / CSS / SCSS
+> ```
+
+**On selection:**
+- "Run /vp-design --sync now" → invoke `/vp-design --sync` skill
+- "Skip" → print: `Tip: run /vp-design --sync to apply design tokens to your stylesheets.`
+
+---
+
 ### Step 1D-a: arch_to_ui_sync noted items → UI Pages → Component Map (ENH-069 Gap 5)
 
 After reading `notes.md → ## arch_to_ui_sync[]`, for each entry with `status: noted`: