solmate-skills 2.0.5 → 2.0.7

package/AGENTS.md

@@ -56,6 +56,23 @@
 - **파일 네이밍**: 모든 파일명 앞에는 `01_`과 같은 **순번(Numbering)**을 반드시 붙여 생성 순서와 계층을 명확히 한다. (예: `01_VISION.md`, `02_UI_DESIGN.md`)
 - **Interactive Process**: 문서를 작성할 때 AI가 독단적으로 내용을 채우지 않는다. 초안 작성 전, **반드시 사용자에게 핵심 질문을 던지고 답변을 바탕으로 문서를 작성(Ask before Write)**한다.
 
+### 2.7. SVG 다이어그램 산출물 표준 (User Journey & Data Flow)
+- **사용자 동선 SVG 필수화**: 주요 기능·화면 흐름 문서에는 사용자 동선(User Journey / Screen Flow)을 설명하는 SVG 다이어그램을 포함한다.
+- **저장 위치**: 사용자 동선 SVG는 `docs/02_UI_Screens/assets/`에 저장하고, 관련 UI 스크린 문서에서 상대 경로로 참조한다.
+- **데이터 흐름 SVG 필수화**: 주요 기능의 기술 명세에는 데이터 흐름(Data Flow / API-DB-External Service Flow)을 설명하는 SVG 다이어그램을 포함한다.
+- **저장 위치**: 데이터 흐름 SVG는 `docs/03_Technical_Specs/assets/`에 저장하고, 관련 기술 명세 문서에서 상대 경로로 참조한다.
+- **작업 관리 위치**: SVG 작성·수정 작업은 `docs/04_Logic_Progress/00_BACKLOG.md` 또는 `docs/04_Logic_Progress/02_EXECUTION_PLAN.md`에 태스크로 관리한다.
+- **검증 위치**: 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을 수행한다.
@@ -87,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, 번들, 이미지) |
@@ -112,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

@@ -2,17 +2,20 @@
 
 Curated skills for Solmate projects. Easily share and install AI tool skills across your team.
 
-## What's New in 2.0.4
+## What's New in 2.0.6
 
-`solmate-skills@2.0.4` keeps **Backlog Context Lock** as the current documentation guardrail, adds **UI-First Gate** expectations, and tightens package hygiene for Codex-local settings.
+`solmate-skills@2.0.6` keeps **Backlog Context Lock** as the current documentation guardrail, adds **UI-First Gate** expectations, requires browser-viewable **HTML UI Previews**, formalizes SVG diagram outputs, and fixes package hygiene so installable skill scripts are included in the npm tarball.
 
 Key changes:
 
 - 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.
+- UI planning must include HTML preview files under `docs/02_UI_Screens/previews/` and link them from the related UI documents.
+- 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.
+- Local Codex settings under `.codex/` are excluded from the npm package, while skill-owned shell scripts remain publishable.
 
 ## Installation
 
@@ -159,7 +162,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. |
 
 ---
