lee-spec-kit 0.8.8 → 0.9.1

package/templates/ko/common/README.md

@@ -16,7 +16,7 @@ npx lee-spec-kit docs get agents --json
 - 기본 실행 경로는 workspace-scoped `AGENTS.md`, Codex 공식 hooks, 그리고 활성 feature 문서입니다.
 - 활성 feature를 정한 뒤에는 `spec.md`, `plan.md`, `tasks.md`, `decisions.md`를 작업 SSOT로 사용합니다.
 - 사용자 승인 요청은 문서화된 workflow checkpoint와 원격/파괴적 작업 전에만 합니다.
-- staged된 docs 경로 검사가 필요하면 `git commit` 전에 `npx lee-spec-kit commit-audit --json`를 사용합니다.
+- `git commit` 전에 `npx lee-spec-kit commit-audit --json`를 사용해 staged docs 경로와 canonical Feature-scoped commit 형식을 검증합니다.
 - 코드나 feature 문서를 바꿨다면 종료 전 `npx lee-spec-kit workflow-audit --json`로 동기화 상태를 확인합니다.
 - `isLeeSpecKitProject: false`면 lee-spec-kit 전용 절차를 건너뛰고 일반 워크플로우로 진행합니다.
 
@@ -30,13 +30,29 @@ npx lee-spec-kit docs get agents --json
 
 ## 상위 구조 요약
 
-| 경로             | 목적               | 핵심 문서/역할 |
-| ---------------- | ------------------ | -------------- |
-| `docs/agents/`   | 에이전트 운영 규칙 | `custom.md`, `constitution.md` (엔진 종속 가이드는 `npx lee-spec-kit docs get <doc-id> --json`으로 조회) |
-| `docs/prd/`      | 제품 요구사항      | 프로젝트별 작성 |
-| `docs/designs/`  | 디자인 참고 자료   | `README.md` (링크/가이드/레퍼런스) |
-| `docs/ideas/`    | 아이디어/To-do     | `README.md` (Idea → Feature 승격 규칙) |
-| `{{featurePath}}` | 기능별 문서        | `{feature-id}/spec.md`, `plan.md`, `tasks.md`, `decisions.md` |
+| 경로              | 목적               | 핵심 문서/역할                                                                                           |
+| ----------------- | ------------------ | -------------------------------------------------------------------------------------------------------- |
+| `docs/agents/`    | 에이전트 운영 규칙 | `custom.md`, `constitution.md` (엔진 종속 가이드는 `npx lee-spec-kit docs get <doc-id> --json`으로 조회) |
+| `docs/prd/`       | 제품 요구사항      | 프로젝트별 작성                                                                                          |
+| `docs/designs/`   | 디자인 참고 자료   | `README.md` (링크/가이드/레퍼런스)                                                                       |
+| `docs/ideas/`     | 아이디어/To-do     | `README.md` (Idea → Feature 승격 규칙)                                                                   |
+| `{{featurePath}}` | 기능별 문서        | `{feature-id}/spec.md`, `plan.md`, `tasks.md`, `decisions.md`                                            |
+
+---
+
+## 문서 라우팅
+
+| 문서 내용                                    | 위치                          |
+| -------------------------------------------- | ----------------------------- |
+| 제품 요구사항·사용자 스토리·제품 로드맵      | `docs/prd/`                   |
+| 여러 Feature가 공유하는 시스템 아키텍처 개요 | `docs/prd/*-overview.md`      |
+| 변경하기 어려운 아키텍처 원칙                | `docs/agents/constitution.md` |
+| Feature 승격 전 기술 조사·후보 비교          | 해당 `docs/ideas/I###-*.md`   |
+| 활성 Feature의 구현 설계                     | 해당 Feature의 `plan.md`      |
+| 기술 선택·대안·트레이드오프                  | 해당 Feature의 `decisions.md` |
+| 화면, Figma, 디자인 시스템, UI 플로우        | `docs/designs/`               |
+
+제품 로드맵은 `prd/`에 두지만 구현 순서와 작업 계획은 활성 Feature의 `plan.md`와 `tasks.md`에서 관리합니다. `designs/`는 UX와 시각 디자인 전용이며 기술 설계 문서를 두지 않습니다.
 
 ---
 
@@ -114,13 +130,24 @@ npx lee-spec-kit docs get agents --json
 - `docsRepo` ("embedded" | "standalone"): Docs 관리 방식
 - `pushDocs` (boolean, optional): `docsRepo: "standalone"`일 때만 생성 (원격 push 여부)
 - `docsRemote` (string, optional): `pushDocs: true`일 때만 생성 (원격 레포 URL)
+- `workflow.prePrReview.reviewer` (object): Pre-PR 서브에이전트 실행 설정
+  - `type`: 현재 `"subagent"`만 지원
+  - `model`: `"inherit"` 또는 런타임이 지원하는 모델명
+  - `reasoningEffort`: `low | medium | high | xhigh | max | ultra`
+  - `onUnavailable`: 지정 모델을 사용할 수 없을 때 `inherit | error`
+- `workflow.baseBranch` (string): 완료된 local Feature를 통합할 기준 브랜치
+- `workflow.completionStrategy` (`"local-ff" | "local-squash" | "none"`): fast-forward, 검증된 단일 squash commit 생성, 또는 명시적으로 통합 없이 종료
+- `workflow.deleteFeatureBranchAfterMerge` (boolean): cleanup 후 통합된 local Feature 브랜치 삭제 여부. 원격 브랜치는 삭제하지 않음
+- `workflow.postMergeChecks` (array): local 통합 뒤 기준 브랜치에서 실행할 구조화 명령. 예: `{ "command": "pnpm", "args": ["test"] }`
 - `approval` (object, optional): repo 정책/커스텀 validator용 승인 checkpoint 메타데이터
   - 기본 Codex-native 경로는 여전히 문서화된 checkpoint와 원격/파괴적 작업을 우선 기준으로 승인 요청합니다.
   - legacy runtime은 이 필드를 직접 소비했지만, 이제는 category 기반 checkpoint 메타데이터가 정말 필요할 때만 유지하세요.
   - 현재 기본값:
     - `mode: "category"`
     - `default: "skip"`
-    - `requireCheckCategories: ["spec_approve", "implementation_approve"]`
+    - `requireCheckCategories: ["spec_approve", "implementation_approve", "local_merge"]`
+  - `local-ff` 또는 `local-squash` workflow에서 `implementation_approve`는 완료된 구현을 승인하고, `local_merge`는 설정된 통합, post-merge 검사, managed worktree 제거, 설정된 local Feature 브랜치 삭제를 별도로 승인합니다.
+  - 구현 승인 한 번으로 남은 local 완료 흐름까지 진행하려는 경우에만 `requireCheckCategories`에서 `local_merge`를 제거하세요.
   - 승인 토큰: `A`
   - 허용 응답: `A`, `A OK`
 - `allowedDocsEntries` (object, optional): 비표준 `docs/` top-level 엔트리를 unmanaged docs로 보지 않도록 허용 목록에 추가
@@ -136,17 +163,35 @@ npx lee-spec-kit docs get agents --json
   "lang": "ko",
   "createdAt": "{{date}}",
   "docsRepo": "embedded",
