vibe-commander 0.1.1 → 0.2.1

package/AGENTS.md

@@ -8,6 +8,7 @@
 ```
 vc init                          # Initialize project (create config)
 vc init --from-existing          # Auto-detect from existing files
+vc init --force                  # Overwrite existing config
 vc set-unit <unitId>             # Set current working unit
 vc set-unit <unitId> --dry-run   # Preview without modifying files
 vc update-commit [sha|N]         # Update commit SHA (no arg=HEAD, number=recent N)

package/README.ko.md

@@ -0,0 +1,643 @@
+# vibe-commander
+
+[![npm version](https://img.shields.io/npm/v/vibe-commander.svg)](https://www.npmjs.com/package/vibe-commander)
+[![license](https://img.shields.io/npm/l/vibe-commander.svg)](https://github.com/viilab/vibe-commander/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/vibe-commander.svg)](https://nodejs.org)
+
+[English](README.md) | [한국어](README.ko.md)
+
+**유닛 기반 바이브 코딩 워크플로우 자동화** — 유닛 ID 하나로 커맨드 파일 섹션을 자동 생성하여, 수동 컨텍스트 수집 시간을 **10분에서 10초로** 단축합니다.
+
+vibe-commander는 작업 유닛 전환 시 반복되는 과정을 자동화합니다: 계획서 파싱, 의존성 수집, 관련 커밋 검색, 에이전트 컨텍스트 조립 — 모두 하나의 설정 파일(config file)로 어떤 프로젝트 구조에든 적응합니다.
+
+## 왜 vibe-commander인가?
+
+AI 에이전트(Cursor, Claude Code, Gemini CLI)와 유닛 기반 개발 파이프라인을 사용할 때, 유닛 전환마다 수동으로 컨텍스트를 수집해야 합니다:
+
+**이전** — 유닛 전환 시 수동 워크플로우:
+
+```
+1. 로드맵에서 다음 유닛 확인                         (~1분)
+2. 계획서를 열고 의존성 파악                          (~2분)
+3. 의존 유닛 문서(계획서, 결과, 런북) 찾기            (~3분)
+4. Git 히스토리에서 관련 커밋 검색                     (~2분)
+5. 페어링 질문 답변 작성                              (~1분)
+6. 특별 요청사항 템플릿 삽입                          (~1분)
+7. 작업 중 커밋 SHA 계속 업데이트                     (지속적)
+─────────────────────────────────────────
+합계: 전환 1회당 ~10–15분 × 하루 3–5회 전환
+```
+
+**이후** — vibe-commander 사용 시:
+
+```bash
+vc set-unit U-042[Mvp]    # 모든 컨텍스트가 ~10초 만에 수집·조립
+vc update-commit           # HEAD에서 커밋 SHA 자동 추적
+```
+
+하나의 명령으로 계획서를 파싱하고, 의존성을 해석하고, 관련 문서와 커밋을 수집하고, 커맨드 파일 섹션을 렌더링하고, 페어링 질문을 처리합니다 — 모두 프로젝트 설정(config)에 의해 구동됩니다.
+
+## 빠른 시작
+
+### 방법 1: npx로 즉시 실행 (설치 불필요)
+
+```bash
+npx vibe-commander init --from-existing
+npx vibe-commander set-unit U-001[Mvp]
+```
+
+> **pnpm 사용자**: `npx` 대신 `pnpm dlx vibe-commander`를 사용하세요.
+
+### 방법 2: 글로벌 설치
+
+```bash
+npm install -g vibe-commander
+# 또는: pnpm add -g vibe-commander
+# 또는: yarn global add vibe-commander
+
+vc init --from-existing
+vc set-unit U-001[Mvp]
+```
+
+### 방법 3: 프로젝트 devDependency
+
+```bash
+npm install -D vibe-commander
+# 또는: pnpm add -D vibe-commander
+# 또는: yarn add -D vibe-commander
+
+npx vc init --from-existing
+npx vc set-unit U-001[Mvp]
+```
+
+> **중요**: 프로젝트에서 사용하는 패키지 매니저와 동일한 도구를 사용하세요. 패키지 매니저를 혼용하면(예: pnpm 프로젝트에서 `npm install` 실행) 의존성 해석 에러가 발생할 수 있습니다.
+
+### 초기 설정
+
+```bash
+# 기존 프로젝트 파일을 스캔하여 설정 자동 생성
+vc init --from-existing
+
+# 또는 대화형으로 설정 생성
+vc init
+
+# 생성된 설정 검증
+vc validate
+```
+
+이 명령은 프로젝트 루트에 `vibe-commander.config.json`을 생성합니다. 디렉토리 구조, 유닛 ID 패턴, 문서 레이아웃에 맞게 자동으로 구성됩니다.
+
+### 일일 워크플로우
+
+설정이 완료되면, 매일의 작업 사이클은 다음과 같습니다:
+
+```bash
+# 1. 작업 가능한 유닛 확인
+vc list-units
+
+# 2. 유닛 전환 — 계획서 파싱, 의존성 수집, 커맨드 파일 업데이트
+vc set-unit U-042[Mvp]
+
+# 3. AI 에이전트(Cursor, Claude Code 등)와 작업
+#    커맨드 파일에 에이전트가 필요한 모든 컨텍스트가 준비되어 있습니다.
+
+# 4. 작업 중 커밋 추적
+vc update-commit              # 최신 HEAD
+vc update-commit 3            # 최근 3개 커밋
+vc update-commit --mode append  # 기존 커밋에 추가
+
+# 5. 다음 유닛으로 이동
+vc set-unit U-043[Mvp]
+```
+
+## CLI 레퍼런스
+
+| 명령어 | 설명 |
+|--------|------|
+| `vc init` | 프로젝트 설정 초기화 (대화형 또는 `--from-existing` 스캔) |
+| `vc set-unit <unitId>` | 현재 작업 유닛 설정 — 커맨드 파일 섹션 자동 생성 |
+| `vc update-commit [sha\|N]` | 커밋 SHA 업데이트 (인자 없음 = HEAD, 숫자 = 최근 N개) |
+| `vc list-units` | 미완료 유닛 목록 및 의존성 상태 조회 |
+| `vc context <unitId>` | 읽기 전용 유닛 컨텍스트 조회 (파일 수정 없음) |
+| `vc validate` | 설정 파일 무결성 검증 (스키마, 경로, 패턴) |
+| `vc skill install` | AI 에이전트용 SKILL 파일 설치 |
+| `vc schema [subcommand]` | 런타임 CLI 스키마 조회 |
+
+### vc set-unit
+
+핵심 명령어입니다. 유닛 계획서를 파싱하고, 모든 의존성 문서와 커밋을 수집하여, 커맨드 파일을 업데이트합니다 — 한 번에.
+
+```bash
+# 기본 사용법
+vc set-unit U-042[Mvp]
+
+# 파일 수정 없이 변경 사항 미리보기
+vc set-unit U-042[Mvp] --dry-run
+
+# 커스텀 특별 요청사항 추가
+vc set-unit U-042[Mvp] --request doc-update --request mcp-codrag
+
+# 자동화를 위한 JSON 출력
+vc set-unit U-042[Mvp] --json
+```
+
+### vc update-commit
+
+작업 중 SHA를 직접 복사하지 않고 커밋을 추적합니다.
+
+```bash
+# HEAD 커밋 자동 감지
+vc update-commit
+
+# 최근 3개 커밋 수집
+vc update-commit 3
+
+# 특정 SHA 지정
+vc update-commit abc1234f
+
+# 기존 커밋에 추가 (교체 대신)
+vc update-commit --mode append
+```
+
+### vc list-units
+
+작업 가능한 유닛을 확인합니다.
+
+```bash
+# 미완료 유닛 전체 조회
+vc list-units
+
+# 단계(phase)별 필터링
+vc list-units --phase Mvp
+
+# 기계 판독용 출력
+vc list-units --json
+```
+
+### vc context
+
+읽기 전용 컨텍스트 조회 — 커맨드 파일을 수정하지 않고 유닛 정보가 필요한 에이전트에 유용합니다.
+
+```bash
+vc context U-042[Mvp] --json
+```
+
+### vc schema
+
+에이전트가 CLI 기능을 동적으로 발견하기 위한 런타임 스키마 인트로스펙션입니다.
+
+```bash
+# 설정 파일의 JSON Schema
+vc schema config --json
+
+# 사용 가능한 모든 명령어와 플래그
+vc schema commands --json
+
+# 유닛 유형과 ID 패턴
+vc schema types --json
+
+# 스키마를 파일로 저장
+vc schema config --json --output config-schema.json
+```
+
+### vc validate
+
+4단계 설정 검증 파이프라인: 스키마 검사, 경로 존재 확인, 정규식 유효성, 패턴 충돌 감지.
+
+```bash
+vc validate
+vc validate --json
+```
+
+## AI 에이전트용 SKILL 파일
+
+SKILL 파일은 AI 에이전트에게 vibe-commander 사용법을 가르칩니다. 하나의 명령으로 지원하는 모든 플랫폼에 가이드를 설치합니다:
+
+```bash
+# 모든 플랫폼에 설치 (Cursor + Claude Code + Gemini)
+vc skill install
+
+# 플랫폼별 설치
+vc skill install --cursor
+vc skill install --claude
+vc skill install --gemini
+
+# 기존 파일 강제 덮어쓰기
+vc skill install --force
+```
+
+설치 후, 에이전트가 자동으로 SKILL 가이드를 발견하는 경로:
+
+- **Cursor**: `.cursor/skills/vibe-commander/SKILL.md`
+- **Claude Code**: `.claude/skills/vibe-commander/SKILL.md`
+- **Gemini**: `.gemini/skills/vibe-commander/SKILL.md`
+
+## 에이전트 우선 설계 (Agent-First Design)
+
+vibe-commander는 AI 에이전트를 일급 소비자(first-class consumer)로 설계되었습니다. 모든 설계 결정이 에이전트 사용성을 우선시합니다.
+
+### AGENTS.md
+
+프로젝트에 포함된 [`AGENTS.md`](AGENTS.md) 파일(npm 패키지에도 번들됨)은 에이전트가 대화 시작 시 읽는 파일입니다. 다음을 포함합니다:
+
+- 명령어 빠른 참조
+- 불변 규칙 (항상 `--dry-run` 먼저, 항상 `--json`, 입력 검증)
+- 안전한 워크플로우 예시
+- 에러 처리 패턴
+
+### 구조화된 출력 (Structured Output)
+
+모든 명령어는 `--json` 플래그로 `ToolResult<T>` 구조의 기계 판독용 출력을 지원합니다:
+
+```json
+{
+  "success": true,
+  "data": {
+    "unitId": "U-042[Mvp]",
+    "title": "U-042[Mvp]: Add authentication module",
+    "depsFound": ["U-041[Mvp]"],
+    "docsFound": [
+      { "unitId": "U-041[Mvp]", "role": "result", "path": "docs/results/U-041[Mvp].md" }
+    ],
+    "commitsFound": ["a1b2c3d4"]
+  }
+}
+```
+
+에러도 구조화되어 반환됩니다:
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "UNIT_TYPE_NOT_FOUND",
+    "message": "No matching unit type for: U-999",
+    "details": "Registered types: implement, refactor, checkpoint",
+    "suggestions": ["U-099[Mvp]", "U-100[Mmp]"]
+  }
+}
+```
+
+### Dry-Run 모드
+
+변경 사항을 적용하기 전에 미리보기 — 에이전트 안전성에 핵심적입니다:
+
+```bash
+vc set-unit U-042[Mvp] --dry-run --json
+```
+
+### 입력 안전성 (Input Safety)
+
+CLI는 에이전트의 환각(hallucination)을 방어하기 위해 위험한 패턴을 거부합니다:
+
+- 경로 순회: `../`, `..\\`
+- 제어 문자: ASCII < 0x20
+- URL 인코딩: `%2e`, `%2F`
+- 쿼리 파라미터: `?`, `#`
+
+잘못된 유닛 ID는 레벤슈타인 거리(Levenshtein distance) 기반의 퍼지 매칭 제안을 트리거합니다.
+
+### 파이프 모드 (Pipe Mode)
+
+자동화 및 오케스트레이터를 위해 stdin으로 JSON을 전달합니다:
+
+```bash
+echo '{"unitId":"U-042[Mvp]"}' | vc set-unit --stdin --json
+```
+
+## VS Code 통합 (VS Code Integration)
+
+vibe-commander는 터미널 전환 없이 에디터 안에서 `vc` 명령어를 바로 실행할 수 있는 VS Code Tasks를 제공합니다. 선택적 DX 개선이며, 모든 기능은 터미널에서도 동일하게 사용 가능합니다.
+
+### 빠른 설정
+
+프로젝트에 Tasks 템플릿을 복사합니다:
+
+```bash
+# npm 패키지에서 복사
+cp node_modules/vibe-commander/examples/vscode-tasks.json .vscode/tasks.json
+```
+
+글로벌 설치 대신 `npx`를 사용하는 경우, Task 명령어의 `vc`를 `npx vc`로 변경하세요.
+
+### 사용 가능한 Tasks
+
+`Ctrl+Shift+P` → **Tasks: Run Task** 또는 `Ctrl+Shift+B`로 빌드 Task 그룹에서 접근할 수 있습니다:
+
+| Task | 명령어 | 설명 |
+|------|--------|------|
+| `vc: Set Unit` | `vc set-unit <unitId>` | 유닛 전환 (ID 입력 프롬프트) |
+| `vc: Set Unit (Dry Run)` | `vc set-unit <unitId> --dry-run` | 파일 수정 없이 변경 미리보기 |
+| `vc: Update Commit (HEAD)` | `vc update-commit` | 최신 HEAD 커밋 추적 |
+| `vc: Update Commit (N)` | `vc update-commit <N>` | 최근 N개 커밋 추적 (개수 입력) |
+| `vc: List Units` | `vc list-units` | 미완료 유닛 목록 |
+| `vc: Validate` | `vc validate` | 설정 파일 무결성 검증 |
+| `vc: Context (JSON)` | `vc context <unitId> --json` | 읽기 전용 컨텍스트 조회 |
+
+유닛 ID가 필요한 Task는 VS Code 입력 대화상자(`${input:unitId}`)를 통해 프롬프트됩니다.
+
+### 권장 키보드 단축키
+
+Task는 단축키 없이도 Command Palette에서 사용 가능하지만, 자주 사용하는 Task에 키를 바인딩하면 더 빠르게 접근할 수 있습니다. `keybindings.json`에 추가하세요 (`Ctrl+Shift+P` → **기본 설정: 바로 가기 키 열기 (JSON)**):
+
+```json
+[
+  {
+    "key": "ctrl+shift+u",
+    "command": "workbench.action.tasks.runTask",
+    "args": "vc: Set Unit"
+  },
+  {
+    "key": "ctrl+shift+alt+u",
+    "command": "workbench.action.tasks.runTask",
+    "args": "vc: Set Unit (Dry Run)"
+  },
+  {
+    "key": "ctrl+shift+k",
+    "command": "workbench.action.tasks.runTask",
+    "args": "vc: Update Commit (HEAD)"
+  },
+  {
+    "key": "ctrl+shift+l",
+    "command": "workbench.action.tasks.runTask",
+    "args": "vc: List Units"
+  }
+]
+```
+
+> **참고**: 키보드 단축키는 사용자 레벨 설정이며 다른 확장과 충돌할 수 있습니다. 선호에 따라 키 조합을 조정하세요.
+
+## 설정 (Configuration)
+
+vibe-commander는 `vibe-commander.config.json`을 통해 어떤 프로젝트에든 적응합니다. 설정 파일은 유닛 ID 패턴, 문서 경로, 파싱 규칙, 커맨드 파일 구조를 정의합니다.
+
+### 최소 설정
+
+```json
+{
+  "$schema": "https://vibe-commander/config-schema.json",
+  "version": 1,
+  "paths": {
+    "commands": "docs/commands.md",
+    "roadmap": "docs/roadmap.md",
+    "docRoots": {
+      "plan": "docs/plans",
+      "result": "docs/results"
+    }
+  },
+  "unitTypes": [
+    {
+      "key": "feature",
+      "displayName": "Feature",
+      "idPattern": "^FEAT-\\d+$",
+      "planDir": "plan",
+      "commandSection": "# Current Feature",
+      "collectDeps": true,
+      "headerTemplate": "### Feature: {{title}}\n- Plan: @{{planPath}}\n- Commit: -"
+    }
+  ]
+}
+```
+
+### 설정 섹션
+
+| 섹션 | 목적 |
+|------|------|
+| `paths` | 문서 디렉토리, 커맨드 파일, 로드맵 위치 |
+| `unitTypes` | ID 패턴, 템플릿, 동작 방식을 포함한 유닛 유형 정의 |
+| `docDiscovery` | 각 역할(plan, result, runbook)별 문서 탐색 방법 |
+| `planParsing` | 계획서에서 제목, 의존성, 페어링 질문 추출 방법 |
+| `backlogParsing` | `list-units`용 로드맵/백로그 파싱 방법 |
+| `commitSearch` | Git 커밋 검색 전략 및 필터 |
+| `commandSections` | 커맨드 파일 섹션 구분자 및 마커 설정 |
+| `defaultSpecialRequests` | 모든 유닛에 추가되는 기본 지시사항 |
+| `specialRequestsByType` | 유형별 추가 지시사항 |
+| `customRequests` | `--request <key>`로 선택 가능한 이름 있는 요청 템플릿 |
+
+### 자동 감지 (Auto-Detection)
+
+기존 프로젝트의 경우, `vc init --from-existing`이 파일 트리를 스캔하여 감지합니다:
+
+- 유닛 ID 패턴 (파일명에서 추출)
+- 문서 디렉토리 구조
+- 커맨드 파일의 섹션 헤더
+- 로드맵 형식
+
+### 템플릿 변수
+
+`headerTemplate`과 `docDiscovery`의 템플릿에서 사용 가능한 변수:
+
+| 변수 | 설명 | 예시 |
+|------|------|------|
+| `{{unitId}}` | 원본 유닛 ID | `U-042[Mvp]` |
+| `{{shortId}}` | 단계(phase) 제거 | `U-042` |
+| `{{bareId}}` | 숫자만 | `042` |
+| `{{title}}` | 전체 제목 (ID 포함) | `U-042[Mvp]: Add auth module` |
+| `{{titleOnly}}` | ID 없는 제목 | `Add auth module` |
+| `{{planPath}}` | 상대 계획서 경로 | `docs/plans/U-042[Mvp].md` |
+| `{{phase}}` | 단계 문자열 | `Mvp` |
+| `{{slug}}` | 케밥 케이스(kebab-case) | `u-042-mvp` |
+
+## 아키텍처
+
+vibe-commander는 엄격한 의존성 방향을 가진 **4-레이어 아키텍처**를 따릅니다:
+
+```
+Layer 4: 소비자(Consumers)  ← 사람, AI 에이전트, 오케스트레이터
+Layer 3: 어댑터(Adapters)   ← CLI, SKILL 파일, stdin/stdout 파이프
+Layer 2: 리졸버(Resolver)   ← 설정 기반 프로젝트 구조 해석
+Layer 1: 코어(Core)         ← 순수 함수 (부수효과 없음, I/O 없음)
+```
+
+- **코어(Core)** 함수는 순수합니다: JSON 입력, JSON 출력. `fs`도 `child_process`도 사용하지 않습니다.
+- **리졸버(Resolver)**는 코드가 아닌 설정을 통해 프로젝트별 차이를 흡수합니다.
+- **어댑터(Adapters)**가 모든 I/O를 처리합니다 — 파일 읽기, Git 명령, 사용자 상호작용.
+- **프로덕션 의존성은 단 1개**: 런타임 검증을 위한 [Zod](https://v4.zod.dev/).
+
+## 소스에서 빌드하기 (Building from Source)
+
+### 사전 요구사항 (Prerequisites)
+
+- **Node.js** >= 24.0.0 (LTS) — [다운로드](https://nodejs.org/)
+- **npm** >= 11 (Node.js 24에 포함)
+- **Git** — [다운로드](https://git-scm.com/)
+- **Windows**: 릴리스 스크립트 실행 시 Git Bash 또는 WSL 권장
+
+환경 확인:
+
+```bash
+node -v   # 기대값: v24.x.x
+npm -v    # 기대값: 11.x.x
+```
+
+### 빌드 단계
+
+```bash
+# 저장소 클론
+git clone https://github.com/viilab/vibe-commander.git
+cd vibe-commander
+
+# 의존성 설치
+npm install
+
+# TypeScript 빌드 → dist/
+npm run build
+```
+
+빌드 결과물은 `dist/` 디렉토리에 컴파일된 JavaScript(`.js`)와 TypeScript 선언(`.d.ts`) 파일로 생성됩니다.
+
+### 로컬 테스트
+
+```bash
+# 로컬 테스트를 위해 글로벌 등록
+npm link
+
+# CLI 동작 확인
+vc --help
+vc --version
+
+# 완료 후 해제
+npm unlink -g vibe-commander
+```
+
+> **Windows 참고**: `npm link`는 관리자 권한이 필요할 수 있습니다. 대안으로 개발 중에는 `npx tsx src/adapters/cli/index.ts -- --help`를 사용할 수 있습니다.
+
+### 클린 빌드
+
+```bash
+# 이전 빌드 산출물 삭제 후 재빌드
+rm -rf dist
+npm run build
+```
+
+### PR 제출 전 체크리스트
+
+풀 리퀘스트를 제출하기 전에 전체 품질 게이트를 통과하는지 확인합니다:
+
+```bash
+npm run check
+```
+
+타입체크 → 린트 → 포맷 검사 → 테스트 순서로 실행되며, 네 단계 모두 통과해야 합니다.
+
+### 패키지 구성물 (Package Contents)
+
+npm 패키지에 포함되는 파일과 디렉토리:
+
+| 경로 | 설명 |
+|------|------|
+| `dist/` | 컴파일된 JavaScript 및 TypeScript 선언 파일 |
+| `skills/` | AI 에이전트용 SKILL 파일 (Cursor, Claude Code) |
+| `schemas/` | 설정 검증 및 IDE 자동완성을 위한 JSON Schema |
+| `examples/` | 예제 설정 파일 (Tauri, Next.js, Python) 및 VS Code Tasks 템플릿 |
+| `AGENTS.md` | 에이전트 빠른 참조 (패키지에 번들됨) |
+| `README.md` | 영문 문서 |
+| `README.ko.md` | 한국어 문서 |
+| `LICENSE` | MIT 라이선스 |
+
+패키지 구성물을 로컬에서 확인하려면:
+
+```bash
+npm pack --dry-run
+```
+
+## 기여하기
+
+### 개발 환경 설정
+
+[소스에서 빌드하기](#소스에서-빌드하기-building-from-source) 섹션의 사전 요구사항을 확인한 후:
+
+```bash
+git clone https://github.com/viilab/vibe-commander.git
+cd vibe-commander
+npm install
+```
+
+### 사용 가능한 스크립트
+
+```bash
+npm run dev           # tsx로 개발 실행
+npm run build         # TypeScript 빌드
+npm run test          # Vitest 테스트 실행
+npm run test:watch    # Vitest 감시 모드
+npm run test:coverage # 테스트 커버리지 리포트
+npm run lint          # ESLint 정적 분석
+npm run lint:fix      # ESLint 자동 수정
+npm run typecheck     # TypeScript 타입 체크
+npm run format        # Prettier 포매팅
+npm run format:check  # Prettier 포맷 검사 (수정 없이)
+npm run check         # 전체 품질 게이트 (타입체크 + 린트 + 포맷 + 테스트)
+```
+
+### 릴리스 절차
+
+릴리스는 npm 라이프사이클 훅(lifecycle hooks)을 사용하여 안전하고 자동화된 파이프라인으로 진행됩니다:
+
+```bash
+# 드라이 런 — 게시 없이 모든 검증 통과 확인
+npm run release:dry
+
+# 패치 릴리스 (0.2.0 → 0.2.1)
+npm run release:patch
+
+# 마이너 릴리스 (0.2.0 → 0.3.0)
+npm run release:minor
+
+# 메이저 릴리스 (0.2.0 → 1.0.0)
+npm run release:major
+```
+
+각 릴리스 명령은 자동으로:
+1. 커밋되지 않은 변경 사항 확인
+2. 전체 품질 게이트 실행 (`타입체크 + 린트 + 포맷 + 테스트`)
+3. 버전 범프 및 Git 태그 생성
+4. TypeScript 출력 빌드
+5. npm에 게시
+6. 버전 커밋과 태그를 Git에 푸시
+
+**버전 전략(Version Strategy)**은 [유의적 버전(Semantic Versioning)](https://semver.org/)을 따릅니다:
+
+| 변경 유형 | 버전 범프 | 예시 |
+|-----------|----------|------|
+| 버그 수정, 문서 | Patch | `0.2.0` → `0.2.1` |
+| 새 기능 (하위 호환) | Minor | `0.2.0` → `0.3.0` |
+| 호환성 깨지는 변경 | Major | `0.2.0` → `1.0.0` |
+
+**릴리스 전 체크리스트**:
+1. npm 레지스트리 로그인 확인: `npm whoami`
+2. 전체 품질 게이트 통과: `npm run check`
+3. 빌드 성공: `npm run build`
+4. `README.md`와 `README.ko.md` 동기화 완료
+5. 패키지 구성물 확인: `npm pack --dry-run`
+
+**npm 로그인** — 최초 게시 전 또는 인증 토큰이 만료되었을 때 필요합니다:
+
+```bash
+# 로그인 (브라우저 인증 또는 자격 증명 입력)
+npm login
+
+# 로그인 확인
+npm whoami
+```
+
+**게시 실패 복구** — 릴리스 명령이 버전 범프와 git push까지 성공했지만 `npm publish`에서 실패한 경우(예: 401/404 에러), 버전이 이미 git에 태그되어 있으므로 범프 없이 게시만 재시도합니다:
+
+```bash
+npm publish --access public
+```
+
+### 문서 동기화
+
+이 프로젝트는 두 개의 README 파일을 유지합니다: `README.md` (영문)와 `README.ko.md` (한국어). 문서를 업데이트할 때 양쪽 버전을 동기화해 주세요. 영문 버전이 npm 패키지 페이지의 기준(source of truth)입니다.
+
+### 프로젝트 원칙
+
+- **설정 기반 범용성** — 프로젝트별 차이는 설정으로 흡수하며, 절대 하드코딩하지 않습니다
+- **순수 함수 코어** — Layer 1은 부수효과가 없습니다 (JSON 입력 → JSON 출력)
+- **점진적 기능(Graceful Degradation)** — 로드맵이 없어도 `set-unit`은 동작합니다. 런북이 없어도 나머지 문서는 수집됩니다.
+- **최소 의존성** — 프로덕션 의존성은 1개(Zod). 나머지는 모두 Node.js 내장 모듈을 사용합니다.
+- **에이전트 부품화** — CLI, SKILL 파일, stdin/stdout 파이프가 사람, 에이전트, 오케스트레이터를 동등하게 지원합니다.
+
+## 라이선스
+
+[MIT](LICENSE) © [viilab](https://github.com/viilab)