@su-record/vibe 3.0.0 → 3.2.0

package/skills/clone/references/capture-rules.md

@@ -0,0 +1,48 @@
+# Clone — Phase 1 Capture Output & Rules
+
+> Loaded by vibe.clone SKILL.md Phase 1 (Capture) — full per-breakpoint output directory listing and the deterministic capture rule set.
+
+### Output per breakpoint
+
+```
+/tmp/{feature}/{bp}/
+  ├── rendered.html       — final DOM after JS execution
+  ├── computed.json       — per-element computed CSS + bounding box
+  ├── screenshot.png      — full-page screenshot
+  ├── states.json         — non-default state rules (hover/focus/active/checked/tab/aria/data-state)
+  ├── behaviors.json      — ACTIVE sweep: scroll / tab / hover / in-view / time-driven + scrollLib
+  ├── assets/
+  │   ├── images/         — all <img>, background-image, <picture> sources
+  │   ├── fonts/          — @font-face srcs
+  │   └── seo/            — favicons, apple-touch-icons, OG images, webmanifest
+  └── asset-map.json      — remote URL → local path mapping
+```
+
+### Capture rules
+
+```
+1. Wait for `networkidle2` (no in-flight requests for 500ms) before snapshot
+2. Scroll to bottom slowly to trigger lazy-loaded content
+3. Resolve all <img src>, srcset, and computed background-image URLs
+4. Resolve @font-face src() URLs from all stylesheets
+5. Download assets in parallel (concurrency=8), preserve original extensions
+6. Rewrite asset URLs in rendered.html and computed.json to local paths
+7. Strip inline analytics/tracking scripts before saving rendered.html
+8. Harvest non-default state rules from all stylesheets → states.json
+   (deterministic: read :hover/:focus/:active/:checked/[aria-*]/[data-state]/.is-*/.active/
+    .scrolled/.sticky/.pinned/… declarations straight from CSS — NO scripted clicking)
+9. ACTIVE interaction sweep → behaviors.json (runs after lazy-load, before freeze).
+   Drives the live page to capture JS-set state that CSS harvesting can't see:
+   - Scroll-state diff: tag sticky/fixed/top-bar headers+nav, snapshot computed CSS at
+     scroll 0, scroll past threshold, re-snapshot, diff → {prop: {from, to}, triggerScrollY}
+   - Tab groups: click tab-like sibling sets, detect whether content swaps on click
+   - Hover diff: hover interactive elements (1 sample per tag+class signature, max 30),
+     diff computed styles → JS-set hover states that :hover harvesting misses
+   - In-view entrance: fresh reload, tag below-fold "waiting to animate" nodes
+     (opacity 0 / transform offset), scroll each into view, diff → fade-up/slide-in
+   - Time-driven: 3s no-input MutationObserver watch → carousel/auto-cycle candidates
+   - Scroll-lib detection: Lenis / Locomotive Scroll (native scrolling feels different —
+     the user spots it immediately; wire the lib page-level, not per-section)
+   Disable with --no-interact (restores the old fully-deterministic, screenshot-stable capture).
+10. SEO asset harvest: favicon / apple-touch-icon / webmanifest / og:image → assets/seo/
+```

package/skills/clone/references/legal-and-error-recovery.md

