lee-spec-kit 0.6.16 → 0.6.18

package/README.en.md

@@ -40,26 +40,29 @@
 # 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.
-This sequence assumes the default `docsRepo: embedded` mode.
+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)
@@ -69,17 +72,32 @@ cd my-app
 # 1) Initialize docs structure
 npx lee-spec-kit init
 
-# 2) Detect project (agent entrypoint)
+# 2) Run initial onboarding checks
+npx lee-spec-kit onboard --strict
+
+# 3) Detect project (agent entrypoint)
 npx lee-spec-kit detect --json
 
-# 3) Create feature and start workflow
+# 4) Create feature and start workflow
 npx lee-spec-kit feature user-auth
-npx lee-spec-kit context --json
+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.
-- If you use `standalone` docs, run commands against the docs repo location (`--dir` or `LEE_SPEC_KIT_DOCS_DIR`).
+
+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
 
@@ -88,7 +106,7 @@ 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
+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
@@ -99,7 +117,7 @@ Start procedure:
 ### 📁 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
@@ -178,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
@@ -214,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
@@ -232,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    |
@@ -246,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)**
 
@@ -415,7 +451,7 @@ npx lee-spec-kit doctor --decisions-placeholders warn
 
 By default, `update` runs only when the `docs/` working tree is clean; in that case it overwrites changed files without prompting.  
 If you want to update while you have uncommitted changes, use `--force`.
-`update` also backfills missing `.lee-spec-kit.json` keys using current defaults (e.g. `workflow.taskCommitGate: "strict"`).
+`update` also backfills missing `.lee-spec-kit.json` keys using current defaults (e.g. `workflow.taskCommitGate: "warn"`).
 
 ```bash
 npx lee-spec-kit update
@@ -444,7 +480,7 @@ Running `init` creates `.lee-spec-kit.json` in your docs root (default: `docs/`)
   "workflow": {
     "mode": "github",
     "codeDirtyScope": "auto",
-    "taskCommitGate": "strict",
+    "taskCommitGate": "warn",
     "prePrReview": { "skills": ["code-review-excellence"] }
   },
   "pr": { "screenshots": { "upload": false } },
@@ -475,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`...)
@@ -522,7 +558,7 @@ Example:
   "workflow": {
     "mode": "github",
     "codeDirtyScope": "auto",
-    "taskCommitGate": "strict",
+    "taskCommitGate": "warn",
     "prePrReview": {
       "skills": ["code-review-excellence"],
       "fallback": "builtin-checklist",
@@ -536,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
@@ -564,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

@@ -55,26 +55,29 @@
 # 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를 초기화하세요.
-이 순서는 기본값인 `docsRepo: embedded` 기준입니다.
+대부분의 사용자(기본값: embedded)는 프로젝트 루트에서 `npx lee-spec-kit init`만 실행하면 됩니다.
 
 ```bash
 # 0. 코드 프로젝트 생성/초기화 (예: Next.js)
@@ -84,17 +87,32 @@ cd my-app
 # 1. docs 구조 초기화
 npx lee-spec-kit init
 
-# 2. 감지 확인 (에이전트 시작점)
+# 2. 초기 온보딩 점검
+npx lee-spec-kit onboard --strict
+
+# 3. 감지 확인 (에이전트 시작점)
 npx lee-spec-kit detect --json
 
-# 3. Feature 생성 후 작업 시작
+# 4. Feature 생성 후 작업 시작
 npx lee-spec-kit feature user-auth
-npx lee-spec-kit context --json
+npx lee-spec-kit context --json-compact
 ```
 
 - `detect --json` 결과가 `isLeeSpecKitProject: true`일 때 lee-spec-kit 워크플로우를 적용하세요.
 - `isLeeSpecKitProject: false`면 일반 프로젝트 워크플로우로 진행하세요.
-- `standalone`으로 docs를 분리한 경우에는 docs 레포 위치(`--dir` 또는 `LEE_SPEC_KIT_DOCS_DIR`) 기준으로 실행하세요.
+
+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
+```
 
 ## 에이전트 킥오프 프롬프트
 
@@ -103,7 +121,7 @@ npx lee-spec-kit context --json
 ```text
 작업 시작 절차:
 1) npx lee-spec-kit detect --json
-2) isLeeSpecKitProject === true 이면 npx lee-spec-kit context --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 전용 절차를 건너뛰고 일반 워크플로우로 진행
@@ -114,7 +132,7 @@ npx lee-spec-kit context --json
 ### 📁 프로젝트 초기화
 
 - 대화형 모드 또는 CLI 옵션으로 프로젝트 설정
