lee-spec-kit 0.6.15 → 0.6.17

package/README.en.md

@@ -40,28 +40,84 @@
 # 1) Initialize docs structure
 npx lee-spec-kit init
 
-# 2) Create a feature
+# 2) Run initial onboarding checks
+npx lee-spec-kit onboard --strict
+
+# 3) Create a feature
 npx lee-spec-kit feature user-auth
 
-# 3) Show next steps (for agents)
+# 4) Show next steps (for agents)
 npx lee-spec-kit context
 
-# 4) Show workflow dashboard
+# 5) Show workflow dashboard
 npx lee-spec-kit view
 
-# 5) Show overall status
+# 6) Show overall status
 npx lee-spec-kit status
 
-# 6) Validate docs / feature metadata
+# 7) Validate docs / feature metadata
 npx lee-spec-kit doctor
 ```
 
+## New Project Start Order
+
+For a brand-new project, scaffold the **codebase first**, then initialize docs.
+For most users (default: embedded), running `npx lee-spec-kit init` in project root is enough.
+
+```bash
+# 0) Create/init the code project first (example: Next.js)
+npx create-next-app@latest my-app
+cd my-app
+
+# 1) Initialize docs structure
+npx lee-spec-kit init
+
+# 2) Run initial onboarding checks
+npx lee-spec-kit onboard --strict
+
+# 3) Detect project (agent entrypoint)
+npx lee-spec-kit detect --json
+
+# 4) Create feature and start workflow
+npx lee-spec-kit feature user-auth
+npx lee-spec-kit context --json-compact
+```
+
+- Apply lee-spec-kit workflow only when `detect --json` returns `isLeeSpecKitProject: true`.
+- If `isLeeSpecKitProject: false`, continue with normal non-lee-spec-kit workflow.
+
+For teams that keep docs separate from the code repo (standalone), the recommended start point is the **parent workspace folder**.
+
+```bash
+# Recommended layout:
+# workspace/
+#   ├─ docs/      (lee-spec-kit docs)
+#   └─ project/   (actual code repo)
+#
+# Run from workspace root
+npx lee-spec-kit init --docs-repo standalone --dir ./docs --project-root ./project
+npx lee-spec-kit detect --json
+```
+
+## Agent Kickoff Prompt
+
+You can paste the following as an agent session-start instruction.
+
+```text
+Start procedure:
+1) Run npx lee-spec-kit detect --json
+2) If isLeeSpecKitProject === true, run npx lee-spec-kit context --json-compact (use --json only when full detail is needed)
+3) If actionOptions exist, show approvalPrompt and finalPrompt exactly as provided, then wait for user approval (<LABEL> or <LABEL> OK)
+4) Do not execute before approval; execute requiresUserCheck=true actions only after approval
+5) If isLeeSpecKitProject === false, skip lee-spec-kit-specific flow and continue with normal workflow
+```
+
 ## Features
 
 ### 📁 Project initialization
 
 - Interactive init or CLI options
-- Supports `single` and `multi` (`fullstack` remains as a backward-compatible alias)
+- Default is `multi`; `single` remains supported for simple single-repo and backward-compatibility scenarios (`fullstack` is a backward-compatible alias of `multi`)
 - Korean/English templates
 
 ### 🚀 Feature creation
@@ -140,6 +196,21 @@ npx lee-spec-kit detect --dir /path/to/workspace
 
 The `--json` payload includes `isLeeSpecKitProject`, `reasonCode` (`PROJECT_DETECTED` | `PROJECT_NOT_DETECTED`), `docsDir`, `configPath`, and `detectionSource` (`config` | `heuristic`).
 
+### Onboarding checks
+
+Validate initial setup readiness (Constitution/PRD/git remotes, etc.).
+
+```bash
+# human-readable output
+npx lee-spec-kit onboard
+
+# JSON output for agents/automation
+npx lee-spec-kit onboard --json
+
+# exit code 1 when WARN/BLOCK exists
+npx lee-spec-kit onboard --strict
+```
+
 ### Create a feature
 
 ```bash
@@ -176,6 +247,7 @@ npx lee-spec-kit context
 # recommended: one feature + labels
 npx lee-spec-kit context F001
 npx lee-spec-kit context F001 --json
+npx lee-spec-kit context F001 --json-compact
 
 # approve + execute (common path)
 npx lee-spec-kit context F001 --approve A --execute
@@ -194,6 +266,7 @@ Use advanced selectors (`--component`, `--all`, `--done`) only when you need mul
 | Option         | Description                                     |
 | -------------- | ----------------------------------------------- |
 | `--json`       | JSON output for agents                          |
+| `--json-compact` | Compact JSON for agents (implies `--json`, minimizes duplicated fields) |
 | `--component <id>` | Select target component in multi mode (e.g. `app`, `api`, `worker`) |
 | `--all`        | Include completed features when auto-detecting  |
 | `--done`       | Show completed (workflow-done) features only    |
