lee-spec-kit 0.4.11 → 0.4.13

package/package.json

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

package/templates/en/common/agents/pr-template.md

@@ -42,15 +42,17 @@ For file links within the repo in PR body, **always use current branch name**:
 
 ## Tests
 
-> ⚠️ **Check only after running tests. Do NOT check items that were not executed.**
+> ⚠️ Add **only the tests you actually ran** below, and ensure **all items are checked ([x])**.  
+> Do not include tests you didn’t run.
 
-- [ ] Unit tests passed
-- [ ] Integration tests completed
+### Tests Run
 
-### Execution Results
+- [x] `{test command 1}` — PASS
+- [x] `{test command 2}` — PASS
 
-- Command: `{test command executed}`
-- Result: `{PASS/FAIL summary}`
+### Notes (Optional)
+
+- {extra context or links to logs}
 
 > - If this includes UI changes, include **screenshots**.
 > - If this includes logic/structure changes, include a **diagram**.
@@ -64,7 +66,10 @@ For file links within the repo in PR body, **always use current branch name**:
 ## Architecture Diagram (Backend / core structure changes)
 
 ```mermaid
-flowchart LR
+flowchart TD
+  %% Guidelines:
+  %% - Focus on components/modules/data flow (structure/flow)
+  %% - Keep it small (≤ 12 nodes recommended); summarize/split if needed
   A[Client] --> B[API]
   B --> C[DB]
 ```
@@ -105,6 +110,9 @@ gh pr create \
 
 After all reviews are resolved:
 
+> ⚠️ Merging (`git merge`/`gh pr merge`) and creating merge commits are considered **remote git operations**.
+> Before running these commands, share the changes with the user and proceed only after the user replies with exactly `OK`.
+
 ```bash
 # Update main before merge
 git checkout main

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

@@ -50,7 +50,7 @@ After completing the action, go back to Step 1 and run `context` again.
 5. Create feature branch
 6. Write `plan.md`
 7. Get `plan.md` approved
-8. Write/execute `tasks.md`
+8. Write/approve/execute `tasks.md` (Doc Status: Review → Approved)
 9. Pre-commit verification
 10. Commit docs
 

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

@@ -32,8 +32,8 @@ Guide for creating Pull Requests.
 
 1. Run relevant test commands (e.g., `npm test`, `pnpm test`); if no tests exist, request them from the user
 2. Check results (PASS/FAIL)
-3. Record **execution results** in the "Tests" section of PR body
-4. All checkboxes must be checked
+3. In the PR body "Tests" section, add **only the tests you actually ran** as checklist items and ensure they are **all checked ([x])** (do not include unexecuted tests)
+4. If you didn’t run any tests, request/confirm with the user before creating the PR
 
 ### 3. Prepare Screenshots / Diagrams (Include in PR Body)
 
@@ -47,6 +47,15 @@ Include the artifacts in the PR body.
 - Use `agent-browser` to generate screenshots.
 - Save files under a local temp folder (`/tmp/lee-spec-kit/pr-assets/`).
 - Upload them as Release assets, then put the image URLs into the "Screenshots" section of the PR body.
+- Before uploading, **open the image file** and verify, then ask the user to validate before PR creation:
+  - It is not a login/permission/error/blank page
+  - The PR-relevant change is actually visible
+  - No sensitive info is exposed (prod tokens/PII/internal URLs)
+
+> If the page requires auth, request one of the following from the user before taking screenshots:
+> - A preview URL that is accessible **without login** (dev-only bypass is OK)
+> - A **test account** (no real accounts / no production tokens) + login instructions
+> - A reproducible route with seeded/dummy data
 
 ```bash
 # (one-time) install agent-browser
@@ -67,6 +76,11 @@ agent-browser open "$PREVIEW_URL"
 agent-browser screenshot /tmp/lee-spec-kit/pr-assets/ui-1.png --full
 agent-browser close
 
