@sduck/sduck-cli 0.1.2 → 0.1.3

package/.sduck/sduck-assets/agent-rules/antigravity.md

@@ -0,0 +1,4 @@
+# Antigravity Instructions
+
+- Follow the repository SDD workflow exactly.
+- Use this workspace rule file together with the shared SDD workflow block.

package/.sduck/sduck-assets/agent-rules/claude-code.md

@@ -0,0 +1,18 @@
+이 프로젝트는 **Spec-Driven Development(SDD)** 워크플로우를 따른다.
+`sduck` CLI가 없으므로 Claude가 직접 파일을 생성하고 상태를 관리한다.
+워크플로우 구조와 규칙은 `sduck` CLI와 동일하다.
+
+## 절대 규칙
+
+다음 두 가지 승인은 절대 Claude가 직접 처리하지 않는다.
+
+- **스펙 승인**은 사용자가 명시적으로 승인해야 한다
+- **플랜 승인**은 사용자가 명시적으로 승인해야 한다
+
+승인 전에는 어떤 코드도 작성하지 않는다.
+
+## Claude Code Instructions
+
+- Follow the repository SDD workflow exactly.
+- Use `CLAUDE.md` as project-level instruction context.
+- Keep plans highly detailed: list exact file paths, likely functions or sections to edit, concrete change intent, and verification commands.

package/.sduck/sduck-assets/agent-rules/codex.md

@@ -0,0 +1,18 @@
+이 프로젝트는 **Spec-Driven Development(SDD)** 워크플로우를 따른다.
+생성된 `AGENT.md`는 codex 계열 도구가 참고할 project-level instruction context다.
+워크플로우 구조와 규칙은 `sduck` CLI와 동일하다.
+
+## 절대 규칙
+
+다음 두 가지 승인은 에이전트가 직접 처리하지 않는다.
+
+- **스펙 승인**은 사용자가 명시적으로 승인해야 한다
+- **플랜 승인**은 사용자가 명시적으로 승인해야 한다
+
+승인 전에는 어떤 코드도 작성하지 않는다.
+
+## Codex Instructions
+
+- Follow the repository SDD workflow exactly.
+- Use `AGENT.md` as project-level instruction context.
+- Keep plans highly detailed: list exact file paths, likely functions or sections to edit, concrete change intent, and verification commands.

package/.sduck/sduck-assets/agent-rules/core.md

