@su-record/vibe 3.2.1 → 3.2.3

package/skills/vibe.spec/SKILL.md

@@ -26,7 +26,7 @@ user-invocable: true
     ↓
 Input 분석 + Smart Resume
     ↓
-Load skill `spec` — 단일 패스: 컨텍스트 수집 → (필요시) 인라인 질문 → SPEC + Feature 작성 → 셀프 리뷰 1회
+Execute the bundled implementation below — 단일 패스: 컨텍스트 수집 → (필요시) 인라인 질문 → SPEC + Feature 작성 → 셀프 리뷰 1회
     ↓
 SPEC 승인 (1회 — automationLevel: autonomous 면 생략)
     ↓
@@ -80,3 +80,125 @@ trace(`/vibe.trace`)·contract(`/vibe.contract`) 는 사용자가 요청하거
 ---
 
 ARGUMENTS: $ARGUMENTS
+
+## Bundled implementation
+
+
+# spec — Single-Pass SPEC
+
+자연어 요구사항 하나를 받아 **한 번의 패스로** 실행 가능한 SPEC을 만든다. 별도의 interview → plan → review 단계는 없다 — 질문이 필요하면 이 패스 안에서 인라인으로 묻고, 리뷰는 셀프 리뷰 1회로 끝낸다. 완성된 SPEC의 승인이 loop-contract 가 정의하는 **유일한 의무적 사람 개입 지점**이다.
+
+> 루프 시맨틱 SSOT: `vibe/rules/loop-contract.md`. SPEC = ANCHOR 아티팩트, Done Criteria = JUDGE 게이트.
+
+## Input
+
+| 입력 | 처리 |
+|---|---|
+| 자연어 요구사항 | 그대로 SPEC 패스의 주 입력 |
+| 📎 첨부 (md/txt/pdf/이미지 등) | Read 도구로 분석 후 요구사항에 병합 |
+| 파일 경로 인자 (PRD 등) | 존재 확인 후 Read — 첨부와 동일 취급 |
+| **레거시 아티팩트** `.vibe/interviews/{feature}.md`, `.vibe/plans/{feature}.md` | 존재하면 **입력 컨텍스트로만** 읽는다. 절대 요구하거나 재생성하지 않는다 — 없어도 정상 경로 |
+
+## Process
+
+### 1. Git branch + pointer
+
+- `git branch --show-current` — `main`/`master` 이면 `git checkout -b feature/{feature-name}` (소문자·하이픈). feature 브랜치면 그대로 진행.
+- feature 이름 확정 즉시 `.vibe/.last-feature` 에 이름 한 줄 기록 (값이 같으면 no-op).
+
+### 2. Project context
+
+- `.vibe/config.json` 읽기 — `references.languages[]` 의 스택 가이드, `stacks` 확인.
+- 기존 코드 파악이 필요하면 네이티브 Explore 서브에이전트에 위임 (main session 에서 프로젝트 파일을 훑지 않는다):
+
+```text
+Task(subagent_type="Explore",
+  prompt="Find existing implementations related to [FEATURE]. Return: tech stack, relevant files, patterns. Under 200 tokens.")
+```
+
+### 3. Clarify — 진짜 모호할 때만
+
+별도 인터뷰 단계가 아니다. 요구사항·첨부·레거시 아티팩트·코드베이스 컨텍스트로 답을 합리적으로 정할 수 있으면 **묻지 않는다**. 다음 조건을 모두 만족할 때만 질문한다:
+
+- 답에 따라 Done Criteria 나 구현 방향이 실제로 갈라진다 (인증 방식, 데이터 모델의 필수 필드, 외부 연동 여부 등)
+- 합리적 기본값을 SPEC 의 Assumptions 로 명시하는 것으로 대체할 수 없다
+
+질문할 때는 **한 번에 묶어서** (번호 목록, 최대 5개), 각 질문에 제안 기본값을 붙인다. `automationLevel: autonomous` 면 질문 없이 기본값을 채택하고 전부 SPEC 의 Assumptions 섹션에 기록한다.
+
+사소한 값(타임아웃, 페이지 크기, 재시도 횟수 등)은 묻지 말고 상식적 기본값을 채택 + Assumptions 에 기록.
+
+### 4. Write SPEC — one pass
+
+`vibe/templates/spec-template.md` 구조로 `.vibe/specs/{feature-name}.md` 를 작성한다. 핵심 요건:
+
+- **Overview / Goal** — 무엇을, 왜. 1-3 문장.
+- **Context Sources** — 입력으로 사용한 파일·문서·URL·관측 상태. 출처 없는 추정은 Assumptions 로 분리.
+- **Requirements** — `REQ-{feature}-NNN` ID와 연결된 Done Criteria를 표로 명시.
+- **Done Criteria** — 결정론적 게이트만. 각 항목은 "명령/관찰로 pass·fail 판정 가능"해야 한다 (테스트 exit code, 빌드 성공, 특정 동작 관찰). "잘 동작한다" 류 서술 금지 — 이것이 루프의 JUDGE 입력이 된다.
+- **Evidence Required** — Done 을 증명할 명령 결과·테스트 리포트·로그·스크린샷·코드 위치.
+- **Human Taste (Non-Blocking)** — UX·브랜드·제품 감각처럼 release 시 사람이 판단할 기준. 완료 게이트로 쓰지 않는다.
+- **Scenarios** — Given-When-Then. Happy path + 주요 edge case. 각 시나리오는 Done Criteria 중 하나에 매핑.
+- **Out of Scope** — 이번에 하지 않는 것을 명시 (비어 있으면 스코프 팽창 신호).
+- **Assumptions** — 3단계에서 채택한 기본값 전부.
+- **Constraints** — 구현·보안·호환성 경계. execution packet으로 압축돼도 반드시 보존한다.
+- **API Contract** (해당 시에만) — 엔드포인트/요청/응답 형태. 이 섹션이 있으면 이후 `/vibe.contract` 가 drift 를 검사한다.
+
+이어서 `.vibe/features/{feature-name}.feature` 를 생성한다: 시나리오 섹션을 gherkin 으로 변환 (Done Criteria ↔ Scenario 매핑 유지). `/vibe.run` 이 이 파일을 구현·검증 단위로 사용한다.
+
+**Large scope** (5+ phases 또는 15+ 신규 파일 또는 4+ 독립 기능): 폴더 분할 — `.vibe/specs/{feature}/_index.md` + `phase-N-{name}.md`, feature 파일도 동일 구조로 매칭. 조용히 분할하고 결과만 보고한다.
+
+**파일 규칙**: `.vibe/` 밖에 파일을 만들지 않는다. SPEC 파일마다 매칭되는 Feature 파일이 있어야 한다.
+
+### 5. Self-review — once
+
+작성 직후, 아래 체크리스트로 자기 SPEC 을 **1회** 점검하고 걸리는 항목을 즉시 고친다. 외부 LLM 리뷰 없음, 수렴 루프 없음 — 한 번 고치면 끝.
+
+- [ ] 모든 Done Criteria 가 명령/관찰로 판정 가능한가 (모델 자기 보고가 아닌)
+- [ ] Context Sources 와 Assumptions 가 분리됐고, 각 Done Criteria 의 Evidence Required 가 있는가
+- [ ] Human Taste 가 결정론적 완료 게이트에 섞이지 않았는가
+- [ ] 모든 시나리오가 Done Criteria 에 매핑되는가 (고아 시나리오 없음)
+- [ ] 수치가 필요한 곳에 수치가 있는가 (제한·타임아웃·크기 — 없으면 기본값 + Assumptions)
+- [ ] Out of Scope 가 비어 있지 않은가
+- [ ] 요구사항에 있던 것 중 SPEC 에서 빠진 것이 없는가
+
+### 6. Approval — the single gate
+
+SPEC 요약(Goal, Done Criteria, 시나리오 수, Out of Scope, 열린 Assumptions)을 제시하고 승인을 받는다:
+
+```
+📋 SPEC 준비 완료: {feature-name}
+   .vibe/specs/{feature-name}.md · .vibe/features/{feature-name}.feature
+
+   Goal: {1줄}
+   Done Criteria: {N}개 (전부 결정론 게이트)
+   Scenarios: {M}개 · Out of Scope: {K}항목
+   Assumptions: {요약 또는 "없음"}
+
+승인하면 이 SPEC 이 루프의 Done 정의가 됩니다.
+[1] 승인 → 구현 진행   [2] 수정 요청   [3] 중단
+```
+
+- 수정 요청 → 반영 후 재제시 (사용자 주도 반복 — 자동 루프 아님).
+- `automationLevel: autonomous` → 승인 생략, 요약만 출력하고 진행.
+- 승인 후 SPEC 변경은 코드 변경과 같은 커밋으로 (SPEC-First — `vibe.run` 참조).
+- **Stakes 편승 질문**: 디스패처의 stakes 판정(`vibe/rules/loop-contract.md` Stakes 표)이 불확실하거나 신호가 상충하면, 이 승인 메시지에 stakes 확인 질문 1개(demo/prototype/production 선택지)를 포함한다. 별도의 추가 확인 왕복을 만들지 않는다 — 승인 게이트가 유일한 질문 지점이다.
+
+## Output
+
+| 파일 | 경로 |
+|---|---|
+| SPEC | `.vibe/specs/{feature-name}.md` (또는 분할 폴더) |
+| Feature (BDD) | `.vibe/features/{feature-name}.feature` (또는 분할 폴더) |
+| Pointer | `.vibe/.last-feature` |
+
+승인된 SPEC 은 루프의 ANCHOR 로 쓰인다: `/vibe.run` 이 시나리오 단위로 구현·검증하고, `/vibe.verify` 가 Done Criteria 를 판정해 `.vibe/metrics/run-ledger.json` 의 `verifyPassed` 를 기록한다. 게이트 통과 여부는 항상 run-ledger·테스트 exit code 가 판정한다.
+
+## Next Step
+
+```
+/vibe.run "{feature-name}"
+```
+
+---
+
+ARGUMENTS: $ARGUMENTS