-- Single(단일 레포) / Multi(멀티 컴포넌트) 프로젝트 타입 지원 (`fullstack`는 하위호환 alias)
+- 기본값은 Multi이며, Single도 단순 단일 레포/기존 호환 시나리오를 위해 지원합니다. (`fullstack`는 `multi` 하위호환 alias)
 - 한국어/영어 템플릿 선택
 
 ### 🚀 Feature 생성
@@ -196,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
@@ -233,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
@@ -251,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만 표시              |
@@ -265,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`은 디버깅/세부 필드 확인이 필요할 때만 사용하세요.
 
 **핵심 필드 (실사용 권장)**
 
@@ -455,7 +491,7 @@ npx lee-spec-kit doctor --decisions-placeholders warn
 
 기본 동작은 `docs/` 작업트리에 변경사항이 없을 때만 업데이트를 진행하며, 이 경우 변경된 파일은 확인 없이 덮어씁니다.  
 변경사항이 있는 상태에서 업데이트하려면 `--force`를 사용하세요.
-또한 `update`는 `.lee-spec-kit.json`의 누락 필드를 현재 기본 정책으로 보강합니다. (예: `workflow.taskCommitGate: "strict"`)
+또한 `update`는 `.lee-spec-kit.json`의 누락 필드를 현재 기본 정책으로 보강합니다. (예: `workflow.taskCommitGate: "warn"`)
 
 ```bash
 # 전체 업데이트
@@ -493,7 +529,7 @@ npx lee-spec-kit update --force
   "workflow": {
     "mode": "github",
     "codeDirtyScope": "auto",
-    "taskCommitGate": "strict",
+    "taskCommitGate": "warn",
     "prePrReview": { "skills": ["code-review-excellence"] }
   },
   "pr": { "screenshots": { "upload": false } },
@@ -526,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`...)
@@ -554,7 +590,7 @@ npx lee-spec-kit update --force
   - `strict`: 최근 `tasks.md` 커밋에서 DONE 전환이 2개 이상이면 차단
   - `warn`: 점검 실패 시 경고만 표시하고 진행 허용
   - `off`: 점검 비활성화
-  - 하위 호환: 값이 없으면 `warn`으로 처리
+  - 기본값: `warn` (값이 없으면 `warn`)
 - `workflow.prePrReview`:
   - `enabled` (선택): pre-PR 리뷰 단계를 강제할지 여부 (기본: `requirePr`와 동일)
   - `skills` (선택): 우선순위 스킬 목록 (기본: `["code-review-excellence"]`)
@@ -570,7 +606,7 @@ npx lee-spec-kit update --force
   "workflow": {
     "mode": "github",
     "codeDirtyScope": "auto",
-    "taskCommitGate": "strict",
+    "taskCommitGate": "warn",
     "prePrReview": {
       "skills": ["code-review-excellence"],
       "fallback": "builtin-checklist",
@@ -584,7 +620,7 @@ npx lee-spec-kit update --force
 #### 모드
 
 - `builtin` (기본): 코드에 내장된 `requiresUserCheck`를 그대로 사용
-- `category` (권장): `actions[].category` 기준으로 확인 정책을 제어
+- `category` (권장): `actionOptions[].category` 기준으로 확인 정책을 제어 (`--json`에서는 `actions[].category`)
 - `steps`: step 번호 기준(변경에 취약하므로 권장하지 않음)
 
 #### 설정 필드
@@ -612,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 결과물 정책)