solmate-skills 2.0.6 → 2.0.8

package/AGENTS.md

@@ -65,6 +65,14 @@
 - **검증 위치**: SVG가 최신 UI·API·DB 구조와 일치하는지 여부는 `docs/05_QA_Validation/`의 QA 체크리스트 또는 검증 문서에서 확인한다.
 - **파일 네이밍**: SVG 파일명에도 순번과 목적을 포함한다. (예: `01_user_journey.svg`, `02_auth_data_flow.svg`)
 
+### 2.8. HTML UI Preview Gate (필수)
+- **HTML Preview 필수화**: `docs/02_UI_Screens/`의 UI 문서는 Markdown 설명만으로 완료할 수 없다. 주요 화면과 사용자 흐름은 반드시 브라우저에서 열어볼 수 있는 HTML Preview로 제작한다.
+- **저장 위치**: HTML Preview는 `docs/02_UI_Screens/previews/`에 저장한다.
+- **파일 네이밍**: HTML 파일명에도 순번과 목적을 포함한다. (예: `01_main_flow_preview.html`, `02_dashboard_preview.html`)
+- **문서 링크 필수**: `00_SCREEN_FLOW.md`, `01_UI_DESIGN.md`, 관련 `XX_PROTOTYPE_REVIEW.md`는 해당 HTML Preview를 상대 경로로 링크해야 한다.
+- **사용자 커뮤니케이션 필수**: 구현 전 HTML Preview를 사용자에게 보여주고 피드백을 받아야 하며, 확인 결과와 보완 사항을 UI 문서 또는 `docs/04_Logic_Progress/00_BACKLOG.md`에 기록한다.
+- **구현 차단 조건**: HTML Preview가 없거나 문서에 링크되지 않았거나 사용자의 화면 확인 기록이 없으면 UI-First Gate를 통과할 수 없고, 구현을 시작할 수 없다.
+
 ## 3. 개발 표준 및 품질
 - **UI 중심 개발 전략 (UI-First)**: Concept_Design -> UI_Screens -> Technical_Specs -> Logic_Progress 순서를 따른다.
 - **git commit 필수**: 중요 작업 전 반드시 git commit을 수행한다.
@@ -96,7 +104,7 @@ AI 에이전트는 본 프로젝트에 설치된 다음 **26개 스킬**을 활
 | | `docs-business` | 사업계획서 작성 (정부 지원, 투자 심사, 파트너십 목적별 구성) |
 | **품질 검증 (QA)** | `verify-implementation` | 모든 `verify-*` 스킬의 통합 순차 실행 및 보고 |
 | | `verify-docs` | 문서 레이어 정합성 및 네이밍/메타데이터, UI-First Gate 검증 |
-| | `verify-ui` | 구현 UI와 화면 문서·사용자 동선·상태별 UI 정합성 검증 |
+| | `verify-ui` | 구현 UI와 화면 문서·HTML Preview·사용자 동선·상태별 UI 정합성 검증 |
 | | `verify-code` | PR 전 코드 품질 종합 리뷰 (로직, 타입, 중복, 사이드 이펙트) |
 | | `verify-security` | OWASP Top 10 기준 보안 취약점 점검 (인증, 인젝션, 시크릿 노출 등) |
 | | `verify-performance` | Lighthouse·Core Web Vitals 기준 성능 점검 (LCP, CLS, 번들, 이미지) |
@@ -121,7 +129,7 @@ AI 에이전트는 사용자가 스킬을 호출하지 않아도, 아래 상황
 | 기술 선택, DB/API/아키텍처 설계 논의 시작 | `manage-decisions` | "결정이 필요한 상황입니다. `/manage-decisions`로 유형별 질문을 진행할까요?" |
 | 보안·인증·인가·환경변수 관련 코드 작성 전후 | `verify-security` | "보안 관련 변경입니다. `/verify-security`로 OWASP 점검을 실행할까요?" |
 | 성능·렌더링·이미지·번들 관련 작업 완료 후 | `verify-performance` | "성능 영향이 있을 수 있습니다. `/verify-performance`로 Lighthouse 점검을 실행할까요?" |
-| UI·화면·컴포넌트 구현 완료 후 | `verify-ui` | "UI 구현 변경입니다. `/verify-ui`로 화면 문서와 사용자 동선 정합성을 검증할까요?" |
+| UI·화면·컴포넌트 구현 완료 후 | `verify-ui` | "UI 구현 변경입니다. `/verify-ui`로 HTML Preview·화면 문서·사용자 동선 정합성을 검증할까요?" |
 | PR 생성 전, 코드 변경 완료 후 | `verify-code`, `verify-implementation` | "PR 전 최종 점검입니다. `/verify-implementation`으로 전체 검증을 실행할까요?" |
 | 기획·UI 문서 작성 요청 | `docs-plan` | "Layer 1-2 문서 작성은 `/docs-plan`을 사용하세요." |
 | DB 스키마·API 명세·백로그 작성 요청 | `docs-dev` | "Layer 3-5 문서 작성은 `/docs-dev`를 사용하세요." |

package/README.md

@@ -1,40 +1,55 @@
 # solmate-skills
 
-Curated skills for Solmate projects. Easily share and install AI tool skills across your team.
+Reusable AI-agent skills for disciplined product work.
 
-## What's New in 2.0.6
+`solmate-skills` packages the Solmate workflow as installable skills: plan the product, create browser-viewable UI previews, lock backlog tasks to their source documents, implement with approval gates, and verify the result before release.
 
-`solmate-skills@2.0.6` keeps **Backlog Context Lock** as the current documentation guardrail, adds **UI-First Gate** expectations, formalizes SVG diagram outputs, and fixes package hygiene so installable skill scripts are included in the npm tarball.
+Use it when you want an AI coding agent to follow a shared workflow instead of improvising project structure, documentation, implementation order, and QA.
 
-Key changes:
+## Install
 
-- Every backlog task must link to related Concept, UI, Technical Spec, and QA documents.
-- UI, user paths, data flow, loading states, empty states, and error states must be confirmed before coding.
-- User journey SVG files belong in `docs/02_UI_Screens/assets/`.
-- Data flow SVG files belong in `docs/03_Technical_Specs/assets/`.
-- `/rules-workflow` now treats linked backlog documents as implementation inputs before coding starts.
-- `/verify-docs` fails backlog items that omit required related-document fields.
-- Local Codex settings under `.codex/` are excluded from the npm package, while skill-owned shell scripts remain publishable.
-
-## Installation
-
-You don't need to install this package globally. Simply use `npx`:
+You do not need a global install. Run it with `npx` from the root of the project where you want the skills installed:
 
 ```bash
 # List available skills
-npx solmate-skills list
+npx solmate-skills@latest list
 
-# Install all available skills (use @latest to bypass npx cache)
+# Install every skill
 npx solmate-skills@latest install all
 
+# Install one skill
+npx solmate-skills@latest install rules-product
+
 # Install proactive hook suggestions for Claude Code projects
 npx solmate-skills@latest install hooks
-
-# Install a specific skill
-npx solmate-skills install rules-docs
 ```
 