@@ -0,0 +1,79 @@
+# SDD Workflow Rules
+
+## 디렉토리 구조
+
+에이전트는 아래 경로를 기준으로 `sduck` 상태를 읽고 쓴다.
+
+```text
+프로젝트 루트/
+├── .sduck/sduck-assets/
+│   ├── eval/
+│   │   ├── plan.yml
+│   │   ├── spec.yml
+│   │   └── task.yml
+│   ├── types/
+│   │   ├── build.md
+│   │   ├── chore.md
+│   │   ├── feature.md
+│   │   ├── fix.md
+│   │   └── refactor.md
+│   └── agent-rules/
+│
+└── .sduck/sduck-workspace/
+    └── {timestamp}-{type}-{slug}/
+        ├── meta.yml
+        ├── spec.md
+        └── plan.md
+```
+
+## 세션 시작 시 필수 확인
+
+작업을 시작하기 전에 반드시 아래를 확인한다.
+
+1. `.sduck/sduck-workspace/` 디렉토리가 있는지 확인
+2. 진행 중인 작업(`IN_PROGRESS`, `PENDING_*`)이 있는지 확인
+3. 있다면 해당 작업의 `meta.yml`을 읽고 현재 상태를 파악한 뒤 이어서 진행
+
+## 사용자 메모 규칙
+
+사용자가 `spec.md`, `plan.md` 같은 문서의 특정 라인 끝에 `<-` 형식으로 메모를 추가할 수 있다.
+
+- `<-` 뒤의 내용은 사용자 메모로 간주한다
+- 에이전트는 문서를 읽을 때 본문과 함께 이 메모도 반드시 반영한다
+- 사용자 메모가 기존 본문과 충돌하면, 사용자 메모를 최신 지시사항으로 우선 해석한다
+- 메모는 가능하면 해당 문장을 수정하거나 정식 섹션에 흡수해 문서 본문에 반영한다
+- 여러 줄에 메모가 흩어져 있어도 무시하지 말고 작업 전 확인한다
+
+## 워크플로우 규칙
+
+- Use the shipped CLI commands for workflow operations: `sduck init`, `sduck start <type> <slug>`, `sduck fast-track <type> <slug>`, `sduck spec approve [target]`, and `sduck plan approve [target]`.
+- Do not write implementation code before spec approval.
+- Do not start implementation before plan approval.
+- Follow the workflow order: `spec -> approval -> plan -> approval -> implementation`.
+- Respect `meta.yml` state transitions and update step completion immediately.
+- Write `plan.md` in detailed implementation units: include target files, the functions/sections or rough line ranges to inspect, the exact change intent for each file, and the tests or commands to verify the step.
+
+## fast-track 규칙
+
+- `sduck fast-track <type> <slug>`는 `spec.md`를 생략하지 않고 minimal spec + minimal plan을 생성하는 빠른 경로다.
+- fast-track은 반복적이거나 범위가 작고 명확한 작업에서만 사용한다.
+- 범위가 크거나 요구사항이 불확실한 작업에는 fast-track 대신 일반 `start -> spec -> plan` 흐름을 사용한다.
+- fast-track은 사용자 승인 자체를 우회하지 않는다.
+- interactive 환경에서만 확인 1회로 spec/plan 승인을 묶을 수 있다.
+- 비대화형 환경에서는 문서 생성만 수행하고, 이후 `sduck spec approve`, `sduck plan approve`로 이어간다.
+
+## 승인 규칙
+
+- 스펙 승인은 반드시 사용자가 직접 승인 의사를 전달해야 한다
+- 플랜 승인도 반드시 사용자가 직접 승인 의사를 전달해야 한다
+- `PENDING_SPEC_APPROVAL` 상태에서는 spec.md 작성/수정만 가능하고 코드 작성은 금지한다
+- `PENDING_PLAN_APPROVAL` 상태에서는 plan.md 작성/수정만 가능하고 코드 작성은 금지한다
+- `IN_PROGRESS` 상태에서만 구현과 step 완료 기록을 진행한다
+- Do not mark a task `DONE` until all completion criteria are satisfied.
+
+## 평가 규칙
+
+- spec을 새로 작성하거나 수정한 직후, 반드시 `.sduck/sduck-assets/eval/spec.yml`을 읽고 그 기준으로 자체 평가 점수를 남긴다
+- plan을 새로 작성하거나 수정한 직후, 반드시 `.sduck/sduck-assets/eval/plan.yml`을 읽고 그 기준으로 자체 평가 점수를 남긴다
+- 모든 Step 완료 후 `spec.md`의 완료 조건 체크리스트를 검증하고, `.sduck/sduck-assets/eval/task.yml`을 읽어 task 평가를 수행한다
+- After implementation is complete, run task evaluation, show the results, and only then move to completion processing.

package/.sduck/sduck-assets/agent-rules/cursor.mdc

@@ -0,0 +1,11 @@
+---
+description: sduck SDD workflow rules
+globs:
+  - "**/*"
+alwaysApply: true
+---
+
+## Cursor Instructions
+
+- Follow the repository SDD workflow exactly.
+- Use this rule file together with the shared SDD workflow block.

package/.sduck/sduck-assets/agent-rules/gemini-cli.md

@@ -0,0 +1,18 @@
+이 프로젝트는 **Spec-Driven Development(SDD)** 워크플로우를 따른다.
+`GEMINI.md`는 Gemini CLI가 직접 파일을 생성하고 상태를 관리할 때 참고하는 project-level instruction context다.
+워크플로우 구조와 규칙은 `sduck` CLI와 동일하다.
+
+## 절대 규칙
+
+다음 두 가지 승인은 절대 에이전트가 직접 처리하지 않는다.
+
+- **스펙 승인**은 사용자가 명시적으로 승인해야 한다
+- **플랜 승인**은 사용자가 명시적으로 승인해야 한다
+
+승인 전에는 어떤 코드도 작성하지 않는다.
+
+## Gemini CLI Instructions
+
+- Follow the repository SDD workflow exactly.
+- Use `GEMINI.md` as project-level instruction context.
+- Keep plans highly detailed: list exact file paths, likely functions or sections to edit, concrete change intent, and verification commands.

package/.sduck/sduck-assets/agent-rules/opencode.md

