viepilot 2.50.1 → 3.7.3

package/workflows/crystallize.md

@@ -4,12 +4,20 @@ Convert brainstorm sessions into structured artifacts for autonomous AI executio
 
 ## Adapter Compatibility
 
-| Feature | Claude Code (terminal) | Cursor (Agent/Skills) | Codex CLI | Antigravity (native) |
-|---------|----------------------|-----------------------|-----------|----------------------|
-| Interactive prompts | ✅ `AskUserQuestion` tool — **REQUIRED** | ❌ text fallback | ❌ text fallback | ❌ text fallback |
+Detected at session start via `vp-tools detect-adapter` → ADAPTER_CONTEXT. Use ADAPTER_CONTEXT.interactive to select prompt mode.
 
-**Claude Code (terminal):** Always call `AskUserQuestion` first. Only fall back to the plain-text menu below if the tool returns an error or is unavailable.
-**Cursor / Codex CLI / Antigravity / other adapters:** `AskUserQuestion` not available — use text menus below.
+| Feature | claude-code | cursor-agent | antigravity | codex | copilot |
+|---------|------------|--------------|-------------|-------|---------|
+| Interactive (ADAPTER_CONTEXT.interactive) | `AUQ` | `text` | `none` | `none` | `text` |
+| Prompt tool | `AskUserQuestion` | text fallback | text fallback | text fallback | text fallback |
+| Shell tool (Sub-scan A) | `Bash` | `run_terminal_cmd` | `shell` | `container.exec` | `runCommands` |
+
+**Interactive fallback chain** (read from ADAPTER_CONTEXT.interactive):
+1. `"AUQ"` → call `AskUserQuestion` (preload via ToolSearch first)
+2. `"text"` → show plain-text numbered list
+3. `"none"` → proceed with session defaults (log decision)
+
+**Sub-scan A shell tool**: use `ADAPTER_CONTEXT.tools.shell` — `Bash` on claude-code, `run_terminal_cmd` on cursor-agent, `shell` on antigravity.
 
 ## ViePilot Skill Scope Policy (BUG-004)
 
@@ -789,6 +797,15 @@ Rule: `secondary_languages[]` = languages with ≥5 files that are not `primary_
 
 1. `tailwind.config.js` / `tailwind.config.ts`
    - Extract: `theme.extend.colors`, `theme.colors`, `theme.fontFamily`, `theme.spacing`, `theme.borderRadius`
+   - **ENH-085 — Breakpoint extraction:** also read `theme.screens` / `theme.extend.screens`
+     - If present: record custom breakpoint values (e.g., `{ sm: '640px', md: '768px', lg: '1024px' }`)
+     - If absent: use Tailwind defaults `{ sm: 640, md: 768, lg: 1024, xl: 1280, '2xl': 1536 }` (report as "Tailwind defaults")
+   - **ENH-085 — Responsive utility detection:** after token scan, grep component source files for responsive prefix patterns:
+     - Scan: `src/**/*.{jsx,tsx,vue,svelte}`, `pages/**/*.{jsx,tsx}`, `app/**/*.{jsx,tsx,svelte}`
+     - Pattern: `\b(sm|md|lg|xl|2xl):[a-zA-Z0-9-]+`
+     - Count occurrences per file; identify top 10 files by responsive class count
+     - Track which prefixes are used (sm/md/lg/xl/2xl) and their relative frequency
+     - Infer strategy: if sm: > 40% of total responsive classes → `mobile-first`; if xl:/2xl: > 40% → `desktop-first`; else → `mixed`
 
 2. CSS custom properties in `*.css` / `globals.css` / `variables.css` / `_variables.scss`
    - `--color-*`, `--primary-*`, `--bg-*`, `--text-*` → TOKEN_MAP.colors
@@ -804,7 +821,38 @@ Rule: `secondary_languages[]` = languages with ≥5 files that are not `primary_
 - ASSUMED prefix for any token not found in any source.
 - Track `source_files[]` — list of all files scanned.
 