package/skills/vibe.test/SKILL.md

@@ -32,12 +32,12 @@ Markdown summary is also printed to the console when the run finishes.
 
 ## Process
 
-Load skill `test` with target harness: `$ARGUMENTS`
+Execute the bundled implementation below with target harness: `$ARGUMENTS`
 
 - If `$ARGUMENTS` is empty, detect the current harness (CC vs Codex) and use that.
 - If the target install dir is missing, exit cleanly with guidance (not an error).
 
-See `skills/test/SKILL.md` for the probe spec and the report template.
+See `skills/vibe.test/SKILL.md` for the probe spec and the report template.
 
 ## Done Criteria
 
@@ -49,3 +49,139 @@ See `skills/test/SKILL.md` for the probe spec and the report template.
 ---
 
 ARGUMENTS: $ARGUMENTS
+
+## Bundled implementation
+
+
+# test — Self-Test
+
+Probe every shipped vibe surface in one install dir and emit a pass/fail report.
+
+## Why this exists
+
+When vibe ships new entry skills, skills, hooks, or agents, one side (CC or Codex) can end up out of sync with the other, frontmatter can drift, and hook tests can silently break. `vibe.test` is the single mechanical check: does every surface in the target install actually load and pass its own tests?
+
+## Target harness
+
+The argument selects which install dir to probe:
+
+| Arg | Probed dir |
+|---|---|
+| (empty) | current harness — CC: `~/.claude/`, Codex: `~/.codex/` |
+| `cc` | `~/.claude/` |
+| `codex` | `~/.codex/` |
+
+If the target dir does not exist, print a clear message and exit with guidance (not an error). Example:
+
+```
+~/.codex/ not found — Codex isn't installed on this machine.
+  To install: npm i -g @openai/codex
+```
+
+## Probes
+
+All probes are **structural or test-based** — no interactive command is ever actually invoked, and no LLM is called.
+
+| Category | Source | Check |
+|---|---|---|
+| entry skills | `<install>/skills/vibe*/SKILL.md` | file readable · frontmatter parses · `name`, `description`, `user-invocable: true` present |
+| skills | `<install>/skills/*/SKILL.md` | frontmatter parses · required fields (`name`, `description`) · body non-empty |
+| hooks | repo `hooks/scripts/*.js` | for each script with a matching `__tests__/<name>.test.js`, run `npx vitest run <test> --reporter=json` and parse pass/fail counts |
+| agents | `<install>/agents/*.md` | file readable · frontmatter parses · required fields (`name`, `description`) |
+
+A probe's failure is captured in its `error` field; the overall run never halts because of one failure.
+
+## Report template
+
+Written to `~/.vibe/test-reports/<YYYYMMDD-HHmm>-<harness>.{json,md}`. Exact schema:
+
+### JSON
+
+```json
+{
+  "harness": "cc",
+  "timestamp": "2026-04-16T18:30:00+09:00",
+  "vibe_version": "2.9.24",
+  "install_dir": "/Users/grove/.claude",
+  "summary": {
+    "total": 42,
+    "passed": 40,
+    "failed": 2
+  },
+  "probes": {
+    "entrySkills": [
+      { "name": "vibe.spec", "status": "pass" },
+      { "name": "vibe.test", "status": "pass" }
+    ],
+    "skills": [
+      { "name": "test", "status": "pass" },
+      { "name": "spec", "status": "fail", "error": "invocation includes `auto` but triggers array is empty" }
+    ],
+    "hooks": [
+      { "name": "pre-tool-guard", "status": "pass", "tests": "38/38" },
+      { "name": "scope-guard", "status": "pass", "tests": "12/12" }
+    ],
+    "agents": [
+      { "name": "implementer", "status": "pass" }
+    ]
+  },
+  "failed": [
+    {
+      "category": "skills",
+      "name": "spec",
+      "error": "frontmatter: triggers array is empty"
+    }
+  ]
+}
+```
+
+- `status`: `"pass"` | `"fail"`
+- `error`: required when `status === "fail"`, omitted otherwise
+- `tests` (hooks only): short `passed/total` string from the vitest JSON reporter
+- `failed[]`: flat list of every failure for quick scanning — mirrors entries found across `probes.*`
+
+### Markdown
+
+```markdown
+# vibe self-test · cc · 2026-04-16 18:30
+
+**Version**: 2.9.24   **Install**: /Users/grove/.claude
+
+| Category | Pass | Fail |
+|---|---:|---:|
+| entry skills | 15 | 0 |
+| skills   | 17 | 1 |
+| hooks    |  6 | 0 |
+| agents   |  3 | 1 |
+| **total**| **41** | **2** |
+
+## Failures
+
+- **skills / spec** — invocation includes `auto` but triggers array is empty
+- **agents / implementer** — agent file not found
+```
+
+If `failed` is empty, replace the Failures section with `_All probes passed._`.
+
+## Steps
+
+1. **Resolve target**: argument (`cc` / `codex` / empty). Empty → detect current harness (`$CLAUDE_PROJECT_DIR` set → `cc`; else fall back to `cc`).
+2. **Resolve install dir**: `cc` → `~/.claude`, `codex` → `~/.codex`. If missing → print guidance + exit.
+3. **Read `vibe_version`** from `package.json` in the current repo.
+4. **Walk each category**, run its check, append `{ name, status, error? }` to `probes.<category>`.
+5. **Compute** `summary` counts and the flat `failed[]` list.
+6. **Ensure** `~/.vibe/test-reports/` exists (`mkdir -p`, dir mode `0o700` — consistent with `~/.vibe/config.json`).
+7. **Write** `<ts>-<harness>.json` and `<ts>-<harness>.md`.
+8. **Print** the Markdown summary to the console.
+9. **If `summary.failed > 0`**, load skill `vibe.regress` with `subcommand: register --from-test` and pass the failed entries. P1 = any probe with `status: fail`.
+
+## Done Criteria
+
+- [ ] No external LLM call — file reads + vitest runs only
+- [ ] One probe failing never halts the overall run
+- [ ] Target install dir missing → clean exit with guidance (not an error)
+- [ ] JSON report matches the template above exactly (fields, types, naming)
+- [ ] Markdown summary printed to console after the run
+- [ ] Reports land in `~/.vibe/test-reports/`, never in project-local `.vibe/`
+- [ ] `failed.length > 0` → auto-invokes `vibe.regress register --from-test`
+- [ ] Entry skills are verified as user-invocable skill surfaces, not deprecated command files