@@ -0,0 +1,18 @@
+이 프로젝트는 **Spec-Driven Development(SDD)** 워크플로우를 따른다.
+`sduck` CLI가 없으므로 opencode가 직접 파일을 생성하고 상태를 관리한다.
+워크플로우 구조와 규칙은 `sduck` CLI와 동일하다.
+
+## 절대 규칙
+
+다음 두 가지 승인은 절대 opencode가 직접 처리하지 않는다.
+
+- **스펙 승인**은 사용자가 명시적으로 승인해야 한다
+- **플랜 승인**은 사용자가 명시적으로 승인해야 한다
+
+승인 전에는 어떤 코드도 작성하지 않는다.
+
+## OpenCode Instructions
+
+- Follow the repository SDD workflow exactly.
+- Use `AGENT.md` as project-level instruction context.
+- Keep plans highly detailed: list exact file paths, likely functions or sections to edit, concrete change intent, and verification commands.

package/.sduck/sduck-assets/eval/plan.yml

@@ -0,0 +1,31 @@
+version: 1
+
+plan_evaluation:
+  scale:
+    min: 1
+    max: 5
+
+  criteria:
+    - key: semantic_clarity
+      label: semantic clarity
+      question: 의미가 분명한가
+
+    - key: abstraction
+      label: abstraction
+      question: 추상화 수준이 적절한가
+
+    - key: typing
+      label: typing
+      question: 타입 안정성을 충분히 고려했는가
+
+    - key: security
+      label: security
+      question: 보안상 문제 가능성을 줄였는가
+
+    - key: maintainability
+      label: maintainability
+      question: 유지보수하기 쉬운 구조인가
+
+    - key: testability
+      label: testability
+      question: 테스트하기 쉬운가

package/.sduck/sduck-assets/eval/spec.yml

@@ -0,0 +1,31 @@
+version: 1
+
+spec_evaluation:
+  scale:
+    min: 1
+    max: 5
+
+  criteria:
+    - key: problem_clarity
+      label: problem clarity
+      question: 문제와 목표가 분명한가
+
+    - key: scope_definition
+      label: scope definition
+      question: 범위와 제외 범위가 명확한가
+
+    - key: completion_criteria
+      label: completion criteria
+      question: 완료 조건이 검증 가능하게 정의되었는가
+
+    - key: feasibility
+      label: feasibility
+      question: 현재 시스템 기준으로 실행 가능한가
+
+    - key: risk_coverage
+      label: risk coverage
+      question: 엣지 케이스와 영향 범위를 충분히 고려했는가
+
+    - key: testability
+      label: testability
+      question: 테스트 및 검증 방법이 드러나는가

package/.sduck/sduck-assets/eval/task.yml

@@ -0,0 +1,31 @@
+version: 1
+
+task_evaluation:
+  scale:
+    min: 1
+    max: 5
+
+  criteria:
+    - key: spec_alignment
+      label: spec alignment
+      question: 구현 결과가 승인된 spec과 일치하는가
+
+    - key: plan_alignment
+      label: plan alignment
+      question: 구현 결과가 승인된 plan의 단계와 의도를 충실히 반영하는가
+
+    - key: implementation_quality
+      label: implementation quality
+      question: 구현 품질과 구조가 충분히 명확하고 견고한가
+
+    - key: test_completeness
+      label: test completeness
+      question: 테스트가 핵심 동작과 회귀 위험을 충분히 검증하는가
+
+    - key: documentation_quality
+      label: documentation quality
+      question: 필요한 문서와 사용 흐름이 구현과 일치하게 정리되었는가
+
+    - key: maintainability
+      label: maintainability
+      question: 이후 수정과 확장이 쉬운 상태로 정리되었는가

package/.sduck/sduck-assets/types/build.md

