@su-record/vibe 2.16.4 → 3.0.0

package/skills/figma/rubrics/css-mapping.md

@@ -0,0 +1,125 @@
+# Figma Property → CSS Mapping Reference
+
+Properties automatically converted by `figma-extract.js` tree extraction (Extract Mode E1) and consumed by `figma-to-scss.js`. Phase 4 forbids hand-writing these values — this table is grounding for reviewing script output (and for modifying the scripts when output is unsatisfactory).
+
+## Layout
+
+| Figma Property | CSS | vw conversion |
+|-----------|-----|---------|
+| `layoutMode=VERTICAL` | `display:flex; flex-direction:column` | No |
+| `layoutMode=HORIZONTAL` | `display:flex; flex-direction:row` | No |
+| `primaryAxisAlignItems` | `justify-content` | No |
+| `counterAxisAlignItems` | `align-items` | No |
+| `itemSpacing` | `gap` | Yes |
+| `layoutGrow=1` | `flex-grow: 1` | No |
+| `padding*` | `padding` | Yes |
+| `absoluteBoundingBox.width/height` | `width/height` | Yes |
+| `layoutPositioning=ABSOLUTE` | `position: absolute` + `top/left` (relative to parent) | Yes |
+| `layoutSizingHorizontal=HUG` | remove width (auto) | — |
+| `layoutSizingHorizontal=FILL` | metadata `layoutSizingH` (converter decides flex:1/100%) | — |
+| `layoutSizingVertical=HUG` | remove height (auto) | — |
+| `layoutSizingVertical=FILL` | metadata `layoutSizingV` (converter decides) | — |
+| `clipsContent` | `overflow: hidden` | No |
+
+## Visual
+
+| Figma Property | CSS | vw conversion |
+|-----------|-----|---------|
+| `fills[].SOLID` | `background-color` | No |
+| `fills[].IMAGE` | `imageRef` + `imageScaleMode` (FILL/FIT/CROP/TILE) | — |
+| `fills[].GRADIENT_LINEAR` | `background-image: linear-gradient(...)` | No |
+| `fills[].GRADIENT_RADIAL` | `background-image: radial-gradient(...)` | No |
+| `fills[] (2 or more)` | `fills` array (type, color, imageRef, gradient, blendMode, filters) | — |
+| `fills[].blendMode` | `background-blend-mode` | No |
+| `fills[].filters.saturation` | `filter: grayscale(X%)` / `saturate(X%)` | No |
+| `fills[].color` (TEXT) | `color` | No |
+| `strokes[] + strokeAlign=INSIDE` | `border` + `box-sizing: border-box` | Yes (width only) |
+| `strokes[] + strokeAlign=OUTSIDE` | `outline` | Yes (width only) |
+| `individualStrokeWeights` | `border-top/right/bottom/left` individually | Yes (width only) |
+| `strokeDashes` | `border-style: dashed` | No |
+| `effects[].DROP_SHADOW` | `box-shadow` | Yes (px only) |
+| `effects[].INNER_SHADOW` | `box-shadow` (inset) | Yes (px only) |
+| `effects[].LAYER_BLUR` | `filter: blur()` (accumulated) | Yes |
+| `effects[].BACKGROUND_BLUR` | `backdrop-filter: blur()` | Yes |
+| `cornerRadius` | `border-radius` | Yes |
+| `opacity` | `opacity` | No |
+| `rotation` | `transform: rotate(Xdeg)` | No |
+| `blendMode` (node level) | `mix-blend-mode` | No |
+
+## Text
+
+| Figma Property | CSS | vw conversion |
+|-----------|-----|---------|
+| `style.fontFamily` | `font-family` | No |
+| `style.fontSize` | `font-size` | Yes |
+| `style.fontWeight` | `font-weight` | No |
+| `style.lineHeightPx` | `line-height` | No |
+| `style.letterSpacing` | `letter-spacing` | Yes |
+| `style.textAlignHorizontal` | `text-align` | No |
+| `style.textCase` | `text-transform` | No |
+| `style.textTruncation` | `overflow: hidden; text-overflow: ellipsis` | No |
+| `style.paragraphSpacing` | `margin-bottom` | Yes |
+| `characters` | text content | — |
+
+## SCSS Property Allowlist (per file group)
+
+```
+Layout (layout/ files):
+  display, flex-direction, justify-content, align-items, gap,
+  flex-grow, padding, width, height, overflow, position, top, left, transform
+
+Visual (components/ files):
+  background-color, background-image, background-blend-mode, color,
+  font-family, font-size, font-weight, line-height, letter-spacing,
+  text-align, text-transform, text-overflow,
+  border-radius, border, outline, box-sizing, box-shadow,
+  opacity, mix-blend-mode, filter, backdrop-filter
+
+If a value is absent in the tree → omit that property (no guessing)
+
+❌ Forbidden: aspect-ratio, container queries, custom @function/@mixin (wp-fluid() etc.),
+   clamp() with guessed values — only 1:1 mapping from the tree is allowed.
+```
+
+## Responsive Unit Conversion (legacy vw workflow — Phase 4C reference)
+
+> Current Phase 4 generates px as-is via figma-to-scss.js. These rules apply to the
+> responsive-integration flow (Phase 4C) and to script maintenance.
+
+```
+vw conversion (mechanical formula only):
+  width, height, padding, gap, border-radius, box-shadow, top, left, border-width
+  vw value = (Figma px / designWidth) × 100
+  ⛔ clamp, min(), max() etc. are allowed only for font-size
+
+Font → clamp(min, vw, max):
+  | Role    | Min   | Determination Basis         |
+  |---------|-------|-----------------------------|
+  | h1~h2   | 16px  | name contains "title"       |
+  | h3~h4   | 14px  | medium size                 |
+  | Body    | 12px  | long text                   |
+  | Caption | 10px  | small fontSize              |
+  | Button  | 12px  | name contains "btn"         |
+  max value = original Figma px as-is
+
+Properties never converted:
+  color, opacity, font-weight, font-family, z-index, text-align,
+  mix-blend-mode, transform(rotate), background-blend-mode,
+  flex-grow, box-sizing, grayscale/saturate, background-image(gradient)
+
+layoutSizing handling:
+  HUG → omit width/height (auto)
+  FILL → same direction as parent → flex: 1 0 0 · cross axis → align-self: stretch
+  FIXED → vw conversion
+
+imageScaleMode:
+  FILL → background-size: cover · FIT → contain
+  CROP → cover + background-position: center · TILE → auto + repeat
+
+MO↔PC responsive (remapped.json pcDiff → @media overrides, MO base preserved):
+  Same value → keep MO only
+  Different px → @media { PC vw }
+  Different layout → @media { flex-direction: row }
+  Different image → @media { background-image: url(pc-xxx.webp) }
+  layoutSizing diff → @media { flex/width change }
+```

