solmate-skills 2.0.4 → 2.0.6

package/verify-implementation/SKILL.md

@@ -5,35 +5,89 @@ disable-model-invocation: true
 argument-hint: "[선택사항: 특정 verify 스킬 이름]"
 ---
 
-# 구현 검증 (Master Template)
+# 구현 검증 (Master)
 
 ## 목적
 
-프로젝트에 존재하는 모든 `verify-*` 스킬을 동적으로 탐색하여 순차적으로 실행하고 통합 검증을 수행합니다.
+프로젝트에 존재하는 모든 `verify-*` 스킬을 동적으로 탐색하여 순차적으로 실행하고 통합 검증을 수행합니다. 기본 순서를 따르되, 변경 파일과 프로젝트 특성에 따라 해당 없는 스킬은 `N/A - 사유`로 기록합니다.
 
-## 실행 대상 스킬 (Dynamic)
+## 기본 실행 순서
 
-| # | 스킬 | 설명 |
-|---|------|------|
-| * | `verify-*` | `.agent/skills` 또는 `.claude/commands`에서 자동 탐색 |
+| 순서 | 스킬 | 목적 |
+|---:|---|---|
+| 1 | `verify-docs` | 문서 구조, Backlog Context Lock, UI-First Gate 검증 |
+| 2 | `verify-ui` | 구현 UI와 화면 문서, 사용자 동선, 상태별 UI 일치 검증 |
+| 3 | `verify-code` | 코드 품질, 타입, 로직, 사이드 이펙트 검증 |
+| 4 | `verify-security` | 인증·인가·입력·시크릿·OWASP 보안 검증 |
+| 5 | `verify-performance` | Lighthouse, Core Web Vitals, 렌더링·번들 검증 |
+| 6 | `verify-drizzle-schema` | DB 스키마 변경 시 명세·관계·인덱스 검증 |
+| 7 | `verify-skills` | solmate-skills 패키지 자체 변경 시 스킬 메타데이터·CLI·패키징 검증 |
 
 ## 워크플로우
 
+### Step 0: Flow 위치 확인
+검증을 시작하기 전에 `rules-product`의 `Flow Status Block` 형식으로 현재 위치를 보고합니다. 일반적으로 현재 위치는 `Phase 5 — 품질 검증`입니다.
+
+```
+[Flow]
+현재: Phase 5 — 품질 검증
+Gate: Quality Gate 진행 중
+완료: Phase 1, Phase 2, UI-First Gate, Pre-Code Technical Brief, Phase 3, Phase 4
+다음: Phase 6 — 최종 전달물 또는 Handoff
+필요 확인: Fail 항목 또는 N/A 처리 사유
+권장 스킬: /verify-implementation
+```
+
 ### Step 1: 동적 스킬 탐색
-`.agent/skills/` 및 `.claude/commands/` 하위의 `verify-*` 패턴을 탐색합니다.
+`.agent/skills/`, `.claude/commands/`, 또는 현재 저장소 하위의 `verify-*` 패턴을 탐색합니다.
+
+### Step 2: 변경 파일 기반 실행 계획 수립
+`git diff --name-only HEAD` 기준으로 실행 대상을 정합니다.
 
-### Step 2: 순차 실행
-각 스킬의 `Workflow`, `Exceptions`, `Related Files`를 파싱하여 개별 검사를 수행합니다.
+- 문서 변경: `verify-docs`
+- TS/TSX/JS/JSX 변경: `verify-code`
+- TSX/JSX 화면 변경: `verify-ui`
+- auth/api/middleware/env/db 변경: `verify-security`
+- page/layout/image/font/bundle 관련 변경: `verify-performance`
+- schema/migration 변경: `verify-drizzle-schema`
+- `SKILL.md`, `agents/openai.yaml`, `bin/cli.js`, `README.md`, `AGENTS.md`, `package.json` 변경: `verify-skills`
 