+# (required) open and validate the screenshot (re-capture if login/error/blank)
+ls -lh /tmp/lee-spec-kit/pr-assets/ui-1.png
+# macOS: open /tmp/lee-spec-kit/pr-assets/ui-1.png
+# Linux: xdg-open /tmp/lee-spec-kit/pr-assets/ui-1.png
+
 # (recommended) stop the dev server you started for screenshots
 kill \"$DEV_PID\" >/dev/null 2>&1 || true
 ```
@@ -87,7 +101,10 @@ echo \"![](https://github.com/${REPO}/releases/download/${TAG}/ui-1.png)\"
 
 #### Logic/structure changes (Backend PR)
 
-- Write a Mermaid diagram (flowchart/sequence/etc.) in the PR body (see the "Architecture Diagram" section in `pr-template.md`).
+- Write a Mermaid diagram in the PR body (see the "Architecture Diagram" section in `pr-template.md`).
+- Default to **`flowchart TD`** (CodeRabbit-style).
+- Focus on components/modules/data flow (structure/flow over implementation detail).
+- Keep it small: **≤ 12 nodes** recommended (summarize or split if it gets too big).
 
 ### 4. Request User Approval
 

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

@@ -21,6 +21,7 @@ Execute the `👉 Next Action` exactly as printed by the CLI.
 
 - If the CLI points to an active task, focus on that task only.
 - If there is no active task, **share the task title and get user approval (OK)**, then switch the next `[TODO]` task to `[DOING]` and start.
+- For **[DOING] → [DONE]**: before marking it `[DONE]`, **share the outcome/changes/verification (including tests)** and get user approval (OK). (Do not mark DONE first.)
 - If the CLI prints commands, copy/paste them. (In standalone setups commands may include `git -C ...` and scopes like `project`/`docs`.)
 
 ### Step 3: Update tasks.md (only what you did)
@@ -33,8 +34,10 @@ Keep `tasks.md` aligned with reality.
 ### Step 3.25: Commit per task (important)
 
 - Complete **only one task at a time** (do not batch-finish multiple tasks in one commit).
-- After marking a task `[DONE]` (and updating any checklist items), create commits (code commit + docs commit) so each task has its own history.
-- Once all tasks are `[DONE]`, share the "Completion Criteria" checklist with the user and get approval (OK), then check it (especially the **User approval (OK) received** item).
+- After you share the outcome/verification and get approval (OK), mark the task `[DONE]` (and update any checklist items), then create commits (code commit + docs commit) so each task has its own history.
+- 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)**.
 
 ### Step 3.5: Record decisions (strongly recommended, effectively required)
 

package/templates/en/fullstack/README.md

@@ -31,6 +31,7 @@ When you run `lee-spec-kit init`, it creates `.lee-spec-kit.json` in the docs ro
 - `docsRepo` ("embedded" | "standalone"): How docs are managed
 - `pushDocs` (boolean, optional): Only written when `docsRepo: "standalone"` (whether to push to remote)
 - `docsRemote` (string, optional): Only written when `pushDocs: true` (remote repo URL)
+- `approval` (object, optional): Override `[CHECK required]` / `requiresUserCheck` policy in `context` output (approval token: `OK`)
 
 ### Examples
 
@@ -40,7 +41,8 @@ When you run `lee-spec-kit init`, it creates `.lee-spec-kit.json` in the docs ro
   "projectType": "fullstack",
   "lang": "en",
   "createdAt": "{{date}}",
-  "docsRepo": "embedded"
+  "docsRepo": "embedded",
+  "approval": { "mode": "builtin" }
 }
 ```
 
@@ -52,6 +54,7 @@ When you run `lee-spec-kit init`, it creates `.lee-spec-kit.json` in the docs ro
   "createdAt": "{{date}}",
   "docsRepo": "standalone",
   "pushDocs": true,
