lee-spec-kit 0.9.0 → 0.9.2

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

@@ -6,12 +6,39 @@
 
 ---
 
+## 선택적 적용
+
+`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`를 만드는 방식을 기본값으로 사용하지 않습니다.
+
 ---
 
 ## 포함하지 않는 문서
@@ -30,7 +57,18 @@
 
 - 외부 링크는 가능한 한 **원본 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,7 +57,11 @@ npx lee-spec-kit workflow-stage <feature-ref> --json
 
 반환되는 `stage`, `nextAction`, `implementationAllowed` 값을 현재 워크플로우 상태로 사용하세요.
 
-`completionStrategy: "local-ff"`인 local workflow의 완료 흐름은 `implementation_approve → local_merge → local_verify → local_cleanup → done`입니다. 각 단계에서 반환된 helper 명령을 그대로 사용하며, `done`은 기준 브랜치가 Feature tip을 포함하고 cleanup까지 완료됐다는 뜻입니다.
+`tasks.md`의 최종 완료 체크박스 3개에는 `lee-spec-kit:completion:*` HTML marker가 있습니다. 사용자에게 보이는 문구는 바꿔도 되지만 각 체크박스 라인의 marker는 유지하세요. `workflow-stage`는 marker를 machine-readable identity로 우선 사용하고, 기존 프로젝트 호환을 위해 marker가 없으면 이전 canonical 문구를 fallback으로 인식합니다.
+
+`completionStrategy`가 `"local-ff"` 또는 `"local-squash"`인 local workflow의 완료 흐름은 `implementation_approve → feature_verify → local_merge → local_cleanup → done`입니다. 검사 실패 시 구현이 허용된 `feature_remediation`으로 이동합니다. `local-ff`는 검증된 Feature SHA만 옮기고, `local-squash`는 통합 tree가 검증된 Feature tree와 같아야 합니다. 둘 다 cleanup 후에만 `done`입니다.
+
+remediation 커밋이 추가되면 기존 검증과 local merge 승인은 무효입니다. Pre-PR review가 활성화되어 있다면 변경된 diff의 review evidence를 갱신하고 새 tip을 검증한 뒤 local merge 승인을 다시 받습니다.
 
 ---
 

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`에서 추적하세요. 영향이 없는 영역은 변경하지 말고 영향 여부만 확인합니다.
 
 ---
 
@@ -80,9 +81,9 @@
 
 > ⚠️ 아래 항목은 **최종 확인 체크리스트**입니다. 실제로 확인/실행한 뒤에만 체크하세요.
 
-- [ ] 모든 태스크가 `[DONE]`이며, 각 태스크의 `Acceptance` 검증 및 `Checklist` 체크 완료
-- [ ] 테스트 실행 및 통과 (아래에 명령어/결과 기록)
-- [ ] 최종 결과를 공유했고, 필요한 사용자 확인을 문서화된 workflow checkpoint 기준으로 기록함
+- [ ] 모든 태스크가 `[DONE]`이며, 각 태스크의 `Acceptance` 검증 및 `Checklist` 체크 완료 <!-- lee-spec-kit:completion:all-tasks -->
+- [ ] 테스트 실행 및 통과 (아래에 명령어/결과 기록) <!-- lee-spec-kit:completion:tests -->
+- [ ] 최종 결과를 공유했고, 필요한 사용자 확인을 문서화된 workflow checkpoint 기준으로 기록함 <!-- lee-spec-kit:completion:final-outcome -->
 
 ### 테스트 실행 기록