@@ -193,13 +196,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.
@@ -210,12 +214,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`
@@ -234,6 +256,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:
@@ -241,6 +265,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/ext-k-skill/scripts/check-setup.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+secrets_file="${1:-$HOME/.config/k-skill/secrets.env}"
+
+missing=0
+
+if [[ ! -f "$secrets_file" ]]; then
+  echo "missing secrets file: $secrets_file"
+  missing=1
+else
+  perms=$(stat -f '%Lp' "$secrets_file" 2>/dev/null || stat -c '%a' "$secrets_file" 2>/dev/null)
+  if [[ "$perms" != "600" ]]; then
+    echo "insecure permissions on $secrets_file: $perms (expected 600)"
+    missing=1
+  fi
+fi
+
+if [[ "$missing" -ne 0 ]]; then
+  cat <<EOF
+next steps:
+  1. create ~/.config/k-skill/secrets.env with your credentials
+  2. chmod 0600 ~/.config/k-skill/secrets.env
+  3. run this check again
+EOF
+  exit 1
+fi
+
+echo "k-skill setup looks usable"

package/ext-k-skill/scripts/run-k-skill-proxy.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SECRETS_FILE="${KSKILL_SECRETS_FILE:-$HOME/.config/k-skill/secrets.env}"
+
+if [[ -f "$SECRETS_FILE" ]]; then
+  set -a
+  # shellcheck disable=SC1090
+  source "$SECRETS_FILE"
+  set +a
+fi
+
+cd "$ROOT_DIR"
+exec node packages/k-skill-proxy/src/server.js

package/ext-k-skill/scripts/validate-skills.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+status=0
+
+while IFS= read -r -d '' skill_dir; do
+  skill_name="$(basename "$skill_dir")"
+  skill_file="$skill_dir/SKILL.md"
+
+  if [[ ! -f "$skill_file" ]]; then
+    echo "missing SKILL.md: $skill_name"
+    status=1
+    continue
+  fi
+
+  if ! head -n 1 "$skill_file" | grep -qx -- "---"; then
+    echo "missing frontmatter start: $skill_file"
+    status=1
+  fi
+
+  if ! grep -q '^name: ' "$skill_file"; then
+    echo "missing name field: $skill_file"
+    status=1
+  fi
+
+  if ! grep -q '^description: ' "$skill_file"; then
+    echo "missing description field: $skill_file"
+    status=1
+  fi
+
+  declared_name="$(sed -n 's/^name: //p' "$skill_file" | head -n 1 | tr -d '"')"
+  if [[ "$declared_name" != "$skill_name" ]]; then
+    echo "name mismatch: $skill_file declares '$declared_name' but directory is '$skill_name'"
+    status=1
+  fi
+done < <(
+  find "$root" -mindepth 1 -maxdepth 1 -type d \
+    ! -name .git \
+    ! -name .github \
+    ! -name .omx \
+    ! -name .changeset \
+    ! -name docs \
+    ! -name node_modules \
+    ! -name packages \
+    ! -name python-packages \
+    ! -name scripts \
+    ! -name examples \
+    -print0
+)
+
+if [[ "$status" -ne 0 ]]; then
+  exit "$status"
+fi
+
+echo "skill layout looks valid"

package/hooks/install.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+# solmate-skills: install.sh
+# Purpose: Install Solmate hook scripts into the current project's .claude/ directory
+#          and merge hook configuration into .claude/settings.json.
+# Usage:   bash .agent/skills/hooks/install.sh
+#          (or run from any location: bash <path-to-hooks>/install.sh)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(pwd)"
+CLAUDE_DIR="$PROJECT_ROOT/.claude"
+HOOKS_DIR="$CLAUDE_DIR/hooks"
+SETTINGS_FILE="$CLAUDE_DIR/settings.json"
+
+echo "Solmate Skills — Hook Installer"
+echo "Project: $PROJECT_ROOT"
+echo ""
+
+# --- Step 1: Create .claude/hooks/ ---
+mkdir -p "$HOOKS_DIR"
+echo "[1/4] Created $HOOKS_DIR"
+
+# --- Step 2: Copy hook scripts ---
+cp "$SCRIPT_DIR/suggest-skills.sh"   "$HOOKS_DIR/solmate-suggest.sh"
+cp "$SCRIPT_DIR/watch-files.sh"      "$HOOKS_DIR/solmate-watch.sh"
+cp "$SCRIPT_DIR/verify-suggest.sh"   "$HOOKS_DIR/solmate-verify-suggest.sh"
+chmod +x "$HOOKS_DIR/solmate-suggest.sh"
+chmod +x "$HOOKS_DIR/solmate-watch.sh"
+chmod +x "$HOOKS_DIR/solmate-verify-suggest.sh"
+echo "[2/4] Copied hook scripts:"
+echo "      .claude/hooks/solmate-suggest.sh         (UserPromptSubmit)"
+echo "      .claude/hooks/solmate-watch.sh           (PreToolUse)"
+echo "      .claude/hooks/solmate-verify-suggest.sh  (Stop)"
+
+# --- Step 3: Merge hook config into settings.json ---
+echo "[3/4] Merging hook config into $SETTINGS_FILE"
+
+python3 - "$SETTINGS_FILE" <<'PYEOF'
+import sys, json, os
+
+settings_path = sys.argv[1]
+
+# Load existing settings or start fresh
+if os.path.exists(settings_path):
+    with open(settings_path, 'r') as f:
+        try:
+            settings = json.load(f)
+        except json.JSONDecodeError:
+            print(f"  WARNING: {settings_path} has invalid JSON. Backing up and starting fresh.")
+            os.rename(settings_path, settings_path + '.bak')
+            settings = {}
+else:
+    settings = {}
+
+hooks = settings.setdefault('hooks', {})
+
+# --- UserPromptSubmit hook ---
+suggest_cmd = "bash .claude/hooks/solmate-suggest.sh"
+submit_hooks = hooks.setdefault('UserPromptSubmit', [])
+
+# Check for duplicate
+already_has_suggest = any(
+    h.get('command') == suggest_cmd
+    for entry in submit_hooks
+    for h in entry.get('hooks', [])
+)
+if not already_has_suggest:
+    submit_hooks.append({
+        "hooks": [{
+            "type": "command",
+            "command": suggest_cmd,
+            "timeout": 5
+        }]
+    })
+    print("  Added: UserPromptSubmit → solmate-suggest.sh")
+else:
+    print("  Skipped (already exists): UserPromptSubmit → solmate-suggest.sh")
+
+# --- PreToolUse hook ---
+watch_cmd = "bash .claude/hooks/solmate-watch.sh"
+pre_hooks = hooks.setdefault('PreToolUse', [])
+
+already_has_watch = any(
+    h.get('command') == watch_cmd
+    for entry in pre_hooks
+    for h in entry.get('hooks', [])
+)
+if not already_has_watch:
+    pre_hooks.append({
+        "matcher": "Read|Write|Edit|Bash",
+        "hooks": [{
+            "type": "command",
+            "command": watch_cmd,
+            "timeout": 5
+        }]
+    })
+    print("  Added: PreToolUse (Read|Write|Edit|Bash) → solmate-watch.sh")
+else:
+    print("  Skipped (already exists): PreToolUse → solmate-watch.sh")
+
+# --- Stop hook ---
+verify_cmd = "bash .claude/hooks/solmate-verify-suggest.sh"
+stop_hooks = hooks.setdefault('Stop', [])
+
+already_has_verify = any(
+    h.get('command') == verify_cmd
+    for entry in stop_hooks
+    for h in entry.get('hooks', [])
+)
+if not already_has_verify:
+    stop_hooks.append({
+        "hooks": [{
+            "type": "command",
+            "command": verify_cmd,
+            "timeout": 10,
+            "statusMessage": "변경 파일 분석 중..."
+        }]
+    })
+    print("  Added: Stop → solmate-verify-suggest.sh")
+else:
+    print("  Skipped (already exists): Stop → solmate-verify-suggest.sh")
+
+# Write back
+os.makedirs(os.path.dirname(settings_path), exist_ok=True)
+with open(settings_path, 'w') as f:
+    json.dump(settings, f, indent=2, ensure_ascii=False)
+    f.write('\n')
+
+print(f"  Saved: {settings_path}")
+PYEOF
+
+# --- Step 4: Add .claude/hooks/ to .gitignore if not already there ---
+GITIGNORE="$PROJECT_ROOT/.gitignore"
+if [ -f "$GITIGNORE" ]; then
+  if ! grep -q "\.claude/hooks/" "$GITIGNORE" 2>/dev/null; then
+    echo "" >> "$GITIGNORE"
+    echo "# Solmate hook scripts (project-local)" >> "$GITIGNORE"
+    echo ".claude/hooks/" >> "$GITIGNORE"
+    echo "[4/4] Added .claude/hooks/ to .gitignore"
+  else
+    echo "[4/4] .gitignore already excludes .claude/hooks/"
+  fi
+else
+  echo "[4/4] No .gitignore found — skipping"
+fi
+
+echo ""
+echo "Done. Hooks are active in this project."
+echo ""
+echo "What was installed:"
+echo "  UserPromptSubmit  → 프롬프트 키워드 감지 → 관련 스킬 제안"
+echo "  PreToolUse        → 편집 중인 파일 패턴 감지 → 관련 스킬 제안"
+echo "  Stop              → 작업 완료 후 변경 파일 분석 → verify-* 스킬 실행 시점 알림"
+echo ""
+echo "To review or disable hooks, open /hooks in Claude Code."
+echo "To uninstall, remove .claude/hooks/ and the 'hooks' section from .claude/settings.json."