-### Step 3: 통합 보고서 생성
+### Step 3: 순차 실행
+기본 실행 순서대로 각 스킬의 `Workflow`, `Exceptions`, `Related Files`를 파싱하여 개별 검사를 수행합니다. 앞 단계가 Fail이면 뒤 단계는 실행하되, 해당 Fail이 뒤 단계 판단을 왜곡하는 경우 `Blocked - 사유`로 표시합니다.
+
+### Step 4: 통합 보고서 생성
 PASS/FAIL 통계와 발견된 이슈 목록을 생성합니다.
+보고서 상단에는 `Flow Status Block`을 다시 포함하고, Gate 상태를 `통과`, `미통과`, `Blocked`, `N/A` 중 하나로 표시합니다.
 
-### Step 4: 수정 옵션 제공
+### Step 5: 수정 옵션 제공
 자동 수정 또는 개별 수정을 사용자에게 제안합니다.
 
-### Step 5: 수정 적용 및 재검증
+### Step 6: 수정 적용 및 재검증
 수정이 적용된 경우 해당 스킬을 다시 실행하여 통과 여부를 최종 확인합니다.
 
+## 보고 형식
+
+```
+## 통합 구현 검증 결과
+
+| 순서 | 스킬 | 결과 | 비고 |
+|---:|---|:---:|---|
+| 1 | verify-docs | Pass / Fail / N/A | |
+| 2 | verify-ui | Pass / Fail / N/A | |
+| 3 | verify-code | Pass / Fail / N/A | |
+| 4 | verify-security | Pass / Fail / N/A | |
+| 5 | verify-performance | Pass / Fail / N/A | |
+| 6 | verify-drizzle-schema | Pass / Fail / N/A | |
+| 7 | verify-skills | Pass / Fail / N/A | |
+
+### 배포/PR 차단 항목
+- [높음] ...
+
+### 재검증 필요 항목
+- ...
+```
+
 ## 예외사항
 1. **자기 자신** (`verify-implementation`)은 실행 대상에서 제외.
 2. **관리 스킬** (`manage-skills` 등)은 `verify-`로 시작하지 않으므로 제외.
+3. **해당 없음**: DB, UI, 패키지 메타데이터 등 변경 범위와 관련 없는 검증은 `N/A - 사유`로 기록.

package/verify-implementation/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Implementation Verification"
+  short_description: "Run all verification skills as one review"
+  default_prompt: "Use $verify-implementation to discover and run the relevant verify skills before PR."

package/verify-performance/SKILL.md

@@ -176,6 +176,20 @@ npx lighthouse http://localhost:3000 --view --output=html
 
 ---
 