@@ -0,0 +1,40 @@
+# Clone — Legal & Ethical Notes + Error Recovery
+
+> Loaded by vibe.clone SKILL.md — full legal/ethical usage notes and the Error Recovery troubleshooting table.
+
+## Legal & Ethical Notes
+
+```
+This skill is intended for:
+  ✅ "Clone coding" learning exercises (markup/layout study)
+  ✅ Rebuilding the user's own previously-deployed sites
+  ✅ Authorized redesigns where the user has rights to the source
+
+NOT intended for:
+  ❌ Republishing copyrighted content (text, images, logos) without permission
+  ❌ Deceptive look-alike sites (phishing, brand impersonation)
+  ❌ Bypassing robots.txt or rate-limiting protections
+
+Claude must:
+  - Replace copyrighted text content with placeholders (e.g. "[Lorem ipsum]") by default
+  - --real-content: ask ONE explicit confirmation (site ownership / permission) before
+    Phase 3; on confirmation keep text verbatim (clone-spec.js --real-content)
+  - Skip and warn when robots.txt disallows fetching the target path
+  - Refuse if the user's stated intent is brand impersonation or deception
+```
+
+## Error Recovery
+
+| Failure | Recovery |
+|---------|----------|
+| clone-extract.js Puppeteer launch failure | Verify Node ≥18 and that Chromium is installed (`npx puppeteer browsers install chrome`). Retry once. |
+| Target site blocks headless (403/Cloudflare) | Retry with `--stealth` flag (uses puppeteer-extra stealth plugin). If still blocked, report to user. |
+| Asset download 404 | Log to asset-map.json with `status: missing`. Use a 1×1 transparent placeholder. Continue. |
+| robots.txt disallows path | Halt Phase 1. Inform user; require explicit `--ignore-robots` flag to proceed. |
+| clone-refine.js produces empty sections | Site likely uses Shadow DOM or canvas rendering. Report and ask whether to fall back to screenshot-only mode. |
+| Pixel diff stuck > 0.05 after 5 rounds | Likely font fallback or anti-aliasing. Report metric, allow user to accept threshold. |
+| Interaction model guess wrong (Phase 5) | section.interaction is a static-DOM heuristic. Re-observe the live site, correct the model in the spec, rebuild the section for the confirmed model. |
+| states.json empty but site has hover/tabs | States may be set via inline JS, not CSS rules. Check behaviors.json (active sweep captures scroll/tab JS state). If still missing, note in the spec and capture manually during Phase 5. |
+| behaviors.json missing or empty | Active sweep was disabled (--no-interact), hit no sticky/tab elements, or errored (logged, non-fatal). Falls back to static states.json. Re-run without --no-interact to retry. |
+| clone-merge-responsive.js reports many mo-only/pc-only selectors | Section detection diverged between BPs (layout differs structurally). Expected for hidden-on-mobile elements; verify each against the two sections.json trees and gate with the media query manually if needed. |
+| Merged build fails Phase 5 at one viewport only | The merge dropped or mis-bucketed a declaration. Diff the failing viewport's computed CSS against its sections.json; fix in the merged SCSS with that evidence. |

package/skills/clone/references/refine-rules.md

@@ -0,0 +1,61 @@
+# Clone — Phase 2 Refinement Rules & Output Schema
+
+> Loaded by vibe.clone SKILL.md Phase 2 (Refine) — full refinement rule set and the sections.json output schema.
+
+### Refinement rules
+
+```
+Refinement applied when converting rendered.html + computed.json → sections.json:
+  1. Strip <script>, <noscript>, <style>, tracking pixels
+  2. Strip nodes with display:none, visibility:hidden, opacity:0, size 0
+  3. Detect sections: <header>, <nav>, top-level <section>/<main> children, <footer>
+     Fallback: top-level children of <body> with height > 100px
+  4. Detect repeated patterns (sibling nodes with same tag+class signature, count >= 3)
+     → mark as component candidates
+  5. Extract design tokens:
+     - colors: unique color/background-color values, sorted by frequency
+     - typography: font-family/size/weight combinations
+     - spacing: padding/margin values (px), bucketed to nearest 4px
+  6. Background images (background-image: url) → images.bg
+  7. Inline <img> → images.content
+  8. Keep CSS subset: layout (display/flex/grid/position/inset/margin/padding/width/height/gap),
+     typography (font-*, line-height, letter-spacing, text-*, color),
+     decoration (background, border, border-radius, box-shadow, opacity),
+     transform/transition
+  9. Classify interaction model per section (static-DOM heuristic) → section.interaction
+     = { model, confidence, signals[], note }. model ∈ static | click-driven | scroll-driven
+     | time-driven | hover. This is a best-guess + ranked SIGNALS, NOT a silent decision —
+     the builder confirms it against the live site (Phase 5). Misidentifying the interaction
+     model is the #1 clone failure mode (scroll-driven original built as a click UI, etc.).
+ 10. Attach matching state rules from states.json to each section → section.states
+     (rules whose selector references a class/leaf-tag inside that section's subtree)
+```
+
+### Output
+
+```
+/tmp/{feature}/{bp}/sections.json:
+  {
+    meta: { feature, url, viewport, bp },
+    tokens: { colors: [...], typography: [...], spacing: [...] },
+    sections: [
+      {
+        name: "Header" | "Hero" | "Features" | ...,
+        nodeRef, tag, size, css,
+        interaction: {        // static-DOM heuristic — builder confirms in Phase 5
+          model: "static" | "click-driven" | "scroll-driven" | "time-driven" | "hover",
+          confidence: "high" | "medium" | "low",
+          signals: [...],     // ranked evidence (sticky, infinite animation, role=tab, …)
+          note
+        },
+        text,                 // text content (placeholder candidates)
+        components: [...],    // detected repeated patterns
+        states: [             // non-default state rules scoped to this section
+          { selector, media, css }
+        ],
+        children: [...],      // full recursive subtree
+        images: { bg, content: [...] }
+      }
+    ]
+  }
+```

