@su-record/vibe 2.9.18 → 2.9.20

package/skills/vibe-contract/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: vibe-contract
+tier: core
+description: "API contract drift detection. Extracts HTTP/GraphQL/event/public-function contracts from SPEC into .claude/vibe/contracts/<feature>.md, compares to implementation, and fails loudly on breaking drift (missing endpoints, removed required fields, type changes). P1 drifts auto-register as regressions via vibe-regress. Must use this skill when user runs /vibe.contract, when /vibe.spec completes, when /vibe.verify passes scenarios, or when the user says 'contract', 'API schema', 'breaking change', 'drift', '계약', '스키마 바뀜'."
+triggers: [contract, drift, "계약", "API 변경", "breaking change", "schema drift"]
+priority: 70
+chain-next: []
+---
+
+# vibe.contract — API Contract Drift Detection
+
+**Purpose**: SPEC에 적힌 외부 계약과 실제 구현이 어긋나면 즉시 잡는다. 테스트 통과 ≠ 계약 준수.
+
+## Why this exists
+
+바이브코딩의 숨은 약점: 구현이 자라면서 SPEC에 명시된 응답 shape에서 조용히 벗어난다. 시나리오 테스트는 통과해도 **외부 소비자는 깨진다**. 사람이 매번 SPEC을 비교하기엔 마찰이 크므로 기계화.
+
+## Storage Contract
+
+```
+.claude/vibe/contracts/
+  <feature>.md             # 계약 SSOT (SPEC에서 추출)
+  <feature>.snapshot.md    # 구현 스냅샷 (마지막 check 시점)
+```
+
+### Contract frontmatter schema
+
+```yaml
+---
+feature: string
+extracted-from: .claude/vibe/specs/<feature>.md
+extracted-at: ISO-8601
+source-spec-hash: sha256  # SPEC 변경 감지용
+endpoints:
+  - id: unique-kebab-id         # 예: get-user-by-id
+    kind: http | graphql | event | function
+    # http
+    method: GET | POST | PUT | DELETE | PATCH
+    path: /users/:id
+    request:
+      params: { name: type, ... }
+      query: { name: type, ... }
+      body: { field: type, ... } | null
+      required: [field, ...]
+    response:
+      statusCodes:
+        200: { schema }
+        404: { error: string }
+      required-fields:
+        200: [id, email]
+    # graphql
+    operation: query | mutation
+    name: string
+    args: { ... }
+    returns: { ... }
+    # event
+    topic: string
+    payload: { ... }
+    # function
+    signature: "(a: string, b: number) => Promise<User>"
+    module: path/to/file.ts
+---
+```
+
+## Subcommands
+
+### 1. `extract <feature>` — SPEC에서 계약 추출
+
+**단계**:
+1. SPEC 파일 로드 (single file or split folder)
+2. 다음 섹션을 순서대로 탐색:
+   - `## API` / `## Endpoints` / `## Interface` / `## Contract`
+   - Markdown 테이블 (method/path/request/response 헤더)
+   - 코드 블록 안의 OpenAPI/JSON Schema 스니펫
+3. 추출 실패(해당 섹션 없음) → **에러 없이 `no-contract` 상태 기록 후 종료**. 모든 feature가 API를 갖진 않음.
+4. 추출 성공 → frontmatter 구조로 변환
+5. `source-spec-hash`: SPEC 파일 내용의 sha256 (다음 extract 시 변경 감지)
+6. `.claude/vibe/contracts/<feature>.md` 저장 (기존 파일이 있고 hash가 같으면 **no-op**)
+
+**주의**: 추출은 LLM 파싱. 신뢰도 낮은 필드는 `# unconfirmed` 주석 달아서 사용자가 검토 가능하게.
+
+### 2. `check <feature>` — 계약 vs 구현 비교
+
+**단계**:
+1. `.claude/vibe/contracts/<feature>.md` 로드. 없으면 **먼저 extract 제안**.
+2. 각 endpoint에 대해 구현 탐색:
+   - http: 프레임워크 감지 (Express, Fastify, Next.js API routes, Hono, ...)
+   - graphql: resolver 파일 찾기
+   - event: 프로듀서/컨슈머 코드
+   - function: 모듈 export
+3. 구현 시그니처/스키마를 추출 → 계약과 비교
+4. Drift 분류 (severity 표는 command file 참고)
+5. 스냅샷 저장: `.claude/vibe/contracts/<feature>.snapshot.md` (현재 구현 상태)
+
+### 3. `diff <feature>` — 이전 스냅샷 대비 변경만
+
+**단계**:
+1. `.snapshot.md`가 없으면 "첫 실행" 안내 후 종료
+2. 현재 구현 재추출 vs 기존 스냅샷 비교
+3. **변경된 필드만** 출력 (ASCII diff 형식):
+   ```
+   endpoints/get-user-by-id/response/200:
+     - email: string
+     + email: string | null   ← nullability 추가 (P1 breaking)
+     + phoneNumber: string    ← 신규 필드 (P3 safe)
+   ```
+4. 드리프트 있으면 `/vibe.regress register --from-contract` 자동 호출
+
+## Drift Severity Matrix
+
+(command file의 표와 동일 — 변경 시 양쪽 갱신)
+
+## Integration Points
+
+### From /vibe.spec
+
+SPEC 작성 완료 직후 자동 호출:
+```
+Load skill `vibe-contract` with: extract <feature>
+```
+실패해도 `/vibe.spec`은 계속 진행 (계약 추출은 옵션). 단 성공 시 `/vibe.run`이 이 계약을 참조.
+
+### From /vibe.verify
+
+모든 scenario pass 후 자동 체인:
+```
+Load skill `vibe-contract` with: check <feature>
+```
+- drift 없음 → verify 통과 유지
+- P1 drift → verify 실패로 강등, regress 자동 등록
+- P2/P3 drift → 경고만, verify 통과 유지
+
+### To /vibe.regress
+
+P1 drift 발견 시:
+```
+Load skill `vibe-regress` with:
+  subcommand: register --from-contract
+  feature: <feature>
+  symptom: "Contract drift: <endpoint-id> <drift-type>"
+  root-cause-tag: integration
+```
+
+## Framework Detection Rules
+
+HTTP framework 감지 순서:
+1. `package.json` dependencies에서: `next` → Next.js API routes
+2. `fastify` → Fastify
+3. `express` → Express
+4. `hono` → Hono
+5. `@nestjs/core` → NestJS
+6. 감지 실패 → user에게 질문 후 manual mapping
+
+감지 후 각 프레임워크의 **라우트 정의 패턴**을 Grep으로 찾아 endpoint 매핑:
+- Next.js: `pages/api/**` or `app/api/**/route.ts`
+- Express: `app.get|post|put|delete|patch\(`
+- Fastify: `fastify.get|post|...` or route configuration
+- Hono: `app.get|post|...`
+
+## Done Criteria
+
+- [ ] `extract`가 API 섹션 없는 SPEC에서 에러 내지 않음
+- [ ] `source-spec-hash` 기반 re-extract 스킵
+- [ ] `check`는 각 drift에 severity + 위치(file:line) 명시
+- [ ] P1 drift는 100% `/vibe.regress` 자동 등록
+- [ ] 프레임워크 감지 실패 시 silently skip 금지 — 반드시 user 질문