-  "docsRemote": "git@github.com:org/{{projectName}}-docs.git"
+  "docsRemote": "git@github.com:org/{{projectName}}-docs.git",
+  "approval": { "mode": "builtin" }
 }
 ```

package/templates/en/fullstack/agents/agents.md

@@ -8,6 +8,7 @@ Operating rules for AI code assistants to perform consistent code generation and
 
 > ⚠️ **The following actions require explicit user approval (OK) before proceeding.**
 > **If approval is not given, stop immediately and request confirmation.**
+> ✅ “OK” means the user replies with exactly `OK`.
 
 | Action                | When to Confirm          | What to Share             |
 | --------------------- | ------------------------ | ------------------------- |
@@ -17,7 +18,7 @@ Operating rules for AI code assistants to perform consistent code generation and
 | Issue Creation        | Before `gh issue create` | Title, body, labels       |
 | PR Creation           | Before `gh pr create`    | Title, body, labels       |
 | Assignee Change       | When assigning others    | Target username           |
-| Remote Git Operations | Before `push`, `merge`   | Branch, changes           |
+| Remote Git Operations | Before `push`, `merge` (including merge commits) | Branch, changes           |
 
 ### Approval Process
 

package/templates/en/fullstack/features/feature-base/plan.md

@@ -9,7 +9,7 @@
 - **Feature ID**: F{number}
 - **Target Repo**: {{projectName}}-{be|fe}
 - **Created**: YYYY-MM-DD
-- **Status**: Draft | Review | Approved
+- **Status**: Review | Approved
 
 ---
 

package/templates/en/fullstack/features/feature-base/spec.md

@@ -11,7 +11,7 @@
 - **Target Repo**: {{projectName}}-{be|fe}
 - **Issue Number**: #{issue-number}
 - **Created**: YYYY-MM-DD
-- **Status**: Draft | Review | Approved
+- **Status**: Review | Approved
 
 ---
 

package/templates/en/fullstack/features/feature-base/tasks.md

@@ -3,19 +3,23 @@
 ## Task Rules
 
 - **Status**: `[TODO]` → `[DOING]` → `[DONE]`
+- **Approvals**:
+  - `[TODO] → [DOING]`: share task title first + user approval (OK)
+  - `[DOING] → [DONE]`: share result/verification first + user approval (OK)
 - **Priority**: P0(urgent) > P1(high) > P2(medium) > P3(low)
 
 ---
 
 ## GitHub Issue
 
+- **Doc Status**: Review | Approved
 - **Repo**: {{projectName}}-{be|fe}
 - **Issue**: #{issue-number}
 - **Branch**: `feat/{issue-number}-{feature-name}`
 - **PR**: -
   - Example: `#123` or PR URL
 - **PR Status**: -
-  - Values: Draft | Review | Approved
+  - Values: Review | Approved
 
 ---
 
@@ -23,11 +27,16 @@
 
 ### Phase 1: {Phase Name}
 
+> Add tasks below. **At least 1 task is required.**
+> Copy and use the format below.
+
+```markdown
 - [TODO][P1] T-F{number}-01 {Task Title}
   - Acceptance:
     - (verification condition)
   - Checklist:
     - [ ] (subtask)
+```
 
 ---
 
@@ -37,7 +46,7 @@
 
 - [ ] All tasks are `[DONE]`, and each task's `Acceptance` is verified and `Checklist` is checked
 - [ ] Tests executed and passing (record command/result below)
-- [ ] User approval (OK) received
+- [ ] Final user approval (OK) received (review the outcome)
 
 ### Test Run Log
 

package/templates/en/single/README.md

@@ -30,6 +30,7 @@ When you run `lee-spec-kit init`, it creates `.lee-spec-kit.json` in the docs ro
 - `docsRepo` ("embedded" | "standalone"): How docs are managed
 - `pushDocs` (boolean, optional): Only written when `docsRepo: "standalone"` (whether to push to remote)
 - `docsRemote` (string, optional): Only written when `pushDocs: true` (remote repo URL)
+- `approval` (object, optional): Override `[CHECK required]` / `requiresUserCheck` policy in `context` output (approval token: `OK`)
 
 ### Examples
 
@@ -39,7 +40,8 @@ When you run `lee-spec-kit init`, it creates `.lee-spec-kit.json` in the docs ro
   "projectType": "single",
   "lang": "en",
   "createdAt": "{{date}}",