package/skills/clone/references/scaffold-phases.md

@@ -0,0 +1,59 @@
+# Clone — Phase 3A/3B/3C Builder Contract
+
+> Loaded by vibe.clone SKILL.md Phase 3 (Scaffold) — full prep/dispatch/merge steps for MO/PC scaffold, the 150-line split rule, framework mapping, Phase 3C's import-switch/selector-review steps, and Claude's role checklist. Phase headers, Input lines, and script invocation commands stay in SKILL.md; this file covers the supporting detail only.
+
+```
+  Prep (sequential, once):
+    a. Step 0: clone-spec.js → emit _specs/mo/{Section}.spec.md for every section
+    b. Step A: clone-to-scss.js → SCSS draft in styles/{feature}/mo/ (computed values)
+    c. Orchestrator resolves every spec TODO BEFORE dispatch:
+       ├─ Confirm the interaction model (spec.interaction is a heuristic guess;
+       │  the spec's active-capture "Dynamic behaviors" block overrides it on conflict)
+       ├─ List the states to implement (spec.states + Dynamic behaviors)
+       ├─ Mark copyrighted text for placeholder replacement (skip with --real-content)
+       └─ Map component candidates against component-index.json (reuse vs create)
+    d. 150-line split rule (mechanical — wc -l, don't override with "but it's related"):
+       a completed spec over 150 lines means the section is too big for one builder →
+       split into sub-component specs (one per card variant / repeated pattern) + one
+       wrapper spec that imports them.
+  Dispatch (parallel):
+    ⛔ Every builder prompt embeds the FULL spec text INLINE — never "go read the file".
+       The spec file stays on disk as the audit trail; the prompt must be self-sufficient.
+    ⛔ Builders that write files in parallel run in worktree isolation; sub-component
+       builders complete before their wrapper builder starts.
+    Builder contract (each agent):
+      1. Build HTML structure + semantic tags + framework-specific component file
+         ⛔ No CSS in <style> blocks — only @import/@use of styles/{feature}/mo/
+         ⛔ Build for the CONFIRMED interaction model in the spec; wire every state
+         Framework mapping:
+           - React/Next → .tsx with CSS Modules or styled-components per stack
+           - Vue/Nuxt   → .vue with scoped <style lang="scss"> @import only
+           - Svelte     → .svelte with <style> @import only
+           - Vanilla    → .html + linked .scss
+      2. Asset references → public/images/{feature}/ (already populated in Phase 1)
+      3. SCSS edits per Immutable Rule 1 (evidence-cited only)
+      4. Verify compile (tsc --noEmit or stack equivalent) before finishing
+  Merge (orchestrator, as builders complete):
+    5. Merge worktrees; resolve conflicts (you have full context on every spec)
+    6. clone-validate.js per section — Step B
+       ├─ PASS → section done
+       └─ FAIL → fix discrepancies → re-run step 6 (loop until P1=0, no round cap)
+
+  2. Switch component style imports from styles/{feature}/{bp}/index.scss to the merged
+     styles/{feature}/index.scss
+  3. Review pc-only/mo-only selectors in the merge report — hide/show them with the
+     media query if the original does (evidence: the two sections.json trees)
+
+Claude's role:
+  ✅ Component candidates: decide which patterns become reusable components
+  ✅ HTML semantics: section/h1/p/button/nav tag selection
+  ✅ Text replacement: substitute copyrighted copy with placeholders or user-supplied text
+  ✅ Interaction model: confirm the spec's heuristic guess, then build for the real model
+  ✅ Interactions: implement every state in the spec (hover/focus/active/open), click handlers
+  ✅ SCSS value edits WITH cited evidence (computed.json/states.json/behaviors.json) —
+     clone-validate.js PASS is the judge
+  ❌ Do NOT invent CSS values without extraction evidence
+  ❌ Do NOT write CSS directly in <style> blocks
+  ❌ Do NOT hand-write vw/clamp/@media in Phase 3A/3B (responsive comes from Phase 3C merge)
+  ❌ Do NOT hotlink remote URLs — all assets must use local public/images/ paths
+```