package/skills/git-worktree/SKILL.md

@@ -3,7 +3,7 @@ name: git-worktree
 invocation: [auto]
 tier: optional
 description: "Git Worktree for parallel branch work. Auto-activates for PR review, hotfix, parallel testing, or working on multiple branches simultaneously."
-triggers: [worktree, PR review, hotfix, parallel branch, multiple branches]
+triggers: [worktree, hotfix, parallel branch, multiple branches]
 priority: 50
 ---
 

package/skills/handoff/SKILL.md

@@ -5,7 +5,7 @@ invocation: [auto]
 tier: standard
 description: "Generate HANDOFF.md work handover document before session end. Auto-activates on handoff, handover, session cleanup keywords."
 triggers: [handoff, handover, session cleanup, session end, context save]
-priority: 70
+priority: 60
 ---
 
 # Handoff — Session Handover Document

package/skills/parallel-research/SKILL.md

@@ -22,41 +22,27 @@ Parallel research patterns for solving complex problems.
 | Technology selection | Comparison analysis needed |
 | Complex bugs | Explore multiple causes |
 
-## Research Agents (4 Parallel)
+## Research Lenses (4 Parallel)
 
-| Agent | Role | Tools |
-|-------|------|-------|
-| best-practices | Search best practices | Web Search, context7 |
-| framework-docs | Search official docs | context7 |
-| codebase-patterns | Analyze existing code patterns | Grep, Glob |
-| security-advisory | Search security advisories | Web Search |
+| Lens | Role | How |
+|-------|------|-----|
+| best-practices | Search best practices | native WebSearch (+context7) |
+| framework-docs | Search official docs | native WebFetch/context7 |
+| codebase-patterns | Analyze existing code patterns | native Explore subagent |
+| security-advisory | Search security advisories | native WebSearch |
 
