lee-spec-kit 0.4.9 → 0.4.11

package/dist/index.js

@@ -188,10 +188,12 @@ var I18N = {
       planWrite: "plan.md \uC791\uC131",
       planApprove: "plan.md \uC2B9\uC778",
       tasksWrite: "tasks.md \uC791\uC131",
+      docsInitialCommit: "\uCD08\uAE30 \uBB38\uC11C \uCEE4\uBC0B",
       docsCommitPlanning: "\uBB38\uC11C \uCEE4\uBC0B(\uB3D9\uAE30\uD654)",
       issueCreate: "GitHub Issue \uC0DD\uC131",
       branchCreate: "\uBE0C\uB79C\uCE58 \uC0DD\uC131",
       tasksExecute: "\uD0DC\uC2A4\uD06C \uC2E4\uD589",
+      docsCommitSync: "\uBB38\uC11C \uCEE4\uBC0B(\uB3D9\uAE30\uD654)",
       prCreate: "PR \uC0DD\uC131",
       codeReview: "\uCF54\uB4DC \uB9AC\uBDF0",
       featureDone: "Feature \uC644\uB8CC"
@@ -208,6 +210,7 @@ var I18N = {
       docsCommitPlanning: 'cd "{docsGitCwd}" && git add "{featurePath}" && git commit -m "docs(planning): {folderName} \uAE30\uD68D \uBB38\uC11C"',
       issueCreateAndWrite: "GitHub Issue\uB97C \uC0DD\uC131\uD55C \uB4A4, spec.md/tasks.md\uC758 \uC774\uC288 \uBC88\uD638\uB97C \uCC44\uC6B0\uACE0 \uBB38\uC11C \uCEE4\uBC0B\uC744 \uC900\uBE44\uD558\uC138\uC694. (skills/create-issue.md \uCC38\uACE0)",
       docsCommitIssueUpdate: 'cd "{docsGitCwd}" && git add "{featurePath}" && git commit -m "docs(#{issueNumber}): {folderName} \uBB38\uC11C \uC5C5\uB370\uC774\uD2B8"',
+      docsCommitUpdate: 'cd "{docsGitCwd}" && git add "{featurePath}" && git commit -m "docs: {folderName} \uBB38\uC11C \uC5C5\uB370\uC774\uD2B8"',
       standaloneNeedsProjectRoot: "standalone \uBAA8\uB4DC\uC5D0\uC11C\uB294 projectRoot \uC124\uC815\uC774 \uD544\uC694\uD569\uB2C8\uB2E4. (npx lee-spec-kit config --project-root ...)",
       createBranch: 'cd "{projectGitCwd}" && git checkout -b feat/{issueNumber}-{slug}',
       tasksAllDoneButNoChecklist: '\uBAA8\uB4E0 \uD0DC\uC2A4\uD06C\uAC00 DONE\uC774\uC9C0\uB9CC \uC644\uB8CC \uC870\uAC74 \uCCB4\uD06C\uB9AC\uC2A4\uD2B8 \uC139\uC158\uC744 \uCC3E\uC9C0 \uBABB\uD588\uC2B5\uB2C8\uB2E4. tasks.md\uC758 "\uC644\uB8CC \uC870\uAC74" \uC139\uC158\uC744 \uCD94\uAC00/\uD655\uC778\uD558\uC138\uC694.',
@@ -363,10 +366,12 @@ var I18N = {
       planWrite: "Write plan.md",
       planApprove: "Approve plan.md",
       tasksWrite: "Write tasks.md",
+      docsInitialCommit: "Initial docs commit",
       docsCommitPlanning: "Commit docs (sync)",
       issueCreate: "Create GitHub Issue",
       branchCreate: "Create branch",
       tasksExecute: "Execute tasks",
+      docsCommitSync: "Commit docs (sync)",
       prCreate: "Create PR",
       codeReview: "Code review",
       featureDone: "Feature done"
@@ -383,6 +388,7 @@ var I18N = {
       docsCommitPlanning: 'cd "{docsGitCwd}" && git add "{featurePath}" && git commit -m "docs(planning): {folderName} planning docs"',
       issueCreateAndWrite: "Create a GitHub Issue, fill the issue number in spec.md/tasks.md, then prepare a docs commit. (See skills/create-issue.md)",
       docsCommitIssueUpdate: 'cd "{docsGitCwd}" && git add "{featurePath}" && git commit -m "docs(#{issueNumber}): {folderName} docs update"',
+      docsCommitUpdate: 'cd "{docsGitCwd}" && git add "{featurePath}" && git commit -m "docs: {folderName} docs update"',
       standaloneNeedsProjectRoot: "Standalone mode requires projectRoot. (npx lee-spec-kit config --project-root ...)",
       createBranch: 'cd "{projectGitCwd}" && git checkout -b feat/{issueNumber}-{slug}',
       tasksAllDoneButNoChecklist: 'All tasks are DONE, but no completion checklist section was found. Add/verify the "Completion Criteria" section in tasks.md.',
@@ -1234,7 +1240,7 @@ function getStepDefinitions(lang) {
     },
     {
       step: 7,
-      name: tr(lang, "steps", "docsCommitPlanning"),
+      name: tr(lang, "steps", "docsInitialCommit"),
       checklist: {
         done: (f) => f.docs.tasksExists && f.tasks.total > 0 && f.specStatus === "Approved" && f.planStatus === "Approved" && f.git.docsEverCommitted
       },
@@ -1366,6 +1372,26 @@ function getStepDefinitions(lang) {
             ];
           }
           if (f.nextTodoTask) {
+            if (f.git.docsHasUncommittedChanges) {
+              return [
+                {
+                  type: "command",
+                  requiresUserOk: true,
+                  scope: "docs",
+                  cwd: f.git.docsGitCwd,
+                  cmd: f.issueNumber ? tr(lang, "messages", "docsCommitIssueUpdate", {
+                    docsGitCwd: f.git.docsGitCwd,
+                    featurePath: f.docs.featurePathFromDocs,
+                    issueNumber: f.issueNumber,
+                    folderName: f.folderName
+                  }) : tr(lang, "messages", "docsCommitUpdate", {
+                    docsGitCwd: f.git.docsGitCwd,
+                    featurePath: f.docs.featurePathFromDocs,
+                    folderName: f.folderName
+                  })
+                }
+              ];
+            }
             return [
               {
                 type: "instruction",
@@ -1393,6 +1419,34 @@ function getStepDefinitions(lang) {
     },
     {
       step: 11,
+      name: tr(lang, "steps", "docsCommitSync"),
+      checklist: {
+        done: (f) => !f.git.docsHasUncommittedChanges
+      },
+      current: {
+        when: (f) => isImplementationDone(f) && f.git.docsHasUncommittedChanges,
+        actions: (f) => [
+          {
+            type: "command",
+            requiresUserOk: true,
+            scope: "docs",
+            cwd: f.git.docsGitCwd,
+            cmd: f.issueNumber ? tr(lang, "messages", "docsCommitIssueUpdate", {
+              docsGitCwd: f.git.docsGitCwd,
+              featurePath: f.docs.featurePathFromDocs,
+              issueNumber: f.issueNumber,
+              folderName: f.folderName
+            }) : tr(lang, "messages", "docsCommitUpdate", {
+              docsGitCwd: f.git.docsGitCwd,
+              featurePath: f.docs.featurePathFromDocs,
+              folderName: f.folderName
+            })
+          }
+        ]
+      }
+    },
+    {
+      step: 12,
       name: tr(lang, "steps", "prCreate"),
       checklist: { done: (f) => isPrMetadataConfigured(f) && !!f.pr.link },
       current: {
@@ -1418,7 +1472,7 @@ function getStepDefinitions(lang) {
       }
     },
     {
-      step: 12,
+      step: 13,
       name: tr(lang, "steps", "codeReview"),
       checklist: {
         done: (f) => isPrMetadataConfigured(f) && f.pr.status === "Approved"
@@ -1453,7 +1507,7 @@ function getStepDefinitions(lang) {
       }
     },
     {
-      step: 13,
+      step: 14,
       name: tr(lang, "steps", "featureDone"),
       checklist: { done: (f) => isFeatureDone(f) },
       current: {

package/package.json

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

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

@@ -52,14 +52,27 @@ For file links within the repo in PR body, **always use current branch name**:
 - Command: `{test command executed}`
 - Result: `{PASS/FAIL summary}`
 
-## Screenshots (for UI changes)
+> - If this includes UI changes, include **screenshots**.
+> - If this includes logic/structure changes, include a **diagram**.
 
-{Attach if applicable}
+## Screenshots (Frontend / UI changes)
+
+> If you follow the Release assets upload flow in `skills/create-pr.md`, you can include images in the PR body without committing files to your branch.
+
+{Screenshot markdown (e.g. ![](URL))}
+
+## Architecture Diagram (Backend / core structure changes)
+
+```mermaid
+flowchart LR
+  A[Client] --> B[API]
+  B --> C[DB]
+```
 
 ## Related Documents
 
-- **Spec**: `docs/features/{be|fe}/F{number}-{feature-name}/spec.md`
-- **Tasks**: `docs/features/{be|fe}/F{number}-{feature-name}/tasks.md`
+- **Spec**: `{{featurePath}}/F{number}-{feature-name}/spec.md`
+- **Tasks**: `{{featurePath}}/F{number}-{feature-name}/tasks.md`
 
 Closes #{issue-number}
 ```

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

@@ -35,7 +35,61 @@ Guide for creating Pull Requests.
 3. Record **execution results** in the "Tests" section of PR body
 4. All checkboxes must be checked
 
-### 3. Request User Approval
+### 3. Prepare Screenshots / Diagrams (Include in PR Body)
+
+Include the artifacts in the PR body.
+
+> - If this includes UI changes, include **screenshots**.
+> - If this includes logic/structure changes, include a **diagram**.
+
+#### UI changes (Frontend PR)
+
+- 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.
+
+```bash
+# (one-time) install agent-browser
+npm i -g agent-browser
+agent-browser install  # install Playwright browsers
+
+# Start a dev server: ports are often already taken, so prefer a free port.
+# - If you already have a running dev server, you can just set PREVIEW_URL to that URL.
+PORT=$(node -e "const net=require('net');const s=net.createServer();s.listen(0,'127.0.0.1',()=>{console.log(s.address().port);s.close();});")
+# (example) Vite
+pnpm dev --host 127.0.0.1 --port \"$PORT\" >/tmp/lee-spec-kit-dev.log 2>&1 &
+DEV_PID=$!
+PREVIEW_URL=\"http://127.0.0.1:${PORT}\"
+
+# (example) capture from a preview URL
+mkdir -p /tmp/lee-spec-kit/pr-assets
+agent-browser open "$PREVIEW_URL"
+agent-browser screenshot /tmp/lee-spec-kit/pr-assets/ui-1.png --full
+agent-browser close
+
+# (recommended) stop the dev server you started for screenshots
+kill \"$DEV_PID\" >/dev/null 2>&1 || true
+```
+
+```bash
+# Upload to Release assets and generate the URL to paste into the PR body
+REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
+SAFE_BRANCH=$(git branch --show-current | tr '/' '-')
+TAG="pr-assets/${SAFE_BRANCH}"
+
+gh release view "$TAG" >/dev/null 2>&1 || \
+  gh release create "$TAG" --prerelease --title "pr-assets: ${SAFE_BRANCH}" --notes ""
+
+gh release upload "$TAG" /tmp/lee-spec-kit/pr-assets/* --clobber
+
+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`).
+
+### 4. Request User Approval
 
 > 🚨 **User Approval Required**
 
@@ -45,7 +99,7 @@ Before creating PR, share the following **in a code block** and wait for **expli
 - Full body (`pr-template.md` format)
 - Labels
 
-### 4. Create PR
+### 5. Create PR
 
 ```bash
 gh pr create \

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

@@ -30,6 +30,12 @@ Keep `tasks.md` aligned with reality.
 - Do not mark `[DONE]` without actually completing the work and verifying criteria.
 - If you need to change a completed task, add a new task instead of rewriting history.
 
+### 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).
+
 ### Step 3.5: Record decisions (strongly recommended, effectively required)
 
 To avoid “why did we implement it like this?” losing context, **record any non-obvious or tradeoff-heavy implementation choice** in `decisions.md`.

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

@@ -37,6 +37,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
 
 ### Test Run Log
 

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

@@ -37,6 +37,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
 
 ### Test Run Log
 

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

@@ -50,14 +50,27 @@ PR 본문에서 레포 내 파일 링크는 **반드시 현재 브랜치명을
 - 명령어: `{실행한 테스트 명령어}`
 - 결과: `{PASS/FAIL 요약}`
 
-## 스크린샷 (UI 변경 시)
+> - UI 변경에 해당된다면 **스크린샷을** 포함하세요.
+> - 로직/구조 변경에 해당된다면 **다이어그램을** 포함하세요.
 
-{있으면 첨부}
+## 스크린샷 (프론트엔드 / UI 변경 시)
+
+> `skills/create-pr.md`의 Release assets 업로드 절차를 사용하면 브랜치에 파일을 커밋하지 않고도 이미지를 본문에 포함할 수 있습니다.
+
+{스크린샷 마크다운 (예: ![](URL))}
+
+## 아키텍처 다이어그램 (백엔드 / 핵심 구조 변경 시)
+
+```mermaid
+flowchart LR
+  A[Client] --> B[API]
+  B --> C[DB]
+```
 
 ## 관련 문서
 
-- **Spec**: `docs/features/{be|fe}/F{번호}-{기능명}/spec.md`
-- **Tasks**: `docs/features/{be|fe}/F{번호}-{기능명}/tasks.md`
+- **Spec**: `{{featurePath}}/F{번호}-{기능명}/spec.md`
+- **Tasks**: `{{featurePath}}/F{번호}-{기능명}/tasks.md`
 
 Closes #{이슈번호}
 ```

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

@@ -35,7 +35,61 @@ Pull Request를 생성할 때 따르는 가이드입니다.
 3. PR 본문 "테스트" 섹션에 **실행 결과** 기록
 4. 모든 체크박스가 체크되어야 함
 
-### 3. 사용자 확인 요청
+### 3. 스크린샷/다이어그램 작성 (PR 본문에 포함)
+
+PR 본문에 결과물을 포함합니다.
+
+> - UI 변경에 해당된다면 **스크린샷을** 포함하세요.
+> - 로직/구조 변경에 해당된다면 **다이어그램을** 포함하세요.
+
+#### UI 변경 (프론트엔드 PR)
+
+- `agent-browser`로 스크린샷을 생성합니다.
+- 스크린샷 파일은 로컬 임시 폴더(`/tmp/lee-spec-kit/pr-assets/`)에 저장합니다.
+- 릴리스 자산(Release assets)으로 업로드한 뒤, 생성된 이미지 URL을 PR 본문 "스크린샷" 섹션에 넣습니다.
+
+```bash
+# (최초 1회) agent-browser 설치
+npm i -g agent-browser
+agent-browser install  # Playwright 브라우저 설치
+
+# 개발 서버 실행: 이미 사용 중인 포트가 많으므로 "빈 포트"를 권장합니다.
+# - 이미 떠있는 개발 서버가 있다면 그 URL을 PREVIEW_URL로 지정해도 됩니다.
+PORT=$(node -e "const net=require('net');const s=net.createServer();s.listen(0,'127.0.0.1',()=>{console.log(s.address().port);s.close();});")
+# (예시) Vite
+pnpm dev --host 127.0.0.1 --port \"$PORT\" >/tmp/lee-spec-kit-dev.log 2>&1 &
+DEV_PID=$!
+PREVIEW_URL=\"http://127.0.0.1:${PORT}\"
+
+# (예시) 미리보기 URL을 정해 스크린샷 생성
+mkdir -p /tmp/lee-spec-kit/pr-assets
+agent-browser open "$PREVIEW_URL"
+agent-browser screenshot /tmp/lee-spec-kit/pr-assets/ui-1.png --full
+agent-browser close
+
+# (권장) 스크린샷을 위해 띄운 개발 서버는 작업이 끝나면 종료합니다.
+kill \"$DEV_PID\" >/dev/null 2>&1 || true
+```
+
+```bash
+# 스크린샷을 Release assets로 업로드하고, PR 본문에 넣을 URL 만들기
+REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
+SAFE_BRANCH=$(git branch --show-current | tr '/' '-')
+TAG="pr-assets/${SAFE_BRANCH}"
+
+gh release view "$TAG" >/dev/null 2>&1 || \
+  gh release create "$TAG" --prerelease --title "pr-assets: ${SAFE_BRANCH}" --notes ""
+
+gh release upload "$TAG" /tmp/lee-spec-kit/pr-assets/* --clobber
+
+echo \"![](https://github.com/${REPO}/releases/download/${TAG}/ui-1.png)\"
+```
+
+#### 로직/구조 변경 (백엔드 PR)
+
+- PR 본문에 Mermaid 다이어그램(예: flowchart/sequence)을 작성합니다. (`pr-template.md`의 "아키텍처 다이어그램" 섹션 참고)
+
+### 4. 사용자 확인 요청
 
 > 🚨 **사용자 확인 필수**
 
@@ -45,7 +99,7 @@ PR 생성 전 다음 내용을 **코드블록으로** 사용자에게 공유하
 - 본문 전체 (`pr-template.md` 형식)
 - 라벨
 
-### 4. PR 생성
+### 5. PR 생성
 
 ```bash
 gh pr create \

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

@@ -47,8 +47,10 @@ CLI가 가리키는 **Active Task** 또는 **Next Action**을 수행합니다.
 #### 3-2) 태스크/체크리스트 업데이트 + 커밋
 
 1. 작업이 끝나면 해당 태스크의 상태를 `[DONE]`으로 변경하고, `Acceptance/Checklist` 항목을 `[x]`로 체크합니다.
-2. 커밋을 생성합니다 (코드 커밋 + 문서 커밋).
-3. **즉시 1단계로 돌아가** 다음 할 일을 CLI에게 물어봅니다.
+2. **한 번에 하나의 태스크만** `[DONE]` 처리합니다. (태스크 2개 이상을 한 번에 완료/커밋으로 묶지 않기)
+3. 커밋을 생성합니다 (코드 커밋 + 문서 커밋). 태스크 단위로 커밋이 남아야 합니다.
+4. 모든 태스크가 `[DONE]`가 되면, "완료 조건" 체크리스트를 사용자에게 공유하고 승인(OK)을 받은 뒤 체크합니다. (특히 **사용자 승인(OK) 완료** 항목)
+5. **즉시 1단계로 돌아가** 다음 할 일을 CLI에게 물어봅니다.
 
 ---
 

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

@@ -37,6 +37,7 @@
 
 - [ ] 모든 태스크가 `[DONE]`이며, 각 태스크의 `Acceptance` 검증 및 `Checklist` 체크 완료
 - [ ] 테스트 실행 및 통과 (아래에 명령어/결과 기록)
+- [ ] 사용자 승인(OK) 완료
 
 ### 테스트 실행 기록
 

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

@@ -37,6 +37,7 @@
 
 - [ ] 모든 태스크가 `[DONE]`이며, 각 태스크의 `Acceptance` 검증 및 `Checklist` 체크 완료
 - [ ] 테스트 실행 및 통과 (아래에 명령어/결과 기록)
+- [ ] 사용자 승인(OK) 완료
 
 ### 테스트 실행 기록