@@ -208,7 +281,8 @@ Use advanced selectors (`--component`, `--all`, `--done`) only when you need mul
 - `--ticket` is required for `--execute` only when the selected action has `requiresUserCheck=true`.
 - It is short-lived (5 minutes by default) and cannot be reused after one execution.
 
-`context --json` is organized into `actions` (atomic actions), `actionOptions` (label mapping), and top-level metadata.
+`context --json-compact` is the default recommended format, providing a reduced and deduplicated decision state.  
+Use `context --json` only when full-detail debugging fields are required.
 
 **Core fields (recommended for normal agent flows)**
 
@@ -437,8 +511,8 @@ Running `init` creates `.lee-spec-kit.json` in your docs root (default: `docs/`)
 `approval` only affects the following values produced by `context`:
 
 - the `[CHECK required]` tag in text output
-- `actions[].requiresUserCheck` in `context --json`
-- `checkPolicy.token` (`context --json`): approval token format (`<LABEL>`)
+- `actionOptions[].requiresUserCheck` in `context --json-compact` (`actions[].requiresUserCheck` in `--json`)
+- `checkPolicy.token` (`context --json-compact`/`--json`): approval token format (`<LABEL>`)
 - `checkPolicy.acceptedTokens`: accepted reply templates (e.g. `["<LABEL>", "<LABEL> OK", "<LABEL> ...", "... <LABEL> ..."]`)
 - `checkPolicy.tokenPattern`: input validation regex for approval replies
 - `checkPolicy.validLabels`: currently selectable labels (`A`, `B`, `C`...)
@@ -498,7 +572,7 @@ Example:
 #### Modes
 
 - `builtin` (default): keep built-in `requiresUserCheck` in steps/actions
-- `category` (recommended): control CHECK policy by `actions[].category`
+- `category` (recommended): control CHECK policy by `actionOptions[].category` (`actions[].category` in `--json`)
 - `steps`: control by step numbers (not recommended; fragile)
 
 #### Fields
@@ -526,7 +600,7 @@ Example:
 }
 ```
 
-> To discover available `category` values, check `actions[].category` in `context --json`.
+> To discover available `category` values, check `actionOptions[].category` in `context --json-compact` first, and use `actions[].category` in `context --json` when needed.
 
 ### pr (PR artifacts policy)
 

package/README.md

@@ -37,6 +37,8 @@
 ## 목차
 
 - [Quick Start](#quick-start)
+- [신규 프로젝트 시작 순서](#신규-프로젝트-시작-순서)
+- [에이전트 킥오프 프롬프트](#에이전트-킥오프-프롬프트)
 - [주요 기능](#주요-기능)
 - [사용법](#사용법)
 - [설정 파일](#설정-파일)
@@ -53,28 +55,84 @@
 # 1. 프로젝트 문서 구조 생성
 npx lee-spec-kit init
 
-# 2. 새 기능 생성
+# 2. 초기 온보딩 점검
+npx lee-spec-kit onboard --strict
+
+# 3. 새 기능 생성
 npx lee-spec-kit feature user-auth
 
-# 3. 진행 상황 및 다음 단계 확인 (AI 에이전트용)
+# 4. 진행 상황 및 다음 단계 확인 (AI 에이전트용)
 npx lee-spec-kit context
 
-# 4. 워크플로우 대시보드 확인
+# 5. 워크플로우 대시보드 확인
 npx lee-spec-kit view
 
-# 5. 전체 상태 확인
+# 6. 전체 상태 확인
 npx lee-spec-kit status
 
-# 6. 문서/Feature 진단
+# 7. 문서/Feature 진단
 npx lee-spec-kit doctor
 ```
 