-  "docsRepo": "embedded"
+  "docsRepo": "embedded",
+  "approval": { "mode": "builtin" }
 }
 ```
 
@@ -51,6 +53,7 @@ When you run `lee-spec-kit init`, it creates `.lee-spec-kit.json` in the docs ro
   "createdAt": "{{date}}",
   "docsRepo": "standalone",
   "pushDocs": true,
-  "docsRemote": "git@github.com:org/{{projectName}}-docs.git"
+  "docsRemote": "git@github.com:org/{{projectName}}-docs.git",
+  "approval": { "mode": "builtin" }
 }
 ```

package/templates/en/single/agents/agents.md

@@ -8,6 +8,7 @@ Operating rules for AI code assistants to perform consistent code generation and
 
 > ⚠️ **The following actions require explicit user approval (OK) before proceeding.**
 > **If approval is not given, stop immediately and request confirmation.**
+> ✅ “OK” means the user replies with exactly `OK`.
 
 | Action                | When to Confirm          | What to Share             |
 | --------------------- | ------------------------ | ------------------------- |
@@ -17,7 +18,7 @@ Operating rules for AI code assistants to perform consistent code generation and
 | Issue Creation        | Before `gh issue create` | Title, body, labels       |
 | PR Creation           | Before `gh pr create`    | Title, body, labels       |
 | Assignee Change       | When assigning others    | Target username           |
-| Remote Git Operations | Before `push`, `merge`   | Branch, changes           |
+| Remote Git Operations | Before `push`, `merge` (including merge commits) | Branch, changes           |
 
 ### Approval Process
 

package/templates/en/single/features/feature-base/plan.md

@@ -9,7 +9,7 @@
 - **Feature ID**: F{number}
 - **Target Repo**: {{projectName}}
 - **Created**: YYYY-MM-DD
-- **Status**: Draft | Review | Approved
+- **Status**: Review | Approved
 
 ---
 

package/templates/en/single/features/feature-base/spec.md

@@ -11,7 +11,7 @@
 - **Target Repo**: {{projectName}}
 - **Issue Number**: #{issue-number}
 - **Created**: YYYY-MM-DD
-- **Status**: Draft | Review | Approved
+- **Status**: Review | Approved
 
 ---
 

package/templates/en/single/features/feature-base/tasks.md

@@ -3,19 +3,23 @@
 ## Task Rules
 
 - **Status**: `[TODO]` → `[DOING]` → `[DONE]`
+- **Approvals**:
+  - `[TODO] → [DOING]`: share task title first + user approval (OK)
+  - `[DOING] → [DONE]`: share result/verification first + user approval (OK)
 - **Priority**: P0(urgent) > P1(high) > P2(medium) > P3(low)
 
 ---
 
 ## GitHub Issue
 
+- **Doc Status**: Review | Approved
 - **Repo**: {{projectName}}
 - **Issue**: #{issue-number}
 - **Branch**: `feat/{issue-number}-{feature-name}`
 - **PR**: -
   - Example: `#123` or PR URL
 - **PR Status**: -
-  - Values: Draft | Review | Approved
+  - Values: Review | Approved
 
 ---
 
@@ -23,11 +27,16 @@
 
 ### Phase 1: {Phase Name}
 
+> Add tasks below. **At least 1 task is required.**
+> Copy and use the format below.
+
+```markdown
 - [TODO][P1] T-F{number}-01 {Task Title}
   - Acceptance:
     - (verification condition)
   - Checklist:
     - [ ] (subtask)
+```
 
 ---
 
@@ -37,7 +46,7 @@
 
 - [ ] All tasks are `[DONE]`, and each task's `Acceptance` is verified and `Checklist` is checked
 - [ ] Tests executed and passing (record command/result below)
-- [ ] User approval (OK) received
+- [ ] Final user approval (OK) received (review the outcome)
 
 ### Test Run Log
 

package/templates/ko/common/agents/pr-template.md

@@ -40,15 +40,17 @@ PR 본문에서 레포 내 파일 링크는 **반드시 현재 브랜치명을
 
 ## 테스트
 
-> ⚠️ **실제 테스트 실행 후 체크하세요. 미실행 항목은 체크하지 마세요.**
+> ⚠️ **실제로 실행한 테스트만** 아래에 항목을 추가하고, **모두 체크([x])** 하세요.  
+> 미실행 테스트는 항목을 만들지 않습니다.
 
-- [ ] 유닛 테스트 통과
-- [ ] 통합 테스트 완료
+### 실행한 테스트
 
-### 실행 결과
+- [x] `{테스트 명령어 1}` — PASS
+- [x] `{테스트 명령어 2}` — PASS
 
-- 명령어: `{실행한 테스트 명령어}`
-- 결과: `{PASS/FAIL 요약}`
+### 로그/비고 (선택)
+
+- {추가 설명 또는 로그 링크}
 
 > - UI 변경에 해당된다면 **스크린샷을** 포함하세요.
 > - 로직/구조 변경에 해당된다면 **다이어그램을** 포함하세요.
@@ -62,7 +64,10 @@ PR 본문에서 레포 내 파일 링크는 **반드시 현재 브랜치명을
 ## 아키텍처 다이어그램 (백엔드 / 핵심 구조 변경 시)
 
 ```mermaid
-flowchart LR
+flowchart TD
+  %% 가이드:
+  %% - 컴포넌트/모듈/데이터 흐름 중심 (구조/흐름)
+  %% - 노드 수 12개 이내 권장 (너무 크면 핵심만 남기고 요약/분리)
   A[Client] --> B[API]
   B --> C[DB]
 ```
@@ -103,6 +108,9 @@ gh pr create \
 
 모든 리뷰 해결 시:
 
+> ⚠️ 머지(`git merge`/`gh pr merge`) 및 머지 커밋 생성은 **Git 원격 작업**에 해당합니다.
+> 실행 전 변경 사항을 사용자에게 공유하고, 사용자가 **정확히 `OK`**라고 답한 뒤에만 진행하세요.
+
 ```bash
 # 머지 전 main 최신화
 git checkout main

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

@@ -45,13 +45,13 @@ CLI가 출력하는 **`👉 Next Action` 메시지를 읽고, 그 지시만 정
 > ⚠️ 이 단계를 외워서 실행하지 마세요. **참조용**일 뿐입니다. 항상 CLI를 믿으세요.
 
 1. **Feature 폴더 생성**: `npx lee-spec-kit feature ...`
-2. **spec.md 작성**: 기능 정의 (Status: Draft)
+2. **spec.md 작성**: 기능 정의 (작성 후 Status: Review로 설정)
 3. **spec.md 승인**: 사용자 검토 및 승인 (Status: Approved)
 4. **GitHub Issue 생성**: 이슈 번호 발급
 5. **브랜치 생성**: `git checkout -b feat/...`
-6. **plan.md 작성**: 구현 계획 (Status: Draft)
+6. **plan.md 작성**: 구현 계획 (작성 후 Status: Review로 설정)
 7. **plan.md 승인**: 사용자 검토 및 승인 (Status: Approved)
-8. **tasks.md 작성/실행**: 태스크 분해 및 진행
+8. **tasks.md 작성/승인**: 태스크 분해 및 진행 (문서 상태: Review → Approved)
 9. **문서 커밋 전 확인**: 최종 점검
 10. **문서 커밋**: Docs Sync
 

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

@@ -32,8 +32,8 @@ Pull Request를 생성할 때 따르는 가이드입니다.
 
 1. 작업과 관련된 테스트 명령어 실행 (예: `npm test`, `pnpm test`), 테스트가 없는 경우 사용자에게 요청
 2. 결과 확인 (PASS/FAIL)
-3. PR 본문 "테스트" 섹션에 **실행 결과** 기록
-4. 모든 체크박스가 체크되어야 함
+3. PR 본문 "테스트" 섹션에 **실행한 테스트만** 체크리스트로 추가하고, **모두 체크([x])** 합니다. (미실행 항목은 작성하지 않기)
+4. 테스트를 실행하지 않았다면, PR 생성 전에 사용자에게 요청/확인합니다.
 
 ### 3. 스크린샷/다이어그램 작성 (PR 본문에 포함)
 
@@ -47,6 +47,15 @@ PR 본문에 결과물을 포함합니다.
 - `agent-browser`로 스크린샷을 생성합니다.
 - 스크린샷 파일은 로컬 임시 폴더(`/tmp/lee-spec-kit/pr-assets/`)에 저장합니다.
 - 릴리스 자산(Release assets)으로 업로드한 뒤, 생성된 이미지 URL을 PR 본문 "스크린샷" 섹션에 넣습니다.
+- 스크린샷을 업로드하기 전에 **이미지 파일을 직접 열어** 다음을 확인하고, PR 생성 전 사용자에게도 검증받습니다.
+  - 로그인 화면/권한 오류/에러 화면/빈 화면이 아닌지
+  - 이번 PR의 변경 사항이 실제로 보이는지
+  - 민감 정보(실서비스 토큰/개인정보/내부 URL)가 노출되지 않았는지
+
+> 로그인/권한이 필요한 화면이라면, 스크린샷을 찍기 전에 사용자에게 아래 중 하나를 요청하세요.
+> - 개발 서버에서 **로그인 없이** 접근 가능한 미리보기 URL 제공 (dev-only bypass 포함)
+> - **테스트 계정** 제공(실계정/실서비스 토큰 금지) + 로그인 절차 안내
+> - 시드 데이터/더미 데이터로 재현 가능한 경로 제공
 
 ```bash
 # (최초 1회) agent-browser 설치