+  "workflow": {
+    "mode": "local",
+    "baseBranch": "main",
+    "completionStrategy": "local-ff",
+    "deleteFeatureBranchAfterMerge": true,
+    "postMergeChecks": [],
+    "prePrReview": {
+      "evidenceMode": "path_required",
+      "reviewer": {
+        "type": "subagent",
+        "model": "inherit",
+        "reasoningEffort": "high",
+        "onUnavailable": "inherit"
+      }
+    }
+  },
   "allowedDocsEntries": {
     "dirs": ["plans"]
   },
   "approval": {
     "mode": "category",
     "default": "skip",
-    "requireCheckCategories": ["spec_approve", "implementation_approve"]
+    "requireCheckCategories": ["spec_approve", "implementation_approve", "local_merge"]
   }
 }
 ```
 
+새 local 프로젝트는 `local-ff`를 사용합니다. base branch에 하나의 commit만 남기려면 `local-squash`를 선택하세요. 이때 task checkpoint 증거를 위해 원본 Feature tip을 내부 `refs/lee-spec-kit/integrations/*` ref로 보존합니다. 기존 local 프로젝트에 명시적 `completionStrategy`가 없으면 `update`가 `none`을 넣어 업그레이드 도중 현재 브랜치를 갑자기 병합하지 않습니다. 준비가 끝난 뒤 `local-ff` 또는 `local-squash`로 명시적으로 전환하세요.
+
 ```json
 {
   "projectName": "{{projectName}}",
@@ -159,7 +204,7 @@ npx lee-spec-kit docs get agents --json
   "approval": {
     "mode": "category",
     "default": "skip",
-    "requireCheckCategories": ["spec_approve", "implementation_approve"]
+    "requireCheckCategories": ["spec_approve", "implementation_approve", "local_merge"]
   }
 }
 ```

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

@@ -27,25 +27,50 @@
 - 활성 feature 문서를 읽은 뒤에는 `npx lee-spec-kit workflow-stage <featureRef> --json`를 실행하고, 그 `nextAction`만 따릅니다.
 - `workflow-stage --json`가 `primaryActionLabel`과 `actionOptions`를 같이 반환하면, `primaryActionLabel`은 기본 옵션 라벨로 보고 사용자에게는 `actionOptions[*].reply` 값을 그대로 보여줍니다.
 
+## 문서 라우팅
+
+| 내용                                         | SSOT 위치                     |
+| -------------------------------------------- | ----------------------------- |
+| 제품 요구사항·사용자 스토리·제품 로드맵      | `docs/prd/`                   |
+| 여러 Feature가 공유하는 시스템 아키텍처 개요 | `docs/prd/*-overview.md`      |
+| 변경하기 어려운 아키텍처 원칙                | `docs/agents/constitution.md` |
+| Feature 전 기술 조사·후보 비교               | 해당 `docs/ideas/I###-*.md`   |
+| 활성 Feature 구현 설계                       | 해당 Feature의 `plan.md`      |
+| 기술 선택·대안·트레이드오프                  | 해당 Feature의 `decisions.md` |
+| 화면·Figma·디자인 시스템·UI 플로우           | `docs/designs/`               |
+
+- `docs/designs/`를 시스템 아키텍처, 데이터/API 설계, 기술 조사, 구현 계획의 목적지로 사용하지 않습니다.
+- 세부 설명은 `docs/README.md`의 문서 라우팅 규칙을 따릅니다.
+
+## 선택적 UI/UX 디자인 정책
+
+- 사용자 요청에 design system, UI/visual redesign, 디자인 일관성, 공통 UI/component library 정리, branding/theme/token 재설계, Figma/디자인 이미지 기반 구현이 명시된 경우에만 `npx lee-spec-kit docs get ui-ux-design --json`을 읽고 적용합니다.
+- 단순히 대상이 web/frontend인 경우, 비 UI/backend Feature, 장기 디자인 규칙과 무관한 단순 버그 수정에는 이 정책을 적용하지 않습니다.
+- 이 문서는 선택적 권장 정책이며 `requiredDocs`나 workflow 승인 gate가 아닙니다.
+
 ## 실행 규칙
 
 - lee-spec-kit은 문서 구조, workflow 단계, validator를 담당합니다.
 - Codex는 실행 루프, 도구 사용, hook lifecycle을 담당합니다.
 - `workflow-stage --json`가 `stage === "implementation"`이고 `implementationAllowed === true`를 반환하기 전에는 구현을 시작하지 않습니다.
+- `workflow-stage --json`의 `nextAction.category`가 `pre_pr_review`이고 `executor`가 `subagent`이면, 반환된 `model`, `reasoningEffort`, `onUnavailable` 정책으로 fresh context의 읽기 전용 서브에이전트 리뷰를 실행합니다. 리뷰 스킬 이름을 선택하거나 요구하지 않습니다.
+- Pre-PR 리뷰 서브에이전트는 finding만 반환하며 코드를 수정하지 않습니다. 메인 에이전트가 finding을 반영하고 reviewer metadata와 최종 decision을 evidence에 기록합니다.
 - spec / plan / tasks 승인, issue 생성, branch 생성은 구현 전 하드 게이트로 취급합니다.
 - standalone 모드에서는 `git worktree add`를 직접 만들지 말고 `workflow-stage`의 정확한 `nextAction.command`를 실행해 managed workspace 경로, stale 디렉터리 정리, `.env`/`.env.*` 복사 단계가 일관되게 유지되도록 합니다.
+- local 모드에서는 구현 승인 직후 종료하지 않습니다. `workflow-stage`가 반환하는 정확한 `local merge`, `local cleanup` 명령을 따라 통합·검증·정리가 확인되어 `done`이 될 때까지 진행합니다.
+- `local-ff` 또는 `local-squash` workflow에서 `local_merge` 승인이 필요하면 구현 승인과 local merge 승인을 구분합니다. 첫 번째 승인은 구현 결과를 수락하고, 두 번째 승인은 설정된 통합 전략, post-merge 검사, local cleanup을 허가합니다.
 - 동작이나 범위가 바뀌는 코드 변경이 있으면 같은 턴 안에서 feature 문서를 같이 동기화합니다.
-- staged된 docs 경로 검사가 필요하면 `git commit` 전에 `npx lee-spec-kit commit-audit --json`를 사용합니다.
+- `git commit` 전에 `npx lee-spec-kit commit-audit --json`를 사용합니다. Feature-scoped commit은 Issue가 연결되어 있으면 `#123`, Issue 없는 local workflow에서는 `F027` 같은 안정적인 Feature ID를 scope로 사용합니다.
 - 기본 docs sync 검사는 `npx lee-spec-kit workflow-audit --json`를 사용합니다.
 
 ## 승인 규칙
 
 사용자 확인 필수 규칙을 항상 먼저 적용합니다.
 
-| 현재 액션 예시 | 공유 내용 |
-| --- | --- |
-| 이슈 생성 | `npx lee-spec-kit github issue <featureRef> --create` 전 |
-| PR 생성 | `npx lee-spec-kit github pr <featureRef> --create` 전 |
+| 현재 액션 예시 | 공유 내용                                                |
+| -------------- | -------------------------------------------------------- |
+| 이슈 생성      | `npx lee-spec-kit github issue <featureRef> --create` 전 |
+| PR 생성        | `npx lee-spec-kit github pr <featureRef> --create` 전    |
 
 - 문서화된 workflow checkpoint와 원격/파괴적 작업 전에만 사용자 승인을 요청합니다.
 - `workflow-stage --json`가 `approvalRequired === true`를 반환하면 그 checkpoint에서 멈추고 사용자 승인을 받습니다.

package/templates/ko/common/agents/git-workflow.md

@@ -6,11 +6,11 @@
 
 ## 핵심 개념
 
-| 개념      | GitHub 매핑  | 설명                    |
-| --------- | ------------ | ----------------------- |
-| Feature   | GitHub Issue | 기능 단위 작업          |
-| 태스크    | Commit       | 개별 구현 단위          |
-| 기능 완료 | Pull Request | Feature 완료 시 PR 생성 |
+| 개념      | GitHub workflow | Local workflow | 설명                    |
+| --------- | --------------- | -------------- | ----------------------- |
+| Feature   | GitHub Issue    | Feature ID     | 기능 단위 작업          |
+| 태스크    | Commit          | Commit         | 개별 구현 단위          |
+| 기능 완료 | Pull Request    | Local merge    | Feature 완료 통합       |
 
 ---
 
@@ -50,10 +50,27 @@ main
 
 ### 형식
 
-```
+Feature scope는 아래 canonical 형식 중 하나만 사용하며, 에이전트가 임의의 scope 형식을 만들지 않습니다.
+
+```text
+# GitHub Issue가 연결된 Feature
 {type}(#{issue}): {description}
+
+# Issue가 없는 local Feature
+{type}({featureId}): {description}
+```
+
+예:
+
+```text
+feat(#123): 사용자 인증 구현
+docs(#123): 인증 스펙 명확화
+feat(F027): 알림 설정 구현
+docs(F027): 알림 문서 업데이트
 ```
 
+local Feature의 scope는 안정적인 Feature ID(`F027`)입니다. 전체 폴더 ref인 `F027-notification-settings`를 scope로 사용하지 않으며, `docs: F027 ...`처럼 Feature scope를 생략한 커밋도 canonical 형식이 아닙니다.
+
 ### Type 목록
 
 | Type       | 설명        | 예시                                |
@@ -114,15 +131,17 @@ git worktree add .worktrees/feat-{issue-number}-{feature-name} feat/{issue-numbe
 
 #### Standalone 모드 커밋 가이드
 
+workflow에 따라 scope를 선택합니다. Issue가 연결되어 있으면 `#123`, Issue 없는 local Feature라면 `F027` 같은 Feature ID를 사용합니다.
+
 1. **Project 커밋** (코드 변경사항이 있는 경우)
 
    ```bash
-   git commit -m "feat(#123): 기능 구현"
+   git commit -m "feat(F027): 기능 구현"
    ```
 
 2. **Docs 커밋** (문서 변경사항이 있는 경우 - **Docs 레포에서 실행**)
    ```bash
-   git commit -m "docs(#123): 기능 구현 문서 업데이트"
+   git commit -m "docs(F027): 기능 구현 문서 업데이트"
    ```
 
 > 💡 **Core Rule**: 태스크 완료 시점에는 **변경된 모든 레포지토리**가 커밋되어야 합니다.

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

@@ -17,7 +17,9 @@ Pull Request를 생성할 때 따르는 가이드입니다.
 
 ## Pre-PR 기본 체크리스트(`builtin-checklist`)
 
-Pre-PR 리뷰에서 항상 수행하는 최소 기준입니다. 가능한 경우 리뷰 스킬을 추가로 사용해 심화 검토를 진행하세요.
+Pre-PR 리뷰에서 서브에이전트가 항상 수행하는 최소 기준입니다. 리뷰 스킬 이름에 의존하지 않습니다.
+
+`workflow-stage --json`의 `nextAction.executor`가 `subagent`이면 fresh context의 읽기 전용 서브에이전트에게 리뷰를 위임합니다. `model: inherit`은 현재 모델을 상속한다는 뜻이며, 그 외 값은 서브에이전트 생성 시 모델 override로 사용합니다. 지정 모델을 사용할 수 없으면 `onUnavailable` 정책(`inherit` 또는 `error`)을 따릅니다.
 
 1. `spec.md` / `plan.md` / `tasks.md` 기준으로 변경 범위 정합성을 확인하고, 구현이 원래 목적에 맞는지 점검합니다.
 2. 회귀/예외 처리, 크리티컬·보안 리스크, 사이드 이펙트, 사용자 흐름 영향, 배포 준비도를 점검합니다.
@@ -31,6 +33,8 @@ Pre-PR 리뷰에서 항상 수행하는 최소 기준입니다. 가능한 경우
 10. `PR 전 리뷰 Decision`은 `결정: approve|changes_requested|blocked ...` (또는 `decision: ...`) 형식을 사용합니다.
 11. PR 생성 단계로 이동하기 전 최종 Decision이 `approve`인지 확인합니다.
 
+리뷰 산출물에는 실제 사용한 `executor`, `model`, `reasoningEffort`, 검토한 commit/diff 범위, finding과 최종 decision을 기록합니다. 리뷰 서브에이전트는 코드를 수정하지 않으며, finding 반영과 문서 갱신은 메인 에이전트가 담당합니다.
+
 ---
 
 ## 단계

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

@@ -1,6 +1,6 @@
-# Feature 범위 분할 가이드 (Feature = Issue 유지)
+# Feature 범위 분할 가이드
 
-하나의 Feature/Issue가 리뷰 가능한 범위를 넘었을 때 사용하는 가이드입니다.
+하나의 Feature가 리뷰 가능한 범위를 넘었을 때 사용하는 가이드입니다. GitHub workflow에서는 Feature가 Issue에 대응하고, local workflow에서는 Feature ID로 추적합니다.
 
 ---
 
@@ -16,7 +16,8 @@
 주의:
 
 - 작은 범위, 강결합 작업은 단일 이슈 유지가 가능합니다.
-- "Feature = Issue" 원칙을 유지하면서 연관 child 이슈/feature를 생성합니다.
+- GitHub workflow에서는 각 child Feature에 대응하는 child Issue를 생성합니다.
+- local workflow에서는 Issue 없이 각 child Feature의 고유 Feature ID로 추적합니다.
 
 ---
 

package/templates/ko/common/agents/ui-ux-design.md

@@ -0,0 +1,128 @@
+# UI/UX 디자인 문서 정책
+
+UI/UX 요청에서 장기 디자인 규칙과 Feature별 시각 자료를 분리하는 선택적 정책입니다.
+이 문서는 workflow stage나 승인 gate를 추가하지 않습니다.
+
+---
+
+## 활성화 조건
+
+사용자 요청에 다음 의도가 **명시적으로 포함된 경우에만** 이 정책을 적용합니다.
+
+- design system 또는 디자인 시스템
+- UI redesign 또는 visual redesign
+- 디자인 일관성
+- 공통 UI 또는 component library 정리
+- branding 또는 theme/token 재설계
+- Figma나 디자인 이미지 기반 구현
+
+다음 경우에는 적용하지 않습니다.
+
+- 단순히 대상 component가 web/frontend인 경우
+- 비 UI 프로젝트나 backend Feature
+- 장기 디자인 규칙을 바꾸지 않는 단순 버그 수정
+- 기존 컴포넌트 한 곳의 국소적인 스타일 수정
+
+애매하면 문서를 만들지 말고 활성 Feature 문서만 사용합니다.
+
+## 권장 구조
+
+활성화 조건을 충족하고 장기 규칙 또는 시각 참조가 실제로 필요할 때만 다음 구조의 필요한 부분을 사용합니다.
+
+```text
+docs/designs/
+├── README.md
+├── design-system.md
+├── <feature-visual-brief>.md
+└── assets/
+    └── <feature-name>/
+```
+
+- 모든 파일을 한꺼번에 만들지 않습니다.
+- `docs/designs/design-system.md`가 이미 있으면 새 파일을 만들지 않고 기존 문서를 참조하거나 갱신합니다.
+- Feature마다 `design.md`를 만드는 방식을 기본값으로 사용하지 않습니다.
+- 기존 프로젝트의 문서 구조를 마이그레이션하거나 이 문서를 필수 gate로 만들지 않습니다.
+
+## 문서별 책임
+
+### `docs/designs/design-system.md`
+
+여러 Feature가 공유하는 장기적인 의미와 사용 규칙을 기록합니다.
+
+- semantic color tokens
+- typography
+- spacing과 layout
+- radius, border, shadow
+- 공통 component와 variant
+- loading, empty, error, processing 같은 상태 표현
+- responsive 규칙
+- accessibility와 motion 규칙
+- content voice
+- 디자인 시스템 변경, deprecation, 동기화 정책
+
+이 파일에는 다음 frontmatter를 사용합니다.
+
+```yaml
+---
+lee-spec-kit:
+  kind: design-system
+  scope: project
+---
+```
+
+### `docs/designs/<feature-visual-brief>.md`
+
+특정 Feature의 UX 방향과 시각 참조를 기록합니다.
+
+- Figma 원본 URL과 필요한 repo 내부 snapshot
+- 디자인 이미지와 참고 화면
+- 화면/flow별 의도와 핵심 상태
+- 현재 데이터/API 계약과 시안 사이의 차이
+- 적용할 `design-system.md` 규칙과 Feature 전용 해석
+
+내용에 따라 `kind: ux-design` 또는 `kind: visual-reference`, `scope: project` frontmatter를 사용합니다. 이 문서는 Feature의 시각적 참조 정본이지만 요구사항, 구현 계획, 기술 결정의 정본을 대체하지 않습니다.
+
+### Feature `spec.md`
+
+- 사용자 요구사항과 acceptance criteria를 유지합니다.
+- 관련 문서의 선택적 `Design Refs`에 design system과 visual brief의 프로젝트 루트 기준 경로를 연결합니다.
+
+### Feature `plan.md`
+
+- token/theme 파일, 공통 component, route/screen, Storybook 또는 동등한 workbench의 변경 범위를 기록합니다.
+- 디자인 규칙을 실제 코드와 테스트에 적용하는 방법을 기록합니다.
+
+### Feature `decisions.md`
+
+- 디자인 시스템을 바꾸거나 예외를 두는 이유를 기록합니다.
+- 예외의 적용 범위, 영향 받는 규칙, 제거 조건을 함께 기록합니다.
+
+## 실행 가능한 정본과 역할 분리
+
+`design-system.md` 하나만 단독 SSOT로 취급하지 않습니다.
+
+| 대상                              | 책임                              |
+| --------------------------------- | --------------------------------- |
+| `docs/designs/design-system.md`   | 의미, 의도, 사용 규칙             |
+| CSS theme/globals 또는 token 파일 | 실행되는 실제 token 값            |
+| 공통 UI 디렉터리                  | 실제 component API와 variant 계약 |
+| Storybook 또는 동등한 workbench   | variant와 상태의 실행 가능한 예시 |
+| Feature `decisions.md`            | 예외, 변경 이유, 제거 조건        |
+
+문서가 의미를 설명하고 코드와 workbench가 실행 가능한 계약을 증명하도록 유지합니다.
+
+## 동기화 규칙
+
+- `design-system.md`가 바뀌는 Feature에서는 `tasks.md`의 같은 task에 영향 받는 디자인 문서, token/theme, 공통 UI, Storybook/workbench, 관련 검증을 구체적으로 적습니다.
+- 실제 영향이 없는 영역을 억지로 변경하지는 않지만, 영향 여부를 task checklist에서 확인합니다.
+- 문서와 코드가 달라지면 같은 Feature task 안에서 영향을 받는 문서와 실행 가능한 정본을 함께 동기화합니다.
+- 디자인 시스템 예외는 `decisions.md`에 이유와 제거 조건을 남깁니다.
+- visual reference 파일은 `docs/designs/assets/<feature-name>/`처럼 repo 내부 경로에 보관하고 개인 컴퓨터의 절대 경로에 의존하지 않습니다.
+- 외부 Figma나 원본 URL은 출처로 유지하되, 구현에 필요한 고정 snapshot이 있으면 repo 내부 asset도 함께 참조합니다.
+
+## 하위 호환성
+
+- `design-system.md`, visual brief, `Design Refs`는 모두 선택 사항입니다.
+- 기존 Feature 문서에 새 section을 backfill할 필요가 없습니다.
+- 이 정책은 spec/plan/tasks 승인 단계나 `workflow-stage` 결과를 변경하지 않습니다.
+- UI/UX 감지 조건을 충족하지 않는 요청에는 기존 Feature 문서 흐름만 사용합니다.

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

@@ -1,4 +1,4 @@
-# Designs
+# UX / Visual Designs
 
 프로젝트에서 참고할 디자인 리소스를 모아두는 폴더입니다.
 
@@ -6,19 +6,69 @@
 
 ---
 
+## 선택적 적용
+
+`design-system.md`와 Feature visual brief는 모든 프로젝트의 필수 문서가 아닙니다.
+
+- design system, UI/visual redesign, 디자인 일관성, 공통 UI/component library 정리, branding/theme/token 재설계, Figma/디자인 이미지 기반 구현 요청에만 사용을 검토합니다.
+- 단순 web/frontend Feature, backend Feature, 장기 디자인 규칙을 바꾸지 않는 버그 수정에는 만들지 않습니다.
+- 세부 정책: `npx lee-spec-kit docs get ui-ux-design --json`
+
+---
+
 ## 포함 대상
 
 - 화면/플로우 참고 자료 (Figma, 이미지, 링크)
 - 컴포넌트/패턴 가이드 (버튼, 폼, 네비게이션 등)
 - 브랜드/타이포/컬러 토큰 등 UI 규칙
 
+## 권장 구조와 책임
+
+```text
+docs/designs/
+├── README.md
+├── design-system.md
+├── <feature-visual-brief>.md
+└── assets/
+    └── <feature-name>/
+```
+
+- `design-system.md`: 여러 Feature가 공유하는 의미와 사용 규칙
+- `<feature-visual-brief>.md`: 특정 Feature의 Figma/이미지, UX 방향, 데이터 계약과 시안의 차이
+- `assets/<feature-name>/`: 구현이 의존하는 repo 내부 visual snapshot
+
+이미 `design-system.md`가 있으면 새 파일을 만들지 않고 기존 문서를 참조하거나 갱신합니다. Feature마다 `design.md`를 만드는 방식을 기본값으로 사용하지 않습니다.
+
+---
+
+## 포함하지 않는 문서
+
+- 시스템/백엔드 아키텍처 (`docs/prd/*-overview.md` 또는 활성 Feature의 `plan.md`)
+- 데이터 모델 및 API 설계 (Feature 전에는 `docs/ideas/I###-*.md`, 이후에는 활성 Feature의 `plan.md`)
+- 오픈소스 후보 조사 (`docs/ideas/I###-*.md` 또는 활성 Feature의 `decisions.md`)
+- 기술 결정과 대안 비교 (Feature 전에는 `docs/ideas/I###-*.md`, 이후에는 활성 Feature의 `decisions.md`)
+- 구현 로드맵과 작업 계획 (활성 Feature의 `plan.md`와 `tasks.md`)
+
+`designs/`의 design은 기술 설계가 아니라 UX, 화면, 시각 디자인을 뜻합니다.
+
 ---
 
 ## 작성 규칙
 
 - 외부 링크는 가능한 한 **원본 URL + 요약(또는 캡처)**를 함께 남깁니다.
 - 파일명은 kebab-case 사용 (예: `auth-flow.md`, `design-system.md`)
-- 이미지/첨부 파일이 필요하면 `assets/` 폴더를 생성하여 관리합니다.
+- 이미지/첨부 파일은 `assets/<feature-name>/` 같은 repo 내부 경로에서 관리하고 개인 컴퓨터의 절대 경로에 의존하지 않습니다.
+- 디자인 문서는 `kind: ux-design`, `kind: design-system`, `kind: visual-reference` 중 맞는 frontmatter와 `scope: project`를 사용합니다.
+
+## 실행 가능한 정본
+
+- `design-system.md`: 의미와 사용 규칙
+- CSS theme/globals 또는 token 파일: 실제 token 값
+- 공통 UI 디렉터리: 실제 component/variant 계약
+- Storybook 또는 동등한 workbench: variant와 상태의 실행 가능한 예시
+- Feature `decisions.md`: 예외, 변경 이유, 제거 조건
+
+`design-system.md`가 바뀌면 같은 Feature task에서 영향 받는 문서, token/theme, 공통 UI, Storybook/workbench와 검증을 함께 확인하고 동기화합니다.
 
 ---
 

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

@@ -45,7 +45,7 @@ Feature는 PRD → idea → feature 흐름에서 실제 구현을 진행하는
 - 번호는 **최소 3자리 패딩** (001, 002, ...)
 - 999를 초과하면 **4자리 이상으로 확장** (F1000, F1001, ...)
 - 기능명은 kebab-case
-- **Feature = Issue**: 각 Feature는 하나의 GitHub Issue에 대응됩니다.
+- **Feature 식별자는 workflow에 따라 결정**: GitHub workflow에서는 각 Feature가 하나의 GitHub Issue에 대응합니다. local workflow에서는 Issue 없이 `F027` 같은 안정적인 Feature ID를 canonical 식별자로 사용합니다.
 
 ---
 
@@ -57,6 +57,8 @@ npx lee-spec-kit workflow-stage <feature-ref> --json
 
 반환되는 `stage`, `nextAction`, `implementationAllowed` 값을 현재 워크플로우 상태로 사용하세요.
 
+`completionStrategy`가 `"local-ff"` 또는 `"local-squash"`인 local workflow의 완료 흐름은 `implementation_approve → local_merge → local_verify → local_cleanup → done`입니다. 각 단계에서 반환된 helper 명령을 그대로 사용합니다. `local-ff`는 조상 관계로, `local-squash`는 squash commit tree와 내부 보존된 원본 Feature tip의 tree 일치로 통합을 증명하며, 둘 다 cleanup 후에만 `done`입니다.
+
 ---
 
 ## PRD 요구사항 추적 (권장)
@@ -129,9 +131,9 @@ Feature가 이미 진행 중이라면, 이 파일들은 활성 워크플로우 S
 
 ---
 
-## Pre-PR 폴백 체크리스트
+## Pre-PR 서브에이전트 체크리스트
 
-모든 Pre-PR 리뷰에서 `agents/skills/create-pr.md`의 `Pre-PR 기본 체크리스트`를 기본 베이스라인으로 사용하고, 리뷰 스킬은 심화 검토용으로 추가 사용하세요.
+모든 Pre-PR 리뷰는 `workflow-stage --json`이 반환한 모델·추론도 설정으로 fresh context의 읽기 전용 서브에이전트에게 맡깁니다. 서브에이전트는 `agents/skills/create-pr.md`의 `Pre-PR 기본 체크리스트`를 기준으로 리뷰하고, 메인 에이전트가 finding 반영과 evidence 기록을 담당합니다.
 
 ---
 

package/templates/ko/common/features/feature-base/decisions.md

@@ -6,7 +6,8 @@ canonical docs surface 밖의 unmanaged docs 산출물(예: `docs/plans/*`, `doc
 > ADR(Architecture Decision Record)은 구현 중 내린 중요한 기술/구조 결정을 남기는 기록입니다.
 > 나중에 "왜 이렇게 만들었는지"를 추적하고, 팀 합의를 재확인하기 위해 작성합니다.
 
-> 형식: `D{번호}: {결정 제목} ({YYYY-MM-DD})`
+> 형식: `DNNN: {결정 제목} ({YYYY-MM-DD})`
+> 결정 ID는 Feature별로 독립된 번호를 사용하며 Feature ID와 관계없이 `D001`부터 시작합니다.
 
 기록 원칙:
 
@@ -17,6 +18,7 @@ canonical docs surface 밖의 unmanaged docs 산출물(예: `docs/plans/*`, `doc
   - 태스크 완료 직전(`[DOING] -> [DONE]`): `Options/Decision/Rationale`를 최종화하고 `Trace`를 보강
   - PR 머지 후: 실제 결과/영향을 `Trace(머지 후 확인)`에 1~2줄 추가
 - 모든 ADR에는 최소 1개 이상의 **Evidence 링크**(커밋/PR/테스트 로그 중 하나 이상)를 남깁니다.
+- 디자인 시스템 변경이나 예외를 기록할 때는 영향 받는 규칙과 범위, 예외 이유, 제거 조건, 실행 가능한 정본의 동기화 영향을 함께 남깁니다.
 
 ---
 

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

@@ -60,3 +60,6 @@
   - 레거시 요구사항 문서에 아직 PRD ID가 없다면, 먼저 원문에 ID를 backfill한 뒤 이 필드와 `tasks.md` 태스크 태그를 함께 갱신하세요.
   - 요구사항/스코프 변경 시 PRD 문서 + 이 필드 + `tasks.md` 태스크 태그를 함께 갱신하세요.
   - 구현 중 더 나은 사용자 동작이 발견되어 최종 요구사항이 바뀌었다면, 이를 영구적인 `[NON-PRD]` 예외로 두지 말고 PRD 업데이트로 취급하세요.
+- Design Refs: - (선택 사항, 명시적인 UI/UX 디자인 작업에만 프로젝트 루트 기준 경로 사용)
+  - Design System: - (예: `docs/designs/design-system.md`)
+  - Visual Brief: - (예: `docs/designs/<feature-visual-brief>.md`)

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

@@ -13,6 +13,7 @@
   - 단, `tasks.md`에서 PRD ID를 임의로 만들지 마세요. `docs/prd` 또는 상위 요구사항 문서에 먼저 정의된 ID만 참조해야 합니다.
   - 레거시 문서에 아직 PRD ID가 없다면, 먼저 원문 요구사항 문서에 ID를 backfill한 뒤 `spec.md`의 `PRD Refs`와 태스크 태그를 함께 맞추세요.
   - `[NON-PRD]`는 내부 구현 작업 전용입니다. 사용자 동작, acceptance criteria, 범위가 바뀌는 태스크라면 PRD를 먼저 backfill하고 `[PRD-...]`로 태깅하세요.
+- **디자인 시스템 동기화(조건부)**: `docs/designs/design-system.md`를 변경하는 태스크는 영향 받는 디자인 문서, token/theme, 공통 UI, Storybook/workbench와 검증을 같은 task의 `Checklist`에서 추적하세요. 영향이 없는 영역은 변경하지 말고 영향 여부만 확인합니다.
 
 ---
 

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

@@ -30,6 +30,36 @@
 
 ---
 
+## 조사 및 후보 비교
+
+- 후보:
+- 장점:
+- 단점:
+- 라이선스:
+- 검증 필요 사항:
+
+---
+
+## 설계 초안
+
+- 데이터 계약:
+- 예상 컴포넌트:
+- 외부 의존성:
+- 미확정 사항:
+
+---
+
+## Feature 승격 매핑
+
+- `spec.md`로 이동할 내용:
+- `plan.md`로 이동할 내용:
+- `decisions.md`로 이동할 내용:
+- `tasks.md`로 이동할 내용:
+
+> 승격 전 초안입니다. Feature 생성 후에는 확정되지 않은 내용을 Candidate 또는 Pending 상태로 옮기고, Idea는 이력으로만 유지합니다.
+
+---
+
 ## 승격 메모
 
 - Feature가 되어도 유지되어야 할 점은 무엇인가?