-When you run the `install` command, the script copies the skill folder to `.agent/skills/<skill-name>` in your current project.
+The installer copies each selected skill folder into `.agent/skills/<skill-name>` in your current project.
+
+## What You Get
+
+- **Product workflow orchestration**: `/rules-product` diagnoses the current phase and routes the agent to the right next skill.
+- **UI-first planning**: `/docs-plan` creates concept and screen documents before implementation starts.
+- **HTML UI Preview Gate**: major screens and flows must have browser-viewable HTML previews under `docs/02_UI_Screens/previews/`.
+- **Backlog Context Lock**: every backlog item must link the Concept, UI, HTML Preview, Technical Spec, and QA documents needed for implementation.
+- **Implementation workflow**: `/rules-workflow` keeps coding work tied to approved documents, preconditions, and acceptance criteria.
+- **Release verification**: `/verify-implementation` runs the verification family for docs, UI, code, security, performance, DB schema, and skill package readiness.
+
+## What's New in 2.0.8
+
+`solmate-skills@2.0.8` refreshes the npm README and package metadata so the package purpose, install path, and core workflow gates are clearer on the npm package page.
+
+Recent workflow guardrails:
+
+- Every backlog task must link to related Concept, UI, HTML Preview, Technical Spec, and QA documents.
+- UI planning must include HTML preview files under `docs/02_UI_Screens/previews/` and link them from the related UI documents.
+- UI, user paths, data flow, loading states, empty states, and error states must be confirmed before coding.
+- User journey SVG files belong in `docs/02_UI_Screens/assets/`.
+- Data flow SVG files belong in `docs/03_Technical_Specs/assets/`.
+- `/rules-workflow` treats linked backlog documents as implementation inputs before coding starts.
+- `/verify-docs` fails backlog items that omit required related-document fields.
+
+## Install Details
 
 `install all` installs only skill folders that contain `SKILL.md`. Use `install hooks` separately when you want prompt/file-change suggestions that nudge the agent toward `/rules-product`, `/rules-workflow`, and the relevant `verify-*` skills.
 
@@ -161,7 +176,7 @@ Skills are organized into five categories.
 | `verify-security` | Check for security vulnerabilities based on OWASP Top 10. |
 | `verify-performance` | Lighthouse & Core Web Vitals check. |
 | `verify-code` | Comprehensive pre-PR code quality review. |
-| `verify-ui` | Verify implemented UI against screen docs and user flows. |
+| `verify-ui` | Verify implemented UI against screen docs, HTML previews, and user flows. |
 | `verify-skills` | Verify skill package metadata, CLI output, and release readiness. |
 
 ---
@@ -195,13 +210,14 @@ docs/
 
 ```
 1. /docs-plan    → Write VISION_CORE.md, LEAN_CANVAS.md, PRODUCT_SPECS.md
-2. /docs-plan    → Write SCREEN_FLOW.md, UI_DESIGN.md
-3. UI-First Gate → Confirm screens, user paths, data flow, and UI states before coding
-4. Pre-Code Technical Brief → Confirm data sources, API shape, state strategy, and acceptance criteria
-5. /docs-dev     → Write DEVELOPMENT_PRINCIPLES.md, DB_SCHEMA.md, API_SPECS.md
-6. /docs-dev     → Write ROADMAP.md, BACKLOG.md with mandatory related document links
-7. /rules-workflow → Implement each backlog item only after reading linked docs and passing UI-First Gate
-8. /verify-implementation  → Audit docs, UI, code, security, performance, DB, and skill package changes
+2. /docs-plan    → Write SCREEN_FLOW.md, UI_DESIGN.md, and HTML UI previews
+3. HTML UI Preview Gate → Show browser-viewable HTML screens and capture user feedback
+4. UI-First Gate → Confirm screens, user paths, data flow, and UI states before coding
+5. Pre-Code Technical Brief → Confirm data sources, API shape, state strategy, and acceptance criteria
+6. /docs-dev     → Write DEVELOPMENT_PRINCIPLES.md, DB_SCHEMA.md, API_SPECS.md
+7. /docs-dev     → Write ROADMAP.md, BACKLOG.md with mandatory related document links
+8. /rules-workflow → Implement each backlog item only after reading linked docs and passing UI-First Gate
+9. /verify-implementation  → Audit docs, UI, code, security, performance, DB, and skill package changes
 ```
 
 Backlog items are intentionally document-linked. Each task in `docs/04_Logic_Progress/00_BACKLOG.md` must include related Concept, UI, Technical Spec, and QA documents, plus implementation preconditions, acceptance criteria, and a document sync check. If a related document does not exist, the item must say `N/A - 사유`; implementation should pause when the missing document is required for a safe decision.
@@ -212,12 +228,30 @@ Backlog Context Lock makes `docs/04_Logic_Progress/00_BACKLOG.md` act as a bridg
 
 ### UI-First Gate
 
-UI-First Gate prevents implementation from starting before the team has reviewed the actual screens and the user's path through them. Before coding, confirm the core screen structure, user entry and exit paths, CTAs, screen-by-screen data flow, loading states, empty states, and error states. If these are missing, update `docs/02_UI_Screens/` or the backlog first.
+UI-First Gate prevents implementation from starting before the team has reviewed the actual screens and the user's path through them. Before coding, confirm the core screen structure, user entry and exit paths, CTAs, screen-by-screen data flow, loading states, empty states, and error states. If these are missing, update `docs/02_UI_Screens/`, its HTML previews, or the backlog first.
+
+### HTML UI Preview Gate
+
+UI planning documents are not complete with Markdown alone. For every major screen or user flow, create a browser-viewable HTML preview and store it under:
+
+```text
+docs/02_UI_Screens/previews/
+```
+
+Recommended naming:
+
+```text
+docs/02_UI_Screens/previews/01_main_flow_preview.html
+docs/02_UI_Screens/previews/02_dashboard_preview.html
+```
+
+Each related UI document must link to the HTML file with a relative path. The preview must be shown to the user before implementation, and feedback must be captured in `XX_PROTOTYPE_REVIEW.md`, `00_SCREEN_FLOW.md`, `01_UI_DESIGN.md`, or the related backlog item.
 
 Required fields for every backlog item:
 
 - `Related Concept Docs`
 - `Related UI Docs`
+- `Related HTML Preview`
 - `Related Technical Docs`
 - `Related QA Docs`
 - `Implementation Preconditions`
@@ -236,6 +270,8 @@ If a related document does not exist, write `N/A - 사유`. Do not leave the fie
   - [Product Specs](../01_Concept_Design/03_PRODUCT_SPECS.md) - feature purpose and user value
 - Related UI Docs:
   - [Screen Flow](../02_UI_Screens/00_SCREEN_FLOW.md) - target screen and interaction flow
+- Related HTML Preview:
+  - [Main Flow Preview](../02_UI_Screens/previews/01_main_flow_preview.html) - browser-viewable UI for user review
 - Related Technical Docs:
   - [API Specs](../03_Technical_Specs/02_API_SPECS.md) - endpoint and data contract
 - Related QA Docs:
@@ -243,6 +279,7 @@ If a related document does not exist, write `N/A - 사유`. Do not leave the fie
 - Implementation Preconditions:
   - [ ] Read all related documents before coding
   - [ ] Confirm screen/UI before coding
+  - [ ] Show the HTML UI preview to the user and capture feedback
   - [ ] Confirm user path and screen-by-screen data flow
   - [ ] Confirm loading, empty, and error states
   - [ ] Confirm implementation scope does not conflict with documented intent