@@ -67,6 +76,11 @@ agent-browser open "$PREVIEW_URL"
 agent-browser screenshot /tmp/lee-spec-kit/pr-assets/ui-1.png --full
 agent-browser close
 
+# (필수) 스크린샷 파일을 열어 검증 (로그인/에러/빈 화면이면 재촬영)
+ls -lh /tmp/lee-spec-kit/pr-assets/ui-1.png
+# macOS: open /tmp/lee-spec-kit/pr-assets/ui-1.png
+# Linux: xdg-open /tmp/lee-spec-kit/pr-assets/ui-1.png
+
 # (권장) 스크린샷을 위해 띄운 개발 서버는 작업이 끝나면 종료합니다.
 kill \"$DEV_PID\" >/dev/null 2>&1 || true
 ```
@@ -87,7 +101,10 @@ echo \"![](https://github.com/${REPO}/releases/download/${TAG}/ui-1.png)\"
 
 #### 로직/구조 변경 (백엔드 PR)
 
-- PR 본문에 Mermaid 다이어그램(예: flowchart/sequence)을 작성합니다. (`pr-template.md`의 "아키텍처 다이어그램" 섹션 참고)
+- PR 본문에 Mermaid 다이어그램을 작성합니다. (`pr-template.md`의 "아키텍처 다이어그램" 섹션 참고)
+- 기본은 **`flowchart TD`** 를 사용합니다. (코드래빗 스타일)
+- 컴포넌트/모듈/데이터 흐름 중심으로 그립니다. (구현 디테일보다 “구조/흐름”)
+- 노드 수는 **12개 이내**를 권장합니다. (너무 크면 핵심만 남기고 분리/요약)
 
 ### 4. 사용자 확인 요청
 

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

@@ -9,7 +9,7 @@
 
 모든 태스크가 완료될 때까지(`[DONE]`) 다음 과정을 **계속 반복**하세요.
 
-### 1단계: 할 일 확인 (Check)
+### 1단계: 할 일 확인
 
 작업을 시작하거나 하나를 마칠 때마다 **반드시** 아래 명령어를 실행합니다.
 
@@ -23,7 +23,7 @@ CLI가 가리키는 **Active Task** 또는 **Next Action**을 수행합니다.
 
 - **[DOING] 상태인 태스크가 있다면**: 해당 태스크를 최우선으로 완료하세요.
 - **[DOING]이 없다면**: CLI가 추천하는 다음 태스크(`[TODO]`)를 시작하기 전에, **태스크 제목을 공유하고 사용자 승인(OK)을 받은 뒤** `[DOING]`으로 변경하세요.
-- **완료 조건(Acceptance)을 검증**하고, 테스트를 통과해야만 완료(`[DONE]`) 처리합니다.
+- **[DOING] → [DONE]**: 완료 처리 전에 **결과물/변경 사항/검증(테스트 포함)을 공유**하고 사용자 승인(OK)을 받은 뒤 `[DONE]`으로 변경하세요. (DONE으로 “먼저” 바꾸지 않기)
 - CLI가 명령어를 출력하면 **그대로 복사해 실행**합니다. (standalone 환경에서도 레포 경로가 포함될 수 있습니다)
 
 ### 3단계: 기록 및 반복 (Record & Loop)
@@ -46,10 +46,12 @@ CLI가 가리키는 **Active Task** 또는 **Next Action**을 수행합니다.
 
 #### 3-2) 태스크/체크리스트 업데이트 + 커밋
 
-1. 작업이 끝나면 해당 태스크의 상태를 `[DONE]`으로 변경하고, `Acceptance/Checklist` 항목을 `[x]`로 체크합니다.
+1. 작업이 끝나면 결과/검증을 사용자에게 공유해 승인(OK)을 받은 뒤, 해당 태스크의 상태를 `[DONE]`으로 변경하고 `Acceptance/Checklist` 항목을 `[x]`로 체크합니다.
 2. **한 번에 하나의 태스크만** `[DONE]` 처리합니다. (태스크 2개 이상을 한 번에 완료/커밋으로 묶지 않기)
 3. 커밋을 생성합니다 (코드 커밋 + 문서 커밋). 태스크 단위로 커밋이 남아야 합니다.
-4. 모든 태스크가 `[DONE]`가 되면, "완료 조건" 체크리스트를 사용자에게 공유하고 승인(OK)을 받은 뒤 체크합니다. (특히 **사용자 승인(OK) 완료** 항목)
+   - `context`에 `[확인 필요]`가 보이면, **커밋/푸시 같은 원격 작업은 사용자에게 커밋 메시지/포함 파일을 공유하고 OK를 받은 뒤** 실행합니다.
+4. 모든 태스크가 `[DONE]`가 되면, "완료 조건" 체크리스트를 사용자에게 공유하고 **최종 승인(OK)** 을 받은 뒤 체크합니다. (특히 **최종 사용자 승인(OK) 완료** 항목)
+   - 참고: `문서 상태(Review→Approved)`는 **진행 승인(OK)** 이고, 완료 조건의 승인은 **최종 승인(OK)** 입니다.
 5. **즉시 1단계로 돌아가** 다음 할 일을 CLI에게 물어봅니다.
 
 ---
@@ -67,7 +69,7 @@ CLI가 가리키는 **Active Task** 또는 **Next Action**을 수행합니다.
 > ⚠️ 직접 판단하지 말고 CLI가 시키는 대로 하세요.
 
 1. **[TODO] → [DOING]**: 작업 시작 시 표시
-2. **[DOING] → [DONE]**: 테스트 통과 및 사용자 승인 후 표시
+2. **[DOING] → [DONE]**: 결과/검증 공유 + 사용자 승인(OK) 후 표시 (테스트 통과 포함)
 
 ```markdown
 - [DONE] T-01: 로그인 UI (완료됨)

