lee-spec-kit 0.4.13 → 0.5.0

package/README.md

@@ -40,6 +40,7 @@
 - [주요 기능](#주요-기능)
 - [사용법](#사용법)
 - [설정 파일](#설정-파일)
+- [오류 코드](#오류-코드)
 - [생성되는 구조](#생성되는-구조)
 - [Feature 워크플로우](#feature-워크플로우)
 - [문제 해결](#문제-해결)
@@ -58,10 +59,13 @@ npx lee-spec-kit feature user-auth
 # 3. 진행 상황 및 다음 단계 확인 (AI 에이전트용)
 npx lee-spec-kit context
 
-# 4. 전체 상태 확인
+# 4. 워크플로우 대시보드 확인
+npx lee-spec-kit view
+
+# 5. 전체 상태 확인
 npx lee-spec-kit status
 
-# 5. 문서/Feature 진단
+# 6. 문서/Feature 진단
 npx lee-spec-kit doctor
 ```
 
@@ -70,7 +74,7 @@ npx lee-spec-kit doctor
 ### 📁 프로젝트 초기화
 
 - 대화형 모드 또는 CLI 옵션으로 프로젝트 설정
-- Single(단일 레포) / Fullstack(FE/BE 분리) 프로젝트 타입 지원
+- Single(단일 레포) / Multi(멀티 컴포넌트) 프로젝트 타입 지원 (`fullstack`는 하위호환 alias)
 - 한국어/영어 템플릿 선택
 
 ### 🚀 Feature 생성
@@ -84,6 +88,16 @@ npx lee-spec-kit doctor
 - 전체 Feature 진행 상태 한눈에 확인
 - 터미널 출력 또는 마크다운 파일로 저장
 
+### 👀 View 대시보드
+
+- Context 기반 워크플로우 현황을 한 번에 확인
+- 단일 Feature/전체 Feature 모두 조회 가능
+
+### 🔁 Flow 오케스트레이션
+
+- `context + status + doctor`를 한 번에 실행/요약
+- 승인/실행 옵션을 그대로 전달해 원자 액션 자동화 가능
+
 ### 🩺 문서 진단 (Doctor)
 
 - docs 구조/설정/Feature 메타데이터를 점검하여 잠재 문제를 빠르게 탐지
@@ -102,18 +116,31 @@ npx lee-spec-kit doctor
 npx lee-spec-kit init
 
 # 옵션 지정
-npx lee-spec-kit init --name my-project --type fullstack
+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` 또는 `fullstack`      | 대화형 선택 |
-| `-l, --lang <lang>` | `ko` (한국어) 또는 `en` (영어) | `en`        |
-| `-d, --dir <dir>`   | 설치 디렉토리                  | `./docs`    |
-| `-y, --yes`         | 대화형 프롬프트 스킵           | -           |
+| 옵션                | 설명                                                                 | 기본값                    |
+| ------------------- | -------------------------------------------------------------------- | ------------------------- |
+| `-n, --name <name>` | 프로젝트 이름                                                        | 현재 폴더명               |
+| `-t, --type <type>` | `single` 또는 `multi` (`fullstack` alias 지원)                        | 대화형 선택 (`--yes`/`--non-interactive`면 `single`) |
+| `--components <list>` | multi 컴포넌트 목록 (쉼표 구분, 예: `fe,be,worker`)                  | `fe,be`                   |
+| `-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) 프로젝트 레포 경로                              | -                         |
+| `--fe-project-root <path>` | standalone(multi) FE 레포 경로                                  | -                         |
+| `--be-project-root <path>` | standalone(multi) BE 레포 경로                                  | -                         |
+| `--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`)을 자동 시도합니다. 환경에 따라 자동 커밋이 생략될 수 있습니다.
 
 ### 새 기능 생성
 
@@ -121,14 +148,29 @@ npx lee-spec-kit init --name my-project --type fullstack
 # Single 프로젝트
 npx lee-spec-kit feature user-auth
 
-# Fullstack 프로젝트
+# Multi 프로젝트
 npx lee-spec-kit feature --repo be user-auth
 npx lee-spec-kit feature --repo fe user-profile
+npx lee-spec-kit feature --component worker queue-jobs
+
+# Feature ID/설명 지정
+npx lee-spec-kit feature payment --id F123 --desc "결제 플로우 개선"
 ```
 
+**옵션:**
+
+| 옵션                | 설명                                         | 기본값      |
+| ------------------- | -------------------------------------------- | ----------- |
+| `-r, --repo <repo>` | multi 대상 컴포넌트 (하위호환 alias)          | 대화형 선택 |
+| `--component <id>`  | multi 대상 컴포넌트                           | 대화형 선택 |
+| `--id <id>`         | Feature ID (`F001` 형식)                     | 자동 생성   |
+| `-d, --desc <desc>` | `spec.md`의 목적(설명) 기본 문구             | 빈 문자열   |
+| `--non-interactive` | 사용자 입력이 필요하면 프롬프트 대신 즉시 실패 | `false`     |
+
 ### Context 확인 (AI 에이전트 가이드)
 
 현재 작업 중인 Feature의 상태와 다음 할 일을 확인합니다. 특히 AI 에이전트가 프로세스를 준수하는 데 유용합니다.
+단일 Feature 상세에서는 다음 작업을 항상 `A/B/C` 옵션으로 표시합니다.
 
 ```bash
 # 자동 감지 (Git 브랜치 기준)
@@ -141,18 +183,93 @@ npx lee-spec-kit context user-auth
 npx lee-spec-kit context F001
 npx lee-spec-kit context F001-user-auth
 
+# multi에서 컴포넌트 지정
+npx lee-spec-kit context --repo fe
+npx lee-spec-kit context --repo worker
+
+# 전체/완료 Feature 포함
+npx lee-spec-kit context --all
+npx lee-spec-kit context --done
+
 # 에이전트용 JSON 출력
 npx lee-spec-kit context --json
+
+# 라벨 승인 선택 (검증만)
+npx lee-spec-kit context F001 --approve A
+
+# 라벨 승인 + 단일 명령 실행
+npx lee-spec-kit context F001 --approve "A OK" --execute
+
+# 승인 라벨이 instruction-only면 실패 처리
+npx lee-spec-kit context F001 --approve A --execute --execute-strict
 ```
 
+**옵션:**
+
+| 옵션            | 설명                                            |
+| --------------- | ----------------------------------------------- |
+| `--json`        | 에이전트용 JSON 출력                            |
+| `--repo <repo>` | multi에서 대상 컴포넌트 지정 (예: `fe`, `be`, `worker`) |
+| `--all`         | 자동 감지 실패 시 완료된 Feature까지 포함해서 표시 |
+| `--done`        | 완료(workflow-done) Feature만 표시              |
+| `--approve <reply>` | 라벨 승인 응답 (`A` 또는 `A OK`)으로 단일 옵션 선택 |
+| `--execute`     | `--approve`로 선택한 옵션이 command일 때 1개만 실행 |
+| `--execute-strict` | `--execute`와 함께 사용 시 instruction-only 옵션이면 실패 |
+
 `--json` 출력에는 다음 액션이 `actions` 배열로 포함됩니다.
 
+- `reasonCode`: 상태 이유 코드 (`SINGLE_MATCHED`, `MULTIPLE_ACTIVE_FEATURES` 등)
 - `type: "command"`: `scope`(project|docs), `cwd`, `cmd` 제공 (복사하여 붙여넣기 가능한 형태로 `cd ... && git ...` 형태로 출력)
 - `type: "instruction"`: 사람이 수행해야 하는 안내 메시지
+- `actionOptions`: `label`(`A`, `B`, `C`...)과 해당 `action` 매핑
 - `category`: 액션 분류 (자동화/반자동용 `approval.mode: "category"`에서 사용)
-- `requiresUserCheck`: 사용자 확인 필요 여부 (에이전트는 **사용자 응답을 정확히 `OK`로 제한**하는 것을 권장 / 설정의 `approval`로 오버라이드 가능)
+- `requiresUserCheck`: 사용자 확인 필요 여부 (에이전트는 **사용자 응답을 `<라벨>` 또는 `<라벨> OK` 형식(예: `A`, `A OK`)으로 제한**하는 것을 권장 / 설정의 `approval`로 오버라이드 가능)
+- `workflowPolicy`: 현재 완료 조건 정책 (`mode`, `requireIssue`, `requireBranch`, `requirePr`, `requireReview`)
 
-또한 `checkPolicy`가 포함되어, 에이전트가 사용자 확인 정책을 적용할 때 참고할 수 있습니다. (`docPath`, `hint`, `token: "OK"`, `config`)
+또한 `checkPolicy`가 포함되어, 에이전트가 사용자 확인 정책을 적용할 때 참고할 수 있습니다. (`docPath`, `hint`, `token: "<LABEL>"`, `acceptedTokens`, `tokenPattern`, `validLabels`, `contextVersion`, `config`)
+
+오류 응답(`status: "error"`)에는 `reasonCode`와 `suggestions`(라벨형 다음 동작: `A/B/C`)가 포함됩니다. (예: `INVALID_APPROVAL`, `CONTEXT_STALE`, `EXECUTION_FAILED`, `EXECUTION_NOT_COMMAND`)
+
+### 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 출력                            |
+| `--repo <repo>` | multi에서 대상 컴포넌트 지정 (예: `fe`, `be`, `worker`) |
+| `--all`         | 자동 감지 실패 시 완료된 Feature까지 포함해서 표시 |
+| `--done`        | 완료(workflow-done) Feature만 표시              |
+
+### Flow 오케스트레이션
+
+```bash
+npx lee-spec-kit flow
+npx lee-spec-kit flow F001 --approve A
+npx lee-spec-kit flow F001 --approve "A OK" --execute
+npx lee-spec-kit flow --strict
+npx lee-spec-kit flow --json
+```
+
+**옵션:**
+
+| 옵션               | 설명 |
+| ------------------ | ---- |
+| `--json`           | 에이전트용 JSON 출력 |
+| `--repo <repo>`    | multi에서 대상 컴포넌트 지정 (예: `fe`, `be`, `worker`) |
+| `--all`            | 자동 감지 실패 시 완료된 Feature까지 포함해서 표시 |
+| `--done`           | 완료(workflow-done) Feature만 표시 |
+| `--approve <reply>`| context 라벨 승인 응답 전달 (`A` 또는 `A OK`) |
+| `--execute`        | 승인한 옵션이 command일 때 실행 |
+| `--execute-strict` | `--execute`와 함께 사용 시 instruction-only 옵션이면 실패 |
+| `--strict`         | `status --strict`, `doctor --strict`까지 함께 검사 |
 
 ### 상태 확인
 
@@ -160,10 +277,37 @@ npx lee-spec-kit context --json
 # 터미널에 출력
 npx lee-spec-kit status
 
+# 에이전트용 JSON 출력
+npx lee-spec-kit status --json
+
 # 파일로 저장
 npx lee-spec-kit status --write
+
+# 중복/누락 ID가 있으면 실패 코드로 종료
+npx lee-spec-kit status --strict
 ```
 
+**옵션:**
+
+| 옵션           | 설명                                          |
+| -------------- | --------------------------------------------- |
+| `--json`       | 에이전트용 JSON 출력                          |
+| `-w, --write`  | `features/status.md` 파일 생성                |
+| `-s, --strict` | 중복/누락 Feature ID 발견 시 종료 코드 1 반환 |
+
+상태값은 구현 완료와 워크플로우 완료를 구분합니다.
+- `DONE`: 태스크는 모두 완료됐지만 워크플로우 요구사항이 완전히 충족되진 않음
+- `WORKFLOW_DONE`: 구현 + 워크플로우 요구사항까지 모두 충족
+
+### 공통 옵션
+
+```bash
+# 도움말 배너 숨김
+npx lee-spec-kit --no-banner --help
+```
+
+또는 환경변수 `LEE_SPEC_KIT_NO_BANNER=1`로 배너 출력을 비활성화할 수 있습니다.
+
 ### 문서 진단 (Doctor)
 
 docs 구조 및 Feature 메타데이터(중복 ID, 누락된 파일/상태, 플레이스홀더 잔존 등)를 점검합니다.
@@ -177,6 +321,12 @@ 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
 ```
 
 ### 템플릿 업데이트
@@ -214,6 +364,8 @@ npx lee-spec-kit update --force
   "lang": "ko",
   "createdAt": "YYYY-MM-DD",
   "docsRepo": "embedded",
+  "workflow": { "mode": "github" },
+  "pr": { "screenshots": { "upload": false } },
   "approval": { "mode": "builtin" }
 }
 ```
@@ -221,13 +373,16 @@ npx lee-spec-kit update --force
 | 필드          | 설명                                    |
 | ------------- | --------------------------------------- |
 | `projectName` | 프로젝트 이름                           |
-| `projectType` | `single` 또는 `fullstack`               |
+| `projectType` | `single` 또는 `multi` (`fullstack` alias 지원) |
+| `components`  | (multi만) 컴포넌트 목록 (예: `["fe","be","worker"]`) |
 | `lang`        | `ko` 또는 `en`                          |
 | `createdAt`   | 생성 날짜                               |
 | `docsRepo`    | `embedded` 또는 `standalone`            |
 | `pushDocs`    | (standalone만) docs 레포를 별도 Git으로 관리/푸시할지 여부 |
 | `docsRemote`  | (standalone+pushDocs) docs 레포 remote URL |
-| `projectRoot` | (standalone만) 프로젝트 레포지토리 경로 (single: string, fullstack: {fe, be}) |
+| `projectRoot` | (standalone만) 프로젝트 레포지토리 경로 (single: string, multi: `{ [component]: path }`) |
+| `workflow`    | (선택) 워크플로우 요구사항 정책 (`github`/`local`) |
+| `pr`          | (선택) PR 결과물 정책 (예: 스크린샷 업로드 여부) |
 | `approval`    | (선택) `context` 출력의 `[확인 필요]`/`requiresUserCheck` 정책 오버라이드 (자동화/반자동용) |
 
 > `docsRepo: "standalone"`을 선택하면 `pushDocs`, `docsRemote`, `projectRoot`가 추가됩니다.
@@ -241,11 +396,29 @@ npx lee-spec-kit update --force
 
 - 텍스트 출력의 `[확인 필요]` 표시
 - `context --json`의 `actions[].requiresUserCheck`
-- `checkPolicy.token` (`context --json`): 승인 토큰 (`OK`)
+- `checkPolicy.token` (`context --json`): 승인 토큰 형식 (`<LABEL>`)
+- `checkPolicy.acceptedTokens`: 허용되는 승인 응답 템플릿 (예: `["<LABEL>", "<LABEL> OK"]`)
+- `checkPolicy.tokenPattern`: 승인 응답 검증용 정규식
+- `checkPolicy.validLabels`: 현재 선택 가능한 라벨 목록 (`A`, `B`, `C`...)
+- `checkPolicy.contextVersion`: stale context 검증용 스냅샷 해시
 
 > 실제 명령 실행을 강제/차단하는 기능은 아닙니다. (에이전트가 참고하도록 신호를 제공)
 > 기존 설정에 `approval`이 없으면 `builtin`으로 동작합니다. (마이그레이션 불필요)
-> `requiresUserCheck: true`인 액션은 에이전트가 사용자로부터 **정확히 `OK` 응답**을 받은 뒤 진행하는 것을 권장합니다.
+> `requiresUserCheck: true`인 액션은 에이전트가 사용자로부터 **정확히 `<라벨>` 또는 `<라벨> OK` 응답(예: `A`, `A OK`)**을 받은 뒤 진행하는 것을 권장합니다.
+
+### workflow (완료 조건 정책)
+
+- `workflow.mode: "github"` (기본): Issue/브랜치/PR/리뷰 단계를 포함한 전체 워크플로우를 완료 조건으로 사용
+- `workflow.mode: "local"`: 로컬 중심 워크플로우로 동작하며 Issue/브랜치/PR/리뷰 단계를 필수로 요구하지 않음
+  - local 모드로 생성한 Feature 템플릿은 기본적으로 Issue/PR 중심 섹션을 축소합니다.
+
+예시:
+
+```json
+{
+  "workflow": { "mode": "local" }
+}
+```
 
 #### 모드
 
@@ -280,6 +453,10 @@ npx lee-spec-kit update --force
 
 > 사용 가능한 `category` 값은 `context --json`의 `actions[].category`로 확인하는 것을 권장합니다.
 
+### pr (PR 결과물 정책)
+
+- `pr.screenshots.upload` (기본: `false`): `true`면 스크린샷을 업로드(예: GitHub Release assets)하고 PR 본문에 URL을 포함할 수 있습니다. `false`면 업로드/URL 포함을 하지 않으며 PR 본문에서도 스크린샷 섹션을 만들지 않는 것을 권장합니다.
+
 ### Standalone 프로젝트 설정 예시
 
 **Single 프로젝트:**
@@ -296,12 +473,12 @@ npx lee-spec-kit update --force
 }
 ```
 
-**Fullstack 프로젝트:**
+**Multi 프로젝트:**
 
 ```json
 {
   "projectName": "my-project",
-  "projectType": "fullstack",
+  "projectType": "multi",
   "lang": "ko",
   "createdAt": "YYYY-MM-DD",
   "docsRepo": "standalone",
@@ -319,14 +496,49 @@ npx lee-spec-kit update --force
 # 현재 설정 확인
 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 수정 (Fullstack)
+# projectRoot 수정 (Multi)
 npx lee-spec-kit config --project-root /new/fe/path --repo fe
 npx lee-spec-kit config --project-root /new/be/path --repo be
+npx lee-spec-kit config --project-root /new/worker/path --component worker
+
+# 비대화형 모드 (필수 옵션 누락 시 즉시 실패)
+npx lee-spec-kit config --project-root /new/fe/path --repo fe --non-interactive
 ```
 
+**옵션:**
+
+| 옵션                 | 설명 |
+| -------------------- | ---- |
+| `--dir <dir>` | 대상 docs 디렉터리 또는 프로젝트 경로 지정 |
+| `--project-root <path>` | projectRoot 경로 설정 |
+| `--repo <repo>` | multi 대상 컴포넌트(하위호환 alias) |
+| `--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)를 참고하세요.
+
 ## 생성되는 구조
 
 ### Fullstack (FE/BE 분리)
@@ -337,13 +549,17 @@ docs/
 ├── agents/
 │   ├── agents.md           # 에이전트 운영 규칙
 │   ├── constitution.md     # 프로젝트 원칙
+│   ├── custom.md           # 프로젝트별 추가 규칙
 │   ├── git-workflow.md     # Git 자동화 규칙
 │   ├── issue-template.md
-│   └── pr-template.md
+│   ├── pr-template.md
+│   └── skills/             # 에이전트 실행 가이드
 ├── designs/                # 디자인 참고 자료
 ├── ideas/                  # 아이디어/To-do (Feature 승격 전)
 ├── prd/
 │   └── README.md
+├── scripts/
+│   └── README.md
 └── features/
     ├── README.md
     ├── feature-base/       # 공용 템플릿
@@ -357,9 +573,12 @@ docs/
 docs/
 ├── README.md
 ├── agents/
+│   ├── custom.md
+│   └── skills/
 ├── designs/
 ├── ideas/
 ├── prd/
+├── scripts/
 └── features/
     ├── feature-base/
     └── F001-feature/       # 개별 기능
@@ -385,7 +604,8 @@ flowchart LR
 | 프로젝트 타입 | 설명                                         |
 | ------------- | -------------------------------------------- |
 | `single`      | 단일 레포 프로젝트 (모노레포 또는 단일 스택) |
-| `fullstack`   | FE/BE 분리 프로젝트                          |
+| `multi`       | 멀티 컴포넌트 프로젝트 (예: FE/BE/worker)    |
+| `fullstack`   | `multi`의 하위호환 alias                     |
 
 ## 문제 해결
 
@@ -408,10 +628,10 @@ flowchart LR
 </details>
 
 <details>
-<summary><strong>Fullstack 프로젝트에서 --repo 옵션이 동작하지 않습니다</strong></summary>
+<summary><strong>Multi 프로젝트에서 --repo/--component 옵션이 동작하지 않습니다</strong></summary>
 
-- `.lee-spec-kit.json`의 `projectType`이 `fullstack`인지 확인하세요
-- `--repo` 값은 `fe` 또는 `be`만 가능합니다
+- `.lee-spec-kit.json`의 `projectType`이 `multi`(또는 구버전 `fullstack`)인지 확인하세요
+- `.lee-spec-kit.json`의 `components` 목록에 해당 값이 포함되어 있는지 확인하세요
 
 </details>