package/docs-dev/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docs-dev
-description: Create and manage development documents for Layer 3 (Technical_Specs), Layer 4 (Logic_Progress), and Layer 5 (QA_Validation). Use when writing DB schema docs, API specs, development principles, roadmaps, backlogs, business logic designs, or test scenarios. Always read existing files before editing. Include Related Documents sections.
+description: Create and manage development documents for Layer 3 (Technical_Specs), Layer 4 (Logic_Progress), and Layer 5 (QA_Validation). Use when writing DB schema docs, API specs, development principles, roadmaps, backlogs, business logic designs, or test scenarios. Enforces backlog links to Concept/UI/HTML Preview/Technical/QA docs before implementation. Always read existing files before editing.
 ---
 
 # Development Documentation Skill
@@ -60,19 +60,21 @@ This skill manages **Layer 3 (Technical_Specs)**, **Layer 4 (Logic_Progress)**,
 
 **Backlog 문서 참조 강제 규칙**: `00_BACKLOG.md`의 모든 작업 항목은 관련 문서를 읽은 뒤 작성해야 하며, 구현자는 코드 작성 전에 해당 문서를 다시 확인해야 한다. 백로그는 단순 ToDo 목록이 아니라 Concept, UI, Technical Spec, QA 기준을 구현으로 연결하는 실행 티켓이어야 한다.
 
-**UI-First Gate 강제 규칙**: 구현 코드는 화면 확인 이후에만 작성한다. 백로그 항목은 관련 UI 문서에서 화면 구조, 사용자 동선, 데이터 흐름, 로딩·빈 상태·오류 상태를 확인했음을 `Implementation Preconditions`에 포함해야 한다. 해당 정보가 없으면 `docs/02_UI_Screens/` 문서부터 보완한다.
+**UI-First Gate 강제 규칙**: 구현 코드는 화면 확인 이후에만 작성한다. 백로그 항목은 관련 UI 문서와 HTML Preview에서 화면 구조, 사용자 동선, 데이터 흐름, 로딩·빈 상태·오류 상태를 확인했음을 `Implementation Preconditions`에 포함해야 한다. 해당 정보가 없으면 `docs/02_UI_Screens/` 문서와 `docs/02_UI_Screens/previews/` HTML 파일부터 보완한다.
 
 **Pre-Code Technical Brief 강제 규칙**: UI 확인 후에도 바로 구현하지 않는다. 데이터 소스, 최소 필드, mutation, 상태 관리 방식, acceptance criteria가 백로그나 기술 문서에 기록되어야 한다. 불명확하면 `docs/03_Technical_Specs/` 문서 또는 백로그 항목을 먼저 보완한다.
 
 Backlog 항목 작성 전 필수 확인 대상:
 - `docs/01_Concept_Design/`: 기능 목적, 사용자 가치, 제품 방향
 - `docs/02_UI_Screens/`: 화면 흐름, UI 상태, 인터랙션
+- `docs/02_UI_Screens/previews/`: 사용자에게 보여줄 HTML UI Preview
 - `docs/03_Technical_Specs/`: API, DB, 데이터 구조, 기술 제약
 - `docs/05_QA_Validation/`: 테스트 기준, 수용 조건, 검증 시나리오
 
 각 Backlog 항목은 다음 필드를 반드시 포함한다:
 - `Related Concept Docs`: 관련 기획/디자인 문서
 - `Related UI Docs`: 관련 화면/플로우 문서
+- `Related HTML Preview`: 관련 HTML 화면 프로토타입
 - `Related Technical Docs`: 관련 기술 명세 문서
 - `Related QA Docs`: 관련 검증 문서
 - `Implementation Preconditions`: 구현 전 반드시 확인할 조건
@@ -85,6 +87,7 @@ Backlog 항목 작성 전 필수 확인 대상:
 - 관련 문서를 실제로 읽었는가?
 - 문서의 요구사항이 Backlog 항목에 반영되어 있는가?
 - 화면 구조와 사용자 동선을 먼저 확인했는가?
+- HTML UI Preview를 사용자에게 보여주고 피드백을 기록했는가?
 - 화면별 입력·출력 데이터와 상태 변화를 확인했는가?
 - 로딩·빈 상태·오류 상태가 UI 문서나 백로그에 반영되어 있는가?
 - 데이터 소스, 최소 필드, mutation, 상태 관리 방식이 정리되었는가?
@@ -188,6 +191,8 @@ Backlog 항목 작성 전 필수 확인 대상:
   - [문서명](../01_Concept_Design/XX_DOCUMENT.md) - 기능 목적/사용자 가치 근거
 - Related UI Docs:
   - [문서명](../02_UI_Screens/XX_DOCUMENT.md) - 화면 흐름/상태/인터랙션 근거
+- Related HTML Preview:
+  - [HTML Preview](../02_UI_Screens/previews/XX_SCREEN_PREVIEW.html) - 사용자 확인용 브라우저 화면
 - Related Technical Docs:
   - [문서명](../03_Technical_Specs/XX_DOCUMENT.md) - API/DB/데이터 구조 근거
 - Related QA Docs:
@@ -195,6 +200,7 @@ Backlog 항목 작성 전 필수 확인 대상:
 - Implementation Preconditions:
   - [ ] 관련 문서 전체 확인 완료
   - [ ] 화면/UI 선확인 완료
+  - [ ] HTML UI Preview 사용자 확인 및 피드백 기록 완료
   - [ ] 사용자 진입·전환·이탈 동선 확인 완료
   - [ ] 화면별 입력·출력 데이터 및 상태 변화 확인 완료
   - [ ] 로딩·빈 상태·오류 상태 확인 완료
@@ -203,6 +209,7 @@ Backlog 항목 작성 전 필수 확인 대상:
   - [ ] 구현 범위와 문서 요구사항 충돌 없음
 - Acceptance Criteria:
   - [ ] 구현 결과가 확인된 화면 구조와 사용자 동선을 따른다
+  - [ ] 구현 결과가 HTML UI Preview와 의도 없이 불일치하지 않는다
   - [ ] 데이터 흐름과 상태 변화가 Pre-Code Technical Brief와 일치한다
   - [ ] QA 기준이 구현 완료 판단에 반영됨
   - [ ] 핵심 사용자 흐름이 검증됨

package/docs-dev/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Development Docs"
-  short_description: "Write technical specs, backlogs, and QA docs"
-  default_prompt: "Use $docs-dev to create technical specs, implementation plans, and QA validation docs."
+  short_description: "Write specs, backlogs, QA, and preview links"
+  default_prompt: "Use $docs-dev to create technical specs, implementation plans, preview-linked backlogs, and QA validation docs."

package/docs-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docs-plan
-description: Create and manage planning documents for Layer 1 (Concept_Design) and Layer 2 (UI_Screens). Use when documenting product vision, lean canvas, product specs, UI design systems, screen flows, or prototype reviews. Ask before writing. Always include Related Documents sections.
+description: Create and manage planning documents for Layer 1 (Concept_Design) and Layer 2 (UI_Screens), including required HTML UI previews under docs/02_UI_Screens/previews/. Use when documenting product vision, lean canvas, product specs, UI design systems, screen flows, HTML prototypes, or prototype reviews. Ask before writing. Always include Related Documents sections.
 ---
 
 # Planning Documentation Skill
@@ -39,6 +39,7 @@ This skill manages **Layer 1 (Concept_Design)** and **Layer 2 (UI_Screens)** —
 **Layer 2 — UI_Screens**
 - `00_SCREEN_FLOW.md` — 전체 사용자 여정, 진입·전환·이탈 흐름, 화면별 데이터 입출력
 - `01_UI_DESIGN.md` — 디자인 시스템, 화면 구조, 상태별 UI, 핵심 CTA