@@ -0,0 +1,194 @@
+# [build] {프로젝트명} — 프로젝트 초기 설정
+
+> **작업 타입:** `build` (Project Init/Build)
+> **작성자:**
+> **작성일:** YYYY-MM-DD
+> **연관 티켓:**
+
+---
+
+## 1. 프로젝트 개요
+
+### 목적 및 배경
+
+<!-- 이 프로젝트가 왜 존재하는지, 어떤 문제를 해결하는지 서술 -->
+
+### 핵심 목표
+
+<!-- 이 빌드 작업을 통해 달성하고자 하는 구체적인 결과물을 나열 -->
+
+- [ ]
+- [ ]
+- [ ]
+
+---
+
+## 2. 기술 스택
+
+| 구분                | 선택 | 버전 | 선택 이유 |
+| ------------------- | ---- | ---- | --------- |
+| 언어                |      |      |           |
+| 런타임              |      |      |           |
+| 프레임워크          |      |      |           |
+| DB                  |      |      |           |
+| ORM / Query Builder |      |      |           |
+| 상태 관리           |      |      |           |
+| 테스트 프레임워크   |      |      |           |
+| CI/CD               |      |      |           |
+| 컨테이너            |      |      |           |
+
+---
+
+## 3. 아키텍처
+
+### 전체 구조
+
+<!-- 디렉토리 구조 및 레이어 분리 방식 기술 (예: Clean Architecture, MVC 등) -->
+
+```
+{project-root}/
+├── src/
+│   ├── ...
+├── tests/
+│   ├── ...
+└── ...
+```
+
+### 계층 및 의존성 규칙
+
+<!-- 각 계층(Layer)의 역할과 의존 방향을 명시 -->
+
+---
+
+## 4. 코드 컨벤션
+
+### 네이밍 규칙
+
+| 대상              | 규칙 | 예시 |
+| ----------------- | ---- | ---- |
+| 파일명            |      |      |
+| 클래스 / 컴포넌트 |      |      |
+| 함수 / 메서드     |      |      |
+| 변수              |      |      |
+| 상수              |      |      |
+| 타입 / 인터페이스 |      |      |
+
+### 포맷팅
+
+<!-- 들여쓰기, 줄 길이, 세미콜론 등 -->
+
+- 들여쓰기:
+- 최대 줄 길이:
+- 기타:
+
+---
+
+## 5. 린팅 및 타입 검사
+
+| 도구         | 설정 파일 | 주요 규칙 |
+| ------------ | --------- | --------- |
+| Linter       |           |           |
+| Formatter    |           |           |
+| Type Checker |           |           |
+
+```
+<!-- 핵심 설정 값 또는 extends/plugins 목록 -->
+```
+
+---
+
+## 6. 테스트 전략
+
+### 목표 커버리지
+
+- 전체: **80%** 이상 (기본값)
+- 비즈니스 로직 (Unit): **%** 이상
+- API / 통합 (Integration): **%** 이상
+
+### 테스트 레벨별 전략
+
+| 레벨        | 도구 | 대상 범위 | 비고 |
+| ----------- | ---- | --------- | ---- |
+| Unit        |      |           |      |
+| Integration |      |           |      |
+| E2E         |      |           |      |
+
+---
+
+## 7. 환경 구성
+
+### 환경 목록
+
+| 환경         | 목적        | 배포 방식 |
+| ------------ | ----------- | --------- |
+| `local`      | 개발자 로컬 | 수동      |
+| `dev`        | 통합 개발   | CI 자동   |
+| `staging`    | QA / 검증   | 수동 승인 |
+| `production` | 운영        | 수동 승인 |
+
+### 환경 변수
+
+```
+# 필수 환경 변수 목록 (값 제외, 키만 명시)
+APP_ENV=
+DATABASE_URL=
+SECRET_KEY=
+```
+
+---
+
+## 8. Git 전략
+
+### 브랜치 모델
+
+<!-- 예: Git Flow / GitHub Flow / Trunk-based 중 선택 및 이유 -->
+
+### 커밋 메시지 컨벤션
+
+```
+<type>(<scope>): <subject>
+
+예) feat(auth): add JWT refresh token logic
+    fix(api): resolve null pointer on user fetch
+```
+
+### PR / MR 규칙
+
+- 최소 리뷰어 수:
+- 머지 방식: (Squash / Rebase / Merge Commit)
+
+---
+
+## 9. CI/CD 파이프라인
+
+```
+Push → Lint & Type Check → Unit Test → Build → (Integration Test) → Deploy
+```
+
+- **Lint / Type Check:** 실패 시 파이프라인 즉시 중단
+- **테스트 커버리지 임계값:** 미달 시 배포 차단
+
+---
+
+## 10. 제약 조건 및 비기능 요구사항
+
+| 항목                    | 요구사항 | 측정 기준 |
+| ----------------------- | -------- | --------- |
+| 성능                    |          |           |
+| 보안                    |          |           |
+| 접근성                  |          |           |
+| 브라우저 / OS 지원 범위 |          |           |
+
+---
+
+## 11. 미결 사항 (Open Questions)
+
+<!-- 아직 결정되지 않았거나 추가 논의가 필요한 항목 -->
+
+- [ ]
+
+---
+
+## 12. 참고 자료
+
+-

package/.sduck/sduck-assets/types/chore.md