package/skills/vibe-docs/templates/architecture.md

@@ -1,80 +1,80 @@
-# Architecture: {{PROJECT_NAME}}
-
-> Version: {{VERSION}} | Updated: {{DATE}}
-
-## Overview
-
-{{2-3 SENTENCES: WHAT THIS SYSTEM DOES AND ITS PRIMARY ARCHITECTURAL APPROACH.}}
-
-## System Diagram
-
-```mermaid
-graph TD
-    {{ENTRY_POINT}}[{{ENTRY_LABEL}}] --> {{MODULE_A}}[{{MODULE_A_LABEL}}]
-    {{MODULE_A}} --> {{MODULE_B}}[{{MODULE_B_LABEL}}]
-    {{MODULE_A}} --> {{MODULE_C}}[{{MODULE_C_LABEL}}]
-    {{MODULE_B}} --> {{STORE}}[({{STORE_LABEL}})]
-    {{MODULE_C}} --> {{EXTERNAL}}[{{EXTERNAL_SERVICE_LABEL}}]
-```
-
-> Replace nodes above based on actual `import` analysis. Run:
-> `grep -r "^import .* from" src/ | sed 's/.*from //' | sort | uniq` to get dependency edges.
-
-## Module Responsibilities
-
-| Module / Directory | Responsibility | Key Files |
-|--------------------|---------------|-----------|
-| `{{MODULE_1}}/` | {{RESPONSIBILITY}} | `{{KEY_FILE}}` |
-| `{{MODULE_2}}/` | {{RESPONSIBILITY}} | `{{KEY_FILE}}` |
-| `{{MODULE_3}}/` | {{RESPONSIBILITY}} | `{{KEY_FILE}}` |
-
-## Data Flow
-
-```
-{{INPUT_SOURCE}}
-  ↓ {{STEP_1_DESCRIPTION}}
-{{PROCESSING_MODULE}}
-  ↓ {{STEP_2_DESCRIPTION}}
-{{OUTPUT_TARGET}}
-```
-
-### Key Data Entities
-
-| Entity | Where Defined | Storage |
-|--------|--------------|---------|
-| `{{ENTITY_1}}` | `{{FILE_PATH}}` | {{DB / FILE / MEMORY}} |
-| `{{ENTITY_2}}` | `{{FILE_PATH}}` | {{DB / FILE / MEMORY}} |
-
-## External Dependencies
-
-| Service | Purpose | Auth Method |
-|---------|---------|-------------|
-| `{{SERVICE_1}}` | {{PURPOSE}} | {{API_KEY / OAUTH / NONE}} |
-| `{{SERVICE_2}}` | {{PURPOSE}} | {{AUTH_METHOD}} |
-
-## Key Decisions
-
-| Decision | Chosen Approach | Alternatives Considered | Rationale |
-|----------|----------------|------------------------|-----------|
-| {{DECISION_1}} | {{CHOICE}} | {{ALTERNATIVES}} | {{WHY}} |
-| {{DECISION_2}} | {{CHOICE}} | {{ALTERNATIVES}} | {{WHY}} |
-
-## Constraints & Non-Goals
-
-**Constraints:**
-- {{CONSTRAINT_1}} (e.g., "Must work offline")
-- {{CONSTRAINT_2}}
-
-**Non-goals (out of scope):**
-- {{NON_GOAL_1}}
-- {{NON_GOAL_2}}
-
-## Local Development Setup
-
-```bash
-{{SETUP_COMMANDS}}
-```
-
-## Further Reading
-
-- {{INTERNAL_LINK_OR_DOC}}
+# Architecture: {{PROJECT_NAME}}
+
+> Version: {{VERSION}} | Updated: {{DATE}}
+
+## Overview
+
+{{2-3 SENTENCES: WHAT THIS SYSTEM DOES AND ITS PRIMARY ARCHITECTURAL APPROACH.}}
+
+## System Diagram
+
+```mermaid
+graph TD
+    {{ENTRY_POINT}}[{{ENTRY_LABEL}}] --> {{MODULE_A}}[{{MODULE_A_LABEL}}]
+    {{MODULE_A}} --> {{MODULE_B}}[{{MODULE_B_LABEL}}]
+    {{MODULE_A}} --> {{MODULE_C}}[{{MODULE_C_LABEL}}]
+    {{MODULE_B}} --> {{STORE}}[({{STORE_LABEL}})]
+    {{MODULE_C}} --> {{EXTERNAL}}[{{EXTERNAL_SERVICE_LABEL}}]
+```
+
+> Replace nodes above based on actual `import` analysis. Run:
+> `grep -r "^import .* from" src/ | sed 's/.*from //' | sort | uniq` to get dependency edges.
+
+## Module Responsibilities
+
+| Module / Directory | Responsibility | Key Files |
+|--------------------|---------------|-----------|
+| `{{MODULE_1}}/` | {{RESPONSIBILITY}} | `{{KEY_FILE}}` |
+| `{{MODULE_2}}/` | {{RESPONSIBILITY}} | `{{KEY_FILE}}` |
+| `{{MODULE_3}}/` | {{RESPONSIBILITY}} | `{{KEY_FILE}}` |
+
+## Data Flow
+
+```
+{{INPUT_SOURCE}}
+  ↓ {{STEP_1_DESCRIPTION}}
+{{PROCESSING_MODULE}}
+  ↓ {{STEP_2_DESCRIPTION}}
+{{OUTPUT_TARGET}}
+```
+
+### Key Data Entities
+
+| Entity | Where Defined | Storage |
+|--------|--------------|---------|
+| `{{ENTITY_1}}` | `{{FILE_PATH}}` | {{DB / FILE / MEMORY}} |
+| `{{ENTITY_2}}` | `{{FILE_PATH}}` | {{DB / FILE / MEMORY}} |
+
+## External Dependencies
+
+| Service | Purpose | Auth Method |
+|---------|---------|-------------|
+| `{{SERVICE_1}}` | {{PURPOSE}} | {{API_KEY / OAUTH / NONE}} |
+| `{{SERVICE_2}}` | {{PURPOSE}} | {{AUTH_METHOD}} |
+
+## Key Decisions
+
+| Decision | Chosen Approach | Alternatives Considered | Rationale |
+|----------|----------------|------------------------|-----------|
+| {{DECISION_1}} | {{CHOICE}} | {{ALTERNATIVES}} | {{WHY}} |
+| {{DECISION_2}} | {{CHOICE}} | {{ALTERNATIVES}} | {{WHY}} |
+
+## Constraints & Non-Goals
+
+**Constraints:**
+- {{CONSTRAINT_1}} (e.g., "Must work offline")
+- {{CONSTRAINT_2}}
+
+**Non-goals (out of scope):**
+- {{NON_GOAL_1}}
+- {{NON_GOAL_2}}
+
+## Local Development Setup
+
+```bash
+{{SETUP_COMMANDS}}
+```
+
+## Further Reading
+
+- {{INTERNAL_LINK_OR_DOC}}

