vibe-commander 0.1.0

package/skills/cursor/SKILL.md

@@ -0,0 +1,353 @@
+---
+name: vibe-commander
+description: vibe-commander CLI(vc)를 활용하여 유닛 기반 워크플로우를 자동화합니다. 유닛 전환, 커밋 추적, 컨텍스트 수집, 설정 검증 요청 시 사용합니다.
+metadata:
+  version: 1.0.0
+  category: workflow-automation
+  tags: [vc, vibe-commander, unit, set-unit, update-commit, list-units, context, validate, init, workflow, 유닛, 커맨드]
+---
+
+# vibe-commander CLI 사용 가이드
+
+vibe-commander(`vc`)는 유닛 기반 바이브 코딩 워크플로우를 자동화하는 CLI 도구입니다.
+유닛 ID 하나로 커맨드 파일 섹션을 자동 생성하여, 에이전트의 컨텍스트 준비 시간을 단축합니다.
+
+## Instructions (Synced from skills/common/cli-reference.md)
+
+### Step 1: 프로젝트 설정 확인
+
+작업 시작 전, 프로젝트 루트에 `vibe-commander.config.json`이 있는지 확인합니다.
+
+```bash
+vc validate
+```
+
+설정이 없으면 초기화합니다:
+
+```bash
+vc init --from-existing    # 기존 파일 스캔으로 자동 감지
+vc init                    # 대화형으로 직접 입력
+```
+
+### Step 2: 유닛 전환 워크플로우
+
+에이전트가 유닛 작업을 수행할 때의 표준 흐름:
+
+```
+1. vc list-units              → 착수 가능 유닛 확인
+2. vc set-unit <unitId>       → 커맨드 파일 자동 구성
+3. (에이전트가 코드 작업 수행)
+4. vc update-commit           → HEAD 커밋 SHA 자동 추적
+5. vc set-unit <nextUnitId>   → 다음 유닛 전환
+```
+
+### Step 3: 컨텍스트 조회 (읽기 전용)
+
+커맨드 파일을 수정하지 않고 유닛 정보만 확인할 때:
+
+```bash
+vc context <unitId> --json
+```
+
+## CLI 레퍼런스
+
+### `vc set-unit <unitId>` — 현재 작업 유닛 설정
+
+커맨드 파일의 해당 섹션을 자동으로 구성합니다.
+
+```bash
+vc set-unit "U-013[Mvp]"
+vc set-unit "U-013[Mvp]" --request mcp-nanobanana,doc-update
+vc set-unit "U-013[Mvp]" --no-prompt    # 페어링 질문 프롬프트 비활성화
+vc set-unit "U-013[Mvp]" --json         # JSON ToolResult 출력
+```
+
+**동작**: 유닛 ID → 유형 자동 매칭 → 계획서 파싱 → 의존성 문서/커밋 수집 → 커맨드 파일 섹션 교체
+
+**옵션**:
+| 옵션 | 설명 |
+|------|------|
+| `--request <key1,key2>` | `customRequests`에서 키로 특별 요청사항 선택 |
+| `--no-prompt` | 페어링 질문 인터랙티브 프롬프트 비활성화 |
+| `--json` | JSON ToolResult 구조로 출력 |
+| `--stdin` | stdin에서 JSON 입력 (`{"unitId":"..."}`) |
+
+### `vc update-commit [sha|N]` — 커밋 SHA 업데이트
+
+```bash
+vc update-commit              # HEAD SHA 자동 감지
+vc update-commit 3            # 최근 3개 커밋 SHA
+vc update-commit abc1234      # 특정 SHA 지정
+vc update-commit abc1234 --mode append  # 기존 값에 추가
+```
+
+**옵션**:
+| 옵션 | 설명 |
+|------|------|
+| `--mode replace\|append` | 값 교체(기본) 또는 기존 값에 추가 |
+| `--section <name>` | 대상 섹션 지정 (미지정 시 자동 감지) |
+
+### `vc list-units` — 미완료 유닛 목록
+
+```bash
+vc list-units                 # 전체 미완료 유닛
+vc list-units --phase Mvp     # 특정 phase 필터
+vc list-units --json          # JSON 출력
+```
+
+**출력 분류**: `ready`(착수 가능), `inProgress`(진행중), `blocked`(의존성 미충족)
+
+### `vc context <unitId>` — 유닛 컨텍스트 조회
+
+`set-unit`과 동일한 파싱을 수행하되, 커맨드 파일을 수정하지 않습니다.
+
+```bash
+vc context "U-013[Mvp]" --json
+```
+
+### `vc validate` — 설정 검증
+
+설정 파일의 스키마, 경로 존재, 정규식 유효성, 패턴 충돌을 4단계로 검증합니다.
+
+```bash
+vc validate           # 사람용 포맷 리포트
+vc validate --json    # JSON ToolResult
+```
+
+### `vc init` — 프로젝트 초기화
+
+```bash
+vc init                    # 대화형 설정 생성
+vc init --from-existing    # 기존 .md 파일 스캔 → 패턴 자동 감지 → 설정 생성
+```
+
+`--from-existing`은 기존 설정이 있으면 커스텀 필드를 보존하며 병합합니다.
+
+### 파이프 모드 (에이전트/오케스트레이터 연동)
+
+모든 명령어에 `--json`과 `--stdin`을 조합하여 프로그래밍 방식으로 사용할 수 있습니다.
+
+```bash
+echo '{"unitId":"U-013[Mvp]"}' | vc set-unit --stdin --json
+echo '{"count":3}' | vc update-commit --stdin --json
+echo '{}' | vc list-units --stdin --json
+echo '{"unitId":"U-013[Mvp]"}' | vc context --stdin --json
+```
+
+**출력 규약**:
+- `stdout`: JSON ToolResult만 출력 (파이프라인 호환)
+- `stderr`: 로그, 경고, 에러 메시지
+
+## Rules
+
+### 에이전트 워크플로우에서의 사용 패턴
+
+**Do ✅ — 유닛 시작 시**:
+
+1. `vc set-unit <unitId> --json --no-prompt`으로 커맨드 파일 구성
+2. 반환된 JSON에서 `pairingQuestions` 확인 → 미결정 항목이 있으면 사용자에게 전달
+3. `docsFound`의 의존성 문서를 `@` 참조로 컨텍스트에 포함
+
+**Do ✅ — 커밋 후**:
+
+1. `vc update-commit`으로 HEAD SHA 자동 업데이트
+2. 여러 커밋이 누적되었으면 `vc update-commit N`으로 최근 N개 수집
+
+**Do ✅ — 다음 유닛 확인 시**:
+
+1. `vc list-units --json`으로 착수 가능 유닛 목록 확인
+2. `ready` 목록에서 사용자가 선택한 유닛으로 `vc set-unit` 실행
+
+**Don't ❌**:
+
+- 커맨드 파일을 직접 편집하여 유닛 정보 삽입 (반드시 `vc set-unit` 사용)
+- `--json` 없이 파이프라인에서 사용 (stdout에 사람용 포맷 출력됨)
+- 유효하지 않은 유닛 ID로 `set-unit` 호출 (설정의 `idPattern`에 매칭되어야 함)
+
+### ToolResult 응답 처리
+
+모든 `--json` 출력은 아래 구조를 따릅니다:
+
+```json
+{
+  "success": true,
+  "data": { /* 명령어별 결과 데이터 */ }
+}
+```
+
+실패 시:
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "PLAN_NOT_FOUND",
+    "message": "계획서를 찾을 수 없음: vibe/unit-plans/U-999.md"
+  }
+}
+```
+
+주요 에러 코드:
+| 코드 | 의미 |
+|------|------|
+| `CONFIG_NOT_FOUND` | 설정 파일 없음 → `vc init` 실행 |
+| `CONFIG_INVALID` | 설정 파일 스키마 오류 → `vc validate`로 확인 |
+| `PLAN_NOT_FOUND` | 계획서 파일 없음 → 경로 확인 |
+| `UNIT_TYPE_NOT_FOUND` | ID가 어떤 unitType에도 매칭 안 됨 → 설정의 idPattern 확인 |
+| `COMMANDS_FILE_NOT_FOUND` | 커맨드 파일 없음 → `paths.commands` 경로 확인 |
+| `ROADMAP_NOT_CONFIGURED` | 로드맵 미설정 → `paths.roadmap` 설정 필요 |
+
+## 설정 파일 가이드
+
+### 최소 필수 구조
+
+```jsonc
+{
+  "version": 1,
+  "paths": {
+    "commands": "vibe/commands.md",      // 커맨드 파일 경로 (필수)
+    "roadmap": "vibe/roadmap.md",        // null이면 list-units 비활성화
+    "docRoots": {
+      "plan": "vibe/unit-plans",         // 계획서 디렉토리
+      "result": "vibe/unit-results"      // 결과 보고서 디렉토리
+    }
+  },
+  "unitTypes": [
+    {
+      "key": "implement",
+      "idPattern": "^(U-\\d+|CP-).*",   // 정규식으로 유닛 ID 매칭
+      "planDir": "plan",                  // docRoots 키 참조
+      "commandSection": "# 유닛 구현",   // 커맨드 파일 섹션 헤더
+      "collectDeps": true,               // 의존성 수집 여부
+      "headerTemplate": "### 현재 구현 유닛: {{title}}\n- 계획서: @{{planPath}}"
+    }
+  ],
+  "docDiscovery": {
+    "plan": { "pattern": "{{unitId}}.md" },
+    "result": { "pattern": "{{unitId}}.md" }
+  },
+  "planParsing": {
+    "titleSource": "h1",
+    "dependsSource": "section",
+    "dependsSectionName": "이전 작업에서 가져올 것",
+    "pairingQuestionSection": "페어링 질문"
+  }
+}
+```
+
+### 템플릿 변수
+
+`headerTemplate`에서 사용 가능한 변수:
+
+| 변수 | 설명 | 예시 |
+|------|------|------|
+| `{{unitId}}` | 원본 유닛 ID | `U-118[Mmp]` |
+| `{{shortId}}` | phase 제거 | `U-118` |
+| `{{title}}` | 전체 제목 (ID 포함) | `U-118[Mmp]: 마크다운 이미지 링크 삽입` |
+| `{{titleOnly}}` | 제목만 (ID 제외) | `마크다운 이미지 링크 삽입` |
+| `{{planPath}}` | 계획서 상대 경로 | `vibe/unit-plans/U-118[Mmp].md` |
+| `{{phase}}` | phase 문자열 | `Mmp` |
+
+### 유닛 유형 우선순위
+
+`unitTypes` 배열 순서가 매칭 우선순위입니다. 더 구체적인 패턴을 앞에 배치하세요.
+
+```jsonc
+"unitTypes": [
+  { "key": "refactor-sub", "idPattern": "^RU-\\d+-[A-Z]\\d+$" },  // 구체적 → 먼저
+  { "key": "implement",    "idPattern": "^(U-\\d+|CP-).*" },       // 일반적 → 나중
+  { "key": "refactor",     "idPattern": "^RU-\\d+\\[.*\\]$" }
+]
+```
+
+## Cursor 통합
+
+### SKILL 설치 위치
+
+이 SKILL 파일은 `vc skill install --cursor` 실행 시 아래 경로에 자동 설치됩니다:
+
+```
+.cursor/skills/vibe-commander/SKILL.md
+```
+
+### .cursor/rules 연동
+
+프로젝트에 `.cursor/rules/` 디렉토리가 있다면, vibe-commander 관련 규칙 파일을 추가하여
+에이전트가 자동으로 `vc` CLI를 활용하도록 설정할 수 있습니다.
+
+```yaml
+# .cursor/rules/vc-workflow.mdc
+---
+description: vibe-commander 워크플로우 자동화
+applyTo: "**/vibe/commands*.md"
+---
+유닛 전환 시 `vc set-unit` 명령어를 사용하고, 커밋 후 `vc update-commit`을 실행하세요.
+```
+
+### 파일 참조 패턴
+
+Cursor에서는 `@` 기호로 파일을 참조합니다. `vc set-unit` 결과의 의존성 문서 경로를
+`@` 참조로 에이전트 컨텍스트에 포함할 수 있습니다:
+
+```
+@vibe/unit-plans/U-117[Mmp].md
+@vibe/unit-results/U-117[Mmp].md
+```
+
+## Examples
+
+### Example 1: 새 유닛 작업 시작
+
+사용자가 "U-112[Mmp] 유닛 구현해줘"라고 요청한 경우:
+
+1. `vc set-unit "U-112[Mmp]" --json --no-prompt` 실행
+2. 커맨드 파일이 자동 구성됨 — 계획서, 의존성 문서, 커밋 SHA 포함
+3. 반환된 JSON의 `planPath`에서 계획서를 읽어 작업 시작
+4. 작업 중 커밋 발생 시 `vc update-commit` 실행
+
+### Example 2: 다음 착수 가능 유닛 확인
+
+사용자가 "다음에 뭐 하면 돼?"라고 질문한 경우:
+
+1. `vc list-units --json` 실행
+2. `ready` 목록에서 착수 가능 유닛 제시
+3. 사용자가 선택하면 `vc set-unit` 실행
+
+### Example 3: 파이프라인 연동
+
+오케스트레이터가 JSON 파이프로 유닛을 설정하는 경우:
+
+```bash
+echo '{"unitId":"U-013[Mvp]"}' | vc set-unit --stdin --json
+```
+
+결과를 파싱하여 에이전트에 컨텍스트를 주입합니다.
+
+## Troubleshooting
+
+### Error: CONFIG_NOT_FOUND
+**원인**: 프로젝트 루트에 `vibe-commander.config.json`이 없음
+**해결**: `vc init` 또는 `vc init --from-existing` 실행
+
+### Error: UNIT_TYPE_NOT_FOUND
+**원인**: 입력한 유닛 ID가 설정의 어떤 `idPattern`에도 매칭되지 않음
+**해결**: `vibe-commander.config.json`의 `unitTypes[].idPattern` 정규식 확인. `vc validate`로 패턴 충돌 여부 점검
+
+### Error: PLAN_NOT_FOUND
+**원인**: 해당 유닛의 계획서 파일이 `docRoots.plan` 디렉토리에 없음
+**해결**: 계획서 파일명이 `docDiscovery.plan.pattern`과 일치하는지 확인 (기본: `{{unitId}}.md`)
+
+### Error: COMMANDS_FILE_NOT_FOUND
+**원인**: `paths.commands`에 지정된 커맨드 파일이 없음
+**해결**: 파일을 생성하거나 `paths.commands` 경로 수정
+
+### Error: set-unit 후 섹션이 갱신되지 않음
+**원인**: 커맨드 파일에 HTML 주석 마커(`<!-- vc:begin:key -->`)가 없거나 섹션 헤더 불일치
+**해결**: `commandSections.useMarkers: true`이면 마커 존재 확인. 마커가 없으면 `commandSection` 헤더 텍스트가 정확한지 확인
+
+## References
+
+- CLI 도움말: `vc --help`
+- 설정 파일 예시: 프로젝트 루트의 `vibe-commander.config.json`
+- PRD: `vibe/prd.md` §6 기능 명세, §7.2 SKILL 파일 인터페이스
+- 아키텍처: `vibe/architecture.md`