package/templates/ko/fullstack/README.md

@@ -31,6 +31,7 @@
 - `docsRepo` ("embedded" | "standalone"): Docs 관리 방식
 - `pushDocs` (boolean, optional): `docsRepo: "standalone"`일 때만 생성 (원격 push 여부)
 - `docsRemote` (string, optional): `pushDocs: true`일 때만 생성 (원격 레포 URL)
+- `approval` (object, optional): `context` 출력의 `[확인 필요]` / `requiresUserCheck` 정책 오버라이드 (승인 토큰: `OK`)
 
 ### 예시
 
@@ -40,7 +41,8 @@
   "projectType": "fullstack",
   "lang": "ko",
   "createdAt": "{{date}}",
-  "docsRepo": "embedded"
+  "docsRepo": "embedded",
+  "approval": { "mode": "builtin" }
 }
 ```
 
@@ -52,6 +54,7 @@
   "createdAt": "{{date}}",
   "docsRepo": "standalone",
   "pushDocs": true,
-  "docsRemote": "git@github.com:org/{{projectName}}-docs.git"
+  "docsRemote": "git@github.com:org/{{projectName}}-docs.git",
+  "approval": { "mode": "builtin" }
 }
 ```

package/templates/ko/fullstack/agents/agents.md

@@ -8,6 +8,7 @@
 
 > ⚠️ **아래 작업은 반드시 사용자의 명시적 승인(OK)을 받은 후에만 진행합니다.**
 > **확인 없이 진행 시 작업을 즉시 중단해야 합니다.**