package/skills/vibe-docs/templates/readme.md

@@ -1,84 +1,84 @@
-# {{PROJECT_NAME}}
-
-> {{ONE_LINE_DESCRIPTION_FROM_PACKAGE_JSON}}
-
-## What is this?
-
-{{2-3 SENTENCES: THE PROBLEM THIS PROJECT SOLVES AND HOW IT SOLVES IT.}}
-
-## Quick Start
-
-```bash
-# Install
-{{PACKAGE_MANAGER}} install {{PACKAGE_NAME}}
-
-# Minimal usage example
-{{USAGE_EXAMPLE}}
-```
-
-## Features
-
-- **{{FEATURE_1}}** — {{BRIEF_DESCRIPTION}}
-- **{{FEATURE_2}}** — {{BRIEF_DESCRIPTION}}
-- **{{FEATURE_3}}** — {{BRIEF_DESCRIPTION}}
-
-## Architecture
-
-> Include this section if the project has 5+ source directories.
-
-```
-{{PROJECT_NAME}}/
-├── {{DIR_1}}/      # {{RESPONSIBILITY_1}}
-├── {{DIR_2}}/      # {{RESPONSIBILITY_2}}
-└── {{DIR_3}}/      # {{RESPONSIBILITY_3}}
-```
-
-## Configuration
-
-| File | Purpose |
-|------|---------|
-| `{{CONFIG_FILE_1}}` | {{PURPOSE}} |
-| `{{CONFIG_FILE_2}}` | {{PURPOSE}} |
-
-**Key environment variables:**
-
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `{{ENV_VAR_1}}` | Yes / No | `{{DEFAULT}}` | {{DESCRIPTION}} |
-
-## Development
-
-```bash
-# Install dependencies
-{{INSTALL_COMMAND}}
-
-# Build
-{{BUILD_COMMAND}}
-
-# Test
-{{TEST_COMMAND}}
-
-# Lint
-{{LINT_COMMAND}}
-```
-
-## API Reference
-
-> Include if the project exposes a public API.
-
-### `{{FUNCTION_OR_CLASS_NAME}}`
-
-```typescript
-{{FUNCTION_SIGNATURE}}
-```
-
-{{DESCRIPTION}}
-
-**Parameters:**
-- `{{PARAM_1}}` — {{TYPE}}: {{DESCRIPTION}}
-
-**Returns:** `{{RETURN_TYPE}}` — {{DESCRIPTION}}
-
-## License
-
-{{LICENSE}} — see [LICENSE](./LICENSE)
+# {{PROJECT_NAME}}
+
+> {{ONE_LINE_DESCRIPTION_FROM_PACKAGE_JSON}}
+
+## What is this?
+
+{{2-3 SENTENCES: THE PROBLEM THIS PROJECT SOLVES AND HOW IT SOLVES IT.}}
+
+## Quick Start
+
+```bash
+# Install
+{{PACKAGE_MANAGER}} install {{PACKAGE_NAME}}
+
+# Minimal usage example
+{{USAGE_EXAMPLE}}
+```
+
+## Features
+
+- **{{FEATURE_1}}** — {{BRIEF_DESCRIPTION}}
+- **{{FEATURE_2}}** — {{BRIEF_DESCRIPTION}}
+- **{{FEATURE_3}}** — {{BRIEF_DESCRIPTION}}
+
+## Architecture
+
+> Include this section if the project has 5+ source directories.
+
+```
+{{PROJECT_NAME}}/
+├── {{DIR_1}}/      # {{RESPONSIBILITY_1}}
+├── {{DIR_2}}/      # {{RESPONSIBILITY_2}}
+└── {{DIR_3}}/      # {{RESPONSIBILITY_3}}
+```
+
+## Configuration
+
+| File | Purpose |
+|------|---------|
+| `{{CONFIG_FILE_1}}` | {{PURPOSE}} |
+| `{{CONFIG_FILE_2}}` | {{PURPOSE}} |
+
+**Key environment variables:**
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `{{ENV_VAR_1}}` | Yes / No | `{{DEFAULT}}` | {{DESCRIPTION}} |
+
+## Development
+
+```bash
+# Install dependencies
+{{INSTALL_COMMAND}}
+
+# Build
+{{BUILD_COMMAND}}
+
+# Test
+{{TEST_COMMAND}}
+
+# Lint
+{{LINT_COMMAND}}
+```
+
+## API Reference
+
+> Include if the project exposes a public API.
+
+### `{{FUNCTION_OR_CLASS_NAME}}`
+
+```typescript
+{{FUNCTION_SIGNATURE}}
+```
+
+{{DESCRIPTION}}
+
+**Parameters:**
+- `{{PARAM_1}}` — {{TYPE}}: {{DESCRIPTION}}
+
+**Returns:** `{{RETURN_TYPE}}` — {{DESCRIPTION}}
+
+## License
+
+{{LICENSE}} — see [LICENSE](./LICENSE)

