lee-spec-kit 0.4.8 → 0.4.10

package/README.en.md

@@ -145,6 +145,9 @@ npx lee-spec-kit doctor --json
 
 ### Update templates
 
+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`.
+
 ```bash
 npx lee-spec-kit update
 npx lee-spec-kit update --agents
@@ -176,11 +179,13 @@ Running `init` creates `.lee-spec-kit.json` in your docs root (default: `docs/`)
 | `lang`        | `ko` or `en`                                     |
 | `createdAt`   | Creation date                                    |
 | `docsRepo`    | `embedded` or `standalone`                       |
-| `projectRoot` | (standalone only) path to the project repository |
+| `pushDocs`    | (standalone only) whether to manage/push docs repo as a separate git repo |
+| `docsRemote`  | (standalone + pushDocs) docs repo remote URL |
+| `projectRoot` | (standalone only) project repo path (single: string, fullstack: {fe, be}) |
 
+> In standalone mode, `init` can add `pushDocs`, `docsRemote`, and `projectRoot` to this config.
 > If you run the CLI outside the docs repo in standalone mode, set `LEE_SPEC_KIT_DOCS_DIR` to the docs repo path.
 
 ## Generated Structure
 
 See the Korean README for the full tree examples and workflow details: `README.md`.
-

package/README.md

@@ -177,6 +177,9 @@ npx lee-spec-kit doctor --json
 
 ### 템플릿 업데이트
 
+기본 동작은 `docs/` 작업트리에 변경사항이 없을 때만 업데이트를 진행하며, 이 경우 변경된 파일은 확인 없이 덮어씁니다.  
+변경사항이 있는 상태에서 업데이트하려면 `--force`를 사용하세요.
+
 ```bash
 # 전체 업데이트
 npx lee-spec-kit update
@@ -190,7 +193,7 @@ npx lee-spec-kit update --skills
 # feature-base/ 폴더만 업데이트
 npx lee-spec-kit update --templates
 
-# 확인 없이 강제 덮어쓰기
+# 변경사항이 있어도 강제 덮어쓰기
 npx lee-spec-kit update --force
 ```
 
@@ -217,7 +220,9 @@ npx lee-spec-kit update --force
 | `lang`        | `ko` 또는 `en`                          |
 | `createdAt`   | 생성 날짜                               |
 | `docsRepo`    | `embedded` 또는 `standalone`            |
-| `projectRoot` | (standalone만) 프로젝트 레포지토리 경로 |
+| `pushDocs`    | (standalone만) docs 레포를 별도 Git으로 관리/푸시할지 여부 |
+| `docsRemote`  | (standalone+pushDocs) docs 레포 remote URL |
+| `projectRoot` | (standalone만) 프로젝트 레포지토리 경로 (single: string, fullstack: {fe, be}) |
 
 > `docsRepo: "standalone"`을 선택하면 `pushDocs`, `docsRemote`, `projectRoot`가 추가됩니다.
 