+## Check 7: 상태별 UI 성능
+
+UI-First Gate에서 정의한 로딩, 빈 상태, 오류 상태가 성능과 레이아웃 안정성을 해치지 않는지 확인한다.
+
+- 로딩 스켈레톤 또는 placeholder가 최종 콘텐츠와 유사한 크기를 가져 CLS를 줄이는지 점검한다.
+- 빈 상태와 오류 상태가 이미지·아이콘·폰트를 과도하게 로드하지 않는지 확인한다.
+- 모바일 첫 화면에서 핵심 CTA가 로딩 상태 또는 오류 배너에 밀려 사라지지 않는지 확인한다.
+- 체크:
+  - [ ] 로딩 상태가 최종 레이아웃과 유사한 공간을 예약하는가?
+  - [ ] 빈/오류 상태가 불필요한 대형 에셋을 초기 로드하지 않는가?
+  - [ ] 상태 전환이 CLS 또는 긴 INP를 유발하지 않는가?
+
+---
+
 ## 보고 형식
 
 ```
@@ -196,6 +210,7 @@ npx lighthouse http://localhost:3000 --view --output=html
 |------|-----------|------|:---------:|
 | src/pages/Home.tsx | 이미지 최적화 | <img> 직접 사용, LCP 지연 가능성 | LCP |
 | src/app/layout.tsx | 폰트 최적화 | Google Fonts <link> 직접 로드 | CLS·FCP |
+| src/components/List.tsx | 상태별 UI 성능 | Empty state 전환 시 레이아웃 시프트 가능 | CLS |
 
 ### 수정 권장 우선순위
 1. [높음] ...
@@ -216,6 +231,7 @@ npx lighthouse http://localhost:3000 --view --output=html
 ## 관련 스킬
 
 - `verify-code`: 코드 품질 전반 리뷰
+- `verify-ui`: 화면 상태와 사용자 동선 검증
 - `verify-security`: 보안 취약점 점검
 - `rules-dev`: 렌더링 전략·코드 스플리팅 컨벤션 기준
 - `verify-implementation`: 전체 verify-* 통합 실행 시 포함 대상

package/verify-performance/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Performance Verification"
+  short_description: "Check Lighthouse and Core Web Vitals risks"
+  default_prompt: "Use $verify-performance to inspect rendering, bundle, image, and Lighthouse risks."

package/verify-security/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Security Verification"
+  short_description: "Review OWASP security risks before release"
+  default_prompt: "Use $verify-security to review authentication, authorization, inputs, secrets, and OWASP risks."

package/verify-skills/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: verify-skills
+description: solmate-skills 패키지 자체를 검증합니다. SKILL.md frontmatter, agents/openai.yaml, CLI 목록, README/AGENTS 스킬 목록, 버전 문구, npm pack dry-run을 점검합니다. 스킬 추가·수정 후, 배포 전, 또는 "스킬 패키지 검증" 요청 시 사용합니다.
+argument-hint: "[선택사항: 특정 스킬 이름 또는 점검 영역]"
+---
+
+# 스킬 패키지 검증 스킬 (verify-skills)
+
+`solmate-skills` 저장소 자체의 배포 품질과 스킬 메타데이터 정합성을 검증한다.
+
+---
+
+## 실행 시점
+
+- 새 스킬 추가 또는 기존 스킬 수정 후
+- `bin/cli.js`, `README.md`, `AGENTS.md`, `package.json` 수정 후
+- npm 배포 또는 태그 생성 전
+- `rules-workflow` Step 17 또는 `verify-implementation` 실행 시
+
+---
+
+## Step 0: 검증 범위 확정
+
+인자가 있으면 해당 스킬 또는 영역만 점검한다. 없으면 루트 패키지 전체를 점검한다.
+
+```bash
+find . -maxdepth 2 -name SKILL.md -print | sort
+node bin/cli.js list
+git status --short
+```
+
+---
+
+## Check 1: 스킬 디렉터리와 CLI 목록
+
+- 루트의 설치 가능한 스킬은 `SKILL.md`가 있는 디렉터리여야 한다.
+- `.claude`, `.codex`, `hooks`, `bin`, `node_modules` 같은 비스킬 디렉터리가 CLI 목록에 나오면 Fail이다.
+
+```bash
+node bin/cli.js list
+find . -maxdepth 2 -name SKILL.md -print | sed 's#^\./##; s#/SKILL.md$##' | sort
+```
+
+- 체크:
+  - [ ] CLI 목록이 실제 `SKILL.md` 보유 디렉터리와 일치하는가?
+  - [ ] 비스킬 디렉터리가 설치 대상으로 노출되지 않는가?
+  - [ ] 새 verify 스킬이 README와 AGENTS 목록에 반영되었는가?
+
+---
+
+## Check 2: SKILL.md frontmatter
+
+- 모든 `SKILL.md`가 YAML frontmatter를 갖고, `name`, `description`이 유효한지 확인한다.
+- `name`은 소문자 hyphen-case여야 한다.
+
+```bash
+python3 -c 'import pathlib, yaml, re
+for p in pathlib.Path(".").glob("*/SKILL.md"):
+    text=p.read_text()
+    m=re.match(r"^---\n(.*?)\n---", text, re.S)
+    assert m, f"frontmatter missing: {p}"
+    data=yaml.safe_load(m.group(1))
+    assert data.get("name") and data.get("description"), f"name/description missing: {p}"
+    assert re.match(r"^[a-z0-9-]+$", data["name"]), f"bad name: {p}"
+print("frontmatter ok")'
+```
+
+- 체크:
+  - [ ] 모든 `SKILL.md` frontmatter가 파싱되는가?
+  - [ ] `name`과 폴더명이 불필요하게 어긋나지 않는가?
+  - [ ] `description`이 사용 시점을 충분히 설명하는가?
+
+---
+
+## Check 3: agents/openai.yaml
+
+- 루트에서 직접 추적하는 스킬은 `agents/openai.yaml`을 갖는 것이 원칙이다. `git ls-files -s`에서 mode `160000`으로 표시되는 gitlink 외부 확장은 제외한다.
+- `interface.display_name`, `short_description`, `default_prompt`가 있어야 하며, `default_prompt`에는 `$skill-name`이 포함되어야 한다.
+
+```bash
+python3 -c 'import pathlib, subprocess, yaml
+bad=[]
+gitlinks=set()
+for line in subprocess.run(["git", "ls-files", "-s"], capture_output=True, text=True).stdout.splitlines():
+    parts=line.split()
+    if len(parts) >= 4 and parts[0] == "160000":
+        gitlinks.add(parts[3])
+for skill in [p.parent for p in pathlib.Path(".").glob("*/SKILL.md")]:
+    if skill.as_posix() in gitlinks:
+        continue
+    meta=skill/"agents/openai.yaml"
+    if not meta.exists():
+        bad.append(f"missing openai.yaml: {skill}")
+        continue
+    data=yaml.safe_load(meta.read_text())
+    interface=data.get("interface", {})
+    prompt=interface.get("default_prompt", "")
+    if "$"+skill.name not in prompt:
+        bad.append(f"default_prompt missing ${skill.name}: {meta}")
+    if not (25 <= len(interface.get("short_description", "")) <= 64):
+        bad.append(f"bad short_description: {meta}")
+print("metadata ok" if not bad else "\n".join(bad))'
+```
+
+- 체크:
+  - [ ] 각 스킬에 `agents/openai.yaml`이 있는가?
+  - [ ] `short_description` 길이가 25-64자인가?
+  - [ ] `default_prompt`가 해당 `$skill-name`을 명시하는가?
+
+---
+
+## Check 4: README, AGENTS, package 버전 동기화
+
+- `package.json` 버전과 README의 최신 버전 문구가 일치하는지 확인한다.
+- README와 AGENTS의 verify 목록이 실제 `verify-*` 디렉터리와 맞는지 확인한다.
+
+```bash
+node -p "require('./package.json').version"
+grep -n "What's New in" README.md
+find . -maxdepth 1 -type d -name 'verify-*' -exec basename {} \; | sort
+grep -n "verify-" README.md AGENTS.md
+```
+
+- 체크:
+  - [ ] README 최신 버전 문구가 `package.json`과 일치하는가?
+  - [ ] README Available Skills에 새 스킬이 반영되었는가?
+  - [ ] AGENTS.md 품질 검증 목록에 새 verify 스킬이 반영되었는가?
+
+---
+
+## Check 5: 패키징 검증
+
+- npm 패키징 dry-run이 통과해야 한다.
+- 사용자 홈 npm 캐시 권한 문제를 피하려면 임시 캐시를 사용할 수 있다.
+
+```bash
+npm_config_cache=/private/tmp/solmate-npm-cache npm pack --dry-run
+```
+
+- 체크:
+  - [ ] dry-run이 성공하는가?
+  - [ ] tarball 내용에 새 스킬 파일과 `agents/openai.yaml`이 포함되는가?
+  - [ ] dry-run 후 실제 `.tgz` 파일이 작업트리에 남지 않았는가?
+
+---
+
+## 보고 형식
+
+```
+## 스킬 패키지 검증 결과
+
+| 검사 항목 | 결과 | 비고 |
+|:---|:---:|:---|
+| CLI 목록 | Pass / Fail | |
+| SKILL.md frontmatter | Pass / Fail | |
+| agents/openai.yaml | Pass / Fail | |
+| README/AGENTS 동기화 | Pass / Fail | |
+| npm pack dry-run | Pass / Fail | |
+
+### 수정 필요 항목
+- [높음] ...
+```
+
+---
+
+## Exceptions
+
+1. **gitlink 외부 확장**: `ext-*`가 gitlink 또는 외부 소스 묶음이면 루트 저장소의 `agents/openai.yaml` 필수 대상에서 제외할 수 있다.
+2. **실험 중인 로컬 스킬**: 배포 대상이 아니라고 명시된 로컬 실험 폴더는 CLI 설치 대상에서 제외되어야 한다.
+3. **npm 캐시 권한 문제**: 사용자 홈 npm 캐시 권한 오류는 코드 Fail이 아니며, 임시 캐시로 재검증한다.
+
+---
+
+## 관련 스킬
+
+- `manage-skills`: verify 스킬 드리프트 탐지
+- `skill-creator`: 스킬 구조와 metadata 작성 기준
+- `verify-docs`: 문서 레이어 검증
+- `verify-implementation`: 전체 verify 스킬 통합 실행

package/verify-skills/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Skills Package Verification"
+  short_description: "Validate skill package metadata and release readiness"
+  default_prompt: "Use $verify-skills to validate skill metadata, CLI output, docs lists, and package dry-run."

package/verify-ui/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: verify-ui
+description: UI 구현이 docs/02_UI_Screens의 화면 설계, 사용자 동선, 데이터 흐름, 로딩·빈 상태·오류 상태와 일치하는지 검증합니다. React/TSX 화면 구현 후, UI-First Gate 확인 후, 또는 "UI 검증", "UX 확인", "화면이 문서와 맞는지 봐줘" 요청 시 사용합니다.
+argument-hint: "[선택사항: 점검할 화면, 라우트, 컴포넌트 경로]"
+---
+
+# UI 구현 검증 스킬 (verify-ui)
+
+구현된 화면이 UI-First Gate에서 합의한 화면 구조, 사용자 동선, 데이터 흐름, 상태별 UI를 실제로 반영하는지 검증한다.
+
+---
+
+## 실행 시점
+
+- React/TSX 화면 또는 컴포넌트 구현 후
+- `rules-workflow` Step 15 사용자 사용 흐름 확인 시
+- `docs/02_UI_Screens/` 문서와 구현 결과의 일치 여부를 확인할 때
+- PR 전 UI/UX 회귀 점검 시
+
+---
+
+## Step 0: 검증 범위 확정
+
+인자가 있으면 해당 화면·라우트·컴포넌트에 집중한다. 없으면 변경된 UI 파일과 관련 문서를 먼저 찾는다.
+
+```bash
+git diff --name-only HEAD
+find docs/02_UI_Screens -maxdepth 1 -type f -name '*.md' 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`를 읽는다.
+
+---
+
+## Check 1: 화면 구조 일치
+
+- 구현된 화면의 주요 영역, 정보 위계, CTA가 UI 문서와 일치하는지 확인한다.
+- 화면에 필요한 헤더, 내비게이션, 주요 콘텐츠, 보조 액션, 피드백 영역이 빠지지 않았는지 점검한다.
+- 체크:
+  - [ ] 주요 화면과 컴포넌트가 문서의 화면 목록과 대응되는가?
+  - [ ] CTA 문구와 위치가 사용자 흐름상 자연스러운가?
+  - [ ] 문서에 없는 큰 UI 변경이 있다면 관련 문서가 업데이트되었는가?
+
+---
+
+## Check 2: 사용자 동선
+
+- 진입, 다음 행동, 뒤로가기/취소, 완료, 이탈 경로가 구현되어 있는지 확인한다.
+- 링크, 버튼, 폼 제출, 모달, 탭, 라우팅이 `00_SCREEN_FLOW.md`의 흐름과 맞는지 점검한다.
+- 체크:
+  - [ ] 핵심 사용자 여정이 끊기지 않는가?
+  - [ ] 주요 CTA가 실제 라우트 또는 상태 변경과 연결되는가?
+  - [ ] 실패 또는 취소 후 사용자가 회복할 경로가 있는가?
+
+---
+
+## Check 3: 데이터 흐름과 상태
+
+- 화면별 입력 데이터, 표시 데이터, 저장/전송 데이터가 문서와 일치하는지 확인한다.
+- mock data, API 응답, 폼 상태, 파생 상태가 화면 요구사항을 과소/과대 구현하지 않는지 점검한다.
+- 체크:
+  - [ ] 화면에서 필요한 데이터가 모두 표시되는가?
+  - [ ] 입력값 검증과 제출 상태가 사용자에게 보이는가?
+  - [ ] 문서상 필요 없는 민감 데이터나 내부 상태가 노출되지 않는가?
+
+---
+
+## Check 4: 상태별 UI
+
+- 로딩, 빈 상태, 오류 상태, 권한 없음, 비활성 상태가 구현되어 있는지 확인한다.
+- 상태별 문구가 사용자의 다음 행동을 안내하는지 점검한다.
+- 체크:
+  - [ ] Loading state가 존재하고 레이아웃을 크게 흔들지 않는가?
+  - [ ] Empty state가 원인과 다음 행동을 설명하는가?
+  - [ ] Error state에 재시도, 이동, 문의 등 회복 경로가 있는가?
+  - [ ] Disabled state가 시각적으로만 아니라 실제 상호작용도 막는가?
+
+---
+
+## Check 5: 접근성과 반응형
+
+- 키보드 탐색, label, aria 속성, focus 상태, 색 대비, 모바일 레이아웃을 확인한다.
+- 체크:
+  - [ ] 버튼과 입력 요소에 접근 가능한 이름이 있는가?
+  - [ ] 폼 입력에 label 또는 aria-label이 있는가?
+  - [ ] 모달/드롭다운/탭이 키보드로 조작 가능한가?
+  - [ ] 모바일에서 텍스트, CTA, 주요 콘텐츠가 겹치거나 잘리지 않는가?
+
+---
+
+## 보고 형식
+
+```
+## UI 검증 결과
+
+### PASS 항목
+- (문제 없는 흐름과 화면 요약)
+
+### 개선 필요 항목
+| 위치 | 영역 | 내용 | 심각도 |
+|------|------|------|:------:|
+| src/app/page.tsx:42 | 상태별 UI | Empty state 미구현 | 중 |
+| src/components/Form.tsx:18 | 접근성 | input label 누락 | 중 |
+
+### 문서 동기화 필요
+- 구현이 문서와 다르면 수정할 문서 또는 코드 위치를 명시한다.
+```
+
+심각도 기준: **높음** (핵심 동선 차단) / **중** (사용성 또는 문서 불일치) / **낮음** (개선 권장)
+
+---
+
+## Exceptions
+
+1. **초기 스파이크 UI**: 명시적으로 탐색용 스파이크라고 표시된 코드는 낮은 심각도로 보고하되, PR 전에는 문서 동기화를 요구한다.
+2. **관리자 내부 화면**: 공개 사용자 화면보다 시각 완성도 기준은 낮출 수 있으나, 상태별 UI와 접근성 기준은 유지한다.
+3. **외부 임베드 UI**: 지도, 결제, 인증 위젯 등 외부 위젯 내부 UI는 제외하되, 로딩·오류·복귀 경로는 검증한다.
+
+---
+
+## 관련 스킬
+
+- `docs-plan`: UI-First Gate와 UI 문서 작성 기준
+- `rules-react`: React 화면 구현 기준
+- `verify-docs`: UI 문서와 백로그 구조 검증
+- `verify-code`: 코드 품질 검토
+- `verify-performance`: 화면 성능 검증

package/verify-ui/agents/openai.yaml

@@ -0,0 +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."