-## Usage Methods
+## Usage
 
-### Method 1: Direct Orchestrator Call
+**Spawn the four lenses as concurrent native subagents in a single message** — each lens is blind to the others; synthesize after all return:
 
-```bash
-node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/infra/orchestrator/index.js').then(o =>
-  o.research('passkey authentication', ['React', 'Supabase'])
-  .then(r => console.log(r.content[0].text))
-)"
 ```
-
-### Method 2: Use /vibe.spec
-
-```
-/vibe.spec "feature-name"
-→ Parallel research runs automatically after requirements confirmed
+Task 1 (Explore): "Analyze existing auth code patterns"          (concurrent)
+Task 2 (general-purpose): "Search React auth best practices"     (concurrent)
+Task 3 (general-purpose): "Search Supabase Auth official docs"   (concurrent)
+Task 4 (general-purpose): "Search auth security vulnerabilities" (concurrent)
 ```
 
-### Method 3: Parallel Task Tool Execution
-
-```
-Task 1: "Search React auth best practices"
-Task 2: "Search Supabase Auth official docs" (concurrent)
-Task 3: "Analyze existing auth code patterns" (concurrent)
-Task 4: "Search auth security vulnerabilities" (concurrent)
-```
+`/vibe.spec "feature-name"` runs this automatically when the SPEC pass needs unfamiliar-technology research.
 
 ## Using Research Results
 

package/skills/priority-todos/SKILL.md

@@ -4,7 +4,7 @@ user-invocable: false
 invocation: [auto]
 tier: standard
 description: "Priority-based TODO management (P1/P2/P3). Auto-activates when managing tasks, reviewing issues, or organizing work by priority."
-triggers: [todo, priority, P1, P2, P3, task management, issue, organize]
+triggers: [todo list, task management, P1, P2, P3, priority todos, organize tasks]
 priority: 60
 ---
 

package/skills/regress/SKILL.md

@@ -14,6 +14,17 @@ tier: core
 
 A classic vibe-coding weakness: LLMs reintroduce bugs of the same class. Regression tests are the only mechanical defense. But if the human has to write the test every time, it gets skipped — so automate.
 