package/skills/{tool-fallback → vibe.tool-fallback}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: tool-fallback
+name: vibe.tool-fallback
 invocation: [auto]
 tier: optional
 description: "Tool failure fallback strategies with circuit breaker. Auto-activates on API errors, search failures, timeouts, 429, 5xx, overloaded errors."

package/skills/{ui-ux-pro-max → vibe.ui-ux-pro-max}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ui-ux-pro-max
+name: vibe.ui-ux-pro-max
 user-invocable: true
 invocation: [command]
 tier: standard
@@ -94,21 +94,21 @@ Extract from user request: **product type**, **style keywords**, **industry**, *
 ### Step 2: Generate Design System (REQUIRED)
 
 ```bash
-python3 skills/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]
+python3 skills/vibe.ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]
 ```
 
 This searches 5 domains in parallel (product, style, color, landing, typography), applies reasoning rules, and returns complete design system.
 
 **Persist for cross-session use:**
 ```bash
-python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name"
+python3 skills/vibe.ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name"
 ```
 
 Creates `design-system/MASTER.md` (global) + optional `design-system/pages/<page>.md` (overrides).
 
 **With page-specific override:**
 ```bash
-python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Name" --page "dashboard"
+python3 skills/vibe.ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Name" --page "dashboard"
 ```
 
 **Hierarchical retrieval**: Page file overrides Master. No page file → Master exclusively.