package/skills/vibe-docs/templates/release-notes.md

@@ -1,74 +1,74 @@
-# Release Notes: {{PROJECT_NAME}}
-
----
-
-## [{{VERSION}}] — {{RELEASE_DATE}}
-
-> {{ONE_SENTENCE_SUMMARY_OF_THIS_RELEASE}}
-
-### Breaking Changes
-
-> If none, remove this section.
-
-- **{{CHANGE_DESCRIPTION}}** — {{MIGRATION_GUIDE}}
-  - Before: `{{OLD_USAGE}}`
-  - After: `{{NEW_USAGE}}`
-
-### Features
-
-- `feat`: {{FEATURE_DESCRIPTION}} ([#{{PR_NUMBER}}]({{PR_URL}}))
-- `feat`: {{FEATURE_DESCRIPTION}} ([#{{PR_NUMBER}}]({{PR_URL}}))
-
-### Bug Fixes
-
-- `fix`: {{BUG_DESCRIPTION}} — {{WHAT_WAS_WRONG_AND_HOW_FIXED}} ([#{{PR_NUMBER}}]({{PR_URL}}))
-
-### Performance
-
-- `perf`: {{IMPROVEMENT_DESCRIPTION}} — {{BEFORE}} → {{AFTER}}
-
-### Other
-
-- `refactor`: {{DESCRIPTION}}
-- `docs`: {{DESCRIPTION}}
-- `chore`: {{DESCRIPTION}}
-
----
-
-## Upgrade Guide
-
-### From {{PREVIOUS_VERSION}} to {{VERSION}}
-
-```bash
-{{UPGRADE_COMMAND}}
-```
-
-**Required config changes:**
-1. {{CONFIG_CHANGE_1}}
-2. {{CONFIG_CHANGE_2}}
-
----
-
-## [{{PREVIOUS_VERSION}}] — {{PREVIOUS_DATE}}
-
-> Past release notes continue below in reverse chronological order.
-
----
-
-<!-- GENERATION NOTES (remove before publishing)
-
-Run to generate draft:
-  git log {{PREVIOUS_TAG}}..HEAD --oneline --no-merges
-
-Classify commits:
-  feat:     → Features
-  fix:      → Bug Fixes
-  perf:     → Performance
-  refactor/docs/chore/test: → Other
-  BREAKING CHANGE in footer: → Breaking Changes
-
-Version bump guidance:
-  Breaking changes → major (x.0.0)
-  New features      → minor (0.x.0)
-  Bug fixes only    → patch (0.0.x)
--->
+# Release Notes: {{PROJECT_NAME}}
+
+---
+
+## [{{VERSION}}] — {{RELEASE_DATE}}
+
+> {{ONE_SENTENCE_SUMMARY_OF_THIS_RELEASE}}
+
+### Breaking Changes
+
+> If none, remove this section.
+
+- **{{CHANGE_DESCRIPTION}}** — {{MIGRATION_GUIDE}}
+  - Before: `{{OLD_USAGE}}`
+  - After: `{{NEW_USAGE}}`
+
+### Features
+
+- `feat`: {{FEATURE_DESCRIPTION}} ([#{{PR_NUMBER}}]({{PR_URL}}))
+- `feat`: {{FEATURE_DESCRIPTION}} ([#{{PR_NUMBER}}]({{PR_URL}}))
+
+### Bug Fixes
+
+- `fix`: {{BUG_DESCRIPTION}} — {{WHAT_WAS_WRONG_AND_HOW_FIXED}} ([#{{PR_NUMBER}}]({{PR_URL}}))
+
+### Performance
+
+- `perf`: {{IMPROVEMENT_DESCRIPTION}} — {{BEFORE}} → {{AFTER}}
+
+### Other
+
+- `refactor`: {{DESCRIPTION}}
+- `docs`: {{DESCRIPTION}}
+- `chore`: {{DESCRIPTION}}
+
+---
+
+## Upgrade Guide
+
+### From {{PREVIOUS_VERSION}} to {{VERSION}}
+
+```bash
+{{UPGRADE_COMMAND}}
+```
+
+**Required config changes:**
+1. {{CONFIG_CHANGE_1}}
+2. {{CONFIG_CHANGE_2}}
+
+---
+
+## [{{PREVIOUS_VERSION}}] — {{PREVIOUS_DATE}}
+
+> Past release notes continue below in reverse chronological order.
+
+---
+
+<!-- GENERATION NOTES (remove before publishing)
+
+Run to generate draft:
+  git log {{PREVIOUS_TAG}}..HEAD --oneline --no-merges
+
+Classify commits:
+  feat:     → Features
+  fix:      → Bug Fixes
+  perf:     → Performance
+  refactor/docs/chore/test: → Other
+  BREAKING CHANGE in footer: → Breaking Changes
+
+Version bump guidance:
+  Breaking changes → major (x.0.0)
+  New features      → minor (0.x.0)
+  Bug fixes only    → patch (0.0.x)
+-->