lee-spec-kit 0.7.3 → 0.7.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lee-spec-kit",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "Project documentation structure generator for AI-assisted development",
   "type": "module",
   "bin": {

package/templates/en/common/README.md

@@ -22,7 +22,8 @@ npx lee-spec-kit context --json-compact
 ## New Project Start Order
 
 - Scaffold the code project first (for example Next.js/NestJS), then run `lee-spec-kit init`.
-- After that, verify detection with `detect --json`, then continue with `feature` and `context`.
+- After that, write top-level requirements in `docs/prd/`, then continue with `idea` and `feature`.
+- Verify detection with `detect --json`, then continue with `context`.
 - In most cases (default: embedded), the steps above are all you need.
 - Choose standalone only when docs are managed separately from the code repo. In that case, prefer running init from a parent workspace folder (for example `workspace/docs`, `workspace/project`) and set both docs/project paths together. (e.g. `npx lee-spec-kit init --docs-repo standalone --dir ./docs --project-root ./project`)
 
@@ -42,14 +43,23 @@ npx lee-spec-kit context --json-compact
 
 To avoid ambiguity, treat the following as the single source of truth (SSOT).
 
+Recommended flow:
+
+1. `docs/prd/`: define the top-level requirements
+2. `docs/ideas/`: capture candidate work derived from PRD
+3. `docs/features/`: move approved work into executable feature units
+
 - **PRD (`docs/prd/`)**: requirements SSOT
+  - This top-level space is created by `init`; PRD is edited directly here rather than generated by a separate CLI step.
   - Assign stable IDs per requirement: `PRD-FR-001`, `PRD-US-002`, `PRD-NFR-003`
   - Keep IDs stable (prefer marking as Deprecated over deleting; do not renumber).
   - Define PRD IDs in the PRD source first. Do not invent them inside feature docs.
 - **Ideas (`docs/ideas/`)**: pre-Feature SSOT (hypotheses/experiments/candidates)
+  - Ideas usually start from PRD requirements and should keep `PRD Refs` when applicable.
   - Put `PRD Refs:` at the top (example: `PRD-FR-001, PRD-US-002`).
   - Once promoted, the SSOT moves to `docs/features/` and the idea should be archived.
 - **Features (`docs/features/`)**: implementation scope/progress SSOT
+  - Features are the executable units that come after PRD and idea refinement.
   - `spec.md`: scope + `PRD Refs` (the PRD IDs this feature covers)
   - `tasks.md`: map each task line to PRD IDs via bracket tags like `[PRD-FR-001]`, or tag non-PRD tasks as `[NON-PRD]`
     - Use `[NON-PRD]` only for internal work such as refactors, renames, tooling, tests, and cleanup.

package/templates/en/common/agents/agents.md

@@ -7,8 +7,8 @@ This document covers **policy only**.
 
 ## 🚨 User Approval Required (MUST)
 
-> ⚠️ The actions below require explicit user approval (OK) before execution.
-> ✅ Approval replies must be in `<label>` or `<label> OK` format (e.g. `A`, `A OK`).
+> ⚠️ The actions below require explicit user approval when they are at an approval boundary.
+> ✅ In approval-waiting state, replies must be in `<label>` or `<label> OK` format (e.g. `A`, `A OK`).
 
 | Action | When to confirm | What to share |
 | --- | --- | --- |
@@ -22,8 +22,9 @@ This document covers **policy only**.
 
 Approval flow:
 1. Share details first
-2. Wait for explicit approval (OK)
-3. Execute after approval (for command execution, default to `npx lee-spec-kit flow <featureRef> --approve <LABEL> --execute`)
+2. Check whether approval is currently required via the latest `context --json-compact` (`approvalRequest.required`)
+3. If approval is required, wait for the exact CLI-provided label prompt response; if not, do not invent a separate approval prompt
+4. Execute after approval (for command execution, default to `npx lee-spec-kit flow <featureRef> --approve <LABEL> --execute`)
 
 Prohibited:
 - Proceeding without user response

package/templates/en/common/agents/skills/create-pr.md

@@ -149,7 +149,7 @@ echo \"![](https://github.com/${REPO}/releases/download/${TAG}/ui-1.png)\"
 
 > 🚨 **User Approval Required**
 
-Before creating PR, share the following **in a code block** and wait for **explicit approval (OK)**:
+Before creating the PR, share the following **in a code block** and, if approval is currently required, wait for the CLI-provided `<LABEL>` or `<LABEL> OK` reply:
 
 - Title
 - Full body template (from `pr.md`)

package/templates/en/common/agents/skills/execute-task.md

@@ -86,11 +86,11 @@ Use the feature’s `decisions.md` template format as final SSOT. (Context/Const
 ### Step 3.5: Commit per task (important)
 
 - Complete **only one task at a time** (do not batch-finish multiple tasks in one commit).
-- After you share the outcome/verification, mark the task `[DONE]` (and update any checklist items). If approval is required (`approvalRequest.required=true`), wait for OK first. Then create commits (code commit + docs commit) so each task has its own history.
+- After you share the outcome/verification, mark the task `[DONE]` (and update any checklist items). If approval is required (`approvalRequest.required=true`), reuse the exact CLI-provided approval lines and wait for a `<LABEL>` or `<LABEL> OK` reply first. If approval is not required, do not invent a separate approval prompt before marking `[DONE]`.
 - In `tasks.md` test logs, keep one entry per test command and update its date/result on reruns (do not keep appending duplicates). Use `YYYY-MM-DD` in local date.
-- If `context` shows `[CHECK required]`, for commits/push/merge, **share the commit message + included files and wait for explicit OK** before running the commands.
-- Once all tasks are `[DONE]`, share the "Completion Criteria" checklist with the user and get **final approval (OK)**, then check it (especially the **Final user approval (OK) received** item).
-  - Note: `Doc Status (Review→Approved)` is **progress approval (OK)**, while the completion checklist approval is **final approval (OK)**.
+- If `context` shows `[CHECK required]`, for commits/push/merge, **share the commit message + included files and wait for the latest CLI-provided label reply** before running the commands.
+- Once all tasks are `[DONE]`, share the "Completion Criteria" checklist with the user. If that point is approval-waiting, get a `<LABEL>` or `<LABEL> OK` reply before checking it; otherwise get a normal confirmation reply. (especially the **Final user approval received** item).
+  - Note: both progress approval and final approval must follow the current `approvalRequest.required` state. When approval is label-gated, always use label replies instead of standalone `OK` as the approval token.
 
 ### Step 4: Repeat
 

package/templates/en/common/features/README.md

@@ -34,6 +34,9 @@ npx lee-spec-kit feature --component app user-profile
 
 > 💡 CLI copies templates from `feature-base/` and auto-assigns IDs.
 
+Features are the executable units in the PRD → idea → feature flow.
+By the time work reaches this folder, the requirement should already be defined in `docs/prd/`, and any pre-feature exploration should already live in `docs/ideas/`.
+
 ---
 
 ## Feature ID Rules
@@ -67,7 +70,7 @@ npx lee-spec-kit status --write
 - Use `[NON-PRD]` only for internal implementation work such as refactors, test-only work, tooling, renames, and cleanup.
 - If a change affects user-facing behavior, acceptance criteria, or scope, update PRD first and retag the task as `[PRD-...]`.
 - Do not invent PRD IDs inside feature docs. Define them in the PRD source first, and backfill legacy docs before linking tasks.
-- Coverage report: `npx lee-spec-kit requirements` (alias: `npx lee-spec-kit prd`)
+- Coverage report: `npx lee-spec-kit requirements`
 
 ---
 

package/templates/en/common/ideas/README.md

@@ -4,6 +4,8 @@ A place for pre-feature ideas / to-dos / experiments.
 
 Core rule: once an idea becomes a Feature, the SSOT moves to `docs/features/`.
 
+Typical flow: PRD defines the requirement, Idea explores or scopes the candidate work, and Feature becomes the executable unit.
+
 ---
 
 ## Conventions

package/templates/en/common/prd/README.md

@@ -2,6 +2,9 @@
 
 This folder contains product requirements documents.
 
+This is the top-level requirements space created by `lee-spec-kit init`.
+Write PRD documents here first, then connect downstream idea and feature docs back to these requirements.
+
 > **📌 Document Scope**
 >
 > - **This folder**: Product requirements, business logic, user stories
@@ -13,6 +16,14 @@ This folder contains product requirements documents.
 2. Write main features and user stories
 3. Include technical architecture overview
 
+## Relationship To Ideas And Features
+
+- `docs/prd/`: defines the source requirements
+- `docs/ideas/`: explores candidate work derived from those requirements
+- `docs/features/`: executes approved work as feature units
+
+If work starts from a PRD item, keep the relationship visible through `PRD Refs` and task tags in downstream docs.
+
 ## Requirement ID Conventions (Recommended)
 
 To let the CLI report “which PRD items are implemented”, assign **stable IDs** to PRD requirements.

package/templates/ko/common/README.md

@@ -22,7 +22,8 @@ npx lee-spec-kit context --json-compact
 ## 신규 프로젝트 시작 순서
 
 - 코드 프로젝트 스캐폴딩(예: Next.js/NestJS) 후 `lee-spec-kit init`을 실행하세요.
-- 그 다음 `detect --json`으로 감지 결과를 확인하고, `feature`/`context` 순서로 진행하세요.
+- 그 다음 `docs/prd/`에 상위 요구사항을 정리하고, `idea`/`feature`로 작업 단위를 구체화하세요.
+- 이후 `detect --json`으로 감지 결과를 확인하고, `context` 순서로 진행하세요.
 - 대부분의 경우(기본값: embedded) 위 순서만 따르면 됩니다.
 - docs를 코드 저장소와 분리해 운영할 때만 standalone을 선택하세요. 이때는 상위 워크스페이스 폴더(예: `workspace/docs`, `workspace/project`)에서 `init`을 실행해 docs/project 경로를 함께 지정하는 방식을 권장합니다. (예: `npx lee-spec-kit init --docs-repo standalone --dir ./docs --project-root ./project`)
 
@@ -42,14 +43,23 @@ npx lee-spec-kit context --json-compact
 
 문서 간 관계가 모호해지지 않도록, 아래를 “SSOT(단일 기준)”로 사용합니다.
 
+권장 흐름:
+
+1. `docs/prd/`: 상위 요구사항 정의
+2. `docs/ideas/`: PRD에서 나온 후보/실험 정리
+3. `docs/features/`: 승인된 작업을 실행 가능한 feature 단위로 전환
+
 - **PRD (`docs/prd/`)**: 요구사항 SSOT
+  - 이 공간은 `init`이 만들어 주며, 별도 생성 명령 없이 여기에서 직접 PRD를 관리합니다.
   - 요구사항마다 ID를 부여합니다: `PRD-FR-001`, `PRD-US-002`, `PRD-NFR-003`
   - ID는 안정적으로 유지합니다. (삭제 대신 `Deprecated` 표기 권장, 재번호 부여 금지)
   - PRD ID는 PRD 원문에 먼저 정의합니다. Feature 문서에서 임의 생성하지 않습니다.
 - **Ideas (`docs/ideas/`)**: Feature 전 단계 SSOT (가설/실험/후보)
+  - 가능하면 PRD에서 출발한 후보라는 점이 보이도록 `PRD Refs`를 유지합니다.
   - Idea 문서 상단에 `PRD Refs:`를 기록합니다. (예: `PRD-FR-001, PRD-US-002`)
   - Feature로 승격되면 SSOT는 `docs/features/`로 이동하고, Idea는 archive로 정리합니다.
 - **Features (`docs/features/`)**: 구현 범위/진행 SSOT
+  - Feature는 PRD와 idea를 바탕으로 실제 구현을 진행하는 실행 단위입니다.
   - `spec.md`: 범위 정의 + `PRD Refs`(기능이 커버하는 PRD ID 목록)
   - `tasks.md`: 태스크 단위로 PRD ID를 태그(`[PRD-FR-001]`)로 매핑하거나, PRD 무관 태스크는 `[NON-PRD]`로 표시
     - `[NON-PRD]`는 refactor, rename, tooling, 테스트, cleanup 같은 내부 작업에만 사용합니다.

package/templates/ko/common/agents/agents.md

@@ -7,8 +7,8 @@
 
 ## 🚨 사용자 확인 필수 규칙 (MUST)
 
-> ⚠️ 아래 작업은 반드시 사용자 명시 승인(OK) 후에만 진행합니다.
-> ✅ 승인 응답은 `<라벨>` 또는 `<라벨> OK` 형식(예: `A`, `A OK`)입니다.
+> ⚠️ 아래 작업은 사용자 승인 경계에 해당하면 반드시 명시 승인 후에만 진행합니다.
+> ✅ 승인 대기 상태에서는 응답 형식이 항상 `<라벨>` 또는 `<라벨> OK` 형식(예: `A`, `A OK`)입니다.
 
 | 작업 | 확인 시점 | 공유 내용 |
 | --- | --- | --- |
@@ -22,8 +22,9 @@
 
 확인 절차:
 1. 작업 내용을 먼저 공유
-2. 명시적 승인(OK) 대기
-3. 승인 후 실행 (명령 실행은 기본적으로 `npx lee-spec-kit flow <featureRef> --approve <LABEL> --execute`를 사용)
+2. 최신 `context --json-compact` 기준으로 승인 대기 여부(`approvalRequest.required`) 확인
+3. 승인 대기 상태면 CLI가 준 승인 문구 그대로 라벨 응답을 기다리고, 비승인 상태면 별도 승인 문구를 만들지 않음
+4. 승인 후 실행 (명령 실행은 기본적으로 `npx lee-spec-kit flow <featureRef> --approve <LABEL> --execute`를 사용)
 
 금지:
 - 사용자 응답 없이 임의 진행

package/templates/ko/common/agents/skills/create-pr.md

@@ -149,7 +149,7 @@ echo \"![](https://github.com/${REPO}/releases/download/${TAG}/ui-1.png)\"
 
 > 🚨 **사용자 확인 필수**
 
-PR 생성 전 다음 내용을 **코드블록으로** 사용자에게 공유하고 **명시적 승인(OK)** 대기:
+PR 생성 전 다음 내용을 **코드블록으로** 사용자에게 공유하고, 승인 대기 상태면 CLI가 준 `<라벨>` 또는 `<라벨> OK` 응답을 기다리세요:
 
 - 제목
 - 본문 전체 템플릿 (`pr.md` 기준)

package/templates/ko/common/agents/skills/execute-task.md

@@ -81,13 +81,13 @@ CLI가 가리키는 **Active Task** 또는 **`👉 Next Options (Atomic)`의 단
 
 #### 3-2) 태스크/체크리스트 업데이트 + 커밋
 
-1. 작업이 끝나면 결과/검증을 공유하고, 승인 대기(`approvalRequest.required=true`) 상태라면 승인(OK) 후 `[DONE]`으로 변경합니다. 이후 `Acceptance/Checklist` 항목을 `[x]`로 체크합니다.
+1. 작업이 끝나면 결과/검증을 공유합니다. 승인 대기(`approvalRequest.required=true`) 상태라면 CLI가 준 승인 문구를 그대로 제시하고 사용자의 `<라벨>` 또는 `<라벨> OK` 응답을 받은 뒤 `[DONE]`으로 변경합니다. 비승인 상태면 별도 승인 문구 없이 `[DONE]`과 `Acceptance/Checklist`를 갱신합니다.
 2. **한 번에 하나의 태스크만** `[DONE]` 처리합니다. (태스크 2개 이상을 한 번에 완료/커밋으로 묶지 않기)
 3. `tasks.md`의 테스트 실행 기록은 명령어별 1개 행만 유지하고, 같은 명령어 재실행 시 날짜/결과를 갱신합니다. (중복 누적 금지, 날짜 형식: 로컬 `YYYY-MM-DD`)
 4. 커밋을 생성합니다 (코드 커밋 + 문서 커밋). 태스크 단위로 커밋이 남아야 합니다.
-   - `context`에 `[확인 필요]`가 보이면, **커밋/푸시 같은 원격 작업은 사용자에게 커밋 메시지/포함 파일을 공유하고 OK를 받은 뒤** 실행합니다.
-5. 모든 태스크가 `[DONE]`가 되면, "완료 조건" 체크리스트를 사용자에게 공유하고 **최종 승인(OK)** 을 받은 뒤 체크합니다. (특히 **최종 사용자 승인(OK) 완료** 항목)
-   - 참고: `문서 상태(Review→Approved)`는 **진행 승인(OK)** 이고, 완료 조건의 승인은 **최종 승인(OK)** 입니다.
+   - `context`에 `[확인 필요]`가 보이면, **커밋/푸시 같은 원격 작업은 사용자에게 커밋 메시지/포함 파일을 공유한 뒤 최신 CLI 승인 문구의 라벨 응답을 받은 후** 실행합니다.
+5. 모든 태스크가 `[DONE]`가 되면, "완료 조건" 체크리스트를 사용자에게 공유합니다. 이 시점이 승인 대기 상태면 `<라벨>` 또는 `<라벨> OK` 응답을 받은 뒤 체크하고, 비승인 상태면 일반 확인 응답을 받은 뒤 체크합니다. (특히 **최종 사용자 승인 완료** 항목)
+   - 참고: 진행 승인/최종 승인은 모두 현재 `approvalRequest.required` 상태를 기준으로 판단합니다. 라벨 승인 상태면 항상 라벨 응답을 사용하고, 비승인 상태면 standalone `OK`를 승인 토큰처럼 강제하지 않습니다.
 6. **즉시 1단계로 돌아가** 다음 할 일을 CLI에게 물어봅니다.
 
 ---

package/templates/ko/common/features/README.md

@@ -34,6 +34,9 @@ npx lee-spec-kit feature --component app user-profile
 
 > 💡 CLI는 `feature-base/`에서 템플릿을 복사하고 ID를 자동 채번합니다.
 
+Feature는 PRD → idea → feature 흐름에서 실제 구현을 진행하는 실행 단위입니다.
+여기까지 오기 전에는 요구사항이 `docs/prd/`에 정의되어 있고, 사전 탐색이 필요했다면 `docs/ideas/`에 정리되어 있는 상태를 권장합니다.
+
 ---
 
 ## 기능 ID 규칙
@@ -67,7 +70,7 @@ npx lee-spec-kit status --write
 - `[NON-PRD]`는 refactor, 테스트 전용 작업, tooling, rename, cleanup 같은 내부 구현 작업에만 사용하세요.
 - 변경이 사용자 동작, acceptance criteria, 범위를 바꾸면 PRD를 먼저 갱신하고 태스크도 `[PRD-...]`로 다시 연결하세요.
 - 단, 태스크 문서에서 PRD ID를 임의 생성하지 않습니다. 먼저 PRD 원문에 정의하고, 레거시 문서는 원문 ID backfill 후 연결하세요.
-- 커버리지 리포트: `npx lee-spec-kit requirements` (alias: `npx lee-spec-kit prd`)
+- 커버리지 리포트: `npx lee-spec-kit requirements`
 
 ---
 

package/templates/ko/common/ideas/README.md

@@ -4,6 +4,8 @@ Feature로 발전하기 전의 아이디어 / To-do / 실험 기록을 모아두
 
 핵심 원칙: **Feature로 승격되면 SSOT는 `docs/features/`로 이동**합니다.
 
+기본 흐름은 PRD가 요구사항을 정의하고, Idea가 후보/범위를 정리하고, Feature가 실제 실행 단위가 되는 구조입니다.
+
 ---
 
 ## 작성 규칙

package/templates/ko/common/prd/README.md

@@ -2,6 +2,9 @@
 
 이 폴더에는 제품 요구사항 문서를 작성합니다.
 
+이 공간은 `lee-spec-kit init`이 만들어 주는 상위 요구사항 영역입니다.
+먼저 여기에서 PRD를 작성하고, 이후 idea와 feature 문서가 이 요구사항을 참조하도록 연결하세요.
+
 > **📌 문서 범위**
 >
 > - **이 폴더**: 제품 요구사항, 비즈니스 로직, 사용자 스토리
@@ -13,6 +16,14 @@
 2. 주요 기능과 사용자 스토리를 작성하세요
 3. 기술 아키텍처 개요를 포함하세요
 
+## Ideas / Features와의 관계
+
+- `docs/prd/`: 요구사항 원문 정의
+- `docs/ideas/`: 요구사항에서 나온 후보/실험 정리
+- `docs/features/`: 승인된 작업을 feature 단위로 실행
+
+PRD에서 시작한 작업이라면, 이후 문서에서도 `PRD Refs`와 태스크 태그를 통해 연결이 계속 보이도록 유지하세요.
+
 ## 요구사항 ID 규칙 (권장)
 
 PRD의 “어느 요구사항이 구현됐는지”를 CLI가 집계할 수 있도록, 요구사항에 **안정적인 ID**를 부여하세요.