@@ -116,7 +116,7 @@ python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persi
 ### Step 3: Detailed Searches (as needed)
 
 ```bash
-python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]
+python3 skills/vibe.ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]
 ```
 
 Domains: `product`, `style`, `typography`, `color`, `landing`, `chart`, `ux`, `react`, `web`, `prompt`
@@ -124,7 +124,7 @@ Domains: `product`, `style`, `typography`, `color`, `landing`, `chart`, `ux`, `r
 ### Step 4: Stack Guidelines (default: html-tailwind)
 
 ```bash
-python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --stack html-tailwind
+python3 skills/vibe.ui-ux-pro-max/scripts/search.py "<keyword>" --stack html-tailwind
 ```
 
 Stacks: `html-tailwind`, `react`, `nextjs`, `vue`, `svelte`, `swiftui`, `react-native`, `flutter`, `shadcn`, `jetpack-compose`

package/skills/{user-personas → vibe.user-personas}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: user-personas
+name: vibe.user-personas
 invocation: [auto, chain]
 tier: standard
 description: "Create refined user personas from research data — 3 personas with JTBD, pains, gains, and unexpected insights."
 triggers: [persona, user persona, user profile, user segment, user research]
 priority: 50
-chain-next: [create-prd, prioritization-frameworks]
+chain-next: [vibe.create-prd, vibe.prioritization]
 ---
 
 # User Personas

package/skills/vibe.verify/SKILL.md

@@ -82,7 +82,7 @@ One row per Done criterion: pass/fail + an evidence pointer (file:line, test nam
 Before printing the failure summary, register each failed scenario as a regression bug so the same failure cannot silently slip through again:
 
 ```