+- `previews/XX_SCREEN_PREVIEW.html` — 브라우저에서 열어볼 수 있는 화면/사용자 흐름 HTML Preview
 - `XX_PROTOTYPE_REVIEW.md` — 페이지별 화면 확인 결과와 구현 전 피드백
 
 ## 3. Interactive Process (Ask Before Write)
@@ -77,7 +78,9 @@ This skill manages **Layer 1 (Concept_Design)** and **Layer 2 (UI_Screens)** —
 18. **User Path**: 사용자는 어디서 진입하고, 어떤 CTA를 누르며, 어디로 이동하거나 이탈하는가?
 19. **Data Flow**: 각 화면에서 필요한 입력 데이터, 표시 데이터, 저장/전송 데이터는 무엇인가?
 20. **State Coverage**: 로딩, 빈 상태, 오류 상태, 권한 없음 상태는 화면에서 어떻게 보이는가?
-21. **Prototype Review**: 사용자가 실제 화면, 스크린샷, 와이어프레임, 또는 프로토타입 리뷰를 먼저 확인했는가?
+21. **HTML UI Preview**: 주요 화면과 사용자 흐름을 `docs/02_UI_Screens/previews/`의 HTML 파일로 제작했는가?
+22. **Preview Links**: `00_SCREEN_FLOW.md`, `01_UI_DESIGN.md`, 관련 `XX_PROTOTYPE_REVIEW.md`에서 HTML Preview를 상대 경로로 링크했는가?
+23. **Prototype Review**: 사용자가 HTML Preview, 실제 화면, 스크린샷, 와이어프레임, 또는 프로토타입 리뷰를 먼저 확인했는가?
 
 ## 4. Templates
 
@@ -143,37 +146,44 @@ This skill manages **Layer 1 (Concept_Design)** and **Layer 2 (UI_Screens)** —
 > Created: YYYY-MM-DD HH:mm
 > Last Updated: YYYY-MM-DD HH:mm
 
-## 1. Prototype Link/Screenshot
-(이미지 또는 작동 프로토타입 링크 첨부)
+## 1. HTML UI Preview
+- Preview: [HTML Preview](./previews/XX_SCREEN_PREVIEW.html)
+- 확인 방식: 브라우저에서 HTML 파일 열람 / 로컬 서버 / 배포 URL
+- 확인 목적: 화면 구조, 사용자 동선, 상태별 UI 커뮤니케이션
 
-## 2. Key User Flows
+## 2. Prototype Link/Screenshot
+(스크린샷, 배포 URL, 또는 추가 작동 프로토타입 링크 첨부)
+
+## 3. Key User Flows
 (이 프로토타입에서 시연된 흐름 설명)
 
-## 3. Screen States
+## 4. Screen States
 - Default:
 - Loading:
 - Empty:
 - Error:
 - Permission denied / unavailable:
 
-## 4. Data Flow
+## 5. Data Flow
 - Inputs:
 - Displayed data:
 - Mutations / saved data:
 - External dependencies:
 
-## 5. User Confirmation
+## 6. User Confirmation
 - 화면/UI 선확인 여부:
+- HTML Preview 확인 여부:
 - 확인자:
 - 확인 일시:
 - 보완 필요 사항:
 
-## 6. Feedback & Improvements
+## 7. Feedback & Improvements
 (구현 전 변경이 필요한 사항)
 
-## 7. Related Documents
+## 8. Related Documents
 - **Concept_Design**: [Product Specs](../01_Concept_Design/03_PRODUCT_SPECS.md) - 사이트맵 및 사용자 플로우
 - **UI_Screens**: [UI Design](./01_UI_DESIGN.md) - 디자인 시스템 및 컴포넌트 가이드라인
+- **UI_Screens**: [HTML Preview](./previews/XX_SCREEN_PREVIEW.html) - 브라우저 확인용 화면 프로토타입
 - **Technical_Specs**: [Related Spec](../03_Technical_Specs/XX_SPEC.md) - 구현 명세 요구사항
 ```
 

package/docs-plan/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Planning Docs"
-  short_description: "Write product vision, concept, and UI docs"
-  default_prompt: "Use $docs-plan to build the product vision, screen flow, and UI planning documents."
+  short_description: "Write product docs and HTML UI previews"
+  default_prompt: "Use $docs-plan to build product vision, screen flow, UI docs, and HTML UI previews."

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "solmate-skills",
-  "version": "2.0.6",
-  "description": "Curated skills for Solmate projects",
+  "version": "2.0.8",
+  "description": "AI workflow skills for UI-first planning, backlog-linked docs, QA, and Solmate projects",
   "main": "bin/cli.js",
   "bin": {
     "solmate-skills": "bin/cli.js"
@@ -10,9 +10,15 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "keywords": [
-    "skills",
+    "ai-skills",
+    "codex",
+    "claude",
+    "workflow",
+    "documentation",
+    "ui-first",
+    "qa",
     "solmate",
-    "antigravity",
+    "skills",
     "automation"
   ],
   "author": "",

package/rules-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rules-docs
-description: Create and manage project documentation according to the 365 Principle (3 Investor Lenses, 6 Rubrics, 5 Documentation Layers) with mandatory cross-layer context linking. Use when the user asks to document features, update documentation, create spec files, or manage project docs. Always include "Related Documents" sections to maintain context continuity across layers.
+description: Create and manage project documentation according to the 365 Principle with mandatory cross-layer context linking, Backlog Context Lock, and HTML UI Preview Gate rules. Use when the user asks to document features, update docs, create spec files, manage project docs, or require browser-viewable UI previews linked from docs/02_UI_Screens/.
 ---
 
 # Documentation Management Skill
@@ -66,19 +66,34 @@ description: Create and manage project documentation according to the 365 Princi
 - `00_ROADMAP.md`: 마일스톤 및 단계별 일정 (Phase별 큰 줄기와 세부 항목 분할)
 - `01_EXECUTION_PLAN.md`: 기술 실행 전략 및 타임라인 (구체적인 구현 스텝 및 체크박스 필수)
 
+### HTML UI Preview Gate (필수)
+
+`docs/02_UI_Screens/`의 UI 문서는 Markdown만으로 완료할 수 없다. 주요 화면과 사용자 흐름은 반드시 브라우저에서 열어볼 수 있는 HTML Preview로 제작하고, 다음 위치에 저장한다.
+
+```text
+docs/02_UI_Screens/previews/
+```
+
+규칙:
+- HTML 파일명은 2자리 순번과 목적을 포함한다. 예: `01_main_flow_preview.html`
+- `00_SCREEN_FLOW.md`, `01_UI_DESIGN.md`, 관련 `XX_PROTOTYPE_REVIEW.md`는 HTML Preview를 상대 경로로 링크한다.
+- HTML Preview는 구현 전 사용자에게 보여주고 피드백을 기록한다.
+- HTML Preview가 없거나 문서에 링크되지 않았거나 사용자 확인 기록이 없으면 UI-First Gate를 통과할 수 없다.
+
 ### Backlog Context Lock (필수)
 
 `docs/04_Logic_Progress/00_BACKLOG.md`의 모든 작업 항목은 다른 레이어의 관련 문서를 구현 입력값으로 연결해야 한다. 백로그는 단독 ToDo가 아니며, 다음 필드를 통해 문서 기반 구현을 강제한다.
 
 - `Related Concept Docs`
 - `Related UI Docs`
+- `Related HTML Preview`
 - `Related Technical Docs`
 - `Related QA Docs`
 - `Implementation Preconditions`
 - `Acceptance Criteria`
 - `Document Sync Check`
 
-각 Related 필드는 상대 경로 링크와 관계 설명을 포함해야 한다. 관련 문서가 없으면 빈칸으로 두지 않고 `N/A - 사유`를 명시한다. 단, 구현 판단에 필요한 Concept, UI, Technical Spec, QA 기준이 아직 문서화되지 않은 경우에는 백로그만으로 구현을 시작할 수 없으며, 먼저 문서 작성 또는 보완 여부를 사용자에게 확인한다.
+각 Related 필드는 상대 경로 링크와 관계 설명을 포함해야 한다. 관련 문서나 HTML Preview가 없으면 빈칸으로 두지 않고 `N/A - 사유`를 명시한다. 단, 구현 판단에 필요한 Concept, UI, HTML Preview, Technical Spec, QA 기준이 아직 문서화되지 않은 경우에는 백로그만으로 구현을 시작할 수 없으며, 먼저 문서 작성 또는 보완 여부를 사용자에게 확인한다.
 
 ### 메타데이터 (필수)
 
@@ -112,13 +127,13 @@ description: Create and manage project documentation according to the 365 Princi
 
 **Concept_Design**: 같은 레이어 문서 + 관련 UI_Screens/Technical_Specs
 
-**UI_Screens**: Concept_Design (Product Specs, UI Design) + 이전/다음 UI_Screens + Technical_Specs
+**UI_Screens**: Concept_Design (Product Specs, UI Design) + 이전/다음 UI_Screens + HTML Preview + Technical_Specs
 
 **Technical_Specs**: Concept_Design + UI_Screens + 다른 Technical_Specs (DB ↔ API) + Logic_Progress
 
 **Logic_Progress**: Concept_Design + UI_Screens + Technical_Specs (DB, API) + QA_Validation
 
-**Backlog Items**: 각 항목 단위로 Concept_Design + UI_Screens + Technical_Specs + QA_Validation 링크를 포함한다. 구현자는 항목 착수 전 링크된 문서를 읽고 `Implementation Preconditions`를 확인해야 한다.
+**Backlog Items**: 각 항목 단위로 Concept_Design + UI_Screens + HTML Preview + Technical_Specs + QA_Validation 링크를 포함한다. 구현자는 항목 착수 전 링크된 문서와 HTML Preview를 확인하고 `Implementation Preconditions`를 확인해야 한다.
 
 **QA_Validation**: 모든 상위 레이어 참조
 

package/rules-docs/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Documentation Rules"
-  short_description: "Apply the five-layer documentation standard"
-  default_prompt: "Use $rules-docs to decide where a document belongs and how it should link context."
+  short_description: "Apply docs, links, and HTML preview rules"
+  default_prompt: "Use $rules-docs to decide where docs, HTML previews, and related links belong."

package/rules-product/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rules-product
-description: Orchestrates the full product development pipeline from planning to development docs. Diagnoses current project phase, checks gate conditions, and delegates to the correct sub-skill at each step. Use this as the entry point for new projects or when resuming work mid-flow.
+description: Orchestrates the full product development pipeline from planning to development docs. Diagnoses current project phase, checks gate conditions including HTML UI Preview Gate and UI-First Gate, and delegates to the correct sub-skill at each step. Use this as the entry point for new projects or when resuming work mid-flow.
 ---
 
 # Product Workflow Orchestrator
@@ -12,6 +12,7 @@ You are a **workflow lead** who guides the user through the full product develop
 ```
 Phase 1: 기획문서       → docs-plan (Concept_Design)
 Phase 2: UI 설계 문서   → docs-plan (UI_Screens)