+## 신규 프로젝트 시작 순서
+
+신규 프로젝트에서는 **코드 스캐폴딩을 먼저** 하고, 그 다음 docs를 초기화하세요.
+대부분의 사용자(기본값: embedded)는 프로젝트 루트에서 `npx lee-spec-kit init`만 실행하면 됩니다.
+
+```bash
+# 0. 코드 프로젝트 생성/초기화 (예: Next.js)
+npx create-next-app@latest my-app
+cd my-app
+
+# 1. docs 구조 초기화
+npx lee-spec-kit init
+
+# 2. 초기 온보딩 점검
+npx lee-spec-kit onboard --strict
+
+# 3. 감지 확인 (에이전트 시작점)
+npx lee-spec-kit detect --json
+
+# 4. Feature 생성 후 작업 시작
+npx lee-spec-kit feature user-auth
+npx lee-spec-kit context --json-compact
+```
+
+- `detect --json` 결과가 `isLeeSpecKitProject: true`일 때 lee-spec-kit 워크플로우를 적용하세요.
+- `isLeeSpecKitProject: false`면 일반 프로젝트 워크플로우로 진행하세요.
+
+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
+```
+
+## 에이전트 킥오프 프롬프트
+
+아래 프롬프트를 에이전트 시작 메시지로 그대로 사용할 수 있습니다.
+
+```text
+작업 시작 절차:
+1) npx lee-spec-kit detect --json
+2) isLeeSpecKitProject === true 이면 npx lee-spec-kit context --json-compact 실행 (필요 시 --json으로 상세 조회)
+3) actionOptions가 있으면 approvalPrompt와 finalPrompt를 그대로 사용자에게 제시하고 승인(<LABEL> 또는 <LABEL> OK) 대기
+4) 승인 전에는 실행하지 말고, requiresUserCheck=true 액션은 승인 후에만 실행
+5) isLeeSpecKitProject === false 이면 lee-spec-kit 전용 절차를 건너뛰고 일반 워크플로우로 진행
+```
+
 ## 주요 기능
 
 ### 📁 프로젝트 초기화
 
 - 대화형 모드 또는 CLI 옵션으로 프로젝트 설정
-- Single(단일 레포) / Multi(멀티 컴포넌트) 프로젝트 타입 지원 (`fullstack`는 하위호환 alias)
+- 기본값은 Multi이며, Single도 단순 단일 레포/기존 호환 시나리오를 위해 지원합니다. (`fullstack`는 `multi` 하위호환 alias)
 - 한국어/영어 템플릿 선택
 
 ### 🚀 Feature 생성
@@ -156,6 +214,21 @@ 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
@@ -193,6 +266,7 @@ 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
@@ -211,6 +285,7 @@ npx lee-spec-kit context F001 --approve A --execute --ticket <TICKET> --execute-
 | 옵션            | 설명                                            |
 | --------------- | ----------------------------------------------- |
 | `--json`        | 에이전트용 JSON 출력                            |
+| `--json-compact` | 에이전트용 압축 JSON 출력 (`--json` 포함, 중복 필드 최소화) |
 | `--component <id>` | multi에서 대상 컴포넌트 지정 (예: `app`, `api`, `worker`) |
 | `--all`         | 자동 감지 실패 시 완료된 Feature까지 포함해서 표시 |
 | `--done`        | 완료(workflow-done) Feature만 표시              |
@@ -225,7 +300,8 @@ npx lee-spec-kit context F001 --approve A --execute --ticket <TICKET> --execute-
 - 선택한 액션이 `requiresUserCheck=true`인 경우에만 `--execute`에서 `--ticket`이 필요합니다.
 - 발급 후 짧은 시간(기본 5분)만 유효하며, 한 번 사용하면 재사용할 수 없습니다.
 
-`context --json` 출력은 크게 `actions`(원자 액션), `actionOptions`(라벨 매핑), 상위 메타데이터로 구성됩니다.
+기본 권장 포맷은 `context --json-compact`이며, 같은 판단 정보를 중복 없이 축약해 전달합니다.  
+`context --json`은 디버깅/세부 필드 확인이 필요할 때만 사용하세요.
 
 **핵심 필드 (실사용 권장)**
 
@@ -486,8 +562,8 @@ npx lee-spec-kit update --force
 `approval`은 `context`가 출력하는 다음 값에만 영향을 줍니다:
 
 - 텍스트 출력의 `[확인 필요]` 표시
-- `context --json`의 `actions[].requiresUserCheck`
-- `checkPolicy.token` (`context --json`): 승인 토큰 형식 (`<LABEL>`)
+- `context --json-compact`의 `actionOptions[].requiresUserCheck` (`--json`에서는 `actions[].requiresUserCheck`)
+- `checkPolicy.token` (`context --json-compact`/`--json`): 승인 토큰 형식 (`<LABEL>`)
 - `checkPolicy.acceptedTokens`: 허용되는 승인 응답 템플릿 (예: `["<LABEL>", "<LABEL> OK", "<LABEL> ...", "... <LABEL> ..."]`)
 - `checkPolicy.tokenPattern`: 승인 응답 검증용 정규식
 - `checkPolicy.validLabels`: 현재 선택 가능한 라벨 목록 (`A`, `B`, `C`...)
@@ -544,7 +620,7 @@ npx lee-spec-kit update --force
 #### 모드
 
 - `builtin` (기본): 코드에 내장된 `requiresUserCheck`를 그대로 사용
-- `category` (권장): `actions[].category` 기준으로 확인 정책을 제어
+- `category` (권장): `actionOptions[].category` 기준으로 확인 정책을 제어 (`--json`에서는 `actions[].category`)
 - `steps`: step 번호 기준(변경에 취약하므로 권장하지 않음)
 
 #### 설정 필드
@@ -572,7 +648,7 @@ npx lee-spec-kit update --force
 }
 ```
 
-> 사용 가능한 `category` 값은 `context --json`의 `actions[].category`로 확인하는 것을 권장합니다.
+> 사용 가능한 `category` 값은 `context --json-compact`의 `actionOptions[].category`에서 우선 확인하고, 필요 시 `context --json`의 `actions[].category`를 참고하세요.
 
 ### pr (PR 결과물 정책)