-Load skill `regress` with:
+Load skill `vibe.regress` with:
   subcommand: register --from-verify
   feature: {feature}   scenario: {scenario}
   error: {error-summary}   location: {file:line}
@@ -95,7 +95,7 @@ Load skill `regress` with:
 After all criteria pass, if `.vibe/contracts/{feature}.md` exists:
 
 ```
-Load skill `contract` with: check "{feature}"
+Load skill `vibe.contract` with: check "{feature}"
 ```
 
 - No drift → verify still passes

package/skills/{video-production → vibe.video-production}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: video-production
+name: vibe.video-production
 invocation: [auto]
 tier: standard
 description: "Video processing gotchas — FFmpeg commands, transcoding pipelines, HLS/DASH streaming setup, subtitle embedding (SRT/VTT), and thumbnail extraction. Use when the project involves any video manipulation, media processing, or streaming infrastructure. Covers codec selection, bitrate optimization, and common FFmpeg pitfalls. Must use this skill when user works with video files, mentions FFmpeg, or needs media processing — even for simple tasks like 'generate a thumbnail'."

package/vibe/rules/loop-contract.md

@@ -42,6 +42,24 @@
 | `--interactive` | off | 단계별 확인 모드 (회전마다 사람 승인 — 과거의 기본값) |
 | `--max-iter N` | — | 회전 상한 명시 (N=1이면 1회 시도) |
 | `automationLevel` | `confirm` | `confirm`(SPEC·stuck에서 질문) / `autonomous`(기록 후 계속, 비대화형) — `.vibe/config.json` |