+HTML UI Preview Gate: 브라우저 확인용 화면 제작·링크·피드백
 UI-First Gate: 화면·동선·데이터 흐름 확인
 Pre-Code Technical Brief: 데이터·API·상태 최소 합의
 Phase 3: React 변환     → rules-react
@@ -32,6 +33,7 @@ Run these checks in order:
 |-------|--------|---------|
 | `docs/01_Concept_Design/` 존재 여부 | 없으면 Phase 1 미완 | 기획문서 필요 |
 | `docs/02_UI_Screens/` 존재 여부 | 없으면 Phase 2 미완 | UI 설계 필요 |
+| HTML UI Preview 확인 여부 | 없으면 Phase 3 진입 보류 | 브라우저 확인용 화면 필요 |
 | UI-First Gate 확인 여부 | 없으면 Phase 3 진입 보류 | 화면·동선·데이터 흐름 확인 필요 |
 | Pre-Code Technical Brief 여부 | 없으면 Phase 3 진입 보류 | 최소 기술 합의 필요 |
 | `src/components/` 또는 React 코드 존재 여부 | 없으면 Phase 3 미완 | React 개발 필요 |
@@ -132,6 +134,8 @@ Phase 1이 완료된 후 언제든 작성 가능하다. Phase 2 진입과 독립
 - [ ] 사용자 진입·이탈·전환 동선이 정의됨
 - [ ] 화면별 입력 데이터, 출력 데이터, 상태 변화가 정의됨
 - [ ] 로딩·빈 상태·오류 상태가 정의됨
+- [ ] `docs/02_UI_Screens/previews/`에 주요 화면 또는 사용자 흐름 HTML Preview가 존재함
+- [ ] UI 문서가 관련 HTML Preview를 상대 경로로 링크함
 - [ ] 사용자가 화면/UI를 먼저 확인했거나, 확인할 수 있는 프로토타입/스크린샷/리뷰 문서가 있음
 
 **위임 지시**:
@@ -142,10 +146,28 @@ Phase 1이 완료된 후 언제든 작성 가능하다. Phase 2 진입과 독립
 참조 문서: docs/01_Concept_Design/ 전체 읽기 후 시작
 ```
 
-Phase 2 완료 후 곧바로 코딩하지 않는다. 먼저 UI-First Gate를 확인하고 다음을 묻는다:
-> "화면 구조, 사용자 동선, 데이터 흐름, 로딩/빈/오류 상태를 먼저 확인했습니다. 현재 단계에서 더 구체화하거나 보완할 점이 있을까요?"
+Phase 2 완료 후 곧바로 코딩하지 않는다. 먼저 HTML UI Preview Gate와 UI-First Gate를 확인하고 다음을 묻는다:
+> "HTML Preview로 화면 구조, 사용자 동선, 데이터 흐름, 로딩/빈/오류 상태를 먼저 확인했습니다. 현재 단계에서 더 구체화하거나 보완할 점이 있을까요?"
 
-Phase 2 완료 보고에는 `Flow Status Block`을 포함하고, 다음 위치가 `UI-First Gate`임을 명시한다.
+Phase 2 완료 보고에는 `Flow Status Block`을 포함하고, 다음 위치가 `HTML UI Preview Gate` 또는 `UI-First Gate`임을 명시한다.
+
+---
+
+## HTML UI Preview Gate: 브라우저 확인용 화면 제작·링크·피드백
+
+**목표**: Markdown UI 문서만으로 소통하지 않고, 사용자가 브라우저에서 직접 볼 수 있는 HTML 화면으로 UI를 확인한다. 이 게이트를 통과하기 전에는 Phase 3 구현을 시작하지 않는다.
+
+**필수 확인 항목**:
+- [ ] 주요 화면 또는 핵심 사용자 흐름별 HTML Preview가 존재함
+- [ ] HTML Preview가 `docs/02_UI_Screens/previews/`에 저장됨
+- [ ] `00_SCREEN_FLOW.md`, `01_UI_DESIGN.md`, 관련 `XX_PROTOTYPE_REVIEW.md`가 HTML Preview를 상대 경로로 링크함
+- [ ] HTML Preview를 사용자에게 보여주고 피드백을 받음
+- [ ] 피드백과 보완 사항이 UI 문서 또는 백로그에 기록됨
+
+**Gate Out**:
+- [ ] HTML Preview 파일 경로가 문서에 링크됨
+- [ ] 사용자 확인 기록이 `XX_PROTOTYPE_REVIEW.md`, `00_SCREEN_FLOW.md`, `01_UI_DESIGN.md`, 또는 백로그에 남아 있음
+- [ ] 필요한 보완 사항이 반영되었거나 백로그에 태스크로 등록됨
 
 ---
 
@@ -160,9 +182,11 @@ Phase 2 완료 보고에는 `Flow Status Block`을 포함하고, 다음 위치
 - [ ] 화면별 입력 데이터, 출력 데이터, 상태 변화
 - [ ] 로딩, 빈 상태, 오류 상태, 권한 없음 상태
 - [ ] 모바일·데스크톱에서 구조 차이가 큰 구간
+- [ ] HTML Preview가 실제 화면 커뮤니케이션 기준으로 확인됨
 - [ ] 사용자 또는 의사결정권자가 화면/UI를 먼저 확인한 기록
 
 **Gate Out**:
+- [ ] HTML UI Preview Gate 통과
 - [ ] `00_SCREEN_FLOW.md`에 사용자 여정과 전환 흐름이 기록됨
 - [ ] `01_UI_DESIGN.md` 또는 `XX_PROTOTYPE_REVIEW.md`에 화면 상태와 피드백이 기록됨
 - [ ] 필요한 경우 `docs/04_Logic_Progress/00_BACKLOG.md`의 작업 항목에 UI 확인 결과가 반영됨
@@ -198,6 +222,7 @@ Pre-Code Technical Brief 보고에는 `Flow Status Block`을 포함하고, 다
 
 **Gate In**:
 - Phase 2 문서 (`02_UI_Screens/`) 존재
+- HTML UI Preview Gate 통과
 - UI-First Gate 통과
 - 화면·동선·데이터 흐름 확인 결과가 백로그 또는 UI 문서에 반영됨
 - Pre-Code Technical Brief 통과

package/rules-product/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Product Workflow"
-  short_description: "Orchestrate planning, UI, docs, and QA phases"
-  default_prompt: "Use $rules-product to diagnose the current product phase and choose the next skill."
+  short_description: "Orchestrate planning, UI previews, docs, QA"
+  default_prompt: "Use $rules-product to diagnose the current phase, gates, HTML previews, and next skill."

package/rules-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rules-workflow
-description: Guides the full implementation lifecycle from planning through PR. Use when implementing a new feature, planning implementation, before committing or creating a PR, or when the user asks for plan review, implementation review, deployment readiness check, or to follow the 18-step workflow (18단계). Ensures plan validation, implementation quality, side-effect checks, and deployment-ready quality.
+description: Guides the full implementation lifecycle from planning through PR. Use when implementing a new feature, planning implementation, before committing or creating a PR, or following the 18-step workflow. Requires product phase preflight, HTML UI Preview Gate, UI-First Gate, Backlog Context Lock, implementation quality checks, and deployment readiness.
 ---
 
 # Implementation & Execution Workflow (18 Steps)
@@ -11,9 +11,9 @@ Follow this workflow for feature implementation and significant code changes. Co
 
 ## Step 0: Product Phase Preflight
 
-기능 구현을 시작하기 전, 먼저 `rules-product` 기준으로 현재 프로젝트 Phase를 진단한다. Concept, UI, UI-First Gate, Pre-Code Technical Brief 중 하나라도 누락되어 구현 판단이 불안정하면 코딩을 시작하지 않고 해당 문서 또는 백로그 보완을 제안한다.
+기능 구현을 시작하기 전, 먼저 `rules-product` 기준으로 현재 프로젝트 Phase를 진단한다. Concept, UI, HTML UI Preview Gate, UI-First Gate, Pre-Code Technical Brief 중 하나라도 누락되어 구현 판단이 불안정하면 코딩을 시작하지 않고 해당 문서 또는 백로그 보완을 제안한다.
 
-- 체크: [ ] 현재 Phase를 진단했는가? [ ] UI-First Gate가 충족되었는가? [ ] 최소 기술 계약이 확인되었는가?
+- 체크: [ ] 현재 Phase를 진단했는가? [ ] HTML UI Preview Gate가 충족되었는가? [ ] UI-First Gate가 충족되었는가? [ ] 최소 기술 계약이 확인되었는가?
 
 진단 결과는 `rules-product`의 `Flow Status Block` 형식으로 먼저 보고한다. 구현 단계 중 사용자가 "지금 어디야?", "다음 뭐야?", "현재 단계가 뭐야?"라고 묻거나 Phase 1-6 경계에 도달하면 같은 형식을 다시 출력한다.
 
@@ -24,10 +24,11 @@ Follow this workflow for feature implementation and significant code changes. Co
 ### Step 1. 계획 수립
 - 요구사항·목적을 문서 또는 이슈 기준으로 정리한다.
 - 백로그 항목이 있으면 `Related Concept Docs`, `Related UI Docs`, `Related Technical Docs`, `Related QA Docs`를 먼저 읽고 구현 입력값으로 요약한다.
-- 코드 작성보다 먼저 UI-First Gate를 확인한다. 화면 구조, 사용자 동선, 데이터 흐름, 로딩·빈 상태·오류 상태가 문서화되지 않았으면 구현 계획을 보류하고 `docs-plan` 또는 `docs-dev` 문서 보완을 제안한다.
+- 코드 작성보다 먼저 HTML UI Preview Gate를 확인한다. `docs/02_UI_Screens/previews/`의 HTML Preview가 없거나 UI 문서에 링크되지 않았거나 사용자 확인 기록이 없으면 구현 계획을 보류하고 `docs-plan` 문서/HTML 보완을 제안한다.
+- 그 다음 UI-First Gate를 확인한다. 화면 구조, 사용자 동선, 데이터 흐름, 로딩·빈 상태·오류 상태가 문서화되지 않았으면 구현 계획을 보류하고 `docs-plan` 또는 `docs-dev` 문서 보완을 제안한다.
 - Pre-Code Technical Brief를 확인한다. 데이터 소스, 최소 필드, mutation, 상태 관리 방식, acceptance criteria가 불명확하면 구현 전에 사용자와 합의한다.
 - 변경할 파일·추가할 컴포넌트·API·DB 영향 범위를 나열한다.
-- 체크: [ ] 목적이 명확한가? [ ] 관련 문서를 읽었는가? [ ] UI-First Gate가 확인되었는가? [ ] 최소 기술 계약이 확인되었는가? [ ] 영향 범위가 정리되었는가?
+- 체크: [ ] 목적이 명확한가? [ ] 관련 문서를 읽었는가? [ ] HTML UI Preview를 확인했는가? [ ] UI-First Gate가 확인되었는가? [ ] 최소 기술 계약이 확인되었는가? [ ] 영향 범위가 정리되었는가?
 
 ### Step 2. 계획 검토
 - 계획이 요구사항과 일치하는지, 누락된 시나리오는 없는지 검토한다.
@@ -48,9 +49,10 @@ Follow this workflow for feature implementation and significant code changes. Co
 ### Step 5. 구현
 - 승인된 계획대로 구현한다. AGENTS.md·프로젝트 컨벤션(커밋, Zod, Luxon 등)을 따른다.
 - 코드 작성 전 백로그 항목의 `Implementation Preconditions`와 `Acceptance Criteria`를 확인한다. 관련 문서 링크가 비어 있거나 `N/A - 사유`가 부실하면 구현을 보류하고 문서 보완 필요 여부를 사용자에게 확인한다.
+- HTML UI Preview Gate가 통과되지 않았거나 사용자가 HTML Preview를 확인하지 않았다면 구현을 시작하지 않는다.
 - UI-First Gate가 통과되지 않았거나 사용자가 화면/UI를 먼저 확인하지 않았다면 구현을 시작하지 않는다.
 - 구현을 시작하기 직전에 `Flow Status Block`을 출력하고, 현재 위치가 `Phase 3 — React 변환` 또는 해당 기능 구현 단계인지 명시한다.
-- 체크: [ ] 계획 대비 변경 사항이 일치하는가? [ ] 백로그의 관련 문서 기준을 반영했는가? [ ] 화면·동선·데이터 흐름 확인 후 구현했는가?
+- 체크: [ ] 계획 대비 변경 사항이 일치하는가? [ ] 백로그의 관련 문서 기준을 반영했는가? [ ] HTML Preview 확인 후 구현했는가? [ ] 화면·동선·데이터 흐름 확인 후 구현했는가?
 
 ---
 

package/verify-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: verify-docs
-description: 프로젝트 문서가 5단계 구조(01~05)와 메타데이터 표준을 준수하는지 검증합니다. 문서 생성/수정 후, PR 전 사용.
+description: 프로젝트 문서가 5단계 구조(01~05), 메타데이터, Related Documents, Backlog Context Lock, HTML UI Preview Gate, UI-First Gate를 준수하는지 검증합니다. 문서 생성/수정 후, PR 전 사용.
 ---
 
 # 문서 구조 검증
@@ -12,10 +12,11 @@ description: 프로젝트 문서가 5단계 구조(01~05)와 메타데이터 표
 2. 메타데이터 표준 (Created / Last Updated)
 3. Related Documents 섹션
 4. Backlog Context Lock
-5. UI-First Gate
-6. Pre-Code Technical Brief
-7. Rubric-First Writing
-8. rules-product Gate Out 조건
+5. HTML UI Preview Gate
+6. UI-First Gate
+7. Pre-Code Technical Brief
+8. Rubric-First Writing
+9. rules-product Gate Out 조건
 
 ## 실행 시점
 
@@ -64,6 +65,7 @@ AGENTS.md 또는 `docs/01_Concept_Design/00_COLLABORATION_GUIDE.md`를 읽어
 - [ ] 모든 Backlog 작업 항목이 체크박스`[ ]` 또는 `[x]`로 시작하는가?
 - [ ] 각 작업 항목에 `Related Concept Docs`가 있는가?
 - [ ] 각 작업 항목에 `Related UI Docs`가 있는가?
+- [ ] 각 작업 항목에 `Related HTML Preview`가 있는가?
 - [ ] 각 작업 항목에 `Related Technical Docs`가 있는가?
 - [ ] 각 작업 항목에 `Related QA Docs`가 있는가?
 - [ ] 각 작업 항목에 `Implementation Preconditions`가 있는가?
@@ -71,16 +73,32 @@ AGENTS.md 또는 `docs/01_Concept_Design/00_COLLABORATION_GUIDE.md`를 읽어
 - [ ] 각 작업 항목에 `Document Sync Check`가 있는가?
 - [ ] Related 필드의 링크가 상대 경로이거나 `N/A - 사유` 형식인가?
 - [ ] `N/A`만 있고 사유가 없는 항목은 없는가?
+- [ ] `Related HTML Preview`가 상대 경로 링크 또는 `N/A - 사유` 형식인가?
+- [ ] `Implementation Preconditions`에 HTML Preview 사용자 확인 및 피드백 기록이 포함되어 있는가?
 - [ ] `Implementation Preconditions`에 화면/UI 선확인, 사용자 동선 확인, 데이터 흐름 확인, 로딩·빈 상태·오류 상태 확인이 포함되어 있는가?
 - [ ] `Implementation Preconditions` 또는 `Acceptance Criteria`에 데이터 소스, 최소 필드, mutation, 상태 관리 방식, 검증 가능한 acceptance criteria가 포함되어 있는가?
 
 위 항목 중 하나라도 누락되면 Backlog Context Lock은 Fail로 처리한다.
 
-### Step 5: UI-First Gate 검사
+### Step 5: HTML UI Preview Gate 검사
+
+`docs/02_UI_Screens/`와 `docs/02_UI_Screens/previews/`를 함께 확인한다.
+
+체크 항목:
+- [ ] `docs/02_UI_Screens/previews/` 폴더가 있는가?
+- [ ] 주요 화면 또는 사용자 흐름에 대응되는 `.html` 파일이 있는가?
+- [ ] HTML 파일명이 2자리 순번과 목적을 포함하는가? (예: `01_main_flow_preview.html`)
+- [ ] `00_SCREEN_FLOW.md`, `01_UI_DESIGN.md`, 관련 `XX_PROTOTYPE_REVIEW.md` 중 하나 이상이 HTML Preview를 상대 경로로 링크하는가?
+- [ ] UI 문서나 백로그에 HTML Preview 사용자 확인 및 피드백 기록이 있는가?
+
+HTML Preview가 없거나 링크·사용자 확인 기록이 누락되면 HTML UI Preview Gate는 Fail로 처리한다.
+
+### Step 6: UI-First Gate 검사
 
 `docs/02_UI_Screens/`와 `docs/04_Logic_Progress/00_BACKLOG.md`를 함께 확인한다.
 
 체크 항목:
+- [ ] HTML UI Preview Gate를 통과했는가?
 - [ ] `00_SCREEN_FLOW.md`에 주요 화면, 진입·전환·이탈 동선이 있는가?
 - [ ] `00_SCREEN_FLOW.md` 또는 관련 UI 문서에 화면별 입력·출력 데이터가 있는가?
 - [ ] `01_UI_DESIGN.md` 또는 `XX_PROTOTYPE_REVIEW.md`에 로딩·빈 상태·오류 상태가 있는가?
@@ -89,7 +107,7 @@ AGENTS.md 또는 `docs/01_Concept_Design/00_COLLABORATION_GUIDE.md`를 읽어
 
 구현 판단에 필요한 화면·동선·데이터 흐름이 누락되면 UI-First Gate는 Fail로 처리한다.
 
-### Step 6: Pre-Code Technical Brief 검사
+### Step 7: Pre-Code Technical Brief 검사
 
 `docs/03_Technical_Specs/`와 `docs/04_Logic_Progress/00_BACKLOG.md`를 함께 확인한다.
 
@@ -101,7 +119,7 @@ AGENTS.md 또는 `docs/01_Concept_Design/00_COLLABORATION_GUIDE.md`를 읽어
 
 데이터·API·상태 계약이 없어 구현자가 임의 구조를 만들 수밖에 없으면 Pre-Code Technical Brief는 Fail로 처리한다.
 
-### Step 7: Rubric-First Writing 검사
+### Step 8: Rubric-First Writing 검사
 
 | 레이어 | 기준 |
 |:---|:---|
@@ -111,7 +129,7 @@ AGENTS.md 또는 `docs/01_Concept_Design/00_COLLABORATION_GUIDE.md`를 읽어
 | Technical_Specs (Layer 3) | Functionality, UX (latency), Open-source 언급 (권장) |
 | Logic_Progress (Layer 4) | Functionality, UX 언급 (권장) |
 
-### Step 8: Gate Out 조건 검사
+### Step 9: Gate Out 조건 검사
 
 rules-product 기준으로 각 Phase의 필수 문서 존재 여부를 확인한다.
 
@@ -123,6 +141,8 @@ rules-product 기준으로 각 Phase의 필수 문서 존재 여부를 확인한
 **Phase 2 (UI 설계)**:
 - [ ] `docs/02_UI_Screens/00_SCREEN_FLOW.md`
 - [ ] `docs/02_UI_Screens/01_UI_DESIGN.md`
+- [ ] `docs/02_UI_Screens/previews/` 내 관련 HTML Preview
+- [ ] UI 문서에서 HTML Preview 상대 경로 링크
 - [ ] 화면·동선·데이터 흐름·상태별 UI 확인 기록
 - [ ] Pre-Code Technical Brief 기록
 
@@ -131,7 +151,7 @@ rules-product 기준으로 각 Phase의 필수 문서 존재 여부를 확인한
 - [ ] `docs/04_Logic_Progress/00_ROADMAP.md`
 - [ ] `docs/05_QA_Validation/02_QA_CHECKLIST.md`
 
-### Step 9: 검증 보고서 출력
+### Step 10: 검증 보고서 출력
 
 검사 완료 후 아래 형식으로 결과를 출력한다:
 
@@ -145,6 +165,7 @@ rules-product 기준으로 각 Phase의 필수 문서 존재 여부를 확인한
 | 메타데이터 | Pass / Fail | 누락 파일 목록 |
 | Related Documents | Pass / Fail | 미연결 파일 목록 |
 | Backlog Context Lock | Pass / Fail | 필수 필드 누락 작업 목록 |
+| HTML UI Preview Gate | Pass / Fail | HTML Preview 파일·링크·확인 기록 누락 목록 |
 | UI-First Gate | Pass / Fail | 화면·동선·데이터 흐름 누락 목록 |
 | Pre-Code Technical Brief | Pass / Fail | 데이터·API·상태 계약 누락 목록 |
 | Rubric-First | Pass / Fail | |

package/verify-docs/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Docs Verification"
-  short_description: "Audit documentation structure and metadata"
-  default_prompt: "Use $verify-docs to audit the five-layer docs structure and metadata fields."
+  short_description: "Audit docs, metadata, and HTML previews"
+  default_prompt: "Use $verify-docs to audit five-layer docs, metadata, links, and HTML UI previews."

package/verify-ui/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: verify-ui
-description: UI 구현이 docs/02_UI_Screens의 화면 설계, 사용자 동선, 데이터 흐름, 로딩·빈 상태·오류 상태와 일치하는지 검증합니다. React/TSX 화면 구현 후, UI-First Gate 확인 후, 또는 "UI 검증", "UX 확인", "화면이 문서와 맞는지 봐줘" 요청 시 사용합니다.
+description: UI 구현이 docs/02_UI_Screens의 화면 설계, HTML UI Preview, 사용자 동선, 데이터 흐름, 로딩·빈 상태·오류 상태와 일치하는지 검증합니다. React/TSX 화면 구현 후, UI-First Gate 확인 후, 또는 "UI 검증", "UX 확인", "화면이 문서와 맞는지 봐줘" 요청 시 사용합니다.
 argument-hint: "[선택사항: 점검할 화면, 라우트, 컴포넌트 경로]"
 ---
 
 # UI 구현 검증 스킬 (verify-ui)
 
-구현된 화면이 UI-First Gate에서 합의한 화면 구조, 사용자 동선, 데이터 흐름, 상태별 UI를 실제로 반영하는지 검증한다.
+구현된 화면이 HTML UI Preview와 UI-First Gate에서 합의한 화면 구조, 사용자 동선, 데이터 흐름, 상태별 UI를 실제로 반영하는지 검증한다.
 
 ---
 
@@ -14,6 +14,7 @@ argument-hint: "[선택사항: 점검할 화면, 라우트, 컴포넌트 경로]
 
 - React/TSX 화면 또는 컴포넌트 구현 후
 - `rules-workflow` Step 15 사용자 사용 흐름 확인 시
+- HTML UI Preview와 실제 구현 결과의 일치 여부를 확인할 때
 - `docs/02_UI_Screens/` 문서와 구현 결과의 일치 여부를 확인할 때
 - PR 전 UI/UX 회귀 점검 시
 
@@ -26,10 +27,24 @@ argument-hint: "[선택사항: 점검할 화면, 라우트, 컴포넌트 경로]
 ```bash
 git diff --name-only HEAD
 find docs/02_UI_Screens -maxdepth 1 -type f -name '*.md' 2>/dev/null
