@byh3071/vhk 1.0.2 → 1.3.1

package/README.md

@@ -1,57 +1,90 @@
 ---
 id: vhk-readme
-date: 2026-05-24
-tags: [vhk, cli, readme, v1.0.0, ga]
+date: 2026-05-28
+tags: [vhk, cli, readme, v1.3.0, ga]
 ---
 
 # 🔧 VHK — Vibe Harness Kit
 
-> 🎉 **v1.0.0 GA** — 바이브코더의 올인원 CLI. 공개 API 안정성 보장.
+> 🎉 **v1.3.0** — 바이브코더의 올인원 CLI. 컨텍스트 + 자율 하네스.
 >
-> AI 코딩 에이전트를 부리는 사람을 위한 **한국어 풀사이클 CLI** (v1.0.0)
+> AI 코딩 에이전트를 부리는 사람을 위한 **한국어 풀사이클 CLI**.
 >
 > 🍽️ **VHK는 VHK로 부트스트랩됨** — 이 레포의 `docs/`, `CLAUDE.md`, `.cursorrules`도 `vhk init`이 만들었습니다.
 
 명령어를 외우지 않아도 됩니다. `vhk`만 치면 메뉴가 나오고, 한국어로 말해도 알아듣습니다.
 
-## 설치
+## 3분 안에 시작하기 (Getting Started)
+
+### 1. 설치
 
 ```bash
 npm install -g @byh3071/vhk
+vhk --version
 ```
 
+> Node.js ≥ 20 필요. `npx @byh3071/vhk` 로 1회성 실행도 가능.
+
+### 2. 첫 프로젝트 — `vhk start` (마법사)
+
 ```bash
-# 한 번만 쓸 때
-npx @byh3071/vhk
+mkdir my-app && cd my-app
+vhk start
 ```
 
-로컬 개발 중:
+`vhk start` 한 번이면 **git init → 문서 생성 → MCP 등록 → 컨텍스트 파일** 까지 자동으로 끝납니다.
 
-```powershell
-cd vhk-cli
-pnpm install
-pnpm build
-pnpm link --global
-vhk --version
+기획이 막 떠올랐다면 검증부터:
+
+```bash
+vhk gate          # 퀵 5문항 — GO / 다듬기 / 다른 아이디어
 ```
 
-## 빠른 시작
+### 3. v1.3 핵심 기능 한눈에
 
-```bash
-vhk
+| 기능 | 한 줄 요약 | 진입 명령 |
+|------|-----------|-----------|
+| 🎯 **Goals 체계** | 단계별 미션 + 게이트 스크립트로 AI가 목표를 스스로 추적 | `vhk goal init` |
+| ▶️ **자율 루프** | `goal next → 작업 → goal check → goal done`. FAIL 3회면 자동 블로커 | `vhk goal next` |
+| 🚧 **HARD_STOP 안전장치** | 블로커 3건 누적 → `.vhk/HARD_STOP` 트립와이어. `vhk resume --confirm` 만 해제 | `vhk blocker "<증상>"` |
+| 🔌 **MCP 24 tool** | Cursor·Claude Desktop 등에서 vhk를 채팅으로 호출 | `vhk mcp-init` |
+| 📋 **컨텍스트 영속화** | `.vhk/context.md` + `memory.json` + `brief.md` 로 세션 간 맥락 유지 | `vhk context` |
+
+### 4. 권장 일일 사이클
+
+```text
+세션 시작 :  vhk context          # AI에 줄 프로젝트 맥락 갱신
+            vhk goal next         # 오늘 작업할 미션 자동 선택
+
+   개발 ...
+
+세션 종료 :  vhk goal check        # 게이트 스크립트로 통과 검증
+            vhk goal done         # 통과 시 status: DONE 으로 전이
+            vhk save              # add → commit → push 한 번에
+            vhk recap             # docs/log/ 에 오늘 기록
 ```
 
-인자 없이 실행하면 **「뭘 도와드릴까요?」** 메뉴가 열립니다.
+### 5. 자연어로도 됩니다
 
 ```bash
-# 자연어로도 가능
 vhk 프로젝트 만들고 싶어
 vhk 기획 끝났고 바로 시작
 vhk 오늘 한 일 정리
 vhk 저장해줘
-vhk 변경사항 보여줘
+vhk 다음 목표
+vhk 블로커 "API 호출 실패"
 ```
 
