@su-record/vibe 3.2.62 → 4.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Su
+Copyright (c) 2025-2026 su-record
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,344 +1,156 @@
-# VIBE
+# vibe 4
 
-**바이브 코딩은 쉽게. 완료 판정은 기계가.**
+**The experience of having an AX/FDE next to you.** Say what you need in plain words. vibe turns it into checkable scenarios, builds it, proves it by running the checks itself, and hands it over to whoever will run it. Vibe-coding quality is the by-product of that discipline.
 
-[![npm](https://img.shields.io/npm/v/@su-record/vibe)](https://www.npmjs.com/package/@su-record/vibe)
-[![npm downloads](https://img.shields.io/npm/dt/@su-record/vibe.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/@su-record/vibe)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D20.12-green)](https://nodejs.org/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
-
-**English** — Vibe is a **verification harness** for AI coding agents. It wraps Claude Code, Codex, and Antigravity CLI so that "done" is decided by deterministic gates — test exit codes, run-ledgers, regression memory — instead of the model's self-report. Models already plan and implement well; what's missing is a reason to trust "it's done." Vibe supplies that ground truth: vibe-code fast, but nothing unverified ships. Install with `npm install -g @su-record/vibe && vibe init`, then throw a natural-language requirement at `/vibe` — one SPEC approval, then an autonomous ANCHOR→ACT→JUDGE→RECORD loop until the gates pass. *(Full docs below are in Korean; the CLI works in any language.)*
-
-Vibe는 AI 코딩을 위한 **검증 하네스(verification harness)** 입니다. 출처가 있는 컨텍스트로 SPEC을 고정하고, **완료 판정을 모델의 자기 보고가 아니라 결정론적 게이트(테스트 exit code, run-ledger, 회귀 기억)에 맡긴 뒤 실행별 Evidence Bundle을 남깁니다.** Model Judge는 발견만 제안하고, Human Taste는 release에서만 판단합니다. 빠르게 바이브 코딩하되, 검증 안 된 코드가 나가지 않게.
+Main surfaces: Claude Code · Codex CLI · ChatGPT desktop app.
 
 ```bash
-npm install -g @su-record/vibe
-vibe init
-```
-
-> Codex CLI에서는 Vibe가 slash command가 아니라 skill로 노출됩니다. `/vibe`가 보이지 않으면 `$vibe`, `$vibe.spec`처럼 호출하거나 `/skills`에서 `vibe`를 선택하세요. Claude Code에서는 기존 `/vibe.*` slash command 흐름을 사용합니다.
-
----
-
-## 철학: 지시하지 않고 검증한다
-
-2026년의 모델에게 "어떻게 일하라"고 가르치는 스캐폴딩은 비용입니다. Vibe v3는 그 층을 걷어냈습니다 — 남긴 것은 **모델이 스스로 증명할 수 없는 것들**뿐입니다:
-
-- **테스트가 실제로 통과했는가** — PR 게이트가 테스트 스위트를 직접 실행
-- **verify가 실제로 실행됐는가** — `.vibe/metrics/run-ledger.json`이 코드로 기록
-- **무엇으로 완료를 증명했는가** — `.vibe/runs/{run-id}/evidence.json`이 Judge 권한과 실행 증거를 기록
-- **리뷰 루프가 수렴하고 있는가** — discover-hash(2라운드 동일 → stuck)가 판정
-- **같은 실수가 반복되지 않는가** — verify 실패가 회귀 테스트로 자동 등록
-
-똑똑한 모델일수록 "다 됐다"는 말이 그럴듯해집니다. 그래서 코드가 판정하는 ground truth는 모델이 강해질수록 **더** 가치 있습니다.
+npm i -g @su-record/vibe
+cd your-project && vibe init                     # Claude Code (CLAUDE.md card · .claude/skills · notification hook)
+cd your-project && vibe init --client codex      # Codex CLI  (AGENTS.md card · .codex/skills · .codex/hooks.json)
 
----
+vibe plugin install                              # Codex CLI + ChatGPT desktop as one OpenAI plugin
+codex plugin marketplace add ~ && codex plugin add vibe@<marketplace>   # the install output prints the exact name
+```
 
-## 워크플로우
+Codex and ChatGPT desktop read the same personal marketplace (`~/.agents/plugins/marketplace.json`); restart ChatGPT desktop after installing. The plugin tree holds only the manifest, the six skills and the notification hooks — its hooks call the globally installed `vibe`.
 
-**진입점 하나.** 자연어 요구사항만 던지세요. SPEC 1패스 → 승인 1회 → 게이트 통과까지 자동 루프.
+Then, in chat:
 
 ```
-/vibe "커피 브랜드 랜딩 페이지" [+ 📎 figma URL / 이미지 / PDF / 파일]
-     |
-     v
-  Intent 분류  ─── new feature? figma-driven? clone? resume? review? regress? ...
-     |
-     v
-  Smart Resume ─── .vibe/{specs,features}/ 감지 ("이어서?")
-     |
-     v
-  SPEC 1패스 ─── 모호할 때만 인라인 질문 → SPEC + BDD 시나리오 생성
-     |
-     v
-  SPEC 확정 1회 승인 ─── 유일한 의무 개입 (Done의 정의 확정)
-     |
-     v
-  루프 ─── ANCHOR→ACT→JUDGE→RECORD (결정론 게이트 통과까지 자동 반복)
+/vibe every week an order spreadsheet arrives — turn it into a settlement sheet and send it to accounting
 ```
 
-**예시:**
+## The flow
 
-```bash
-/vibe "패럴랙스 웹사이트 만들어줘"
-/vibe "https://figma.com/file/abc 로 로그인 페이지"
-/vibe "로그인 회귀 테스트 다시 통과시켜줘"
-/vibe "이 SPEC 리뷰만" + 📎 .vibe/specs/login.md
 ```
-
-**SPEC 1패스** — 구세대의 인터뷰→기획→SPEC→리뷰 4단계는 폐지됐습니다. 모델이 한 번에 SPEC을 만들고, 진짜 갈림길에서만 질문합니다. 승인 게이트는 SPEC 확정 단 하나.
-
-**Smart Resume** — 아무 단계에서나 멈추고 나중에 돌아오세요. `/vibe`는 `.vibe/` 디렉토리에서 진행 상황을 감지하고 "이어서?" 제안합니다.
-
-**루프 기본 실행** — 승인 후 게이트 통과까지 자동 루프. `--interactive`로 단계별 확인, `--max-iter N`으로 반복 상한. `automationLevel: autonomous`(`.vibe/config.json`)면 비대화형으로 완주합니다.
-
-**Advanced** — 정확히 어느 phase 실행할지 알면 `/vibe.spec`, `/vibe.figma`, `/vibe.run`, `/vibe.verify`, `/vibe.trace` 등을 직접 호출할 수 있습니다.
-
----
-
-## 빠른 시작
-
-```bash
-# 설치
-npm install -g @su-record/vibe
-
-# 프로젝트 초기화 (스택 자동 감지)
-cd your-project
-vibe init
-
-# AI 코딩 도구 시작 (둘 중 하나)
-claude
-codex
-
-# 워크플로우 실행
-/vibe "사용자 인증 추가"
+request (/vibe …)
+  → interview      discover: at most three questions, sample profiling, anomalies said first
+  → scenarios      scope: each scenario bound to a check · research · skills needed → one approval
+  → build          one scenario at a time, `vibe check` after each
+  → prove          `vibe check --all` — every scenario plus every regression, ordered by the work graph
+  → report + handoff   a document the operator can run alone; irreversible steps need a token
 ```
 
-> **npm 12 를 쓴다면** — npm 12 는 `allowScripts` 정책으로 install 스크립트를 기본 차단한다.
-> 그러면 설치는 성공하는데 `better-sqlite3` 네이티브 바인딩이 빌드되지 않아 메모리·RAG 가 죽는다.
-> `vibe upgrade` 가 자동 복구하지만, 근본적으로 막으려면 한 번 승인해 두면 된다:
->
-> ```bash
-> npm config set allow-scripts=@su-record/vibe,better-sqlite3 --location=user
-> ```
->
-> 상태는 `vibe status` 의 `Native bindings` 행으로 확인한다.
+Any client can pick the work up: `vibe state` says where you are, because the state lives in plain files inside the repository. There is no handoff document — the state is the handoff.
 
----
+## Five things the harness does (and nothing else)
 
-## Figma ↔ 코드
+1. **Independent verdict.** Every scenario carries a check: `run` (exit code), `file` (exists / regex / contains / JSON Schema / column sum), `http` (status / JSON Schema / latency ceiling), `eval` (count of matching labelled cases through a runner), or `human` (no verdict — goes to the inbox). Only what `vibe check` executed itself becomes evidence. A model saying "done" changes nothing; DONE is void the moment a file changes.
+2. **Memory across sessions and clients.** `.vibe/` holds the intent, scenarios, evidence, ledger, inbox, regressions and knowledge as plain files you can read and commit.
+3. **Permission stays with people.** Who may authorize is your policy, not the harness's law (see below).
+4. **A ledger, not a claim.** Every run records client, model, result, cost when the client provides it. Comparisons are ledger queries with four verdicts — insufficient runs, mixed scenario sets, inconclusive, difference observed — and never a winner, ratio or percentage. Events also carry typed edges (`supersedes`, `decided-by`, `implements`, `caused`), so `vibe ledger why <node>` can answer "why does this regression exist" or "which approval covers this file".
+5. **It speaks first.** Human attention is narrow. At each stage the harness surfaces up to three things you did not ask about, each with a reason it found in your files, ledger or history.
 
-양방향. Figma에서 디자인을 읽거나, 기획서에서 Figma에 디자인을 쓰거나.
+## Check types
 
-```bash
-# READ — 기존 프로젝트에 UI 추가 (프로젝트 컨벤션 준수)
-/vibe.figma <figma-url> <figma-url>
-
-# READ — 신규 독립 페이지 (독립 스타일)
-/vibe.figma --new <figma-url>
-
-# WRITE — 기획서에서 Figma 디자인 생성
-/vibe.figma plan.md --create                 # Full (와이어 + 비주얼 디자인)
-/vibe.figma plan.md --create-storyboard      # 와이어만
-/vibe.figma plan.md --create-design          # 비주얼 디자인만
-```
+| type | verdict | arguments |
+|---|---|---|
+| `run` | exit code | `cmd`, `expect` (default 0), `timeoutMs`, `cwd` |
+| `file` | exists · regex · substring · JSON Schema · column sum | `path`, `exists` / `pattern` / `contains` / `schema` / `sum: {column, equals, tolerance}` |
+| `http` | status · body schema · latency ceiling | `url`, `method`, `expect: {status, schema, maxMs}`, `timeoutMs` |
+| `eval` | count of matching cases (never a ratio) | `cases` (jsonl `{id, input, expected}`), `runner` (stdin → stdout), `expect: {pass}` |
+| `human` | none — a question in the inbox | `question` |
 
-**READ 동작**: Figma REST API로 노드 트리 + 30개 CSS 속성 추출. Auto Layout → Flexbox 1:1 기계적 매핑. 스크린샷은 검증용 — 트리가 원천. 렌더링은 pixelmatch 시각 대조로 게이트.
+Tables (`csv` · `tsv` · `jsonl` · `json`) are read by the harness itself; `vibe profile <file>` prints columns, types, missing values, duplicates and up to three anomalies before the interview. Spreadsheets are exported as CSV — the harness takes no dependency for Excel.
 
-**WRITE 동작**: 기획서의 Look & Feel, 레이아웃, 반응형 전략 섹션을 파싱하여 와이어프레임을 먼저 그리고 (구조 검토), 그 위에 디자인 시스템 컴포넌트로 비주얼 적용. 멱등성 보장 — 기획서 수정 후 재실행하면 변경된 섹션만 갱신.
+## The work graph
 
----
+A scenario may declare what it depends on:
 
-## DESIGN.md — 시각 품질 SSOT
-
-`CLAUDE.md`(코드)·`AGENTS.md`(빌드) 에 이은 **세 번째 SSOT**. Google Stitch 9-섹션 표준으로 프로젝트 루트에 위치하며, 외부 AI 에이전트가 직접 읽을 수 있는 휴먼-리더블 시각 규약입니다. **Figma 종속 X** — Figma 는 4 입력 경로 중 하나일 뿐.
-
-```bash
-# 4 가지 init 경로 (Figma 없이도 시작 가능)
-/vibe.design init                                  # 인터뷰 (디폴트)
-/vibe.design init --from=code                      # 기존 코드 토큰 역추출 (Tailwind/CSS-vars/styled-components)
-/vibe.design init --from=reference --reference=linear   # awesome-design-md 시드 12 종
-/vibe.design init --from=figma --file=<key>        # /vibe.figma 위임 (옵션)
-
-# 라이프사이클
-/vibe.design lint                                  # Stitch 9-섹션 완전성 검증
-/vibe.design verify                                # 구현 ↔ DESIGN.md hex 토큰 드리프트
+```yaml
+- id: build
+  then: dist is produced
+  check: { type: run, cmd: "npm run build" }
+- id: tests
+  needs: [build]
+  then: every test passes
+  check: { type: run, cmd: "npm test" }
 ```
 
-**자동 통합**:
-- `/vibe.run` — UI 작업 진입 시 DESIGN.md 없으면 1 회 권유 (autonomous silent skip, 절대 블록 X)
-- `/vibe.verify` — `### 3.2 Visual Drift Detection` 으로 hex 하드코딩 P1 검출
-- `/vibe.review` — `#### Visual P1 Baseline` — DESIGN.md 우선, 없으면 WCAG AA 폴백
-- `/vibe.figma` — `--emit-design-md` 로 READ 산출물을 DESIGN.md 로 출력, WRITE 는 DESIGN.md 톤·팔레트 1 차 입력
-
-> v1 범위: hex 컬러 드리프트. spacing / font 드리프트는 Phase 2+
-
----
-
-## 품질 게이트
-
-탐지는 편집 시점에, 차단은 결정론적 게이트에서:
-
-| 계층 | 동작 |
-|------|------|
-| 편집 훅 (Edit/Write) | 오탐률 낮은 하드룰만 **탐지** — `any`/`@ts-ignore`, `console.log` → 모델에 즉시 주입(additionalContext). 함수 길이·중첩 같은 휴리스틱은 없음 — 모델이 컨텍스트 안에서 더 정확히 판단 |
-| 결정론 게이트 | **PR 테스트 게이트**(PR 생성 전 테스트 스위트 직접 실행, `gh pr create` 포함) · **auto-commit verify 게이트**(verify 통과 전 커밋 거부) · **Stop 훅** verify-skip 경고/차단 · **scope-guard**(opt-in, SPEC 범위 밖 편집 감시) · **sentinel**(파괴적 명령·하네스 자기 수정 차단) |
-| 노드 게이트 | 게이트를 파이프라인 끝에만 두지 않음 — **SPEC Code Guard**가 승인 **전에** 하류 요구사항(REQ-ID·Stakes·Done Criteria·미치환 placeholder)을 검사하고, 실패하면 SPEC 작성으로 되돌림(backward edge) |
-| 사람 게이트 | **게이트 객체** — 대기 중인 질문을 디스크(`.vibe/gates/`)에 남겨 세션이 끊겨도 무엇을 묻는지 살아남음. **비용 게이트** — 되돌릴 수 없는 지출(유료 생성)과 이상 규모 팬아웃 직전에만 승인 요청(평상시 규모는 통과) |
-| 리뷰 + 수렴 루프 | `code-reviewer`를 관점(focus)별 병렬 인스턴스로 실행(correctness/architecture/performance/data-integrity/…) + `security-reviewer`. P1=0까지 루프하되 수렴은 discover-hash가 판정 — 2라운드 동일 findings면 stuck으로 확정하고 사람에게 질문. 절대 조용히 넘어가지 않음 |
+`vibe check` runs scenarios whose parents have passed, up to four at a time, then their dependents. A dependent of a failed parent is reported `blocked` and never run. `vibe check tests` pulls in `build` if it has not passed yet. Unknown ids, cycles and a `human` parent are rejected at draft time. `vibe state --graph` prints the graph as mermaid with the last result on each node.
 
----
+Routing stays in code: the model never decides the order. Keep a graph under six connected scenarios; past that, split the intent. When independent scenarios are built by parallel agents, each works in its own worktree and the branches are merged before `vibe check --all` — the harness orders checks, it does not run agents.
 
-## 주요 기능
-
-**7+ 에이전트** — 전역 7개(architect, implementer, tester, code-reviewer, security-reviewer 등) + 조건부 그룹 4개(UI/Event — 해당 스택 프로젝트에만 로컬 설치, 총 11개). 단계별 지시 스크립트가 아니라 목표+제약+Done 기준으로 위임하고, 탐색·계획·병렬 실행은 하네스의 네이티브 서브에이전트를 그대로 사용합니다.
-
-**52개 스킬** — 한 번에 다 로드되지 않음. 공개 스킬은 모두 `vibe.*` namespace를 사용하며, 내부 core 동작은 공개 스킬 본문에 통합됩니다:
-
-| 티어 | 로드 시점 | 용도 | 예시 |
-|------|----------|------|------|
-| **Entry** | 전역 설치 | 공개 워크플로 진입점 | vibe.spec, vibe.test, vibe.docs |
-| **Standard** | 전역 설치 | 공통 워크플로 지원 | vibe.handoff, vibe.agents-md |
-| **Optional/Local** | 명시 호출 또는 프로젝트별 설치 | 스택·capability 지원 | vibe.chub-usage, vibe.design-review |
-
-스킬이 가르치는 것은 모델이 모르는 것(도메인 gotcha, 최신 API, 프로젝트 규약)뿐입니다. 디버깅하는 법 같은 기본기 재교육 스킬은 v3에서 전부 삭제됐습니다.
-
-**세컨드 오피니언 (opt-in)** — 기본 실행은 세션 모델 단독. 원할 때만 `gpt …`/`agy …` 접두사로 외부 LLM에게 물어보거나 `/vibe.review --race`로 교차 검증합니다. 자동 라우팅으로 외부 모델이 끼어드는 일은 없습니다.
-
-**스택 감지** — 24개 프레임워크 자동 감지 (Next.js, Django, Rails, Go, Rust, Flutter 등) 후 프레임워크별 규칙과 스킬 적용.
-
-**회귀 기억** — verify 실패가 `/vibe.regress`에 자동 등록되고, 반복 패턴은 예방 테스트로 승격. 결정·제약은 SQLite + FTS5로 세션 간 유지.
-
-**Smart Resume** — `.last-feature` 포인터가 마지막 작업을 추적. 인자 없이 `/vibe`를 호출하면 중단된 위치를 보여주거나 진행 중 feature 목록을 제시.
-
-**루프 엔지니어링** — `/vibe.loop`로 자율 목표 루프를 설계·설치(트리아지 → run/verify 파이프라인). 완료 판정은 자기 보고가 아니라 결정론 게이트(run-ledger/테스트)가 내리고, 폭주 방어도 마찬가지 — 회전 수를 코드가 세고 **전체 회전**과 **검증을 통과한 회전**을 따로 집계해 헛도는 루프와 큰 작업을 구분합니다. 결과는 사람 리뷰 인박스로 — 루프는 push/release를 하지 않습니다.
-
----
-
-## 플러그인으로 설치 (실험적)
-
-npm 전역 설치의 **대안** 경로다. Claude Code · Codex · ChatGPT 세 곳에 같은 배포 트리(`plugins/vibe`)가 올라간다.
-
-**Claude Code — 저장소에서 바로** (npm 설치 불필요)
+## Token policy
 
 ```bash
-claude plugin marketplace add su-record/vibe
-claude plugin install vibe@vibe
-claude plugin details vibe               # Skills 52 · Agents 11 · Hooks 6
+vibe init --tokens strict         # approval and irreversible actions both need a six-digit human token
+vibe init --tokens irreversible   # default — a plain "yes" approves; push/deploy/send/delete/spend need a token
+vibe init --tokens off            # no tokens; everything is recorded as "auto" (you already skip permissions)
 ```
 
-**npm 으로 이미 설치한 경우**
+Tokens are six digits, valid ten minutes, single use, bound to what they authorize, and stored only as hashes. The verdict itself is never configurable.
 
-```bash
-vibe plugin install                      # 배포 트리 조립 + 마켓플레이스 두 벌 등록
-vibe plugin status                       # 조립·등록 상태 확인
-
-claude plugin marketplace add ~/.vibe/plugin
-claude plugin install vibe@vibe
+## Commands
 
-codex plugin marketplace add ~
-codex plugin add vibe@vibe
 ```
-
-**저장소를 클론한 경우** (개발·검증용)
-
-```bash
-npm run build:plugin                     # plugins/vibe/ 로 조립 (package.json files 기준)
-claude plugin validate plugins/vibe
-codex plugin marketplace add .
-codex plugin add vibe@vibe-local
+setup     init · status · uninstall
+work      state [--graph] · profile <file> · intent draft | show · approve · check · evidence · abandon
+human     ask · authorize · inbox
+memory    regress record | list · knowledge add
+research  research --from-intent | "query"
+skills    skill suggest · create · add · search · list · used · prune · dismiss
+ledger    ledger · ledger compare · ledger why <node> · ledger edges [--type]
 ```
 
-> **훅 이중 실행은 자동으로 막힌다.** npm 설치본의 프로젝트 훅이 이미 있으면 플러그인 훅은
-> 스스로 물러난다 (`plugin-hook-entry.js`). 그러지 않으면 같은 게이트가 2회 돌고
-> Stop 의 auto-commit 도 2회 돈다.
->
-> **`plugins/vibe/` 는 커밋되는 생성물이다.** Claude Code 마켓플레이스는 저장소를 클론해 읽는데
-> `dist/` 는 gitignore 대상이고 `agents/*.md` 의 frontmatter 는 postinstall 이 만든다 —
-> 즉 저장소를 그대로 가리키면 기능이 빠진 플러그인이 된다 (실측: 에이전트 11개 중 7개만,
-> 그나마 description 없이 로드). 드리프트는 CI 의 `validate:plugin-tree` 가 막는다.
-
-ChatGPT 데스크톱 앱에서는 앱을 **재시작**한 뒤 Plugins Directory 에서 "Vibe (local)" → `vibe` 를 설치한다.
-
-> 마켓플레이스 파일만 만들어두면 잡히지 않는다 — `marketplace add` 로 **등록**해야 한다.
-> `source.path` 는 저장소 루트가 아니라 빌드 산출물(`./plugins/vibe`)을 가리킨다.
-> 루트를 가리키면 워킹트리가 통째로 캐시에 복사된다 (실측 655MB, 그중 620MB 가 `node_modules`).
-
-| 번들 | Claude Code | Codex CLI | ChatGPT 앱 |
-|---|---|---|---|
-| skills (52) | ✅ | ✅ | ✅ |
-| agents (11) | ✅ | — | — |
-| hooks (6 이벤트) | ✅ | ✅ (trust 승인 후) | **미확인** — 훅 문서가 Codex 아래에만 있다 |
-
-> ⚠️ Codex 에서 훅은 설치·활성화만으로 신뢰되지 않는다 — Codex 가 정의를 검토·승인할 때까지 건너뛴다.
-> `vibe init` 이 만드는 프로젝트 로컬 설정과 `vibe upgrade` 의 자기복구는 플러그인이 대체하지 못한다 —
-> 그 둘이 필요하면 npm 설치를 함께 쓴다.
-
----
-
-## 지원 도구
-
-| CLI | 상태 |
-|-----|------|
-| [Claude Code](https://claude.ai/code) | 전체 지원 |
-| [Codex](https://github.com/openai/codex) | 전체 지원 (`~/.codex/`, AGENTS.md, native hooks.json, config.toml notify, codex exec agent fallback) |
-| Antigravity CLI (`agy`) | 에이전트 + 스킬 |
-
----
+`vibe --help` has the details. Every command accepts `--json`. The exit code is the verdict: 0 ok · 1 verdict failed · 2 usage · 3 token · 4 invalid transition.
 
-## 명령어
+## Research — see what exists before building
 
-`/vibe` 하나로 시작하면 나머지는 vibe 가 라우팅한다. 아래는 특정 단계를 직접 부르고 싶을 때의 목록이다.
+`vibe research --from-intent` turns the intent title, the hosts its `http` checks target and the stack into queries, searches GitHub repositories, code (`SKILL.md` files — needs a token) and skill catalogs, and ranks up to five candidates by keyword match, recency, stars and license. Each candidate carries one action: `vibe skill add …`, a knowledge note, or none. The note lands in `.vibe/knowledge/research/`; the same query is cached for a day. Nothing fetched is executed or installed.
 
-**핵심 흐름**
+Default catalogs: `anthropics/skills`, `vercel-labs/agent-skills`, `NousResearch/hermes-agent` (a skill is any directory with a `SKILL.md`, at any depth). Add your own under `catalogs` in `.vibe/config.json`. Without a GitHub token (`GITHUB_TOKEN`, or `gh auth login`) code search is skipped and catalogs are read within the public limits.
 
-| 명령어 | 용도 |
-|--------|------|
-| `/vibe` | **메인 진입점** — 자연어 요구사항 → SPEC 1패스 → 1회 승인 → 게이트 통과까지 루프 |
-| `/vibe.spec` | SPEC 1패스 명시적 호출 — 인라인 질문 → SPEC + BDD → 승인 |
-| `/vibe.run` | SPEC 기반 구현 |
-| `/vibe.verify` | 구현이 SPEC Done 기준에 맞는지 검증 — 결과는 run-ledger 에 기록 |
-| `/vibe.continue` | 세션 복원 — 85%+ 컨텍스트에서 `save_memory` → `/new` 후 이어서 |
+## Skills
 
-**CLI**
+Six common skills ship with the package — `vibe` (entry), `discover`, `scope`, `build`, `prove`, `handoff` — under 300 lines in total. They contain the harness command sequence and message shapes for each stage, nothing about how to code.
 
-| 명령 | 용도 |
-|---|---|
-| `vibe status` | 하네스 상태 — 하네스별 훅, 네이티브 바인딩, LLM 인증 |
-| `vibe upgrade` | 업그레이드 + 자기복구 (전역 자산 · 프로젝트 훅 · 네이티브 바인딩) |
-| `vibe plugin install` | 플러그인 배포 트리 조립 + 마켓플레이스 등록 |
+Project-specific skills live only inside the project (`.claude/skills`, `.codex/skills`, registry in `.vibe/skills/`) and are installed only when bound to a check or carrying knowledge the model lacks:
 
-**검증 · 품질**
-
-| 명령어 | 용도 |
-|--------|------|
-| `/vibe.review` | 관점별 병렬 리뷰 (correctness / security / performance …) — P1=0 까지 수렴 |
-| `/vibe.regress` | 회귀 테스트 자동 진화 — verify 실패 자동 등록, 반복 패턴 승격 |
-| `/vibe.contract` | SPEC API 계약 ↔ 구현 drift 탐지 — P1 drift 는 regress 로 전파 |
-| `/vibe.trace` | 요구사항 추적 매트릭스 (RTM) |
-| `/vibe.loop` | 자율 목표 루프 설계·설치 — 완료는 결정론 게이트가 판정 |
-| `/vibe.test` | vibe 설치 자가검진 (CC ↔ Codex 동등성) — 릴리즈 전 권장 |
-| `/vibe.harness` | 프로젝트 하네스 품질 6축 진단 (N/100) |
-
-**설계 · UI**
+```
+vibe skill suggest                         # ≤3 proposals from signals: http hosts, regression clusters, repeated questions, handoff
+vibe skill create <name> --check run|file|http|eval [--from-scenario <id>]
+vibe skill add owner/repo[@name] [--pin <sha>] [--yes]   # shows the commands inside, installs only with --yes, pinned to a commit
+vibe skill search <keyword> · list · used <name> · prune [--unused-runs 10] · dismiss <ref>
+```
 
-| 명령어 | 용도 |
-|--------|------|
-| `/vibe.figma` | Figma ↔ 코드 (읽기 또는 쓰기, 3가지 모드) |
-| `/vibe.design` | DESIGN.md 시각 품질 SSOT — init / lint / verify / sync / preview |
-| `/vibe.clone` | 참조 사이트 URL → 현재 스택으로 마크업 재현 (픽셀 검증 루프) |
-| `/vibe.image` | 이미지 생성 (Antigravity) — 아이콘 / 배너 / 목업 |
+Proposals are proposals: the harness never installs, runs remote commands, or writes outside the project by itself. A dismissed proposal is not repeated.
 
-**분석 · 문서 · 운영**
+## Language
 
-| 명령어 | 용도 |
-|--------|------|
-| `/vibe.analyze` | 코드·문서·웹·Figma 분석 → 근거 있는 리포트 |
-| `/vibe.reason` | 복잡한 문제의 가설·근거·트레이드오프 구조화 |
-| `/vibe.docs` | README·가이드·아키텍처·릴리즈 노트·다이어그램을 코드와 동기화 |
-| `/vibe.scaffold` | 새 프로젝트 구조 생성 / 기존 구조 감사 |
-| `/vibe.llm` | provider 별 사용 가능 모델 목록 갱신 |
+The always-on card (1KB), the skills and every record vibe writes are English. The model talks to you in your language.
 
-> 위는 자주 쓰는 것들이다. 설치된 전체 스킬 목록은 [SKILL-CATALOG.md](SKILL-CATALOG.md) 에 있고,
-> 표에 없는 요구사항도 `/vibe` 가 description 기반 Catch-all 라우팅으로 처리한다.
+## What is inside `.vibe/`
 
----
+```
+intent.md        what and why — the one page you approve
+scenarios.yaml   given / when / then + the check that judges each + needs (the work graph)
+evidence/        what the harness actually ran, per run
+ledger.jsonl     state changes, client, model, results, cost, typed edges
+inbox.jsonl      questions, STUCK notices, token hashes
+regressions/     fixed failures as reproducing checks
+knowledge/       domain notes the model reads when it needs them; research/ holds search notes
+skills/          registry of project-local skills and dismissed proposals
+cache/           research results, one day
+config.json      token policy · skill catalogs
+```
 
-## 문서
+## Status
 
-상세 가이드, 스킬 레퍼런스, 설정 방법은 [Wiki](https://github.com/su-record/vibe/wiki)를 참고하세요.
+`4.0.0` — phase 1: CLI core + Claude Code. Phase 2: Codex CLI and ChatGPT desktop adapters, the work graph and typed ledger edges. Phase 3a: `http` / `eval` checks, column sums, sample profiling. Phase 3b: GitHub research, project-local skills and proposals. Phase 3c: the end-to-end order-settlement example. Phase 4: the bench and `ledger compare --by harness`. vibe 3 stays on its 3.x tags and is no longer developed.
 
-- [README (English)](README.en.md)
-- [릴리스 노트](https://github.com/su-record/vibe/releases) — 태그마다 CI 가 SPEC·커밋에서 결정론적으로 생성
+## Bench — the ledger is the benchmark
 
----
+`bench/run.js` runs the same task under different arms (Claude Code · Codex, harness on · off), judges every run with the same scenarios, and appends one `check` line per run to `bench/ledger.jsonl`. `vibe ledger compare --by harness --metric checks --ledger bench/ledger.jsonl` answers with one of four verdicts and never a ratio. See `bench/README.md`.
 
-## 요구사항
+## Example
 
-- Node.js >= 20.12.0 (`better-sqlite3` 는 Node 20+, `@clack/prompts` 는 20.12+ 요구)
-- Claude Code 또는 Codex CLI 중 하나
-- GPT, Antigravity (선택 — 세컨드 오피니언 전용)
+`examples/order-settlement/` is the design walkthrough run for real: an order CSV with a duplicate row and a missing amount, a settlement script, a schema, and a dry-run send. This repository's own scenarios judge it — profile anomalies, exit codes, the `total` column sum, the summary schema — and the project-local skill created from the settle scenario has to survive `vibe skill prune`.
 
-## 라이선스
+## Develop
 
-MIT — Copyright (c) 2025 Su
+```bash
+npm ci && npm run check          # build + tests
+node dist/cli.js check --all     # vibe 4 judges its own scenarios
+```

package/card.md

@@ -0,0 +1,9 @@
+You are working inside vibe. Rules:
+1. Before changing anything, run `vibe state --json` and continue from it.
+2. Nothing is done until `vibe check` says DONE. Never claim completion yourself.
+3. When the harness asks for a human token (approval or an irreversible action), show the number and wait for it in chat. Never invent one.
+4. If `vibe check` fails twice the same way, stop and `vibe ask`.
+5. Surface at most three things the user did not ask about, each with a reason from the harness.
+6. Record any failure you fixed with `vibe regress record`.
+7. Talk to the user in the user's language. Write every record (intent, scenarios, inbox, knowledge, docs) in English.
+Start with `/vibe {request}`.