+| `stakes` | `production` | 태스크 무게. `demo` / `prototype` / `production` — 아래 매핑이 SSOT |
+
+## Stakes — 태스크 무게 비례 실행 (SSOT)
+
+파이프라인 깊이는 태스크의 무게에 비례해야 한다. 분류는 `/vibe` 디스패처 Phase 1이 수행하고, 매핑 정의는 이 표가 유일하다. **판정이 불확실하면 항상 상향(production)한다.**
+
+| stakes | 판정 신호 | max_iterations | 리뷰 | 검증 스크립트 |
+|---|---|---|---|---|
+| `demo` | 명시 키워드(데모·일회성·실험·테스트용·throwaway·토이) / 기존 프로젝트 코드와 무관한 신규 폴더 / `.vibe/config.json` 없는 임시 디렉토리 | 1 | 1패스 (리뷰어 스케일링 최소 셋) | **신규 생성 금지** — 기존 테스트 러너·브라우저 게이트만 사용 |
+| `prototype` | 검증용 초기 버전 명시 / 유지보수 가능성 있으나 배포 대상 아님 | 1 | 1패스 (리뷰어 스케일링 축소 셋) | 신규 생성 금지 |
+| `production` | 기본값 — 신호 없음·상충 포함 | 10 | 수렴 루프 (기본 리뷰어 셋) | 허용 |
+
+- demo/prototype 판정 신호가 상충하면 SPEC 승인 메시지에 stakes 확인 질문 1개를 **편승**시킨다 (별도 왕복 금지) — `vibe.spec` 승인 게이트 참조.
+- production 행은 기존 기본 동작과 동일하다 — 이 표의 도입으로 기본 동작은 변하지 않는다.
+
+### JUDGE 검증 산출물 절제 (모든 stakes 공통)
+
+JUDGE는 이번 feature의 **신규 생성 파일** 기준으로 검증 코드 총량(테스트·검증 스크립트)과 구현 코드 총량을 `git diff --numstat` 로 비교한다. 검증 코드 바이트 합 > 구현 코드 바이트 합이면 **P2 경고**를 run-ledger 에 기록한다 (restraint 원칙의 프로세스 적용). 경고는 advisory — 게이트 통과 여부를 바꾸지 않는다.
 
 ## 금지 (루프 권한 경계)
 

package/skills/arch-guard/SKILL.md

