solmate-skills 2.0.3 → 2.0.5

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."