+## Characterization — lock behavior first
+
+Before modifying legacy or untested code whose behavior is uncertain (large files without tests, complex branching, API contracts), **lock current behavior first, then change**:
+
+1. Generate characterization tests over the public surface — snapshot the **actual** output (`toMatchSnapshot()`), not what you think it should be. Do NOT fix bugs while locking: a wrong value gets locked as-is; the goal is regression detection, not correctness.
+2. Run them — all must pass against the unmodified code. A failure means the characterization is wrong: fix the test, never the code.
+3. Make the change incrementally, re-running after each step. Unexpected failure = regression, stop and investigate.
+4. Reconcile: update snapshots only for **intentionally** changed behavior, and add new tests for the new behavior.
+
+Skip this for code you just wrote, already-well-tested code, or trivial changes — write regular unit tests instead. Test file naming/stack detection follows `generate` (below).
+
 ## Storage Contract
 
 ```

package/skills/restraint/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: restraint
+user-invocable: false
+invocation: [auto]
+tier: core
+description: "Restraint gate — block premature abstraction and premature optimization. Escalate the YAGNI ladder only on demonstrated need; optimize only on measured evidence. Merges yagni-ladder + rob-pike."
+triggers: [premature optimization, premature abstraction, abstraction layer, helper module, utility class, wrapper class, manager class, config system, cache layer, parallelize, benchmark]
+priority: 60
+---
+
+# Restraint — Don't Write It, Don't Tune It (Yet)
+
+Two constraints, one gate:
+
+- **No premature code.** New abstractions must be *pulled* by a demonstrated
+  need, never pushed by "might need it later." Once the code exists, deleting
+  it costs more than never writing it.
+- **No premature optimization.** Performance work must be *pulled* by a
+  measurement, never by a hunch.
+
+## The YAGNI Ladder (code axis)
+
+Satisfy the need at the **highest** rung that covers it; lower rungs are
+blocked while a higher one applies:
+
+1. **Not needed** — the requirement doesn't ask for it → don't build it
+2. **Stdlib / built-ins** already do it (`crypto`, `Intl`, `pathlib`, …)
+3. **Native platform feature** does it (`<input type="date">`, CSS `:has()`, DB constraints)
+4. **Already-installed dependency** covers it — check the lockfile, don't guess
+5. **One line** — a single expression; no new file, no class
+6. **Minimal code** — only now, and nothing for "later"
+
+Tie-break: native beats a one-liner; stdlib beats a dependency. Generalize
+only when a *second* caller exists.
+
+## Pike's Rules (optimization axis)
+
+- You can't tell where a program spends its time — bottlenecks surprise.
+  **Measure; don't guess.**
+- Don't tune until one part *measurably* overwhelms the rest.
+- Fancy algorithms are slow when n is small — and n is usually small.
+  Ask "what's n?" before "what's the Big-O?"
+- Simple algorithms + the right data structures beat clever code. Data dominates.
+
+Optimization is justified only when ALL hold: a measured bottleneck exists →
+it dominates runtime → the fix is the simplest change addressing it → you
+re-measure after.
+
+## Blocked Impulses
+
+| Impulse | Constraint | Counter |
+|---|---|---|
+| helper / utility / wrapper / manager class | rungs 1–5 | a stdlib call or one line usually suffices |
+| config system for one value | rung 1 | a `const` is the config |
+| generic `Processor(strategy, validator…)` | rung 1 | one concrete function until a second caller exists |
+| "add a cache here" / "parallelize this" | measure first | is this path even hot? Often it's I/O |
+| swap in a B-tree / trie / skip list | what's n? | O(n²) with n=100 is microseconds |
+| "this loop looks slow" | measure first | the bottleneck is probably elsewhere |
+
+## Overrides — Restraint Never Erodes These
+
+1. **Security and trust-boundary work are requirements**, not optional
+   complexity. Input validation, auth checks, escaping stay in — "one line"
+   is no excuse to drop them.
+2. **Deliberate simplifications get a comment + upgrade path**, so the next
+   reader sees a *choice*, not an oversight:
+
+   ```ts
+   // Global lock is enough at current throughput.
+   // Switch to per-account locking if write contention shows up.
+   const lock = new Mutex();
+   ```

package/skills/seo-checklist/SKILL.md

@@ -3,8 +3,8 @@ name: seo-checklist
 invocation: [auto]
 tier: core
 description: "SEO gotchas for web development — easy-to-miss items that hurt search ranking. Covers meta tags, Open Graph, structured data (JSON-LD), sitemap, robots.txt, canonical URLs, and Naver/Google-specific requirements. Use when building or reviewing any public-facing web page, landing page, or marketing site. Must use this skill when user mentions SEO, search ranking, meta tags, or when deploying a web app that needs to be discoverable."
-triggers: [seo, search, meta, sitemap, schema, structured data, og, opengraph, google, naver]
-priority: 65
+triggers: [seo, meta tags, sitemap, structured data, opengraph, search ranking, robots.txt, naver]
+priority: 60
 ---
 
 # SEO Checklist