package/skills/clone/references/setup-and-layout.md

@@ -0,0 +1,30 @@
+# Clone — Setup Steps & Output Layout
+
+> Loaded by vibe.clone SKILL.md Full Flow / Phase 0 (Setup) — working-directory + code-output layout and the full Phase 0 setup steps.
+
+```
+Working directory:
+  /tmp/{feature}/
+  ├── mo/ (375×812)  — rendered.html, computed.json, screenshot.png, assets/, sections.json
+  ├── pc/ (1440×900) — rendered.html, computed.json, screenshot.png, assets/, sections.json
+  └── tokens.json    — extracted design tokens (colors/fonts/spacing)
+
+Code output: placed directly in the project directory per detected stack
+  components/{feature}/, components/{feature}/_specs/{mo,pc}/,
+  styles/{feature}/{mo,pc}/ (per-BP drafts) → styles/{feature}/ (Phase 3C merged),
+  public/images/{feature}/, public/ (favicons/OG from assets/seo/)
+```
+
+```
+1. Stack detection:
+   - .vibe/config.json → stack (react/vue/next/svelte/vanilla, scss/tailwind/css-modules)
+   - Fallback: package.json deps
+2. Feature name: URL hostname → kebab-case (e.g. stripe.com → stripe-clone)
+   - User may override with --name=<custom>
+3. Directories:
+   - components/{feature}/, styles/{feature}/, public/images/{feature}/
+4. Component indexing → /tmp/{feature}/component-index.json
+   (scan up to 50 existing components, extract props/slots/classes, within 2 minutes)
+5. Design token scan → /tmp/{feature}/project-tokens.json
+   (SCSS > CSS Variables > Tailwind > CSS-in-JS)
+```

package/skills/docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docs
-description: 프로젝트 문서 생성 본체 — README / 아키텍처 / 사용자 가이드 / 릴리즈 노트.
+description: 프로젝트 문서 생성 본체 — README / 아키텍처 / 사용자 가이드 / 릴리즈 노트 / Mermaid 다이어그램 / codemaps.
 when_to_use: /vibe.docs 진입점에서 체인 호출. 직접 호출 금지.
 user-invocable: false
 tier: standard
