lee-spec-kit 0.7.4 → 0.7.7

package/README.md

@@ -7,7 +7,7 @@
 </div>
 
 <p align="center">
-  <strong>AI 에이전트 기반 개발을 위한 프로젝트 문서 구조 생성 CLI</strong>
+  <strong>AI 에이전트 기반 개발을 위한 오케스트레이션 하네스 CLI</strong>
 </p>
 
 <p align="center">
@@ -18,9 +18,9 @@
 
 <p align="center">
   <a href="#quick-start">Quick Start</a> •
-  <a href="#주요-기능">주요 기능</a> •
-  <a href="#사용법">사용법</a> •
-  <a href="#생성되는-구조">생성되는 구조</a>
+  <a href="#이-cli가-하는-일">Why</a> •
+  <a href="#에이전트가-주로-실행하는-명령">Commands</a> •
+  <a href="#docs">Docs</a>
 </p>
 
 <p align="center">
@@ -34,921 +34,87 @@
 
 ---
 
-## 목차
-
-- [Quick Start](#quick-start)
-- [신규 프로젝트 시작 순서](#신규-프로젝트-시작-순서)
-- [에이전트 킥오프 프롬프트](#에이전트-킥오프-프롬프트)
-- [주요 기능](#주요-기능)
-- [사용법](#사용법)
-- [설정 파일](#설정-파일)
-- [오류 코드](#오류-코드)
-- [생성되는 구조](#생성되는-구조)
-- [Feature 워크플로우](#feature-워크플로우)
-- [문제 해결](#문제-해결)
-- [기여하기](#기여하기)
-- [라이선스](#라이선스)
-
 ## Quick Start
 
+대부분의 경우 사용자는 자연어로 요청하고, 메인 에이전트가 아래 흐름을 실행합니다.
+
 ```bash
-# 1. 프로젝트 문서 구조 생성
 npx lee-spec-kit init
-
-# 2. Codex 사용 시 bootstrap 1회 설치 (repo-root AGENTS.md 없이 운영할 때)
-npx lee-spec-kit setup codex-bootstrap
-
-# 3. 초기 온보딩 점검
-npx lee-spec-kit onboard --strict
-
-# 4. 새 기능 생성
+npx lee-spec-kit idea improve-auth-flow
 npx lee-spec-kit feature user-auth
-
-# 5. 진행 상황 및 다음 단계 확인 (AI 에이전트용)
 npx lee-spec-kit context
+npx lee-spec-kit flow
+```
 
-# 6. 워크플로우 대시보드 확인
-npx lee-spec-kit view
+## 왜 만들었나
 
-# 7. 전체 상태 확인
-npx lee-spec-kit status
+이 CLI는 AI 에이전트와 함께 프로젝트를 진행할 때 spec-driven development 기반의 흐름을 더 일관되게 만들기 위해 만들어졌습니다.
+목표는 단순히 문서 폴더를 생성하는 것이 아니라, 프로젝트가 어떤 요구사항에서 출발했고 어떤 아이디어를 거쳐 어떤 구현 단위로 내려왔는지를
+에이전트와 사람이 함께 추적할 수 있게 만드는 것입니다.
 
-# 8. 문서/Feature 진단
-npx lee-spec-kit doctor
-```
+이를 위해 `lee-spec-kit`는 `PRD → idea → feature` 단계로 작업을 구조화하고, 실제 구현과 협업 흐름에서는 git 기반의 issue/PR 구조를 자연스럽게 연결하도록 설계되었습니다.
+즉, 문서 작성 단계와 코드 변경 단계가 따로 놀지 않도록, 에이전트가 읽을 수 있는 상태와 사람이 리뷰할 수 있는 상태를 같은 흐름 안에 두는 데 초점을 둡니다.
 
-## 신규 프로젝트 시작 순서
+여기서 PRD는 `init`이 만들어 주는 `docs/prd/`에서 직접 관리하는 상위 요구사항 공간입니다.
+Idea는 그 요구사항에서 나온 후보와 실험을 정리하는 단계이고, Feature는 그중 실제로 실행하기로 한 단위를
+`spec.md`, `plan.md`, `tasks.md`로 내려서 관리하는 단계입니다.
 
-신규 프로젝트에서는 **코드 스캐폴딩을 먼저** 하고, 그 다음 docs를 초기화하세요.
-대부분의 사용자(기본값: embedded)는 프로젝트 루트에서 `npx lee-spec-kit init`만 실행하면 됩니다.
+구조적으로는 [spec-kit](https://github.com/github/spec-kit)과 [OpenSpec](https://github.com/Fission-AI/OpenSpec)의 접근을 참고했지만,
+`lee-spec-kit`는 실제 프로젝트 진행 방식과 에이전트 오케스트레이션에 맞게 더 실무적인 문서 단계, feature 단위, 그리고 git workflow 연결을 강조하도록 재구성되었습니다.
 
-```bash
-# 0. 코드 프로젝트 생성/초기화 (예: Next.js)
-npx create-next-app@latest my-app
-cd my-app
+## 이 CLI가 하는 일
 
-# 1. docs 구조 초기화
-npx lee-spec-kit init
+`lee-spec-kit`는 사람이 매번 세부 명령을 직접 치는 도구라기보다,
+메인 에이전트가 현재 상태를 읽고 다음 액션을 고르도록 돕는 개발 하네스입니다.
 
-# 2. Codex 사용 시 bootstrap 1회 설치 (repo-root AGENTS.md 없이 운영할 때)
-npx lee-spec-kit setup codex-bootstrap
+- 사람은 보통 자연어로 요청합니다.
+- 메인 에이전트는 그 요청을 `detect`, `context`, `flow`, `idea`, `feature` 같은 명령으로 번역해 실행합니다.
+- 더 깊은 운영 명령은 여전히 지원되지만 기본 help에는 전면 노출하지 않습니다.
 
-# 3. 초기 온보딩 점검
-npx lee-spec-kit onboard --strict
+## 어떻게 동작하나
 
-# 4. 감지 확인 (에이전트 시작점)
-npx lee-spec-kit detect --json
+1. `init`으로 docs/workflow 구조를 붙입니다.
+2. `docs/prd/`에서 상위 요구사항을 정리합니다.
+3. `idea`로 후보/실험을 정리하거나, 바로 `feature`로 실행 단위를 만듭니다.
+4. 메인 에이전트가 `detect`와 `context`를 읽고 진행합니다.
+5. 사람은 승인, 예외 처리, 방향 수정 시점에 개입합니다.
+6. 현재 다음 액션과 승인 대기 상태는 `context`, 전체 상태 요약은 `flow`로 확인합니다.
 
-# 5. Feature 생성 후 작업 시작
-npx lee-spec-kit feature user-auth
-npx lee-spec-kit context --json-compact
-```
+## 사람은 보통 이렇게 요청합니다
 
-- Codex에서 프로젝트 루트 `AGENTS.md` 없이 운영한다면 `setup codex-bootstrap`를 1회 실행하세요. 이 명령은 `~/.codex/config.toml`에 `docs/AGENTS.md` fallback과 compact 재확인용 managed block을 추가합니다.
-- `detect --json` 결과가 `isLeeSpecKitProject: true`일 때 lee-spec-kit 워크플로우를 적용하세요.
-- `isLeeSpecKitProject: false`면 일반 프로젝트 워크플로우로 진행하세요.
+- "이 문서 읽고 프로젝트 구조 시작하려고 해."
+- "이 요구사항 기준으로 idea 정리해줘."
+- "이 idea를 feature로 올려서 진행해줘."
+- "지금 다음 액션이 뭐야?"
+- "전체 상태 한번 점검해줘."
 
-docs를 코드 저장소와 분리해 운영하는 팀(standalone)은 **상위 워크스페이스 폴더**를 기준으로 시작하는 것을 권장합니다.
+## 에이전트가 주로 실행하는 명령
 
-```bash
-# 권장 레이아웃:
-# workspace/
-#   ├─ docs/      (lee-spec-kit 문서)
-#   └─ project/   (실제 코드 저장소)
-#
-# workspace 루트에서 실행
-npx lee-spec-kit init --docs-repo standalone --dir ./docs --project-root ./project
-npx lee-spec-kit detect --json
-```
+- `init`: docs/workflow 구조를 초기화합니다.
+- `idea`: 구현 전 아이디어 문서를 생성합니다.
+- `feature`: 실제 작업 단위를 생성합니다.
+- `detect`: 현재 워크스페이스가 lee-spec-kit 프로젝트인지 감지합니다.
+- `context`: 현재 feature 상태와 다음 액션을 읽습니다.
+- `flow`: 전체 워크플로우 상태를 요약합니다.
 
 ## 에이전트 킥오프 프롬프트
 
-아래 프롬프트를 에이전트 시작 메시지로 그대로 사용할 수 있습니다.
-
 ```text
 작업 시작 절차:
 1) npx lee-spec-kit detect --json
-2) isLeeSpecKitProject === true 이면 npx lee-spec-kit context --json-compact 실행 (필요 시 --json으로 상세 조회)
-3) approvalRequest.required=true 이면 approvalRequest.userFacingLines를 그대로 사용자에게 제시하고 승인(<LABEL> 또는 <LABEL> OK) 대기
+2) isLeeSpecKitProject === true 이면 npx lee-spec-kit context --json-compact 실행
+3) approvalRequest.required=true 이면 approvalRequest.userFacingLines를 그대로 사용자에게 제시하고 승인 대기
 4) 승인 전에는 실행하지 말고, requiresUserCheck=true 액션은 승인 후에만 실행
 5) isLeeSpecKitProject === false 이면 lee-spec-kit 전용 절차를 건너뛰고 일반 워크플로우로 진행
 ```
 
-## 주요 기능
-
-### 📁 프로젝트 초기화
-
-- 대화형 모드 또는 CLI 옵션으로 프로젝트 설정
-- 기본값은 Multi이며, Single도 단순 단일 레포/기존 호환 시나리오를 위해 지원합니다. (`fullstack`는 `multi` 하위호환 alias)
-- 한국어/영어 템플릿 선택
-
-### 🚀 Feature 생성
-
-- spec.md, plan.md, tasks.md, decisions.md 자동 생성
-- Multi 프로젝트에서 임의 컴포넌트(app/api/worker 등) 분리 지원
-- GitHub Issue/PR 템플릿 연동
-
-### 📊 상태 관리
-
-- 전체 Feature 진행 상태 한눈에 확인
-- 터미널 출력 또는 마크다운 파일로 저장
-
-### 👀 View 대시보드
-
-- Context 기반 워크플로우 현황을 한 번에 확인
-- 단일 Feature/전체 Feature 모두 조회 가능
-
-### 🔁 Flow 오케스트레이션
-
-- `context + status + doctor`를 한 번에 실행/요약
-- 승인/실행 옵션을 그대로 전달해 원자 액션 자동화 가능
-
-### 🩺 문서 진단 (Doctor)
-
-- docs 구조/설정/Feature 메타데이터를 점검하여 잠재 문제를 빠르게 탐지
-- `--json` 출력으로 에이전트 파이프라인에 쉽게 연동
-
-### 🔄 자동 업데이트
-
-- 최신 버전 체크 및 템플릿 업데이트 지원
-
-## 사용법
-
-### 프로젝트 초기화
-
-```bash
-# 대화형 모드
-npx lee-spec-kit init
-
-# 옵션 지정
-npx lee-spec-kit init --name my-project --type multi
-npx lee-spec-kit init --name my-project --type fullstack  # alias
-```
-
-**옵션:**
-
-| 옵션                | 설명                                                                 | 기본값                    |
-| ------------------- | -------------------------------------------------------------------- | ------------------------- |
-| `-n, --name <name>` | 프로젝트 이름                                                        | 현재 폴더명               |
-| `-t, --type <type>` | `single` 또는 `multi` (`fullstack` alias 지원)                        | 대화형 선택 (`--yes`/`--non-interactive`면 `multi`) |
-| `--components <list>` | multi 컴포넌트 목록 (쉼표 구분, 예: `app,api,worker`)                | `app`                     |
-| `-l, --lang <lang>` | `ko` (한국어) 또는 `en` (영어)                                       | `en`                      |
-| `--workflow <mode>` | 워크플로우 모드: `github`(issue/PR/review 포함) 또는 `local`(로컬 중심) | `github`                  |
-| `-d, --dir <dir>`   | 설치 디렉토리                                                        | `./docs`                  |
-| `--docs-repo <mode>` | docs 레포 모드 (`embedded` 또는 `standalone`)                        | `embedded`                |
-| `--project-root <path>` | standalone(single) 프로젝트 레포 경로 또는 standalone(multi) JSON 매핑 (`{"app":"/path/app","api":"/path/api"}`) | -                         |
-| `--component-project-roots <pairs>` | standalone(multi) 컴포넌트별 레포 경로 (`app=/path/app,api=/path/api,worker=/path/worker`) | - |
-| `--push-docs` | standalone docs 원격 push 사용 (`--docs-remote`와 함께 사용)     | `false`                   |
-| `--docs-remote <url>` | standalone docs 원격 URL (`--push-docs`와 함께 사용)              | -                         |
-| `-y, --yes`         | 대화형 입력을 대부분 스킵 (단, 대상 디렉토리가 비어있지 않으면 덮어쓰기 확인은 표시) | -                         |
-| `-f, --force`       | 대상 디렉토리가 비어있지 않아도 확인 없이 덮어쓰기                  | `false`                   |
-| `--non-interactive` | 사용자 입력이 필요하면 프롬프트 대신 즉시 실패                       | `false`                   |
-
-> `init`은 docs 생성 후 Git 초기화/커밋(`git init`, `git add`, `git commit`)을 자동 시도합니다. 환경에 따라 자동 커밋이 생략될 수 있습니다.
-
-### 프로젝트 감지 (에이전트 시작점)
-
-```bash
-# 현재 경로 기준 감지
-npx lee-spec-kit detect
-
-# 에이전트/자동화용 JSON
-npx lee-spec-kit detect --json
-
-# 특정 경로 기준 감지
-npx lee-spec-kit detect --dir /path/to/workspace
-```
-
-`--json` 출력은 `isLeeSpecKitProject`, `reasonCode`(`PROJECT_DETECTED` | `PROJECT_NOT_DETECTED`), `docsDir`, `configPath`, `detectionSource`(`config` | `heuristic`)를 포함합니다.
-
-### 온보딩 점검
-
-초기 설정(Constitution/PRD/Git remote 등) 준비 상태를 점검합니다.
-
-```bash
-# 사람 읽기 쉬운 출력
-npx lee-spec-kit onboard
-
-# 에이전트/자동화용 JSON
-npx lee-spec-kit onboard --json
-
-# WARN/BLOCK이 있으면 종료 코드 1
-npx lee-spec-kit onboard --strict
-```
-
-### 새 기능 생성
-
-```bash
-# Single 프로젝트
-npx lee-spec-kit feature user-auth
-
-# Multi 프로젝트
-npx lee-spec-kit feature --component api user-auth
-npx lee-spec-kit feature --component app user-profile
-npx lee-spec-kit feature --component worker queue-jobs
-
-# Feature ID/설명 지정
-npx lee-spec-kit feature payment --id F123 --desc "결제 플로우 개선"
-```
-
-**옵션:**
-
-| 옵션                | 설명                                         | 기본값      |
-| ------------------- | -------------------------------------------- | ----------- |
-| `--component <id>`  | multi 대상 컴포넌트                           | 대화형 선택 |
-| `--id <id>`         | Feature ID (`F001` 형식)                     | 자동 생성   |
-| `-d, --desc <desc>` | `spec.md`의 목적(설명) 기본 문구             | 빈 문자열   |
-| `--non-interactive` | 사용자 입력이 필요하면 프롬프트 대신 즉시 실패 | `false`     |
-| `--json`            | JSON 출력 (`featureId`, `featurePath`, `component`) | `false` |
-
-### Context 확인 (AI 에이전트 가이드)
-
-현재 작업 중인 Feature의 상태와 다음 할 일을 확인합니다. 특히 AI 에이전트가 프로세스를 준수하는 데 유용합니다.
-단일 Feature 상세에서는 다음 작업을 항상 `A/B/C` 옵션으로 표시합니다.
-
-```bash
-# 기본 조회 (브랜치 기준 자동 감지)
-npx lee-spec-kit context
-
-# 특정 Feature 상태 + 라벨 확인 (에이전트 권장)
-npx lee-spec-kit context F001
-npx lee-spec-kit context F001 --json
-npx lee-spec-kit context F001 --json-compact
-
-# 승인 + 실행 (일반 케이스)
-npx lee-spec-kit context F001 --approve A --execute
-
-# 선택된 액션이 `requiresUserCheck=true`일 때만 티켓 포함
-npx lee-spec-kit context F001 --approve A --execute --ticket <TICKET>
-
-# 엄격 실행 모드 (instruction-only 라벨이면 실패)
-npx lee-spec-kit context F001 --approve A --execute --ticket <TICKET> --execute-strict
-```
-
-고급 선택자(`--component`, `--all`, `--done`)는 multi 범위 제어나 예외 상황에서만 사용하세요.
-
-**옵션:**
-
-| 옵션            | 설명                                            |
-| --------------- | ----------------------------------------------- |
-| `--json`        | 에이전트용 JSON 출력                            |
-| `--json-compact` | 에이전트용 압축 JSON 출력 (`--json` 포함, 중복 필드 최소화) |
-| `--component <id>` | multi에서 대상 컴포넌트 지정 (예: `app`, `api`, `worker`) |
-| `--all`         | 자동 감지 실패 시 완료된 Feature까지 포함해서 표시 |
-| `--done`        | 완료(workflow-done) Feature만 표시              |
-| `--approve <reply>` | 라벨 포함 승인 응답으로 단일 옵션 선택 (예: `A`, `A OK`, `A 진행해`) |
-| `--ticket <token>` | `--approve` 결과에서 받은 1회용 실행 티켓 (`requiresUserCheck=true` 옵션에서 필요) |
-| `--execute`     | 승인된 command 옵션 1개만 실행 (`requiresUserCheck=true`면 `--ticket` 필요) |
-| `--execute-strict` | `--execute`와 함께 사용 시 instruction-only 옵션이면 실패 |
-
-**티켓(approval ticket)이란?**
-
-- `--approve`로 라벨을 승인할 때 CLI가 발급하는 1회용 실행 토큰입니다.
-- 선택한 액션이 `requiresUserCheck=true`인 경우에만 `--execute`에서 `--ticket`이 필요합니다.
-- 발급 후 짧은 시간(기본 5분)만 유효하며, 한 번 사용하면 재사용할 수 없습니다.
-- handoff-only command(`pre_pr_review_run`, `code_review_run`)를 `--execute`하면 일반 실행 완료(`approved_executed`) 대신 `approved_handoff_prepared`와 `nextMainState`가 반환됩니다.
-
-기본 권장 포맷은 `context --json-compact`이며, 에이전트 hot path에 필요한 상태만 최소 계약으로 전달합니다.  
-`context --json`은 디버깅/세부 필드 확인이 필요할 때만 사용하세요.
-
-**핵심 필드 (실사용 권장)**
-
-- `status`/`reasonCode`: 현재 상태와 이유 코드
-- `actionOptions[]`: `label`(`A`, `B`, `C`...) + 최소 실행 계약 (`detail`, `actionType`, `category`, `operationType`, `requiresUserCheck`, 그리고 command/instruction payload)
-- `approvalRequest`: 승인 대기 여부와 사용자 표시 문구 (`required`, `userFacingLines`, `finalPrompt`)
-- `requiredDocs`: 현재 액션 전에 읽어야 할 CLI 내장 문서 목록 (`id`, `command`)
-- `checkPolicy`: 최소 승인 상태 (`token`, `validLabels`, `checkRequiredLabels`, `checkRequiredCategories`, `approvalRequired`, `contextVersion`)
-- `agentOrchestration`: compact에서는 `subAgentHandoff`만 유지합니다. 위임 SSOT는 `matchedFeature.currentSubstate*` + `subAgentHandoff`입니다.
-- `matchedFeature.currentSubstateId/currentSubstateOwner/currentSubstatePhase`: step 내부 실행 상태와 owner/phase 기반 오케스트레이션 판단용 필드
-- `actions[]`: 원자 액션 원본 목록은 상세 `context --json`에서 확인합니다.
-
-**고급/참고 필드 (자동화 고급 시나리오 또는 디버깅용)**
-
-- `selectionFallback`: 자동 감지 실패 시 사용된 폴백 (`none` | `open_features` | `all_features` | `done_features`) - compact에서는 비-hot-path 상태에서만 노출될 수 있음
-- `primaryActionLabel`/`workflowPolicy`/`taskCommitGatePolicy`/`prePrReviewPolicy`: 상세 `context --json`에서 확인하는 디버깅/정책 필드
-
-오류 응답(`status: "error"`)에는 `reasonCode`와 `suggestions`(라벨형 다음 동작: `A/B/C`)가 포함됩니다. (예: `INVALID_APPROVAL`, `CONTEXT_STALE`, `EXECUTION_FAILED`, `EXECUTION_NOT_COMMAND`)
-
-### CLI 내장 문서 조회
-
-`agents.md`를 프로젝트에 복구하지 않는 환경에서는 아래 명령으로 내장 가이드를 직접 조회할 수 있습니다.
-`docs get create-issue|issue-doc|create-pr|pr-doc --json` 응답에는 `contract`(필수 섹션/아티팩트 규칙)도 포함됩니다.
-
-```bash
-# 조회 가능한 내장 문서 목록
-npx lee-spec-kit docs list --json
-
-# 루트 가이드
-npx lee-spec-kit docs get agents --json
-
-# 이슈/PR 절차 + 템플릿
-npx lee-spec-kit docs get create-issue --json
-npx lee-spec-kit docs get issue-doc --json
-npx lee-spec-kit docs get create-pr --json
-npx lee-spec-kit docs get pr-doc --json
-```
-
-### View 대시보드
-
-```bash
-npx lee-spec-kit view
-npx lee-spec-kit view F001
-npx lee-spec-kit view --all
-npx lee-spec-kit view --json
-```
-
-**옵션:**
-
-| 옵션            | 설명                                            |
-| --------------- | ----------------------------------------------- |
-| `--json`        | 에이전트용 JSON 출력                            |
-| `--component <id>` | multi에서 대상 컴포넌트 지정 (예: `app`, `api`, `worker`) |
-| `--all`         | 자동 감지 실패 시 완료된 Feature까지 포함해서 표시 |
-| `--done`        | 완료(workflow-done) Feature만 표시              |
-
-### Flow 오케스트레이션
-
-```bash
-# 워크플로우 요약 (context + status + doctor)
-npx lee-spec-kit flow
-
-# 승인 + 실행 (에이전트 기본 실행 경로)
-npx lee-spec-kit flow F001 --approve A --execute
-
-# 자동 진행: 특정 category가 나오면 멈추고 사용자 승인 대기
-npx lee-spec-kit flow F004 --auto-until-category pr_create,code_review,pr_status_update
-
-# 자동 진행: preset 사용
-npx lee-spec-kit flow F004 --auto-preset pr-handoff
-
-# 자동 진행 + 새 요청 선반영(user_request_replan 우선 실행)
-npx lee-spec-kit flow F004 --request "issue 004를 F004로 승격시켜서 진행해" --auto-until-category pr_create,code_review,pr_status_update
-
-# 기본 preset 설정 시 더 짧게 실행 가능
-npx lee-spec-kit flow F004 --request "issue 004를 F004로 승격시켜서 진행해"
-
-# 장시간 자동 진행: run 체크포인트 생성 + 재개
-npx lee-spec-kit flow F004 --auto-until-category pr_create,code_review,pr_status_update --start-auto --json-compact
-npx lee-spec-kit flow --resume <RUN_ID> --json-compact
-
-# 에이전트 파이프라인용 JSON
-npx lee-spec-kit flow --json
-npx lee-spec-kit flow --json-compact
-
-# 엄격 검사(선택)
-npx lee-spec-kit flow --strict
-```
-
-**옵션:**
-
-| 옵션               | 설명 |
-| ------------------ | ---- |
-| `--json`           | 에이전트용 JSON 출력 |
-| `--json-compact`   | 에이전트용 압축 JSON 출력 (`--json` 포함, 중복 필드 최소화) |
-| `--component <id>` | multi에서 대상 컴포넌트 지정 (예: `app`, `api`, `worker`) |
-| `--all`            | 자동 감지 실패 시 완료된 Feature까지 포함해서 표시 |
-| `--done`           | 완료(workflow-done) Feature만 표시 |
-| `--request <text>` | auto 모드에서 새 사용자 요청을 먼저 반영 (`user_request_replan` 라벨 자동 선택) |
-| `--auto-preset <name>` | 이름 기반 auto preset 사용 (기본 제공: `pr-handoff`) |
-| `--auto-until-category <categories>` | command 액션을 자동 실행하다가 지정 category 중 하나가 나오면 중지 (쉼표 구분) |
-| `--start-auto`     | auto 실행 체크포인트(run id) 저장 후 JSON에 재개 정보(`autoRun.run`)를 함께 출력 |
-| `--resume <run-id>` | 저장된 auto 실행 체크포인트를 run id로 재개 |
-| `--approve <reply>`| context 라벨 승인 응답 전달 (예: `A`, `A OK`, `A 진행해`) |
-| `--execute`        | 승인한 옵션이 command일 때 실행 (`requiresUserCheck=true`면 티켓 연동, 아니면 티켓 없이 실행) |
-| `--execute-strict` | `--execute`와 함께 사용 시 instruction-only 옵션이면 실패 |
-| `--strict`         | `status --strict`, `doctor --strict`까지 함께 검사 |
-
-자동 게이트 모드 규칙:
-- auto 모드(`--auto-until-category`/`--auto-preset`) 사용 시 `<feature-name>`은 필수입니다. (예: `F004`)
-- auto 모드(`--auto-until-category`/`--auto-preset`)는 `--approve`, `--execute`와 함께 사용할 수 없습니다.
-- `--request`는 auto 모드와 함께 사용해야 합니다.
-  - 예외적으로 `workflow.auto.defaultPreset`이 설정되어 있으면 `--request`만으로도 auto 모드가 활성화됩니다.
-- `--resume <run-id>`는 `<feature-name>`, `--component`, `--all`, `--done`, `--auto-*`, `--request`와 함께 사용할 수 없습니다. (체크포인트에 저장된 설정을 사용)
-- 자동 진행은 지정한 category가 등장하면 `gate_reached`로 멈추고, `autoRun.gate.userFacingLines`를 그대로 출력합니다. (이 값은 해당 단계의 `approvalRequest.userFacingLines`를 flow 결과에 복사한 것입니다.)
-- `context --json` / `--json-compact`의 `autoRun.available`는 "지금 바로 실행 가능한 auto-run"만 의미합니다. 설정상 auto-run 대상이어도 현재 단계가 instruction-only이면 `autoRun.available=false`, `autoRun.policyEligible=true`, `autoRun.executableNow=false`, `autoRun.manualBoundary`로 표시됩니다.
-- 현재 액션이 instruction-only라 command 자동 실행이 불가능하면 `AUTO_MANUAL_REQUIRED`로 멈출 수 있습니다. (CLI 오류가 아니라 자동화 경계 도달 상태)
-- 진행 정체(동일 context/action 반복)가 감지되면 `AUTO_NO_PROGRESS`로 중단됩니다.
-- JSON 모드에서는 `autoRun.status`, `autoRun.reasonCode`, `autoRun.gate`, `autoRun.manual`, `autoRun.resume`를 확인하세요.
-  - 상세 `flow --json`은 `autoRun.executions` 배열을 유지합니다.
-  - 압축 `flow --json-compact`는 `autoRun.executionCount`, `autoRun.lastExecution`만 유지합니다.
-- JSON `agentOrchestration`과 `matchedFeature.currentSubstate*`로 메인/서브 에이전트 역할 및 중단/보고 조건을 확인할 수 있습니다.
-  - 위임 판단은 `matchedFeature.currentSubstateOwner`와 `subAgentHandoff`를 우선 사용하세요. compact는 `subAgentHandoff`만 유지하고, 상세 `--json`/`flow --json`이 추가 오케스트레이션 메타데이터를 제공합니다.
-- `--start-auto`를 사용하면 JSON `autoRun.run`에 `runId`, `status`, `resumeCommand`가 포함됩니다.
-
-에이전트 재개 규칙(권장):
-- `flow --json-compact`(또는 `flow --json`) 결과에 `autoRun.enabled=true`가 있으면, 중단/압축 후에도 `autoRun.resume.flowCommand`를 그대로 재실행해 이어갑니다.
-- 재개 전 현재 지점 확인이 필요하면 `autoRun.resume.contextCommand`를 먼저 실행합니다.
-- `context --json-compact`(또는 `context --json`) 확인 결과 `approvalRequest.required=true`면 즉시 멈추고 사용자에게 보고합니다.
-- `--start-auto`를 사용하는 경우에는 `autoRun.run.resumeCommand`(`flow --resume <runId>`)를 우선 재개 경로로 사용합니다.
-
-### GitHub helper
-
-```bash
-# 선택된 Feature 기준 Issue 본문 생성
-npx lee-spec-kit github issue F001
-
-# Issue 본문 생성 + 실제 Issue 생성
-npx lee-spec-kit github issue F001 --create --confirm OK --labels enhancement,frontend
-
-# PR 본문 생성
-npx lee-spec-kit github pr F001
-
-# PR 본문 생성 (스크린샷/Mermaid 섹션 강제 포함)
-npx lee-spec-kit github pr F001 --screenshots on --mermaid on
-
-# PR 본문 생성 + PR 생성 + tasks.md 메타데이터 동기화 + merge 재시도
-npx lee-spec-kit github pr F001 --create --merge --confirm OK --labels enhancement,frontend
-```
-
-핵심 동작:
-- Issue/PR helper는 필수 섹션과 관련 문서 경로를 검증합니다.
-- `--json` 출력에는 `body`(본문 문자열)와 `bodyFile`(파일 경로)가 함께 제공됩니다.
-- `--labels`를 생략하면 기본값 `enhancement`를 사용합니다. 값을 직접 줄 때는 비어 있으면 안 됩니다.
-- `--create`/`--merge`는 원격 작업이므로 `--confirm OK`가 필요합니다.
-- PR helper는 기본적으로 `tasks.md`의 `PR`/`PR Status`를 동기화합니다. (`--no-sync-tasks`로 비활성화)
-- PR helper의 아티팩트 섹션은 `--screenshots (auto|on|off)`, `--mermaid (auto|on|off)`로 제어할 수 있습니다.
-- merge 시 head 브랜치가 뒤쳐진 경우 fetch/rebase/force-push 후 재시도합니다.
-
-### 상태 확인
-
-```bash
-# 터미널에 출력
-npx lee-spec-kit status
+## Docs
 
-# 에이전트용 JSON 출력
-npx lee-spec-kit status --json
+- [Public CLI Reference](./docs/reference/public-cli.md)
+- [Agent CLI Reference](./docs/reference/agent-cli.md)
+- [Internal CLI Reference](./docs/reference/internal-cli.md)
+- [Reference Index](./docs/reference/README.md)
 
-# 파일로 저장
-npx lee-spec-kit status --write
+## License
 
-# 중복/누락 ID가 있으면 실패 코드로 종료
-npx lee-spec-kit status --strict
-```
-
-**옵션:**
-
-| 옵션           | 설명                                          |
-| -------------- | --------------------------------------------- |
-| `--json`       | 에이전트용 JSON 출력                          |
-| `-w, --write`  | `features/status.md` 파일 생성                |
-| `-s, --strict` | 중복/누락 Feature ID 발견 시 종료 코드 1 반환 |
-
-상태값은 구현 완료와 워크플로우 완료를 구분합니다.
-- `DONE`: 태스크는 모두 완료됐지만 워크플로우 요구사항이 완전히 충족되진 않음
-- `WORKFLOW_DONE`: 구현 + 워크플로우 요구사항까지 모두 충족
-
-### PRD 요구사항 추적
-
-PRD 요구사항 ID(`PRD-FR-001` 등)와 Feature `tasks.md` 태그(`[PRD-FR-001]`)를 기반으로 PRD 커버리지를 집계합니다.
-
-SSOT(단일 기준) 권장:
-- PRD(`docs/prd/`): 요구사항 SSOT (ID 안정성 유지)
-- Ideas(`docs/ideas/`): Feature 전 단계 (상단에 `PRD Refs` 기록)
-- Features(`docs/features/`): 구현/진행 SSOT (`spec.md`의 `PRD Refs`, `tasks.md`의 태스크 태그, `decisions.md`의 변경 기록)
-
-중간에 요구사항/범위가 바뀌면 최소 아래를 함께 갱신하세요:
-- PRD 문서 + `spec.md`의 `PRD Refs` + `tasks.md`의 태스크 태그
-- (필요 시) `plan.md`, `decisions.md`
-
-```bash
-# 터미널에 출력
-npx lee-spec-kit requirements
-
-# alias
-npx lee-spec-kit prd
-
-# 에이전트용 JSON 출력
-npx lee-spec-kit requirements --json
-
-# 파일로 저장 (docs/prd/status.md)
-npx lee-spec-kit requirements --write
-
-# 이슈가 있으면 종료 코드 1 (unknown refs / unmapped tasks / untracked requirements)
-npx lee-spec-kit requirements --strict --json
-```
-
-### 공통 옵션
-
-```bash
-# 도움말 배너 숨김
-npx lee-spec-kit --no-banner --help
-```
-
-또는 환경변수 `LEE_SPEC_KIT_NO_BANNER=1`로 배너 출력을 비활성화할 수 있습니다.
-비TTY 출력(예: 에이전트/파이프라인)에서는 배너가 기본적으로 출력되지 않습니다.
-
-### 문서 진단 (Doctor)
-
-docs 구조 및 Feature 메타데이터(중복 ID, 누락된 파일/상태, 플레이스홀더 잔존 등)를 점검합니다.
-
-```bash
-# 진단 실행
-npx lee-spec-kit doctor
-
-# 문제 발견 시 종료 코드 1 (CI/에이전트 파이프라인용)
-npx lee-spec-kit doctor --strict
-
-# 에이전트용 JSON 출력
-npx lee-spec-kit doctor --json
-
-# 안전한 자동 수정 적용
-npx lee-spec-kit doctor --fix
-
-# 수정 예정 항목만 미리 확인 (파일 미변경)
-npx lee-spec-kit doctor --fix --dry-run
-
-# decisions.md 플레이스홀더 진단 레벨 조정
-npx lee-spec-kit doctor --decisions-placeholders off
-npx lee-spec-kit doctor --decisions-placeholders info
-npx lee-spec-kit doctor --decisions-placeholders warn
-```
-
-- `--decisions-placeholders <mode>`
-  - `off`: `decisions.md` 플레이스홀더를 진단에서 제외
-  - `info` (기본): 정보 레벨로만 보고 (strict 실패 대상 아님)
-  - `warn`: 경고로 보고
-
-### 템플릿 업데이트
-
-기본 동작은 `docs/` 작업트리에 변경사항이 없을 때만 업데이트를 진행하며, 이 경우 변경된 파일은 확인 없이 덮어씁니다.  
-변경사항이 있는 상태에서 업데이트하려면 `--force`를 사용하세요.
-또한 `update`는 `.lee-spec-kit.json`의 누락 필드를 현재 기본 정책으로 보강합니다. (예: `workflow.taskCommitGate: "warn"`)
-
-```bash
-# 전체 업데이트
-npx lee-spec-kit update
-
-# agents/ 폴더만 업데이트
-npx lee-spec-kit update --agents
-
-# agents/skills 폴더만 업데이트
-npx lee-spec-kit update --skills
-
-# feature-base/ 폴더만 업데이트
-npx lee-spec-kit update --templates
-
-# 변경사항이 있어도 강제 덮어쓰기
-npx lee-spec-kit update --force
-```
-
-> `agents/skills`와 `features/feature-base`는 CLI 내장(SSOT)으로 관리됩니다.  
-> `update --skills`, `update --templates`는 기존 프로젝트의 레거시 복사본을 정리하는 용도로 동작합니다.
-
-## 설정 파일
-
-### `.lee-spec-kit.json`
-
-`init`을 실행하면 문서 루트(기본: `docs/`)에 `.lee-spec-kit.json`이 생성됩니다.
-
-```json
-{
-  "projectName": "my-project",
-  "projectType": "single",
-  "lang": "ko",
-  "createdAt": "YYYY-MM-DD",
-  "docsRepo": "embedded",
-  "workflow": {
-    "mode": "github",
-    "codeDirtyScope": "auto",
-    "taskCommitGate": "warn",
-    "prePrReview": {
-      "skills": ["code-review-excellence"],
-      "enforceExecutionEvidence": false
-    }
-  },
-  "pr": { "screenshots": { "upload": false } },
-  "approval": { "mode": "builtin" }
-}
-```
-
-| 필드          | 설명                                    |
-| ------------- | --------------------------------------- |
-| `projectName` | 프로젝트 이름                           |
-| `projectType` | `single` 또는 `multi` (`fullstack` alias 지원) |
-| `components`  | (multi만) 컴포넌트 목록 (예: `["app","api","worker"]`) |
-| `lang`        | `ko` 또는 `en`                          |
-| `createdAt`   | 생성 날짜                               |
-| `docsRepo`    | `embedded` 또는 `standalone`            |
-| `pushDocs`    | (standalone만) docs 레포를 별도 Git으로 관리/푸시할지 여부 |
-| `docsRemote`  | (standalone+pushDocs) docs 레포 remote URL |
-| `projectRoot` | (standalone만) 프로젝트 레포지토리 경로 (single: string, multi: `{ [component]: path }`) |
-| `workflow`    | (선택) 워크플로우 요구사항 정책 (`github`/`local`, `codeDirtyScope`, `taskCommitGate`, `prePrReview`) |
-| `pr`          | (선택) PR 결과물 정책 (예: 스크린샷 업로드 여부) |
-| `approval`    | (선택) `context` 출력의 `[확인 필요]`/`requiresUserCheck` 정책 오버라이드 (자동화/반자동용) |
-
-> `docsRepo: "standalone"`을 선택하면 `pushDocs`, `docsRemote`, `projectRoot`가 추가됩니다.
-
-> 어디서 실행하든 설정을 찾을 수 있도록, CLI는 현재 디렉토리에서 상위로 올라가며 `.lee-spec-kit.json` 또는 `docs/.lee-spec-kit.json`을 탐색합니다.
-> standalone 환경에서 docs 레포 바깥(예: 프로젝트 레포)에서 실행해야 한다면 `LEE_SPEC_KIT_DOCS_DIR`에 docs 레포 경로를 지정할 수 있습니다.
-
-### approval (사용자 확인 정책)
-
-`approval`은 `context`가 출력하는 다음 값에만 영향을 줍니다:
-
-- 텍스트 출력의 `[확인 필요]` 표시
-- `context --json-compact`의 `actionOptions[].requiresUserCheck` (`--json`에서는 `actions[].requiresUserCheck`)
-- `checkPolicy.token` (`context --json-compact`/`--json`): 승인 토큰 형식 (`<LABEL>`)
-- `checkPolicy.validLabels`: 현재 선택 가능한 라벨 목록 (`A`, `B`, `C`...)
-- `checkPolicy.checkRequiredLabels` / `checkPolicy.checkRequiredCategories`: 현재 승인 필수 라벨/카테고리
-- `checkPolicy.approvalRequired`: 현재 승인 대기 여부
-- `checkPolicy.contextVersion`: stale context 검증용 스냅샷 해시
-- `checkPolicy.acceptedTokens`, `tokenPattern`, `activeCategories`, `knownCategories`, `uncategorizedLabels`, `categoryPolicyGuidance`, `requireExplanationBeforeApproval`, `requiredExplanationFields`는 상세 `context --json`에서 확인합니다.
-
-> 실제 명령 실행을 강제/차단하는 기능은 아닙니다. (에이전트가 참고하도록 신호를 제공)
-> 기존 설정에 `approval`이 없으면 `builtin`으로 동작합니다. (마이그레이션 불필요)
-> `requiresUserCheck: true`인 액션은 에이전트가 사용자로부터 **정확히 `<라벨>` 또는 `<라벨> OK` 응답(예: `A`, `A OK`)**을 받은 뒤 진행하는 것을 권장합니다.
-
-### workflow (완료 조건 정책)
-
-- `workflow.mode: "github"` (기본): Issue/브랜치/PR/리뷰 단계를 포함한 전체 워크플로우를 완료 조건으로 사용
-- `workflow.mode: "local"`: 로컬 중심 워크플로우로 동작하며 Issue/브랜치/PR/리뷰 단계를 필수로 요구하지 않음
-  - local 모드로 생성한 Feature 템플릿은 기본적으로 Issue/PR 중심 섹션을 축소합니다.
-- `workflow.codeDirtyScope`:
-  - `repo`: 프로젝트 레포 전체 변경으로 코드 미커밋 여부를 판정
-  - `component`: 현재 Feature 컴포넌트 경로 변경만 판정 (multi 권장)
-  - `auto`: `single => repo`, `multi => component`
-  - `workflow.componentPaths`(선택): component 판정 경로를 컴포넌트별로 명시 (예: `"web": ["apps/web", "packages/web-ui"]`)
-  - 하위 호환: 값이 없으면 기존 동작인 `repo`로 처리
-- `workflow.taskCommitGate`:
-  - `strict`: 최근 `tasks.md` 커밋에서 DONE 전환이 2개 이상이면 차단
-  - `warn`: 점검 실패 시 경고만 표시하고 진행 허용
-  - `off`: 점검 비활성화
-  - 기본값: `warn` (값이 없으면 `warn`)
-- `workflow.prePrReview`:
-  - `enabled` (선택): pre-PR 리뷰 단계를 강제할지 여부 (기본: `requirePr`와 동일)
-  - `skills` (선택): 우선순위 스킬 목록 (기본: `["code-review-excellence"]`)
-  - `fallback` (선택): 기본 베이스라인 정책 (기본: `"builtin-checklist"`)
-    - 상세 기준은 `docs get create-pr --json`의 `Pre-PR 기본 체크리스트` 섹션을 단일 기준으로 사용
-  - `evidenceMode` (선택): Evidence 검증 방식 (`"path_required"` | `"any"`, 기본: `"path_required"`)
-    - `path_required`: 실제 존재하는 로컬 경로만 인정
-  - `decisionEnum` (선택): 허용 Decision 값 목록 (기본: `["approve","changes_requested","blocked"]`)
-    - PR 단계로 진행하려면 최종 Decision이 `approve`여야 함
-  - `enforceExecutionEvidence` (선택): 리뷰 에이전트 실제 실행 증거 강제 여부 (기본: `false`)
-    - `true`일 때 `pre-pr-review`는 `--evidence`와 비어있지 않은 `commandsExecuted`를 요구
-    - `false`일 때도 구현 품질 리뷰 필드는 필수이며, `commandsExecuted`는 선택적 보조 evidence입니다
-  - `executionCommandPrefixes` (선택): 실행 증거를 강제할 때 `commandsExecuted`와 매칭할 명령 prefix 목록 (기본: `[]`)
-    - 비어있지 않으면 실행 명령 중 최소 1개가 해당 prefix로 시작해야 함
-- `workflow.auto`:
-  - `defaultPreset` (선택): `flow --request "<요청>"` 실행 시 기본으로 사용할 auto preset 이름 (기본: `"pr-handoff"`)
-  - `defaultUntilCategories` (선택): 기본 gate category 목록 (설정 시 `defaultPreset`보다 우선)
-  - `presets` (선택): 사용자 정의 preset 맵
-    - 예: `"my-handoff": ["pr_create", "code_review"]`
-
-예시:
-
-```json
-{
-  "workflow": {
-    "mode": "github",
-    "codeDirtyScope": "auto",
-    "taskCommitGate": "warn",
-    "auto": {
-      "defaultPreset": "pr-handoff",
-      "presets": {
-        "my-handoff": ["pr_create", "code_review", "pr_status_update"]
-      }
-    },
-    "prePrReview": {
-      "skills": ["code-review-excellence"],
-      "fallback": "builtin-checklist",
-      "evidenceMode": "path_required",
-      "decisionEnum": ["approve", "changes_requested", "blocked"],
-      "enforceExecutionEvidence": false,
-      "executionCommandPrefixes": []
-    }
-  }
-}
-```
-
-Pre-PR 실행 게이트 리스크와 완화:
-- 처리량 병목: 타임아웃/재시도와 maintainer 수동 우회 경로를 함께 둡니다.
-- 비용 증가: 변경 파일/규모 기준으로 리뷰 에이전트 실행 대상을 제한합니다.
-- 품질 착시: 자동 로그가 있어도 주기적 수동 샘플 리뷰를 유지합니다.
-- 오탐/노이즈: high severity만 차단 게이트로 쓰고 나머지는 코멘트로 처리합니다.
-- 도구 종속: 산출물 JSON 스키마를 고정해 실행기를 교체 가능하게 유지합니다.
-
-#### 모드
-
-- `builtin` (기본): 코드에 내장된 `requiresUserCheck`를 그대로 사용
-- `category` (권장): `actionOptions[].category` 기준으로 확인 정책을 제어 (`--json`에서는 `actions[].category`)
-- `steps`: step 번호 기준(변경에 취약하므로 권장하지 않음)
-
-#### 설정 필드
-
-- `default` (`category`만): `keep` | `require` | `skip` (기본: `keep`)
-- `requireCheckCategories` (`category`만): 확인을 **항상** 요구할 category 목록 (예: `["pr_create"]`, `["*"]`)
-- `skipCheckCategories` (`category`만): 확인을 **절대** 요구하지 않을 category 목록 (예: `["docs_commit"]`, `["*"]`)
-- `requireCheckSteps` (`steps`만): 확인이 필요한 step 번호 목록 (예: `[3, 5, 12]`)
-- `taskExecuteCheck` (선택): 레거시 `task_execute` 시작/완료 phase 호환용 확인 정책 (`both` | `start_only`, 기본: `both`)
-  - `both`: 기존 `task_execute` 호환 경로에서 TODO→DOING, DOING→DONE 모두 승인 필요
-  - `start_only`: 기존 `task_execute` 호환 경로에서 TODO→DOING만 승인 필요, DOING→DONE은 기본 승인 생략
-
-#### category 예시
-
-```json
-{
-  "approval": { "mode": "category", "default": "skip" }
-}
-```
-
-```json
-{
-  "approval": {
-    "mode": "category",
-    "default": "keep",
-    "skipCheckCategories": ["docs_commit"]
-  }
-}
-```
-
-> 사용 가능한 `category` 값은 `context --json`의 `checkPolicy.activeCategories`/`checkPolicy.knownCategories`, 또는 `actionOptions[].category`에서 확인하세요. compact는 hot path 최소 계약만 유지합니다.
-
-### pr (PR 결과물 정책)
-
-- `pr.screenshots.upload` (기본: `false`): `true`면 스크린샷을 업로드(예: GitHub Release assets)하고 PR 본문에 URL을 포함할 수 있습니다. `false`면 업로드/URL 포함을 하지 않으며 PR 본문에서도 스크린샷 섹션을 만들지 않는 것을 권장합니다.
-
-### Standalone 프로젝트 설정 예시
-
-**Single 프로젝트:**
-
-```json
-{
-  "projectName": "my-project",
-  "projectType": "single",
-  "lang": "ko",
-  "createdAt": "YYYY-MM-DD",
-  "docsRepo": "standalone",
-  "pushDocs": false,
-  "projectRoot": "/path/to/my-project"
-}
-```
-
-**Multi 프로젝트:**
-
-```json
-{
-  "projectName": "my-project",
-  "projectType": "multi",
-  "lang": "ko",
-  "createdAt": "YYYY-MM-DD",
-  "docsRepo": "standalone",
-  "pushDocs": false,
-  "projectRoot": {
-    "app": "/path/to/app",
-    "api": "/path/to/api"
-  }
-}
-```
-
-### 설정 확인 및 수정
-
-```bash
-# 현재 설정 확인
-npx lee-spec-kit config
-
-# 여러 docs 경로가 있을 때 대상 지정
-npx lee-spec-kit config --dir ./docs2
-
-# projectRoot 수정 (Single)
-npx lee-spec-kit config --project-root /new/path
-npx lee-spec-kit config --dir ./docs2 --project-root /new/path
-
-# projectRoot 수정 (Multi)
-npx lee-spec-kit config --project-root /new/app/path --component app
-npx lee-spec-kit config --project-root /new/api/path --component api
-npx lee-spec-kit config --project-root /new/worker/path --component worker
-
-# 비대화형 모드 (필수 옵션 누락 시 즉시 실패)
-npx lee-spec-kit config --project-root /new/app/path --component app --non-interactive
-```
-
-**옵션:**
-
-| 옵션                 | 설명 |
-| -------------------- | ---- |
-| `--dir <dir>` | 대상 docs 디렉터리 또는 프로젝트 경로 지정 |
-| `--project-root <path>` | projectRoot 경로 설정 |
-| `--component <id>` | multi 대상 컴포넌트 |
-| `--non-interactive` | 사용자 입력이 필요하면 프롬프트 대신 즉시 실패 |
-
-> `--non-interactive`는 `init`, `feature`, `config`에서 지원됩니다.
-> 오류 시 출력되는 `[REASON_CODE]` 형식(`PROMPT_BLOCKED`, `CONFIG_NOT_FOUND` 등)은 자동화 분기용으로 사용할 수 있습니다.
-> 또한 텍스트 모드 오류에는 `👉 Next Options (Error)`로 `A/B/C` 제안이 함께 출력됩니다.
-
-## 오류 코드
-
-- 이 CLI는 자동화 분기를 위해 에러에 `reasonCode`(JSON) 또는 `[REASON_CODE]`(텍스트)를 제공합니다.
-- 오류 시 다음 동작 제안이 `A/B/C` 라벨로 함께 제공됩니다. (JSON: `suggestions`, 텍스트: `👉 Next Options (Error)`)
-- 대표 코드:
-  - `PROMPT_BLOCKED`: 비대화형 모드에서 사용자 입력이 필요함
-  - `CONFIG_NOT_FOUND`: `.lee-spec-kit.json`을 찾지 못함
-  - `DOCS_NOT_FOUND`: docs 구조를 찾지 못함
-  - `LOCK_WAIT_TIMEOUT` / `LOCK_ACQUIRE_TIMEOUT`: 락 대기/획득 타임아웃
-  - `INVALID_APPROVAL`, `CONTEXT_STALE`, `EXECUTION_FAILED`, `EXECUTION_NOT_COMMAND`: `context --approve/--execute` 흐름 오류
-
-상세 코드 목록과 의미는 `errors.md`(한국어), `errors.en.md`(English)를 참고하세요.
-
-## 생성되는 구조
-
-### Multi (컴포넌트 분리)
-
-```
-docs/
-├── README.md
-├── agents/
-│   ├── constitution.md     # 프로젝트 원칙
-│   ├── custom.md           # 프로젝트별 추가 규칙
-├── designs/                # 디자인 참고 자료
-├── ideas/                  # 아이디어/To-do (Feature 승격 전)
-├── prd/
-│   └── README.md
-├── scripts/
-│   └── README.md
-└── features/
-    ├── README.md
-    ├── app/                # App Features
-    └── api/                # API Features
-```
-
-### Single (단일 레포)
-
-```
-docs/
-├── README.md
-├── agents/
-│   ├── constitution.md
-│   ├── custom.md
-├── designs/
-├── ideas/
-├── prd/
-├── scripts/
-└── features/
-    └── F001-feature/       # 개별 기능
-```
-
-## Feature 워크플로우
-
-```mermaid
-flowchart LR
-    A[spec.md] --> B[사용자 리뷰]
-    B --> C[plan.md]
-    C --> D[tasks.md]
-    D --> E[구현]
-    E --> F[decisions.md]
-```
-
-1. **spec.md 작성** - 무엇을, 왜 만드는지 정의
-2. **사용자 리뷰 요청** - 스펙 검토 및 승인
-3. **plan.md 작성** - 어떻게 만드는지 (기술 스택, 설계)
-4. **tasks.md 작성** - 태스크 분해 및 체크리스트
-5. **decisions.md** - 기술 결정 기록 (ADR)
-
-| 프로젝트 타입 | 설명                                         |
-| ------------- | -------------------------------------------- |
-| `single`      | 단일 레포 프로젝트 (모노레포 또는 단일 스택) |
-| `multi`       | 멀티 컴포넌트 프로젝트 (예: app/api/worker)  |
-| `fullstack`   | `multi`의 하위호환 alias                     |
-
-## 문제 해결
-
-<details>
-<summary><strong>init 명령어가 실패합니다</strong></summary>
-
-- Node.js 18 이상이 설치되어 있는지 확인하세요
-- `npx` 캐시 문제일 수 있습니다: `npx clear-npx-cache` 후 재시도
-
-</details>
-
-<details>
-<summary><strong>feature 명령어가 설정 파일을 찾지 못합니다</strong></summary>
-
-- `docs/` 폴더에 `.lee-spec-kit.json` 파일이 있는지 확인하세요
-- `init` 명령어를 먼저 실행했는지 확인하세요
-- embedded 모드라면 프로젝트 루트/하위 어디서 실행해도 상위 디렉토리 탐색으로 설정을 찾습니다.
-- standalone 모드에서 docs 레포 밖에서 실행 중이면, docs 레포로 이동하거나 `LEE_SPEC_KIT_DOCS_DIR=/path/to/docs`를 설정하세요.
-
-</details>
-
-<details>
-<summary><strong>Multi 프로젝트에서 --component 옵션이 동작하지 않습니다</strong></summary>
-
-- `.lee-spec-kit.json`의 `projectType`이 `multi`(또는 구버전 `fullstack`)인지 확인하세요
-- `.lee-spec-kit.json`의 `components` 목록에 해당 값이 포함되어 있는지 확인하세요
-
-</details>
-
-## 기여하기
-
-1. Fork → 브랜치 생성 → 개발 → Pull Request
-
-이슈나 PR은 언제든 환영합니다!
-
-## 라이선스
-
-[MIT License](./LICENSE)
-
----
-
-<p align="center">
-  Made with ❤️ by <a href="https://github.com/leey00nsu">leey00nsu</a>
-</p>
+MIT