solmate-skills 2.0.5 → 2.0.7

package/hooks/suggest-skills.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# solmate-skills: suggest-skills.sh
+# Event: UserPromptSubmit
+# Purpose: Detect keywords in user prompt and inject skill suggestions as context.
+# Output: JSON with hookSpecificOutput.additionalContext (non-blocking)
+
+set -euo pipefail
+
+# Read stdin JSON
+INPUT=$(cat)
+
+# Extract the user prompt text
+PROMPT=$(echo "$INPUT" | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+# UserPromptSubmit provides 'prompt' field
+print(data.get('prompt', ''))
+" 2>/dev/null || echo "")
+
+if [ -z "$PROMPT" ]; then
+  exit 0
+fi
+
+SUGGESTIONS=""
+
+# --- Keyword matching (Korean + English) ---
+
+# Decision / Design → manage-decisions
+if echo "$PROMPT" | grep -qiE '결정|설계|어떻게 할|어떤 방식|DB 스키마|테이블|API 구조|아키텍처|폴더 구조|기능 범위|MVP|스택|라이브러리|어떤 거|어떤게'; then
+  SUGGESTIONS="$SUGGESTIONS\n- 결정이 필요한 상황입니다. \`/manage-decisions\`를 실행하면 유형별 질문 템플릿으로 대화를 통해 결정을 이끌어냅니다."
+fi
+
+# Security → verify-security
+if echo "$PROMPT" | grep -qiE '보안|security|취약|OWASP|인증|인가|token|jwt|secret|API ?key|sql|injection|xss|csrf'; then
+  SUGGESTIONS="$SUGGESTIONS\n- 보안 관련 작업입니다. \`/verify-security\`로 OWASP Top 10 기준 점검을 실행하세요."
+fi
+
+# Performance → verify-performance
+if echo "$PROMPT" | grep -qiE '성능|performance|lighthouse|느리|느림|최적화|LCP|CLS|FID|번들|bundle|이미지 최적|lazy|loading'; then
+  SUGGESTIONS="$SUGGESTIONS\n- 성능 관련 작업입니다. \`/verify-performance\`로 Lighthouse 및 Core Web Vitals 점검을 실행하세요."
+fi
+
+# PR / Commit / Code review → verify-code
+if echo "$PROMPT" | grep -qiE 'PR|pull ?request|코드 ?리뷰|review|commit|머지|merge|배포 전|pre-deploy'; then
+  SUGGESTIONS="$SUGGESTIONS\n- PR 또는 배포 전 점검입니다. \`/verify-code\`로 코드 품질을 종합 리뷰하고, \`/verify-implementation\`으로 전체 verify-* 스킬을 통합 실행하세요."
+fi
+
+# Documentation → verify-docs / docs-plan / docs-dev
+if echo "$PROMPT" | grep -qiE '문서|docs?|README|VISION|LEAN_CANVAS|PRODUCT_SPECS|API_SPECS|DB_SCHEMA|ROADMAP|백로그|backlog'; then
+  SUGGESTIONS="$SUGGESTIONS\n- 문서 작업입니다. 기획·UI 문서는 \`/docs-plan\`, 기술·진행·QA 문서는 \`/docs-dev\`, 문서 구조 검증은 \`/verify-docs\`를 사용하세요."
+fi
+
+# Feature implementation / workflow → rules-workflow
+if echo "$PROMPT" | grep -qiE '기능 ?구현|구현|implement|feature|작업 ?시작|어디서 ?시작|어떻게 ?시작|개발 ?시작|시작할게'; then
+  SUGGESTIONS="$SUGGESTIONS\n- 기능 구현을 시작하려 합니다. 먼저 \`/rules-product\`로 현재 Phase를 진단하고 Flow Status Block을 확인한 뒤, \`/rules-workflow\`로 18단계 구현 워크플로우를 진행하세요."
+fi
+
+# Flow position question → rules-product
+if echo "$PROMPT" | grep -qiE '지금.*어디|현재.*단계|현재.*위치|다음.*뭐|어느.*Phase|flow status|플로우.*상태|단계.*확인'; then
+  SUGGESTIONS="$SUGGESTIONS\n- 현재 위치 확인 요청입니다. \`/rules-product\` 기준 Flow Status Block으로 현재 Phase, Gate, 다음 액션을 먼저 보고하세요."
+fi
+
+# React / UI component → rules-react
+if echo "$PROMPT" | grep -qiE 'React|컴포넌트|component|페이지|page|UI|화면|shadcn|tailwind'; then
+  SUGGESTIONS="$SUGGESTIONS\n- React/UI 작업입니다. \`/rules-react\`로 컴포넌트 설계 기준을 확인하고, 구현 후 \`/verify-ui\`로 화면 문서와 사용자 동선 정합성을 검증하세요."
+fi
+
+# UI verification explicit request → verify-ui
+if echo "$PROMPT" | grep -qiE 'UI ?검증|UX ?검증|화면 ?검증|화면.*맞|동선.*검증|상태별 UI|empty state|loading state|error state'; then
+  SUGGESTIONS="$SUGGESTIONS\n- UI 검증 요청입니다. \`/verify-ui\`로 화면 구조, 사용자 동선, 데이터 흐름, 상태별 UI를 점검하세요."
+fi
+
+# Skill package changes → verify-skills
+if echo "$PROMPT" | grep -qiE '스킬.*검증|skill.*verify|SKILL\.md|openai\.yaml|solmate-skills|npm pack|패키지.*검증'; then
+  SUGGESTIONS="$SUGGESTIONS\n- 스킬 패키지 작업입니다. \`/verify-skills\`로 SKILL.md, agents/openai.yaml, CLI 목록, README/AGENTS, npm pack을 검증하세요."
+fi
+
+# Drizzle / DB schema → verify-drizzle-schema
+if echo "$PROMPT" | grep -qiE 'drizzle|schema\.ts|마이그레이션|migration|pgTable|sqliteTable'; then
+  SUGGESTIONS="$SUGGESTIONS\n- Drizzle 스키마 작업입니다. \`/verify-drizzle-schema\`로 스키마 정합성을 검증하세요."
+fi
+
+# New project / product pipeline → rules-product
+if echo "$PROMPT" | grep -qiE '새 프로젝트|신규 프로젝트|프로젝트 시작|어디서 시작|뭐부터|처음부터|from scratch'; then
+  SUGGESTIONS="$SUGGESTIONS\n- 새 프로젝트입니다. \`/rules-product\`를 실행하면 현재 단계를 자동 진단하고 올바른 스킬로 안내합니다."
+fi
+
+# Pitch deck / business plan → docs-pitch / docs-business
+if echo "$PROMPT" | grep -qiE '피치|pitch|투자|investor|사업 ?계획|business ?plan|데모데이|해커톤'; then
+  SUGGESTIONS="$SUGGESTIONS\n- 발표·투자 자료 작업입니다. 피치덱은 \`/docs-pitch\`, 사업계획서는 \`/docs-business\`를 사용하세요."
+fi
+
+# If no suggestions, exit silently
+if [ -z "$SUGGESTIONS" ]; then
+  exit 0
+fi
+
+# Output JSON with additionalContext (non-blocking)
+python3 -c "
+import json, sys
+suggestions = sys.argv[1]
+output = {
+    'hookSpecificOutput': {
+        'hookEventName': 'UserPromptSubmit',
+        'additionalContext': '[Solmate Skills 제안]\n' + suggestions.strip()
+    }
+}
+print(json.dumps(output))
+" "$SUGGESTIONS"

package/hooks/verify-suggest.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# Claude Stop 훅: git 변경 파일을 분석하여 적절한 verify-* 스킬을 제안합니다
+
+python3 - <<'PYEOF'
+import subprocess, json
+
+r = subprocess.run(['git', 'diff', '--name-only', 'HEAD'], capture_output=True, text=True)
+files = [f for f in r.stdout.strip().split('\n') if f]
+
+if not files:
+    exit()
+
+s = []
+
+if any('schema' in f and (f.endswith('.ts') or f.endswith('.sql')) for f in files):
+    s.append('  DB 스키마 변경 감지    →  /verify-drizzle-schema')
+
+if any(f.endswith(('.tsx', '.jsx')) or f.startswith('docs/02_UI_Screens/') for f in files):
+    s.append('  UI/화면 변경 감지      →  /verify-ui')
+
+if any(any(k in f.lower() for k in ('auth', 'middleware', 'api', 'route', 'token', 'session'))
+       and (f.endswith('.ts') or f.endswith('.tsx')) for f in files):
+    s.append('  인증/API 파일 변경 감지 →  /verify-security')
+
+if any(f.endswith('.ts') or f.endswith('.tsx') for f in files):
+    s.append('  코드 파일 변경 감지    →  /verify-code')
+
+if any(f.endswith('.md') for f in files):
+    s.append('  문서 파일 변경 감지    →  /verify-docs')
+
+if any(
+    f.endswith('/SKILL.md')
+    or f.endswith('/agents/openai.yaml')
+    or f in ('bin/cli.js', 'package.json', 'README.md', 'AGENTS.md')
+    for f in files
+):
+    s.append('  스킬 패키지 변경 감지  →  /verify-skills')
+
+if s:
+    msg = '[ 검증 시점 알림 ]\n' + '\n'.join(s)
+    print(json.dumps({'systemMessage': msg}))
+PYEOF

package/hooks/watch-files.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# solmate-skills: watch-files.sh
+# Event: PreToolUse (matcher: Read|Write|Edit|Bash)
+# Purpose: Detect file patterns being modified and inject relevant skill suggestions.
+# Output: JSON with hookSpecificOutput.additionalContext (non-blocking)
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+# Extract file path and tool name
+FILE_PATH=$(echo "$INPUT" | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+inp = data.get('tool_input', {})
+# Write/Edit use file_path; Bash use command
+print(inp.get('file_path', inp.get('command', '')))" 2>/dev/null || echo "")
+
+TOOL_NAME=$(echo "$INPUT" | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+print(data.get('tool_name', ''))" 2>/dev/null || echo "")
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+SUGGESTIONS=""
+
+# --- File pattern matching ---
+
+# Drizzle schema file → verify-drizzle-schema
+if echo "$FILE_PATH" | grep -qiE 'schema\.(ts|js)|drizzle'; then
+  SUGGESTIONS="$SUGGESTIONS\n- Drizzle 스키마 파일을 수정 중입니다. 작업 후 \`/verify-drizzle-schema\`로 스키마 정합성을 검증하세요."
+fi
+
+# .env files → verify-security
+if echo "$FILE_PATH" | grep -qiE '\.env|\.env\.local|\.env\.production|\.env\.example'; then
+  SUGGESTIONS="$SUGGESTIONS\n- 환경변수 파일을 수정 중입니다. \`/verify-security\` Check 1(시크릿 노출)을 실행하여 민감 정보 노출 여부를 확인하세요."
+fi
+
+# SKILL.md files → manage-skills
+if echo "$FILE_PATH" | grep -qiE 'SKILL\.md'; then
+  SUGGESTIONS="$SUGGESTIONS\n- 스킬 파일을 수정 중입니다. \`/manage-skills\`로 verify 스킬과의 정합성 드리프트를 점검하고, 작업 후 \`/verify-skills\`로 패키지 메타데이터를 검증하세요."
+fi
+
+# Skill metadata / package files → verify-skills
+if echo "$FILE_PATH" | grep -qiE 'agents/openai\.yaml|bin/cli\.js|package\.json|README\.md|AGENTS\.md'; then
+  SUGGESTIONS="$SUGGESTIONS\n- 스킬 패키지 메타데이터 또는 배포 파일을 수정 중입니다. 작업 후 \`/verify-skills\`를 실행하세요."
+fi
+
+# UI implementation files → verify-ui
+if echo "$FILE_PATH" | grep -qiE '\.(tsx|jsx)$|docs/02_UI_Screens/.*\.md'; then
+  SUGGESTIONS="$SUGGESTIONS\n- UI 구현 또는 화면 문서를 수정 중입니다. 작업 후 \`/verify-ui\`로 화면 구조·동선·상태별 UI 정합성을 검증하세요."
+fi
+
+# Page/route files → verify-performance
+if echo "$FILE_PATH" | grep -qiE 'page\.(tsx|jsx|ts|js)|route\.(tsx|jsx|ts|js)|layout\.(tsx|jsx)'; then
+  SUGGESTIONS="$SUGGESTIONS\n- 페이지·라우트 파일을 수정 중입니다. 작업 후 \`/verify-performance\`로 Core Web Vitals 및 렌더링 전략을 점검하세요."
+fi
+
+# API route files → verify-security
+if echo "$FILE_PATH" | grep -qiE 'api/.*route\.(ts|js)|api/.*index\.(ts|js)|\bapi\b.*\.(ts|js)'; then
+  SUGGESTIONS="$SUGGESTIONS\n- API 라우트 파일을 수정 중입니다. 작업 후 \`/verify-security\` Check 2(인증·인가) 및 Check 5(CSRF)를 점검하세요."
+fi
+
+# Auth-related files → verify-security
+if echo "$FILE_PATH" | grep -qiE 'auth\.(ts|js|tsx)|middleware\.(ts|js)|session\.(ts|js)'; then
+  SUGGESTIONS="$SUGGESTIONS\n- 인증·미들웨어 파일을 수정 중입니다. \`/verify-security\`로 인증·인가 취약점을 점검하세요."
+fi
+
+# Documentation files → verify-docs
+if echo "$FILE_PATH" | grep -qiE 'docs/(01|02|03|04|05)_.*\.md'; then
+  SUGGESTIONS="$SUGGESTIONS\n- 문서 레이어 파일을 수정 중입니다. 작업 후 \`/verify-docs\`로 메타데이터 및 구조 정합성을 검증하세요."
+fi
+
+# AGENTS.md → remind about skill count
+if echo "$FILE_PATH" | grep -qiE 'AGENTS\.md'; then
+  SUGGESTIONS="$SUGGESTIONS\n- AGENTS.md를 수정 중입니다. 스킬 목록·개수가 변경된 경우 Section 4의 테이블과 개수를 함께 업데이트하세요."
+fi
+
+if [ -z "$SUGGESTIONS" ]; then
+  exit 0
+fi
+
+python3 -c "
+import json, sys
+suggestions = sys.argv[1]
+output = {
+    'hookSpecificOutput': {
+        'hookEventName': 'PreToolUse',
+        'additionalContext': '[Solmate Skills 파일 감지]\n' + suggestions.strip()
+    }
+}
+print(json.dumps(output))
+" "$SUGGESTIONS"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solmate-skills",
-  "version": "2.0.5",
+  "version": "2.0.7",
   "description": "Curated skills for Solmate projects",
   "main": "bin/cli.js",
   "bin": {

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-react/scripts/fetch-stitch.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+URL=$1
+OUTPUT=$2
+if [ -z "$URL" ] || [ -z "$OUTPUT" ]; then
+  echo "Usage: $0 <url> <output_path>"
+  exit 1
+fi
+echo "Initiating high-reliability fetch for Stitch HTML..."
+curl -L -f -sS --connect-timeout 10 --compressed "$URL" -o "$OUTPUT"
+if [ $? -eq 0 ]; then
+  echo "✅ Successfully retrieved HTML at: $OUTPUT"
+  exit 0
+else
+  echo "❌ Error: Failed to retrieve content. Check TLS/SNI or URL expiration."
+  exit 1
+fi

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/tools-shadcn/scripts/verify-setup.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+# shadcn/ui Setup Verification Script
+# Validates that a project is correctly configured for shadcn/ui
+
+set -e
+
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+echo "🔍 Verifying shadcn/ui setup..."
+echo ""
+
+# Check if components.json exists
+if [ -f "components.json" ]; then
+    echo -e "${GREEN}✓${NC} components.json found"
+else
+    echo -e "${RED}✗${NC} components.json not found"
+    echo -e "  ${YELLOW}Run:${NC} npx shadcn@latest init"
+    exit 1
+fi
+
+# Check if tailwind.config exists
+if [ -f "tailwind.config.js" ] || [ -f "tailwind.config.ts" ]; then
+    echo -e "${GREEN}✓${NC} Tailwind config found"
+else
+    echo -e "${RED}✗${NC} tailwind.config.js not found"
+    echo -e "  ${YELLOW}Install Tailwind:${NC} npm install -D tailwindcss postcss autoprefixer"
+    exit 1
+fi
+
+# Check if tsconfig.json has path aliases
+if [ -f "tsconfig.json" ]; then
+    if grep -q '"@/\*"' tsconfig.json; then
+        echo -e "${GREEN}✓${NC} Path aliases configured in tsconfig.json"
+    else
+        echo -e "${YELLOW}⚠${NC} Path aliases not found in tsconfig.json"
+        echo "  Add to compilerOptions.paths:"
+        echo '  "@/*": ["./src/*"]'
+    fi
+else
+    echo -e "${YELLOW}⚠${NC} tsconfig.json not found (TypeScript not configured)"
+fi
+
+# Check if globals.css or equivalent exists
+if [ -f "src/index.css" ] || [ -f "src/globals.css" ] || [ -f "app/globals.css" ]; then
+    echo -e "${GREEN}✓${NC} Global CSS file found"
+    
+    # Check for Tailwind directives
+    CSS_FILE=$(find . -name "globals.css" -o -name "index.css" | head -n 1)
+    if grep -q "@tailwind base" "$CSS_FILE"; then
+        echo -e "${GREEN}✓${NC} Tailwind directives present"
+    else
+        echo -e "${RED}✗${NC} Tailwind directives missing"
+        echo "  Add to your CSS file:"
+        echo "  @tailwind base;"
+        echo "  @tailwind components;"
+        echo "  @tailwind utilities;"
+    fi
+    
+    # Check for CSS variables
+    if grep -q "^:root" "$CSS_FILE" || grep -q "@layer base" "$CSS_FILE"; then
+        echo -e "${GREEN}✓${NC} CSS variables defined"
+    else
+        echo -e "${YELLOW}⚠${NC} CSS variables not found"
+        echo "  shadcn/ui requires CSS variables for theming"
+    fi
+else
+    echo -e "${RED}✗${NC} Global CSS file not found"
+fi
+
+# Check if components/ui directory exists
+if [ -d "src/components/ui" ] || [ -d "components/ui" ]; then
+    echo -e "${GREEN}✓${NC} components/ui directory exists"
+    
+    # Count components
+    COMPONENT_COUNT=$(find . -path "*/components/ui/*.tsx" -o -path "*/components/ui/*.jsx" | wc -l)
+    echo -e "  ${COMPONENT_COUNT} components installed"
+else
+    echo -e "${YELLOW}⚠${NC} components/ui directory not found"
+    echo "  Add your first component: npx shadcn@latest add button"
+fi
+
+# Check if lib/utils exists
+if [ -f "src/lib/utils.ts" ] || [ -f "lib/utils.ts" ]; then
+    echo -e "${GREEN}✓${NC} lib/utils.ts exists"
+    
+    # Check for cn function
+    UTILS_FILE=$(find . -name "utils.ts" | grep "lib" | head -n 1)
+    if grep -q "export function cn" "$UTILS_FILE"; then
+        echo -e "${GREEN}✓${NC} cn() utility function present"
+    else
+        echo -e "${RED}✗${NC} cn() utility function missing"
+    fi
+else
+    echo -e "${RED}✗${NC} lib/utils.ts not found"
+fi
+
+# Check package.json dependencies
+if [ -f "package.json" ]; then
+    echo ""
+    echo "📦 Checking dependencies..."
+    
+    # Required dependencies
+    REQUIRED_DEPS=("react" "tailwindcss")
+    RECOMMENDED_DEPS=("class-variance-authority" "clsx" "tailwind-merge" "tailwindcss-animate")
+    
+    for dep in "${REQUIRED_DEPS[@]}"; do
+        if grep -q "\"$dep\"" package.json; then
+            echo -e "${GREEN}✓${NC} $dep installed"
+        else
+            echo -e "${RED}✗${NC} $dep not installed"
+        fi
+    done
+    
+    echo ""
+    echo "Recommended dependencies:"
+    for dep in "${RECOMMENDED_DEPS[@]}"; do
+        if grep -q "\"$dep\"" package.json; then
+            echo -e "${GREEN}✓${NC} $dep installed"
+        else
+            echo -e "${YELLOW}⚠${NC} $dep not installed (recommended)"
+        fi
+    done
+fi
+
+echo ""
+echo -e "${GREEN}✓${NC} Setup verification complete!"
+echo ""
+echo "Next steps:"
+echo "  1. Add components: npx shadcn@latest add [component]"
+echo "  2. View catalog: npx shadcn@latest add --help"
+echo "  3. Browse docs: https://ui.shadcn.com"