+---
+
+## 빠른 시작 (인터랙티브 메뉴)
+
+```bash
+vhk
+```
+
+인자 없이 실행하면 **「뭘 도와드릴까요?」** 메뉴가 열립니다.
+
 ## 워크플로우 (권장 순서)
 
 ```text
@@ -109,6 +142,33 @@ vhk 기획 끝났고 바로 시작
 | `vhk context-show` | `맥락보기` | 현재 컨텍스트 파일 내용 출력 |
 | `vhk memory` | `기억` | 결정사항 기억 관리 (`add` / `list` / `remove`, `.vhk/memory.json` 기반, 태그 지원) |
 | `vhk brief` | `브리핑` | 프로젝트 정보 + git 상태 + 결정사항 + 레퍼런스 통합 보고서 `.vhk/brief.md` |
+| `vhk goal` | `목표` | Goal 단계별 미션 관리 (`init` / `list` / `next` / `check` / `done`) — vspec/vooster 패턴 |
+| `vhk blocker <설명>` | `블로커` | 블로커 1건 → `docs/state/blockers.md` append. 3건 누적 시 `.vhk/HARD_STOP` 자동 생성 |
+| `vhk learn <교훈>` | `교훈` | 교훈 1건 → `docs/state/learnings.md` append (memory.json 과 별도 SoT) |
+| `vhk resume --confirm` | `재개` | `.vhk/HARD_STOP` 해제 (사람 확인 필요, 자동 호출 금지) |
+
+### 자율 루프 (v1.3+)
+
+`AGENTS.md` 의 Loop Protocol 참조. 단방향 사이클:
+
+```text
+vhk context → vhk goal next → (작업) → vhk goal check → vhk goal done
+                                          ↓ FAIL × 3 cycle
+                                   vhk blocker "<증상>"
+                                          ↓ 3건 누적
+                                   .vhk/HARD_STOP 자동 → 사람 검토 → vhk resume --confirm
+```
+
+### goal 서브커맨드 (v1.2+)
+
+| 서브 | 설명 |
+|------|------|
+| `vhk goal init` | 현재 프로젝트에 `goals/` + `docs/state/` 스캐폴딩 (기존 파일 보존) |
+| `vhk goal list` | `goals/*.md` frontmatter 파싱 → id 순 목록 (status/priority/title) |
+| `vhk goal next` | active goal (IN_PROGRESS → 첫 NOT_STARTED) 선택 → `docs/state/next-task.md` 갱신 |
+| `vhk goal check [--id N]` | `scripts/check-goal-<id>.sh` 실행 (생략 시 active goal) |
+| `vhk goal done [--id N]` | 게이트 재검증 → 통과 시 frontmatter `status: DONE` + `completed: YYYY-MM-DD` |
+| `vhk check --goal N` | 위 `goal check` 의 별칭 (기존 `check` 시그니처 무변경 + optional 옵션) |
 
 ### init 옵션
 
@@ -135,7 +195,16 @@ vhk mcp-init           # .cursor/mcp.json 자동 생성
 # 예: "상태 알려줘" → Cursor가 vhk status 도구 호출
 ```
 
-노출되는 MCP 도구 8개: `save`, `undo`, `status`, `diff`, `ship`, `doctor`, `check`, `recap`.
+노출되는 MCP 도구 **24개** (v1.1):
+
+- **git 워크플로 (8)**: `save`, `undo`, `status`, `diff`, `ship`, `doctor`, `check`, `recap`
+- **환경/규칙 (4)**: `env`, `env-check`, `sync`, `secure`
+- **품질/감사 (3)**: `audit`, `harness`, `mcp-init`
+- **컨텍스트/기록 (4)**: `context`, `context-show`, `memory-list`, `brief`
+- **dry-info (4)**: `deploy`, `publish`, `migrate`, `update` — 인터랙티브 본질이라 실제 실행 안 함, 진단/안내만
+- **레퍼런스 (1)**: `ref-list`
+
+MCP 제외 확정 커맨드 (대화형 본질): `gate`, `init`, `start`, `design palette`, `theme`, `goal` (각각 CLI 에서만 동작).
 
 MCP 서버를 수동으로 띄우려면:
 
@@ -178,7 +247,7 @@ vhk brief               # 세션 종료 시 상태 보고서
 - **공개 API 안정성**: 명령어 이름, CLI 인자, `.vhk/` 파일 포맷은 v2.0까지 breaking change 없음
 - **deprecation 절차**: 명령어/옵션 제거 전 1개 마이너 버전(1.x.0)에서 deprecation 경고
 - **i18n 키**: `ko.ts`의 `t()` 키 이름은 안정. 신규 키 누적, 기존 키 미제거
-- **MCP 서버 도구**: 8개 도구(save/undo/status/diff/ship/doctor/check/recap) 인터페이스 안정
+- **MCP 서버 도구**: v1.0 GA 의 8개 baseline 도구(save/undo/status/diff/ship/doctor/check/recap) 인터페이스 안정 — v1.1 에서 16개 추가되어 총 24개
 
 > **`vhk memory` vs Claude Code `auto memory`** — `vhk memory`는 **프로젝트 단위** 결정사항(`.vhk/memory.json`, 팀 공유). Claude Code의 `auto memory`는 **사용자 단위** (`~/.claude/projects/.../memory/`, 개인 컨텍스트). 둘은 별개.
 
@@ -229,7 +298,7 @@ vhk ref open 1          # 1번 레퍼런스를 브라우저로 열기
 
 | 기능 | 설명 |
 |------|------|
-| **MCP 서버** | `vhk mcp` — 8개 도구(save/undo/status/diff/ship/doctor/check/recap)를 stdio로 노출. Cursor 등 MCP 클라이언트에서 자연어로 호출 |
+| **MCP 서버** | `vhk mcp` — stdio MCP 서버 첫 도입 (v0.6.0 당시 8개 도구 — save/undo/status/diff/ship/doctor/check/recap). 현재 v1.3 기준 **24개** 로 확장 — 위 "Cursor와 MCP로 연동하기" 섹션 참조 |
 | **mcp-init** | `vhk mcp-init` — Cursor `.cursor/mcp.json` 자동 생성. 재시작 한 번으로 연동 완료 |
 | **자연어 라우팅 확장** | `vhk mcp설정` → `vhk mcp-init` 별칭 |
 | **보안** | MCP save 도구의 shell injection 차단 — 모든 git 호출에 `execFileSync` 사용 |