@@ -179,6 +179,41 @@ Output: `RELEASE_NOTES.md` or append to `CHANGELOG.md`
 - refactor/docs/chore items
 ```
 
+### `/vibe.docs diagram` — Diagram Generation
+
+Generate Mermaid diagrams for architecture, ERD, flowchart, or sequence
+visualization directly (native capability — no dedicated agent). Ground the
+diagram in sources first: folder structure and imports for architecture;
+`models/`, `migrations/`, `schema.*`, ORM definitions for ERDs; the real
+branch/return structure of the code for flowcharts.
+
+**Options:**
+- `/vibe.docs diagram` (default): Architecture overview
+- `/vibe.docs diagram --er`: Entity-Relationship Diagram
+- `/vibe.docs diagram --flow`: Flowchart
+- `/vibe.docs diagram --seq`: Sequence Diagram
+
+> Read `references/diagram-spec.md` for the full output conventions (Mermaid syntax per diagram type, save location, accuracy constraints).
+
+**Example:**
+```
+/vibe.docs diagram --er
+```
+
+### `/vibe.docs codemaps` — Codemaps Generation
+
+Generate auto-documentation from codebase structure directly (native
+capability — no dedicated agent).
+
+**Output Location:** `docs/CODEMAPS/`
+
+> Read `references/codemaps-output.md` for the full generated-files tree, per-file contents, and tools used.
+
+**Example:**
+```
+/vibe.docs codemaps
+```
+
 ## Pipeline Integration
 
 `/vibe.docs` completes the development pipeline:
@@ -202,9 +237,9 @@ When `/vibe.trace` completes with all scenarios passing, suggest:
 - Preserve existing documentation that's still accurate
 - Include concrete code examples from the actual project
 - Keep language consistent with project (Korean/English based on CLAUDE.md)
-- Use documenter agent (changelog mode) for `/vibe.docs release`
-- Use documenter agent (api-docs mode) for API-heavy projects
-- Use diagrammer agent for `/vibe.docs arch` Mermaid generation
+- For `/vibe.docs release` (changelog mode), follow `references/api-docs-changelog.md` natively — no dedicated agent
+- For API-heavy projects (api-docs mode), follow `references/api-docs-changelog.md` natively
+- For `/vibe.docs arch` and `/vibe.docs diagram` Mermaid generation, follow `references/diagram-spec.md` natively
 - Use the `agents-md` skill for `/vibe.docs agent` — applies equally to CLAUDE.md and AGENTS.md
 
 ### DON'T

package/skills/docs/references/api-docs-changelog.md

@@ -0,0 +1,34 @@
+# docs — API Docs & Changelog Spec
+
+> Loaded by docs SKILL.md for `/vibe.docs release` (changelog mode) and API-heavy projects (api-docs mode) — documentation rules for the two artifacts that go stale fastest: API docs and changelogs.
+
+## API Mode
+
+Walk the route handlers/controllers in the given scope and document each
+endpoint: method + path, auth requirement, parameters (path/query/body with
+types, required vs optional, enum values), success and error responses (all
+status codes actually returned), and a runnable example (curl or fetch). List
+endpoints that exist in code but lack documentation — the gap list is as
+valuable as the docs.
+
+## Changelog Mode
+
+From `git diff` and `git log`, classify changes as breaking / added /
+changed / fixed / performance / internal / dependencies. Recommend the
+semantic version bump with a one-line reason. Every breaking change gets
+migration steps; every fix states old vs new behavior.
+
+## Constraints
+
+Return documentation as text output only — never create or write files; the
+calling command decides where content lands. Descriptions are user-facing:
+what changed for the consumer, not which internal function was refactored
+(pure refactors go under Internal, briefly). Document what the code actually
+does, not what comments claim — when they disagree, flag the discrepancy
+rather than picking one silently.
+
+## Done
+
+- API mode: every endpoint in scope documented or explicitly listed as an undocumented gap
+- Changelog mode: all changes classified, version bump recommended with reason, breaking changes have migration steps
+- Output is paste-ready text; zero files created

package/skills/docs/references/codemaps-output.md

@@ -0,0 +1,23 @@
+# docs — Codemaps: Generated Files & Contents
+
+> Loaded by docs SKILL.md `codemaps` mode — full generated-files tree, per-file contents, and tools used.
+
+**Generated Files:**
+```
+docs/CODEMAPS/
+├── INDEX.md          # Overview of all areas
+├── frontend.md       # Frontend structure
+├── backend.md        # API/backend structure
+├── database.md       # Schema documentation
+└── integrations.md   # External services
+```
+
+**Each file contains:**
+- Module table (name, path, description)
+- Data flow diagram (Mermaid)
+- Dependencies list
+- Related areas
+
+**Tools Used:**
+- ts-morph (TypeScript AST)
+- madge (dependency graph)

package/{agents/diagrammer.md → skills/docs/references/diagram-spec.md}

@@ -1,19 +1,6 @@
-# Diagrammer Agent
+# docs — Diagram Generation Spec
 
-Diagram generation specialist — renders architecture, data models, and flows
-as Mermaid.
-
-## Role
-
-- Architecture diagrams from project structure and dependencies
-- ERD from database schemas and model definitions
-- Flowcharts of business logic and user flows
-
-## Model
-
-**Haiku** — fast, structured output
-
-## Goal
+> Loaded by docs SKILL.md `diagram` mode — Mermaid diagram generation rules (architecture, ERD, flowcharts, sequence).
 
 Produce a Mermaid diagram that reflects the actual code, not a generic
 picture. Ground it in sources first: folder structure and imports for

package/skills/exec-plan/SKILL.md

@@ -129,7 +129,7 @@ Ready to execute:
   /vibe.run "{feature-name}" ultrawork
 
 Or hand off to new session:
-  /vibe.utils --continue
+  /vibe.continue
   → Load: .vibe/specs/{feature-name}-execplan.md
 ```
 