+find docs/02_UI_Screens/previews -maxdepth 1 -type f -name '*.html' 2>/dev/null
 find . -path '*/src/*' \( -name '*.tsx' -o -name '*.jsx' \) 2>/dev/null
 ```
 
-검증 전 `docs/02_UI_Screens/00_SCREEN_FLOW.md`, `01_UI_DESIGN.md`, 관련 `XX_PROTOTYPE_REVIEW.md`, 백로그 항목의 `Related UI Docs`를 읽는다.
+검증 전 `docs/02_UI_Screens/00_SCREEN_FLOW.md`, `01_UI_DESIGN.md`, 관련 `XX_PROTOTYPE_REVIEW.md`, `docs/02_UI_Screens/previews/*.html`, 백로그 항목의 `Related UI Docs`와 `Related HTML Preview`를 읽는다.
+
+---
+
+## Check 0: HTML UI Preview 기준 확인
+
+- 주요 화면 또는 사용자 흐름에 대응되는 HTML Preview가 있는지 확인한다.
+- UI 문서와 백로그가 HTML Preview를 상대 경로로 링크하는지 확인한다.
+- 구현 결과가 HTML Preview와 의도 없이 크게 달라졌다면 문서 또는 구현 중 어느 쪽이 최신 기준인지 확인한다.
+- 체크:
+  - [ ] 관련 HTML Preview가 존재하는가?
+  - [ ] HTML Preview가 UI 문서 또는 백로그에 링크되어 있는가?
+  - [ ] 사용자 피드백과 보완 사항이 문서 또는 백로그에 반영되어 있는가?
+  - [ ] 구현이 HTML Preview의 정보 위계, CTA, 주요 레이아웃을 유지하는가?
 
 ---
 
@@ -105,6 +120,7 @@ find . -path '*/src/*' \( -name '*.tsx' -o -name '*.jsx' \) 2>/dev/null
 
 ### 문서 동기화 필요
 - 구현이 문서와 다르면 수정할 문서 또는 코드 위치를 명시한다.
+- HTML Preview와 구현이 다르면 최신 기준이 무엇인지 명시하고 문서 또는 코드 수정 대상을 적는다.
 ```
 
 심각도 기준: **높음** (핵심 동선 차단) / **중** (사용성 또는 문서 불일치) / **낮음** (개선 권장)

package/verify-ui/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "UI Verification"
-  short_description: "Check UI implementation against screen docs"
-  default_prompt: "Use $verify-ui to compare implemented screens with UI docs, user flows, and state coverage."
+  short_description: "Check UI against docs and HTML previews"
+  default_prompt: "Use $verify-ui to compare implemented screens with UI docs, HTML previews, flows, and states."