+> ✅ 승인(OK)은 사용자가 **정확히 `OK`**라고 답하는 것을 의미합니다.
 
 | 작업          | 확인 시점            | 공유 내용                   |
 | ------------- | -------------------- | --------------------------- |
@@ -17,7 +18,7 @@
 | 이슈 생성     | `gh issue create` 전 | 제목, 본문, 라벨            |
 | PR 생성       | `gh pr create` 전    | 제목, 본문, 라벨            |
 | Assignee 변경 | 본인 외 지정 시      | 대상 사용자명               |
-| Git 원격 작업 | `push`, `merge` 전   | 브랜치, 변경 사항           |
+| Git 원격 작업 | `push`, `merge` 전 (머지 커밋 포함) | 브랜치, 변경 사항           |
 
 ### 확인 프로세스
 

package/templates/ko/fullstack/features/feature-base/plan.md

@@ -9,7 +9,7 @@
 - **기능 ID**: F{번호}
 - **대상 레포**: {{projectName}}-{be|fe}
 - **작성일**: YYYY-MM-DD
-- **상태**: Draft | Review | Approved
+- **상태**: Review | Approved
 
 ---
 

package/templates/ko/fullstack/features/feature-base/spec.md

@@ -11,7 +11,7 @@
 - **대상 레포**: {{projectName}}-{be|fe}
 - **이슈 번호**: #{이슈번호}
 - **작성일**: YYYY-MM-DD
-- **상태**: Draft | Review | Approved
+- **상태**: Review | Approved
 
 ---
 

package/templates/ko/fullstack/features/feature-base/tasks.md

@@ -3,19 +3,23 @@
 ## 태스크 규칙
 
 - **상태**: `[TODO]` → `[DOING]` → `[DONE]`
+- **승인**:
+  - `[TODO] → [DOING]`: 시작 전 태스크 제목 공유 + 사용자 승인(OK)
+  - `[DOING] → [DONE]`: 완료 전 결과/검증 공유 + 사용자 승인(OK)
 - **우선순위**: P0(긴급) > P1(높음) > P2(보통) > P3(낮음)
 
 ---
 
 ## GitHub Issue
 
+- **문서 상태**: Review | Approved
 - **레포**: {{projectName}}-{be|fe}
 - **Issue**: #{이슈번호}
 - **브랜치**: `feat/{이슈번호}-{기능명}`
 - **PR**: -
   - 예: `#123` 또는 PR URL
 - **PR 상태**: -
-  - 값: Draft | Review | Approved
+  - 값: Review | Approved
 
 ---
 
@@ -23,11 +27,16 @@
 
 ### Phase 1: {단계명}
 
+> 아래에 태스크를 추가하세요. **최소 1개가 필요**합니다.
+> 아래 포맷을 복사해 사용하세요.
+
+```markdown
 - [TODO][P1] T-F{번호}-01 {태스크 제목}
   - Acceptance:
     - (검증 조건)
   - Checklist:
-    - [ ] (세부 작업)
+    - [ ] (서브 태스크)
+```
 
 ---
 
@@ -37,7 +46,7 @@
 
 - [ ] 모든 태스크가 `[DONE]`이며, 각 태스크의 `Acceptance` 검증 및 `Checklist` 체크 완료
 - [ ] 테스트 실행 및 통과 (아래에 명령어/결과 기록)
-- [ ] 사용자 승인(OK) 완료
+- [ ] 최종 사용자 승인(OK) 완료 (결과물 확인)
 
 ### 테스트 실행 기록