package/skills/exec-plan/templates/plan.md

@@ -144,4 +144,4 @@ save_memory("execplan-{{FEATURE_NAME}}", {
 })
 ```
 
-Resume: `/vibe.utils --continue` → load this file.
+Resume: `/vibe.continue` → load this file.

package/skills/handoff/SKILL.md

@@ -16,9 +16,9 @@ Record work status before session end so the next session can pick up immediatel
 
 A file that records the current work status before context reset. Reading this file in a new session allows immediate continuation.
 
-### Difference from `/vibe.utils --continue`
+### Difference from `/vibe.continue`
 
-| Item | `/vibe.utils --continue` | Handoff |
+| Item | `/vibe.continue` | Handoff |
 |------|--------------------------|---------|
 | Method | Automatic session context restore | Manual handover document |
 | Includes | Memory + session state | Work progress + notes + file list |
@@ -98,7 +98,7 @@ Read HANDOFF.md and continue working
 Or use alongside VIBE auto-restore:
 
 ```
-/vibe.utils --continue
+/vibe.continue
 ```
 
 In this case, saved decisions are also restored via `core_recall_memory`.

package/skills/handoff/templates/handoff.md

@@ -86,7 +86,7 @@ Last commit: `{{LAST_COMMIT_HASH}}` — {{LAST_COMMIT_MESSAGE}}
 
 ```bash
 # 1. Load context
-/vibe.utils --continue
+/vibe.continue
 
 # 2. Read this file if context is missing
 # cat HANDOFF.md

package/skills/vibe/SKILL.md

@@ -64,13 +64,14 @@ user-invocable: true
 | **regression fix** | "회귀", "테스트 깨졌", "다시 통과" | regress → run → verify |
 | **contract drift** | "API 변경", "계약 깨졌", "스펙 불일치" | contract → regress (P1만) |
 | **scaffold** | "프로젝트 만들기", "셋업", "초기 구조" | scaffold |
-| **docs sync** | "문서 갱신", "README", "AGENTS.md" | docs |
+| **docs sync** | "문서 갱신", "README", "AGENTS.md", "다이어그램", "코드맵" | docs (diagram/codemaps 의도 포함) |
 | **analyze** | "분석", "조사", "이건 뭐야" + 파일/URL | analyze |
 | **reason** | "추론", "깊게 생각", "트레이드오프", "어떻게 접근" 등 복잡한 사고 요청 | reason |
 | **event** | "이벤트", "커뮤니티", "D-Day", "행사 자동화" | event |
 | **harness check** | "하네스", "환경 점검" | harness |
 | **test self** | "vibe 테스트", "CC ↔ Codex 비교" | test |
-| **utils** | "이어서", "메모리", "체크포인트" | utils |
+| **session continue** | "이어서", "메모리", "체크포인트" | continue |
+| **image generation** | "이미지 생성", "아이콘", "배너", "목업 이미지" | image |
 
 복수 의도면 우선순위: resume > figma-driven > new feature > 기타.