@@ -1,183 +0,0 @@
----
-name: arch-guard
-user-invocable: false
-invocation: [auto]
-tier: core
-description: "Generate import-rule tests that mechanically enforce architecture layer constraints (e.g., 'UI must not import DB') — for new modules, layer refactors, or circular dependencies."
-triggers: [arch guard, architecture test, layer test, boundary test, structural test, arch validation, layer enforcement, dependency rules, architectural boundaries, circular dependency]
-priority: 60
----
-
-# Arch Guard — Architecture Boundary Test Generator
-
-> **Principle**: "Mechanical enforcement over documentation." If a rule exists only in docs, it will be violated. Turn architecture constraints into failing tests.
-
-## When to Use
-
-| Scenario | Signal |
-|----------|--------|
-| `vibe init` / `vibe update` | Auto-generate for detected stack |
-| New layer/module added | Boundaries need enforcement |
-| Architecture violation found in review | Prevent recurrence with test |
-| "Services should not import UI" type rules | Turn into automated check |
-
-## Core Flow
-
-```
-DETECT → INFER → GENERATE → VERIFY
-```
-
-### Step 1: DETECT — Identify Project Architecture
-
-Analyze the project to determine its layer structure:
-
-```
-Parallel exploration:
-- Agent 1: Scan directory structure (src/, app/, lib/, etc.)
-- Agent 2: Read existing architecture docs (CLAUDE.md, README, ADR)
-- Agent 3: Analyze import graph (which files import what)
-```
-
-**Common patterns to detect:**
-
-| Pattern | Layers | Typical Stacks |
-|---------|--------|----------------|
-| MVC | Controller → Service → Model | Rails, NestJS, Spring |
-| Clean Architecture | UI → Application → Domain → Infrastructure | General |
-| Feature-based | Feature A ↛ Feature B internals | Next.js, React |
-| Hexagonal | Adapters → Ports → Domain | DDD projects |
-| Component hierarchy | Page → Feature → Shared → UI Primitives | Frontend |
-
-### Step 2: INFER — Define Boundary Rules
-
-From detected structure, generate rules:
-
-```typescript
-// Rule format
-interface ArchRule {
-  name: string;           // "service-no-ui-import"
-  from: string;           // Glob pattern: "src/services/**"
-  cannotImport: string[]; // ["src/components/**", "src/pages/**"]
-  canImport: string[];    // ["src/models/**", "src/utils/**"]
-  reason: string;         // "Services must be UI-agnostic"
-}
-```
-
-**Default rules by stack:**
-
-| Stack | Rule |
-|-------|------|
-| Next.js / React | `components/` cannot import from `pages/` or `app/` |
-| Next.js / React | `lib/` cannot import from `components/` |
-| NestJS | `*.service.ts` cannot import from `*.controller.ts` |
-| NestJS | `*.module.ts` is the only valid cross-boundary import |
-| General TS | `src/domain/` cannot import from `src/infra/` |
-| General TS | No circular dependencies between top-level dirs |
-| Python Django | `models.py` cannot import from `views.py` |
-| Python FastAPI | `schemas/` cannot import from `routers/` |
-
-### Step 3: GENERATE — Create Test File
-
-Output: `tests/arch-guard.test.ts` (or equivalent for stack)
-
-```typescript
-/**
- * Architecture Boundary Tests
- * Generated by arch-guard skill
- *
- * These tests enforce architectural constraints mechanically.
- * If a test fails, it means an import violates the intended architecture.
- */
-import { describe, it, expect } from 'vitest';
-import fs from 'fs';
-import path from 'path';
-
-// Helper: extract imports from a file
-function extractImports(filePath: string): string[] {
-  const content = fs.readFileSync(filePath, 'utf-8');
-  const importRegex = /(?:import|require)\s*\(?['"]([^'"]+)['"]\)?/g;
-  const imports: string[] = [];
-  let match;
-  while ((match = importRegex.exec(content)) !== null) {
-    imports.push(match[1]);
-  }
-  return imports;
-}
-
-// Helper: resolve relative import to absolute path
-function resolveImport(fromFile: string, importPath: string): string {
-  if (importPath.startsWith('.')) {
-    return path.resolve(path.dirname(fromFile), importPath);
-  }
-  return importPath; // external package
-}
-
-// Helper: glob files matching pattern
-function globFiles(pattern: string, baseDir: string): string[] {
-  // Use fast-glob or manual recursive scan
-  // Implementation depends on available dependencies
-}
-
-describe('Architecture Boundaries', () => {
-  // GENERATED RULES GO HERE
-  // Each rule becomes a test case:
-
-  it('services cannot import UI components', () => {
-    const serviceFiles = globFiles('src/services/**/*.ts', process.cwd());
-    const violations: string[] = [];
-
-    for (const file of serviceFiles) {
-      const imports = extractImports(file);
-      for (const imp of imports) {
-        const resolved = resolveImport(file, imp);
-        if (resolved.includes('/components/') || resolved.includes('/pages/')) {
-          violations.push(`${file} imports ${imp}`);
-        }
-      }
-    }
-
-    expect(violations).toEqual([]);
-  });
-});
-```
-
-### Step 4: VERIFY — Run and Fix
-
-1. Run the generated tests: `npx vitest run tests/arch-guard.test.ts`
-2. If violations found:
-   - Report each violation with file:line
-   - Suggest fix (move shared code to appropriate layer)
-   - Do NOT auto-fix — violations need human review
-
-## Output Files
-
-| File | Purpose |
-|------|---------|
-| `tests/arch-guard.test.ts` | Executable boundary tests |
-| `.vibe/arch-rules.json` | Machine-readable rules (for CI) |
-
-## Customization
-
-Users can add custom rules to `.vibe/arch-rules.json`:
-
-```json
-{
-  "rules": [
-    {
-      "name": "no-direct-db-in-handlers",
-      "from": "src/handlers/**",
-      "cannotImport": ["src/db/**"],
-      "reason": "Handlers must use services, not direct DB access"
-    }
-  ]
-}
-```
-
-The test generator reads this file and adds custom rules to the test suite.
-
-## Integration
-
-- `vibe init` → auto-detect and generate initial arch-guard tests
-- `vibe update` → refresh rules if directory structure changed
-- Pre-commit hook → run arch-guard tests before commit
-- `vibe.review` (skill) → code-reviewer (focus: architecture) checks against arch-rules.json