@@ -232,7 +237,10 @@ npx lee-spec-kit update --force
 {
   "projectName": "my-project",
   "projectType": "single",
+  "lang": "ko",
+  "createdAt": "YYYY-MM-DD",
   "docsRepo": "standalone",
+  "pushDocs": false,
   "projectRoot": "/path/to/my-project"
 }
 ```
@@ -243,7 +251,10 @@ npx lee-spec-kit update --force
 {
   "projectName": "my-project",
   "projectType": "fullstack",
+  "lang": "ko",
+  "createdAt": "YYYY-MM-DD",
   "docsRepo": "standalone",
+  "pushDocs": false,
   "projectRoot": {
     "fe": "/path/to/frontend",
     "be": "/path/to/backend"

package/dist/index.js

@@ -18,21 +18,25 @@ async function copyTemplates(src, dest) {
     errorOnExist: false
   });
 }
+function applyReplacements(content, replacements) {
+  const keys = Object.keys(replacements).sort((a, b) => b.length - a.length);
+  let next = content;
+  for (const key of keys) {
+    next = next.replaceAll(key, replacements[key]);
+  }
+  return next;
+}
 async function replaceInFiles(dir, replacements) {
   const files = await glob("**/*.md", { cwd: dir, absolute: true });
   for (const file of files) {
     let content = await fs8.readFile(file, "utf-8");
-    for (const [search, replace] of Object.entries(replacements)) {
-      content = content.replaceAll(search, replace);
-    }
+    content = applyReplacements(content, replacements);
     await fs8.writeFile(file, content, "utf-8");
   }
   const shFiles = await glob("**/*.sh", { cwd: dir, absolute: true });
   for (const file of shFiles) {
     let content = await fs8.readFile(file, "utf-8");
-    for (const [search, replace] of Object.entries(replacements)) {
-      content = content.replaceAll(search, replace);
-    }
+    content = applyReplacements(content, replacements);
     await fs8.writeFile(file, content, "utf-8");
   }
 }
@@ -93,6 +97,8 @@ var I18N = {
       "update.updatedTotal": "\uCD1D {count}\uAC1C \uD30C\uC77C \uC5C5\uB370\uC774\uD2B8 \uC644\uB8CC!",
       "update.changeDetected": "\uBCC0\uACBD \uAC10\uC9C0 (--force\uB85C \uB36E\uC5B4\uC4F0\uAE30)",
       "update.fileUpdated": "{file} \uC5C5\uB370\uC774\uD2B8",
+      "update.gitStatusUnavailable": "git \uC0C1\uD0DC\uB97C \uD655\uC778\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4. (git repo\uAC00 \uC544\uB2C8\uAC70\uB098 git \uC2E4\uD589 \uBD88\uAC00) --force\uB85C \uAC15\uC81C \uB36E\uC5B4\uC4F0\uAE30\uB97C \uC0AC\uC6A9\uD558\uC138\uC694.",
+      "update.docsWorktreeDirty": "docs \uC791\uC5C5\uD2B8\uB9AC\uC5D0 \uBCC0\uACBD\uC0AC\uD56D\uC774 \uC788\uC5B4 update\uB97C \uC9C4\uD589\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4. \uBCC0\uACBD\uC0AC\uD56D\uC744 \uCEE4\uBC0B/\uC2A4\uD0DC\uC2DC \uD6C4 \uB2E4\uC2DC \uC2E4\uD589\uD558\uAC70\uB098 --force\uB85C \uB36E\uC5B4\uC4F0\uC138\uC694.",
       "doctor.title": "\u{1F50E} \uBB38\uC11C \uC9C4\uB2E8",
       "doctor.envWarnings": "\u26A0\uFE0F  \uD658\uACBD \uACBD\uACE0:",
       "doctor.noIssues": "\u2705 \uBB38\uC81C\uB97C \uCC3E\uC9C0 \uBABB\uD588\uC2B5\uB2C8\uB2E4.",
@@ -182,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"
@@ -202,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.',
@@ -266,6 +275,8 @@ var I18N = {
       "update.updatedTotal": "Updated {count} files!",
       "update.changeDetected": "changes detected (use --force to overwrite)",
       "update.fileUpdated": "{file} updated",
+      "update.gitStatusUnavailable": "Cannot determine git status (not a git repo or git unavailable). Use --force to overwrite.",
+      "update.docsWorktreeDirty": "Docs working tree has changes. Commit/stash your changes, or run with --force to overwrite.",
       "doctor.title": "\u{1F50E} Docs Doctor",
       "doctor.envWarnings": "\u26A0\uFE0F  Environment warnings:",
       "doctor.noIssues": "\u2705 No issues found.",
@@ -355,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"
@@ -375,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.',
@@ -983,6 +997,7 @@ async function runFeature(name, options) {
     process.exit(1);
   }
   const { docsDir, projectType, lang } = config;
+  const projectName = config.projectName;
   assertValid(validateSafeName(name), "\uAE30\uB2A5 \uC774\uB984");
   let repo = options.repo;
   if (projectType === "fullstack" && !repo) {
@@ -1043,6 +1058,7 @@ async function runFeature(name, options) {
   const idNumber = featureId.replace("F", "");
   const repoName = projectType === "fullstack" && repo ? `{{projectName}}-${repo}` : "{{projectName}}";
   const replacements = {
+    "{{projectName}}": projectName ?? "{{projectName}}",
     // ko placeholders
     "{\uAE30\uB2A5\uBA85}": name,
     "{\uBC88\uD638}": idNumber,
@@ -1224,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
       },
@@ -1356,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",
@@ -1383,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: {
@@ -1408,7 +1472,7 @@ function getStepDefinitions(lang) {
       }
     },
     {
-      step: 12,
+      step: 13,
       name: tr(lang, "steps", "codeReview"),
       checklist: {
         done: (f) => isPrMetadataConfigured(f) && f.pr.status === "Approved"
@@ -1443,7 +1507,7 @@ function getStepDefinitions(lang) {
       }
     },
     {
-      step: 13,
+      step: 14,
       name: tr(lang, "steps", "featureDone"),
       checklist: { done: (f) => isFeatureDone(f) },
       current: {
@@ -2065,18 +2129,28 @@ async function getFeatureNameFromSpec(featureDir, fallbackSlug, fallbackFolderNa
   return fallbackSlug || fallbackFolderName;
 }
 function updateCommand(program2) {
-  program2.command("update").description("Update docs templates to the latest version").option("--agents", "Update agents/ folder only").option("--skills", "Update agents/skills folder only").option("--templates", "Update feature-base/ folder only").option("-f, --force", "Force overwrite without confirmation").action(async (options) => {
+  program2.command("update").description("Update docs templates to the latest version").option("--agents", "Update agents/ folder only").option("--skills", "Update agents/skills folder only").option("--templates", "Update feature-base/ folder only").option(
+    "-f, --force",
+    "Force overwrite even if docs has uncommitted changes"
+  ).action(async (options) => {
     try {
       await runUpdate(options);
     } catch (error) {
+      const config = await getConfig(process.cwd());
+      const lang = config?.lang ?? DEFAULT_LANG;
       if (error instanceof Error && error.message === "canceled") {
-        const config = await getConfig(process.cwd());
-        const lang = config?.lang ?? DEFAULT_LANG;
         console.log(chalk6.yellow(`
 ${tr(lang, "cli", "common.canceled")}`));
         process.exit(0);
       }
-      console.error(chalk6.red(tr(DEFAULT_LANG, "cli", "common.errorLabel")), error);
+      if (error instanceof Error) {
+        console.error(
+          chalk6.red(tr(lang, "cli", "common.errorLabel")),
+          chalk6.red(error.message)
+        );
+      } else {
+        console.error(chalk6.red(tr(lang, "cli", "common.errorLabel")), error);
+      }
       process.exit(1);
     }
   });
@@ -2096,6 +2170,7 @@ async function runUpdate(options) {
   const { docsDir, projectType, lang } = config;
   const templatesDir = getTemplatesDir();
   const sourceDir = path4.join(templatesDir, lang, projectType);
+  const forceOverwrite = !!options.force || await isDocsWorktreeCleanOrThrow(docsDir, lang);
   const hasExplicitSelection = !!(options.agents || options.skills || options.templates);
   const updateAgents = options.agents || options.skills || !hasExplicitSelection;
   const updateTemplates = options.templates || !hasExplicitSelection;
@@ -2120,15 +2195,20 @@ async function runUpdate(options) {
     const typeAgents = agentsMode === "skills" ? path4.join(typeAgentsBase, "skills") : typeAgentsBase;
     const targetAgents = agentsMode === "skills" ? path4.join(targetAgentsBase, "skills") : targetAgentsBase;
     const featurePath = projectType === "fullstack" ? "docs/features/{be|fe}" : "docs/features";
-    const replacements = {
+    const projectName = config.projectName ?? "{{projectName}}";
+    const commonReplacements = {
+      "{{projectName}}": projectName,
       "{{featurePath}}": featurePath
     };
+    const typeReplacements = {
+      "{{projectName}}": projectName
+    };
     if (await fs8.pathExists(commonAgents)) {
       const count = await updateFolder(
         commonAgents,
         targetAgents,
-        options.force,
-        replacements,
+        forceOverwrite,
+        commonReplacements,
         lang
       );
       updatedCount += count;
@@ -2137,8 +2217,8 @@ async function runUpdate(options) {
       const count = await updateFolder(
         typeAgents,
         targetAgents,
-        options.force,
-        void 0,
+        forceOverwrite,
+        typeReplacements,
         lang
       );
       updatedCount += count;
@@ -2154,11 +2234,14 @@ async function runUpdate(options) {
     const sourceFeatureBase = path4.join(sourceDir, "features", "feature-base");
     const targetFeatureBase = path4.join(docsDir, "features", "feature-base");
     if (await fs8.pathExists(sourceFeatureBase)) {
+      const replacements = {
+        "{{projectName}}": config.projectName ?? "{{projectName}}"
+      };
       const count = await updateFolder(
         sourceFeatureBase,
         targetFeatureBase,
-        options.force,
-        void 0,
+        forceOverwrite,
+        replacements,
         lang
       );
       updatedCount += count;
@@ -2191,9 +2274,7 @@ async function updateFolder(sourceDir, targetDir, force, replacements, lang = DE
       }
       let sourceContent = await fs8.readFile(sourcePath, "utf-8");
       if (replacements) {
-        for (const [key, value] of Object.entries(replacements)) {
-          sourceContent = sourceContent.replaceAll(key, value);
-        }
+        sourceContent = applyReplacements(sourceContent, replacements);
       }
       let shouldUpdate = true;
       if (await fs8.pathExists(targetPath)) {
@@ -2230,6 +2311,42 @@ async function updateFolder(sourceDir, targetDir, force, replacements, lang = DE
   }
   return updatedCount;
 }
+function getGitTopLevel2(cwd) {
+  try {
+    const out = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+function getDocsPorcelainStatus(docsDir) {
+  const top = getGitTopLevel2(docsDir);
+  if (!top) return null;
+  const rel = path4.relative(top, docsDir) || ".";
+  try {
+    return execFileSync("git", ["status", "--porcelain=v1", "--", rel], {
+      cwd: top,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+  } catch {
+    return null;
+  }
+}
+async function isDocsWorktreeCleanOrThrow(docsDir, lang) {
+  const status = getDocsPorcelainStatus(docsDir);
+  if (status === null) {
+    throw new Error(tr(lang, "cli", "update.gitStatusUnavailable"));
+  }
+  if (status.trim().length > 0) {
+    throw new Error(tr(lang, "cli", "update.docsWorktreeDirty"));
+  }
+  return true;
+}
 function configCommand(program2) {
   program2.command("config").description("View or modify project configuration").option("--project-root <path>", "Set project root path").option("--repo <repo>", "Repository type for fullstack: fe | be").action(async (options) => {
     try {

package/package.json

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

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

@@ -52,14 +52,24 @@ 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)
+## Screenshots (Frontend / UI changes)
 
-{Attach if applicable}
+> 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,54 @@ 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.
+
+#### Frontend PR (UI changes)
+
+- 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\"
+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
+```
+
+```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)\"
+```
+
+#### Backend PR (Core structure)
+
+- 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 +92,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,24 @@ PR 본문에서 레포 내 파일 링크는 **반드시 현재 브랜치명을
 - 명령어: `{실행한 테스트 명령어}`
 - 결과: `{PASS/FAIL 요약}`
 
-## 스크린샷 (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,54 @@ Pull Request를 생성할 때 따르는 가이드입니다.
 3. PR 본문 "테스트" 섹션에 **실행 결과** 기록
 4. 모든 체크박스가 체크되어야 함
 
-### 3. 사용자 확인 요청
+### 3. 스크린샷/다이어그램 작성 (PR 본문에 포함)
+
+PR 본문에 결과물을 포함합니다.
+
+#### 프론트엔드 PR (UI 변경)
+
+- `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\"
+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
+```
+
+```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 +92,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) 완료
 
 ### 테스트 실행 기록