-**Scan Report field:** `ui_tokens: { detected: N, assumed: M, source_files: [] }`
+**Scan Report field:**
+```yaml
+ui_tokens:
+  detected: N
+  assumed: M
+  source_files: []
+  # ENH-085 — responsive additions (present only when tailwind detected):
+  breakpoints: { sm: 640, md: 768, lg: 1024, xl: 1280 }    # custom or Tailwind defaults
+  breakpoints_source: custom | tailwind-defaults
+  responsive_utilities:
+    prefixes_used: [sm, md, lg, xl]
+    strategy_inference: mobile-first | desktop-first | mixed | unknown
+    top_responsive_files:
+      - { file: "src/components/Nav.tsx", prefixes: [sm, md, lg], count: 34 }
+      - { file: "src/layouts/Dashboard.tsx", prefixes: [md, lg], count: 21 }
+    # (top 10 files by responsive class count; omitted if no responsive classes found)
+```
+
+**RESPONSIVE SUMMARY block** (appended to Sub-scan A output when breakpoints detected):
+```
+📱 RESPONSIVE SUMMARY
+──────────────────────────────────────────────────
+Breakpoints: sm(640) md(768) lg(1024) xl(1280) [source: tailwind-defaults]
+Strategy inference: mobile-first (sm: dominant — 52% of responsive classes)
+Top responsive files:
+  src/components/Nav.tsx           — 34 responsive classes [sm, md, lg]
+  src/layouts/Dashboard.tsx        — 21 responsive classes [md, lg]
+  src/components/DataTable.tsx     — 15 responsive classes [sm, md]
+```
+
+> If no `tailwind.config.js` found → skip breakpoint extraction and responsive utility detection silently.
+> If no responsive classes found in source → emit `strategy_inference: unknown`, omit top_responsive_files.
 
 ---
 
@@ -1486,10 +1534,12 @@ ls -la .viepilot/ui-direction/ 2>/dev/null
 
 When available, for the selected/latest session:
 - Read `.viepilot/ui-direction/{session-id}/notes.md` first (source of design decisions)
+  - Also check for: `## Component Responsive Map`, `responsive_strategy`, `target_devices` (ENH-085 — consumed in Step 1A-iv)
 - If `pages/` exists and contains `*.html`:
   - Require section **`## Pages inventory`** in `notes.md`; treat it as the **site map** (page count, purpose, navigation).
   - List all `pages/*.html` and confirm each file is represented in the inventory table (if mismatch → stop and ask user to fix brainstorm artifacts or document assumptions).
   - Read **each** `pages/{slug}.html` for section structure, components, and interaction hints.
+    - Also check each page for `<div class="responsive-breakdown">` sections (ENH-085 — consumed in Step 1A-iv)
   - Read hub `index.html` for cross-page navigation intent.
 - Else (legacy single-file layout):
   - Read `index.html` + `style.css` only (no `pages/`).
@@ -1561,6 +1611,74 @@ For each idea entry:
 
 Record all resolutions in working notes before Step 7 runs.
 
+---
+
+### Step 1A-iv: Consume Responsive / Breakpoint Metadata (ENH-085)
+
+**Run after Step 1A-i and Step 1A-iii.**
+
+**Source 1 — notes.md Component Responsive Map:**
+If `notes.md` contains `## Component Responsive Map`:
+- Extract `responsive_strategy` from the metadata comment (first line after the heading)
+- Extract `target_devices` from the metadata comment
+- Extract the component table rows (Nav / Grid / Table / Modal / Forms / Buttons / Images)
+- Store as `crystallize_context.responsive_components`
+
+**Source 2 — notes.md or session context responsive_strategy:**
+If `responsive_strategy` is set anywhere in `notes.md` (metadata comment, YAML front-matter, or `## design_tokens`):
+- Store `crystallize_context.responsive.strategy`
+
+**Source 3 — pages/*.html responsive-breakdown sections:**
+For each `pages/{slug}.html` that contains `<div class="responsive-breakdown">`:
+- Extract Mobile layout description and nav
+- Extract Tablet layout description and nav (if present)
+- Extract Desktop layout description and nav (if present)
+- Store per-page: `responsive_pages[slug] = { mobile: {...}, tablet: {...}, desktop: {...} }`
+
+**Source 4 — Sub-scan A ui_tokens.responsive_utilities (brownfield only):**
+If `ui_tokens.responsive_utilities` is present in the HANDOFF/scan data:
+- Copy `breakpoints`, `strategy_inference`, `top_responsive_files` into `crystallize_context.responsive`
+
+**Output — Responsive Implementation Notes in ARCHITECTURE.md:**
+
+When ANY of Sources 1–4 yields data, append to `.viepilot/ARCHITECTURE.md`:
+
+```markdown
+## Responsive Implementation Notes
+
+> Generated by crystallize ENH-085 from UI Direction artifacts + Sub-scan A data.
+
+**Strategy**: {responsive_strategy} (base styles {mobile-first: no prefix / desktop-first: full width} → {sm:/md:/lg:} scale {up/down})
+**Breakpoints**: {breakpoints list, e.g. "sm(640px) md(768px) lg(1024px) xl(1280px)"}
+
+### Per-Page Responsive Targets
+| Page | Mobile Layout | Tablet Layout | Desktop Layout | Nav Pattern |
+|------|---------------|---------------|----------------|-------------|
+| {slug} | {mobile.layout} | {tablet.layout} | {desktop.layout} | {mobile.nav} → {tablet.nav} → {desktop.nav} |
+| ... | | | | |
+
+### Component Responsive Map
+(Copied from UI Direction notes.md — source of truth)
+
+| Component      | Mobile (≤767px)     | Tablet (768–1023px)  | Desktop (≥1024px)  |
+|----------------|---------------------|---------------------|--------------------|
+| Navigation     | {from notes.md}     | ...                 | ...                |
+| ...            | ...                 | ...                 | ...                |
+
+### High-Priority Responsive Components (brownfield only)
+| File | Breakpoints Used | Responsive Class Count |
+|------|-----------------|------------------------|
+| {from top_responsive_files} | | |
+
+> **Implementation guidance**: Use `{responsive_strategy}` approach. Start with base styles,
+> apply `md:` for tablet overrides, `lg:` for desktop. See Component Responsive Map for
+> per-component variant expectations.
+```
+
+**Skip condition:** If none of Sources 1–4 yields any responsive data → omit `## Responsive Implementation Notes` entirely (backward-compat, non-mobile projects).
+
+---
+
 </step>
 
 <step name="research_stack_official">

package/workflows/design.md

@@ -4,6 +4,28 @@ community import), syncing tokens to stylesheets (Tailwind/CSS/SCSS), auditing c
 and importing brand templates from the awesome-design-md catalog.
 </purpose>
 
+<adapter_context>
+## ADAPTER_CONTEXT (FEAT-021)
+
+At skill start, read ADAPTER_CONTEXT to determine shell tool for --sync file operations:
+
+```bash
+ADAPTER_CONTEXT_JSON=$(node "$HOME/.claude/viepilot/bin/vp-tools.cjs" detect-adapter --json 2>/dev/null \
+  || echo '{"adapter":"claude-code","tools":{"shell":"Bash"}}')
+```
+
+Shell tool by adapter:
+| Adapter | Shell tool | Notes |
+|---|---|---|
+| claude-code | `Bash` | Full file I/O |
+| cursor-agent | `run_terminal_cmd` | Full file I/O |
+| antigravity | `shell` | Via MCP plugins |
+| codex | `container.exec` | Sandboxed |
+| copilot | `runCommands` | Limited |
+
+Silent on error — fall back to `Bash` (claude-code default).
+</adapter_context>
+
 <process>
 
 <step name="command_router">
@@ -207,6 +229,13 @@ rounded:
   md: "{radius}px"
   lg: "{radius * 2}px"
   full: "9999px"
+# ─── Responsive Breakpoints ────────────────────────────────
+screens:
+  mobile:  "0–767px"
+  tablet:  "768–1023px"
+  desktop: "1024–1279px"
+  wide:    "1280px+"
+strategy: mobile-first
 ---
 
 # Design System — {brand_name}
@@ -238,6 +267,21 @@ Base unit: {n}px. Scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96 / 128
 ## Border Radius
 sm={rounded.sm} · md={rounded.md} · lg={rounded.lg} · full={rounded.full}
 
+## Responsive Breakpoints
+**Strategy:** {strategy} | **Breakpoints:** mobile(0–767px) · tablet(768–1023px) · desktop(1024–1279px) · wide(1280px+)
+
+## Responsive Components
+
+| Component   | Mobile (≤767px)       | Tablet (768–1023px)   | Desktop (≥1024px)   |
+|-------------|----------------------|----------------------|---------------------|
+| Navigation  | Hamburger drawer     | Tab bar               | Full horizontal     |
+| Layout grid | 1 column             | 2 columns             | 3+ columns          |
+| Modal       | Bottom sheet         | Centered dialog       | Centered dialog     |
+| Data table  | Card list            | Scrollable table      | Full table          |
+| Forms       | Stacked single-col   | 2-col grouped         | 2-col grouped       |
+| Buttons CTA | Full-width           | Auto / inline         | Auto / inline       |
+| Images      | 100% width, cropped  | 50–75% width          | Fixed aspect ratio  |
+
 ## Components
 > Extend this section per component as your design system grows.
 
@@ -359,7 +403,9 @@ TOKEN_MAP = {
   colors: { primary, surface, surface_secondary, error, success, warning, text_primary, text_secondary },
   typography: { font_sans, font_mono, scale_ratio, heading_line_height, body_line_height },
   spacing: { base, scale[] },
-  rounded: { sm, md, lg, full }
+  rounded: { sm, md, lg, full },
+  screens: { mobile, tablet, desktop, wide },   // optional — present only when screens: block exists
+  strategy: "mobile-first" | "desktop-first"    // optional — defaults to mobile-first when absent
 }
 ```
 
@@ -412,10 +458,21 @@ theme: {
       lg: '{rounded.lg}',
       full: '{rounded.full}',
     },
+    // Responsive breakpoints — emitted only when screens: block exists in design.md
+    // Strategy: {strategy} (mobile-first = min-width; desktop-first = max-width)
+    screens: {
+      mobile: '0px',      // base — mobile-first (no prefix needed)
+      tablet: '768px',    // md: breakpoint
+      desktop: '1024px',  // lg: breakpoint
+      wide: '1280px',     // xl: breakpoint
+    },
   },
 },
 ```
 
+> **Note:** `screens` block is skipped gracefully if `TOKEN_MAP.screens` is absent (backward-compat).
+> Custom px values from `design.md` override the defaults above.
+
 **CSS custom properties mode** — inject into `:root` block in target CSS file:
 ```css
 :root {
@@ -434,6 +491,10 @@ theme: {
   --rounded-md: {rounded.md};
   --rounded-lg: {rounded.lg};
   --rounded-full: {rounded.full};
+  /* Responsive breakpoints (emitted only when screens: block present in design.md) */
+  --screen-tablet: 768px;
+  --screen-desktop: 1024px;
+  --screen-wide: 1280px;
 }
 ```
 

package/workflows/request.md

@@ -52,6 +52,57 @@ DEBT_COUNT=$(ls .viepilot/requests/DEBT-*.md 2>/dev/null | wc -l)
 ```
 </step>
 
+<step name="url_enrichment">
+## 1B. URL Enrichment Pre-Step (ENH-093)
+
+**Trigger**: `{{VP_ARGS}}` contains a URL matching a known issue tracker pattern.
+
+Run URL detection before Step 2:
+```js
+const { detectIssueUrl } = require('lib/request/url-enricher.cjs');
+const result = detectIssueUrl(VP_ARGS);
+```
+
+**On match** (github / linear / jira / trello / notion):
+
+**Claude Code adapter** — dispatch browser-intake-agent:
+```js
+Agent({ subagent_type: "browser-intake-agent",
+  description: "browser-intake-agent: extract request details from issue URL",
+  prompt: `op: read_url. url: ${result.url}. extract_mode: ticket. projectRoot: ${projectRoot}` })
+```
+
+On success, display pre-fill preview and ask user to confirm:
+```
+Context extracted from: {url}
+
+  Title:       {title}
+  Type:        {type} (detected from labels)
+  Description: {description preview}
+  Priority:    {priority}
+```
+
+**AUQ prompt** (Claude Code terminal):
+```
+question: "Review extracted details — confirm or edit?"
+options:
+  - label: "Confirm — use these details"
+    description: "Skip redundant questions, proceed to acceptance criteria"
+  - label: "Edit — adjust before proceeding"
+    description: "Return to Step 2 with pre-filled values"
+```
+
+On "Confirm": skip Step 2 gather questions, jump directly to Step 3 (create request file) using extracted values.
+On "Edit": proceed to Step 2 with extracted values pre-loaded as defaults.
+
+**On no match / extraction failure / agent-browser not available**:
+- Skip enrichment silently
+- Proceed normally from Step 2
+- URL stored as `related_url` in request file if present
+
+**Non-CC adapters**: skip Agent dispatch entirely, proceed from Step 2. URL stored as `related_url`.
+</step>
+
 <step name="detect_type">
 ## 2. Detect Request Type
 
@@ -104,14 +155,9 @@ If triggered:
 **Claude Code (terminal) — invoke research-agent:**
 ```
 Agent({
-  subagent_type: "general-purpose",
-  description: "research-agent: feasibility study for {topic}",
-  prompt: `
-    Load agents/research-agent.md for full spec.
-    Topic: {extracted from user description}
-    Questions: ["What SDK/API exists?", "What are integration points?", "What config dir/convention?", "Feasibility rating?"]
-    Return a ## Research Findings section + ## Sources.
-  `
+  subagent_type: "research-agent",
+  description: "Feasibility study: {topic}",
+  prompt: "topic: {extracted from user description}. questions: [\"What SDK/API exists?\", \"What are integration points?\", \"What config dir/convention?\", \"Feasibility rating?\"]"
 })
 ```