@@ -0,0 +1,164 @@
+# [chore] {작업 내용 요약}
+
+> **작업 타입:** `chore` (Chore)
+> **세부 분류:** `dependency-update` / `build-config` / `ci-cd` / `documentation` / `infra` / `기타`
+> **작성자:**
+> **작성일:** YYYY-MM-DD
+> **연관 티켓:**
+
+---
+
+## 1. 작업 개요
+
+### 작업 목적
+
+<!-- 왜 이 작업이 필요한지 간략히 기술 -->
+
+### 작업 범위
+
+- [ ] 패키지 / 의존성 업데이트
+- [ ] 빌드 스크립트 / 설정 변경
+- [ ] CI/CD 파이프라인 수정
+- [ ] 문서 작성 / 수정
+- [ ] 환경 설정 변경
+- [ ] 기타:
+
+---
+
+## 2. 변경 상세
+
+### 현재 상태 (As-Is)
+
+<!-- 현재 버전, 설정, 문서 내용 등 -->
+
+### 변경 후 상태 (To-Be)
+
+<!-- 변경 후 버전, 설정, 문서 내용 등 -->
+
+### 변경 파일 목록
+
+```
+target_paths:
+  - package.json
+  - .github/workflows/...
+  - docs/...
+```
+
+---
+
+## 3. 의존성 변경 (해당 시)
+
+### 업데이트 목록
+
+| 패키지 | 현재 버전 | 변경 버전 | 변경 유형             | 변경 이유 |
+| ------ | --------- | --------- | --------------------- | --------- |
+|        |           |           | major / minor / patch |           |
+|        |           |           | major / minor / patch |           |
+
+### 주요 Breaking Changes 검토 (Major 업데이트 시)
+
+| 패키지 | Breaking Change 내용 | 대응 방안 |
+| ------ | -------------------- | --------- |
+|        |                      |           |
+
+### 제거 패키지
+
+| 패키지 | 제거 이유 | 대체 패키지 |
+| ------ | --------- | ----------- |
+|        |           |             |
+
+---
+
+## 4. CI/CD 변경 (해당 시)
+
+### 변경 전 파이프라인
+
+```
+(기존 파이프라인 흐름 또는 설정)
+```
+
+### 변경 후 파이프라인
+
+```
+(변경된 파이프라인 흐름 또는 설정)
+```
+
+### 변경 이유
+
+<!-- 성능, 보안, 유지보수성 등 -->
+
+---
+
+## 5. 문서 변경 (해당 시)
+
+| 문서            | 변경 내용 요약 | 변경 이유 |
+| --------------- | -------------- | --------- |
+| README.md       |                |           |
+| CONTRIBUTING.md |                |           |
+| docs/...        |                |           |
+
+---
+
+## 6. 검증 계획
+
+> chore 작업은 기능 변경이 없으므로 기존 테스트 통과 + 빌드 성공이 핵심 기준이다.
+
+### 검증 체크리스트
+
+- [ ] `lint` 통과
+- [ ] `build` 성공
+- [ ] 기존 단위 테스트 전체 통과
+- [ ] 기존 통합 테스트 전체 통과 (해당 시)
+- [ ] CI/CD 파이프라인 전체 동작 확인 (해당 시)
+- [ ] 로컬 개발 환경 정상 동작 확인
+- [ ] 스테이징 배포 및 동작 확인 (해당 시)
+
+### 검증 방법
+
+<!-- 특이사항이 있다면 구체적인 검증 명령어나 절차 기술 -->
+
+```bash
+# 예시
+npm install
+npm run lint
+npm run build
+npm test
+```
+
+---
+
+## 7. 영향 범위
+
+### 런타임 영향
+
+- [ ] 런타임 코드 변경 없음
+- [ ] 런타임에 영향 있음 (내용 명시):
+
+### 개발자 환경 영향
+
+<!-- 팀원들이 로컬 환경을 어떻게 업데이트해야 하는지 -->
+
+- [ ] `npm install` 재실행 필요
+- [ ] `.env` 파일 업데이트 필요: _(추가/변경 키 명시)_
+- [ ] 별도 마이그레이션 절차 필요:
+- [ ] 변경 없음
+
+---
+
+## 8. 롤백 계획
+
+- 롤백 방법: Git 스펙 단위 커밋 되돌리기
+- 특이사항: (예: 패키지 lock 파일 함께 롤백 필요)
+
+---
+
+## 9. 공지 사항
+
+<!-- 팀원들에게 공유해야 할 내용 (로컬 환경 업데이트 방법, 변경된 명령어 등) -->
+
+---
+
+## 10. 참고 자료
+
+- Changelog / Release Notes:
+- 관련 이슈: