viepilot 2.50.1 → 3.7.2

package/workflows/brainstorm.md

@@ -5,12 +5,18 @@ Allows research inline within the same brainstorm session when needed.
 
 ## 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 list | defaults | defaults | text list |
+| Shell tool | `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)
 
 ## ViePilot Skill Scope Policy (BUG-004)
 
@@ -22,7 +28,24 @@ Allows research inline within the same brainstorm session when needed.
 <process>
 
 <step name="detect_session_language">
-## 0. Detect Session Language (ENH-032)
+## 0. ADAPTER_CONTEXT Load (FEAT-021)
+
+Detect active adapter and inject capability context. All interactive prompts in this workflow
+use ADAPTER_CONTEXT.interactive to select the correct prompt mode.
+
+```bash
+ADAPTER_CONTEXT_JSON=$(node "$HOME/.claude/viepilot/bin/vp-tools.cjs" detect-adapter --json 2>/dev/null \
+  || node "$(pwd)/bin/vp-tools.cjs" detect-adapter --json 2>/dev/null \
+  || echo '{"adapter":"claude-code","interactive_mode":"AUQ","orchestration":{"parallel":true}}')
+```
+
+Parse `interactive_mode` from JSON:
+- `"AUQ"` → use `AskUserQuestion` tool (preload via ToolSearch first)
+- `"text"` or `"none"` → use plain-text numbered list fallback
+
+Silent on error — fallback assumes claude-code defaults. Continue without blocking.
+
+## 0B. Detect Session Language (ENH-032)
 
 Read `~/.viepilot/config.json` → set `BRAINSTORM_LANG`:
 - `BRAINSTORM_LANG` = `language.document` from config (default: `en`)
@@ -254,6 +277,38 @@ If the user chooses to continue:
 5. If the session already has a **`## Phases`** section: briefly summarize existing phases; all subsequent updates must **merge** into that section (no silent deletion) unless the user explicitly requests narrowing/expanding scope.
 </step>
 
+<step name="reference_url_research">
+### Step 3A: Reference URL Research (ENH-092)
+
+**Trigger**: User provides a URL in their brainstorm input (competitor, reference app, documentation site).
+
+URL pattern detection: `https?://` present in user message before or during Step 3.
+
+When triggered:
+1. Extract URL from user message
+2. Dispatch research-agent with browser research op:
+   ```js
+   Agent({ subagent_type: "research-agent",
+     description: "research-agent: browse reference URL for brainstorm context",
+     prompt: `op: browse_url. url: "${url}". extract_focus: "features,ux-patterns,pricing,tech-stack". topic: "${sessionTitle}"` })
+   ```
+3. Present findings as `## Reference Research` section in brainstorm output:
+   - Key features / capabilities
+   - UX patterns observed
+   - Pricing model (if applicable)
+   - Tech stack clues
+4. Use findings as context for subsequent brainstorm questions
+5. If agent-browser not available: attempt WebFetch fallback (static HTML only — warn if empty)
+
+**Multiple URLs**: if user provides 2+ URLs, dispatch `compare_products` op:
+```js
+Agent({ subagent_type: "research-agent",
+  prompt: `op: compare_products. urls: ${JSON.stringify(urls)}. topic: "${sessionTitle}"` })
+```
+
+**Non-CC adapters**: skip agent dispatch, use WebFetch directly on the URL.
+</step>
+
 <step name="upgrade_gap_detection">
 ### Step 3B: Upgrade Gap Detection (ENH-067)
 
@@ -671,7 +726,7 @@ Map brainstorm UI signal keywords to capability tags:
 | UI Signal keywords | Capability match |
 |-------------------|-----------------|
 | `component`, `layout`, `screen`, `page`, `UI`, `UX` | `ui-generation`, `component-design` |
-| `responsive`, `mobile`, `grid` | `responsive-layout` |
+| `responsive`, `mobile`, `grid`, `breakpoint`, `viewport`, `adaptive`, `touch`, `swipe`, `safe-area`, `hamburger` | `responsive-layout` |
 | `design`, `theme`, `color`, `typography` | `design-system`, `design-tokens` |
 | `form`, `button`, `input`, `modal` | `component-design` |
 
@@ -699,6 +754,96 @@ After the session's first UI artifact is generated (or updated), append to `note
 If `## skills_used` already exists: merge (add new skills, update applied_at).
 If no skills matched or registry absent: omit `## skills_used` section.
 
+### Mobile Design Direction Sub-Phase (ENH-085)
+
+**Trigger:** UI Direction Mode is active AND any of these keywords appear in the session:
+`mobile` · `responsive` · `breakpoint` · `viewport` · `adaptive` · `touch` · `swipe`
+`safe-area` · `hamburger` · `tablet` · `phone` · `narrow` · `narrow screen` · `screen size`
+
+**When triggered — fire TWO sequential AUQ prompts before HTML generation begins:**
+
+**AUQ 1 — Viewport Strategy:**
+```
+question: "What is the responsive design strategy for this project?"
+options:
+  - label: "Mobile-first (Recommended)"
+    description: "Base styles target mobile; breakpoints (md:, lg:) scale up. Default for most web apps."
+  - label: "Desktop-first"
+    description: "Full desktop layout; shrink down with max-width breakpoints."
+  - label: "Mobile only"
+    description: "No desktop variant needed (PWA, native-style app, mobile-specific tool)."
+  - label: "Desktop only"
+    description: "Internal tool or dashboard — no mobile support required."
+```
+
+**AUQ 2 — Target Device Scope (multiSelect: true):**
+```
+question: "Which device types need UI direction?"
+multiSelect: true
+options:
+  - label: "Phone (≤767px)"
+    description: "Small screens, touch-first, vertical scroll, hamburger nav."
+  - label: "Tablet (768–1023px)"
+    description: "Medium screens, touch+pointer, hybrid layouts."
+  - label: "Desktop (≥1024px)"
+    description: "Large screens, pointer-first, dense information layouts."
+  - label: "Wide / TV (≥1280px)"
+    description: "Very large screens, 3+ column layouts, dashboard displays."
+```
+
+**Store answers as session context:**
+```yaml
+responsive_strategy: mobile-first | desktop-first | mobile-only | desktop-only
+target_devices: [phone, tablet, desktop, wide]   # subset based on AUQ selections
+```
+
+**Fallback (if AUQ not available):** set `responsive_strategy: mobile-first`, `target_devices: [phone, tablet, desktop]` silently.
+
+**Skip conditions:**
+- No mobile/responsive keywords in session → skip entirely (non-mobile project)
+- `responsive_strategy` already set in session context (resume) → skip AUQ, reuse stored values
+
+**Component Responsive Map in notes.md (ENH-085)**
+
+After the Mobile Design Direction AUQ completes (or on session resume with `responsive_strategy` set),
+append a `## Component Responsive Map` section to `notes.md`:
+
+```markdown
+## Component Responsive Map
+
+> ViePilot ENH-085 — Strategy: {responsive_strategy} | Devices: {target_devices joined with ", "}
+> Generated: {date}
+
+| Component      | Mobile (≤767px)        | Tablet (768–1023px)    | Desktop (≥1024px)    |
+|----------------|------------------------|------------------------|----------------------|
+| Navigation     | {mobile_nav}           | {tablet_nav}           | {desktop_nav}        |
+| Layout grid    | 1 column, full-width   | 2 columns              | 3+ columns / sidebar |
+| Data table     | Card list (stacked)    | Scrollable table       | Full table + filters |
+| Modal / dialog | Bottom sheet           | Centered dialog        | Centered dialog      |
+| Forms          | Single column          | 2-col grouped          | 2-col grouped        |
+| Buttons (CTA)  | Full-width             | Auto / inline          | Auto / inline        |
+| Images / media | 100% width, cropped    | 50–75% width           | Fixed aspect ratio   |
+
+### Navigation Pattern Detail
+- **Mobile**: {mobile_nav_detail}
+- **Tablet**: {tablet_nav_detail}
+- **Desktop**: {desktop_nav_detail}
+
+### Responsive Utilities Reference (Tailwind)
+```
+Mobile base  →  no prefix     (e.g., flex flex-col p-4)
+Tablet       →  `md:` prefix  (e.g., md:flex-row md:grid-cols-2)
+Desktop      →  `lg:` prefix  (e.g., lg:grid-cols-3 lg:sidebar-fixed)
+Wide         →  `xl:` prefix  (e.g., xl:max-w-7xl xl:px-12)
+```
+```
+
+Nav values for the table: use Navigation strategy lookup table defined in the per-breakpoint HTML section above.
+
+**Guard:** If `notes.md` already contains `## Component Responsive Map` → skip (do not overwrite).
+
+**Skip:** If `responsive_strategy` is null (non-mobile session) → omit section entirely.
+
 **Required hook (multi-page only)**
 
 When the `pages/` directory exists or any `pages/*.html` is added / renamed / removed:
@@ -707,6 +852,76 @@ When the `pages/` directory exists or any `pages/*.html` is added / renamed / re
 - Immediately update the **`## Pages inventory`** section in `notes.md` (table: Slug | File | Title | Purpose | Key sections | Nav to) — must match 100% of the current `pages/*.html` file set.
 - Do not end a topic / do not consider the UI session “synced” if the inventory diverges from files on disk.
 
+**Per-breakpoint sections in pages/*.html (ENH-085)**
+
+When `responsive_strategy` is set (from Mobile Design Direction sub-phase), append a
+`<div class="responsive-breakdown">` section to the bottom of every generated `pages/{slug}.html`:
+
+```html
+<!-- Responsive Breakdown — ViePilot ENH-085 -->
+<div class="responsive-breakdown">
+  <h2>Responsive Breakdown</h2>
+  <!-- Render only sections for active target_devices -->
+
+  <!-- Phone section: render when target_devices includes "phone" -->
+  <details open>
+    <summary>📱 Mobile (≤767px)</summary>
+    <div class="breakpoint-notes">
+      <p><strong>Layout:</strong> {mobile_layout}</p>
+      <p><strong>Navigation:</strong> {mobile_nav}</p>
+      <ul>{mobile_key_changes}</ul>
+    </div>
+  </details>
+
+  <!-- Tablet section: render when target_devices includes "tablet" -->
+  <details>
+    <summary>💻 Tablet (768–1023px)</summary>
+    <div class="breakpoint-notes">
+      <p><strong>Layout:</strong> {tablet_layout}</p>
+      <p><strong>Navigation:</strong> {tablet_nav}</p>
+      <ul>{tablet_key_changes}</ul>
+    </div>
+  </details>
+
+  <!-- Desktop section: render when target_devices includes "desktop" -->
+  <details>
+    <summary>🖥 Desktop (≥1024px)</summary>
+    <div class="breakpoint-notes">
+      <p><strong>Layout:</strong> {desktop_layout}</p>
+      <p><strong>Navigation:</strong> {desktop_nav}</p>
+    </div>
+  </details>
+</div>
+```
+
+**`<details open>`** = primary breakpoint (phone if mobile-first, desktop if desktop-first).
+
+**Navigation strategy lookup** (infer from page purpose):
+
+| Page purpose | Mobile nav | Tablet nav | Desktop nav |
+|---|---|---|---|
+| App / dashboard | Hamburger drawer | Bottom tab bar | Left sidebar |
+| Marketing / landing | Hamburger menu | Hamburger menu | Full horizontal nav |
+| E-commerce | Bottom tab (Home/Search/Cart/Profile) | Tab bar + filters | Full nav + mega menu |
+| Admin / internal | Bottom nav (compact) | Collapsible sidebar | Full left sidebar |
+| Auth (login/signup) | Single-column form | Centered card | Centered card |
+| Content / reader | Bottom nav | Collapsed sidebar | Persistent sidebar |
+
+**Skip conditions:**
+- `responsive_strategy` absent → skip block entirely
+- `responsive_strategy: mobile-only` → render Phone section only (no details wrapper needed)
+- `responsive_strategy: desktop-only` → render Desktop section only
+
+**CSS to append to shared `style.css`** (once per workspace, not per page):
+
+```css
+/* ENH-085 — Responsive Breakdown */
+.responsive-breakdown{margin-top:2rem;border-top:2px solid #e5e7eb;padding-top:1.5rem}
+.responsive-breakdown details{margin-bottom:1rem;border:1px solid #e5e7eb;border-radius:8px;padding:1rem}
+.responsive-breakdown summary{font-weight:600;cursor:pointer;padding:.25rem 0;user-select:none}
+.breakpoint-notes{padding-top:.75rem}
+```
+
 3. If the user sends references/components (including 21st.dev prompts/links), record clearly:
    - reference source
    - the UI area it applies to (page slug if multi-page)

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?\"]"
 })
 ```