@sduck/sduck-cli 0.1.1 → 0.1.3

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/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/README.md

@@ -0,0 +1,212 @@
+# 🦆 sduck (Spec-Driven Development CLI)
+
+> "Don't let your AI write code before you approve the plan."
+
+sduck은 AI 에이전트(Claude Code, Cursor, Codex 등)가 설계를 건너뛰고 바로 코드를 작성하는 것을 방지하고, Spec-Driven Development(SDD) 워크플로우를 물리적으로 강제하는 CLI 도구입니다.
+
+![node](https://img.shields.io/badge/node-%3E%3D20-blue.svg)
+![license](https://img.shields.io/badge/License-MIT-yellow.svg)
+
+## 🚀 왜 sduck인가요?
+
+AI 에이전트와 협업할 때 가장 흔한 문제는 **"충분한 설계 없이 타이핑부터 시작한다"**는 것입니다. 이는 결국 잘못된 설계로 인한 재작업(Rework)과 기술 부채로 이어집니다.
+
+sduck은 개발자와 AI 사이의 '설계-승인-구현' 프로세스를 도구 수준에서 강제합니다:
+
+- **물리적 승인 단계:** 사용자가 스펙과 플랜을 승인하기 전까지 AI가 코드를 수정하지 못하게 차단합니다.
+- **구조화된 작업 관리:** 모든 작업은 `spec.md`, `plan.md`, `meta.yml`을 통해 기록되고 관리됩니다.
+- **우리 팀만의 워크플로우 자산:** 팀의 컨벤션에 맞는 템플릿과 평가 기준을 프로젝트 자산으로 관리합니다.
+
+## 🔄 워크플로우 (The SDD Process)
+
+sduck은 아래의 엄격한 절차를 지향하며, 각 단계는 CLI를 통해 전이됩니다.
+
+1. **Init:** 프로젝트 환경 설정 및 에이전트 규칙(`CLAUDE.md` 등) 생성
+2. **Start:** 새로운 작업(feature, fix 등) 생성 및 템플릿 준비
+3. **Fast Track (optional):** minimal spec + minimal plan을 빠르게 생성하고, 대화형 환경에서는 확인 1회로 승인까지 이어질 수 있음
+4. **Spec:** AI가 요구사항을 분석하여 `spec.md` 작성 및 자체 품질 평가
+5. **Approve Spec:** 사용자가 설계를 검토하고 `sduck spec approve` 실행
+6. **Plan:** AI가 상세 구현 계획을 `plan.md`에 단계별로 작성
+7. **Approve Plan:** 사용자가 계획을 검토하고 `sduck plan approve` 실행
+8. **Implementation:** 승인된 계획의 Step에 따라 AI가 실제 코드 구현
+9. **Done:** spec 체크리스트와 task eval 기준을 확인한 뒤 `sduck done` 실행
+
+## 🛠 설치 및 초기화
+
+```bash
+# 글로벌 설치
+npm install -g @sduck/sduck-cli
+
+# 프로젝트 초기화 (사용할 에이전트 지정)
+sduck init --agents claude-code,cursor,codex
+```
+
+## 📖 주요 명령어
+
+### 빠른 시작 예시
+
+```bash
+# 1) 초기화
+sduck init --agents claude-code,codex
+
+# 2) 일반 흐름
+sduck start feature login-system
+sduck spec approve login-system
+sduck plan approve login-system
+
+# 3) 빠른 흐름
+sduck fast-track fix copy-bug
+
+# 4) 구현 완료 후
+sduck done login-system
+```
+
+### 1. 작업 시작 (Start)
+
+작업 타입에 맞는 폴더와 템플릿 파일을 생성합니다.
+
+```bash
+# sduck start <type> <slug>
+sduck start feature login-system
+sduck start fix auth-bug
+```
+
+생성 직후 상태는 `PENDING_SPEC_APPROVAL`입니다.
+
+### 2. 스펙 승인 (Approve Spec)
+
+작성된 `spec.md`를 검토한 후 승인합니다. 상태가 `SPEC_APPROVED`로 변경됩니다.
+target을 지정할 때는 정확한 `slug` 또는 전체 task `id`만 허용됩니다.
+
+```bash
+sduck spec approve [slug]
+```
+
+### 3. 빠른 시작 (Fast Track)
+
+반복적이거나 범위가 명확한 작업은 minimal spec과 minimal plan을 한 번에 생성할 수 있습니다. `spec.md`는 생략되지 않으며, 비대화형 환경에서는 자동 승인 없이 생성만 수행합니다.
+
+- `spec.md`는 항상 생성됩니다
+- interactive 환경에서는 확인 1회 후 spec/plan 승인을 묶어 진행할 수 있습니다
+- 비대화형 환경에서는 생성만 수행하고, 이후 `sduck spec approve <slug>` → `sduck plan approve <slug>`로 이어집니다
+- 범위가 크거나 요구사항이 불명확한 작업은 일반 `start` 흐름을 권장합니다
+
+```bash
+sduck fast-track <type> <slug>
+```
+
+### 4. 플랜 승인 (Approve Plan)
+
+`plan.md`에 작성된 단계(Steps)를 검토하고 승인합니다. 상태가 `IN_PROGRESS`로 변경되며 구현 권한이 부여됩니다.
+target을 지정할 때는 정확한 `slug` 또는 전체 task `id`만 허용됩니다.
+
+```bash
+sduck plan approve [slug]
+```
+
+### 5. 작업 완료 (Done)
+
+구현이 끝난 작업의 step 완료 여부, spec 체크리스트, task eval 자산을 확인한 뒤 `DONE` 상태로 마감합니다.
+
+- `steps.total`과 `steps.completed`가 모두 맞아야 합니다
+- `spec.md`의 체크리스트가 모두 완료돼야 합니다
+- target을 지정할 때는 정확한 `slug` 또는 전체 task `id`만 허용됩니다
+
+```bash
+sduck done [slug]
+```
+
+## ✅ 상태 전이
+
+```text
+PENDING_SPEC_APPROVAL -> SPEC_APPROVED -> IN_PROGRESS -> DONE
+```
+
+- `start`: `PENDING_SPEC_APPROVAL`
+- `spec approve`: `SPEC_APPROVED`
+- `plan approve`: `IN_PROGRESS`
+- `done`: `DONE`
+- `fast-track`: minimal spec/plan을 생성하고, 환경에 따라 `PENDING_SPEC_APPROVAL` 또는 `IN_PROGRESS`까지 진행
+
+## 🧭 일반 흐름 vs fast-track
+
+| 구분          | 일반 흐름                      | fast-track                                |
+| ------------- | ------------------------------ | ----------------------------------------- |
+| 문서 생성     | 타입 템플릿 기반 spec, 빈 plan | minimal spec + minimal plan               |
+| 승인 방식     | spec 승인, plan 승인 각각 진행 | interactive에서는 확인 1회로 묶을 수 있음 |
+| 비대화형 동작 | 각 명령 수동 실행              | 생성만 수행, 승인 자동 진행 없음          |
+| 추천 상황     | 범위가 크거나 애매한 작업      | 반복적이고 범위가 명확한 작업             |
+
+## 🎨 자산 커스터마이징 (Asset Customization)
+
+sduck은 팀의 컨벤션을 자산(`.sduck/sduck-assets/`)으로 관리합니다. 이 폴더를 Git에 포함하여 팀원 모두가 동일한 기준을 공유하세요.
+
+### 1. 스펙 템플릿 (`types/`)
+
+작업 타입별 `spec.md`의 형식을 정의합니다. 보안 체크리스트나 성능 고려사항을 추가하세요.
+
+- 경로: `.sduck/sduck-assets/types/` (`feature.md`, `fix.md`, `refactor.md` 등)
+
+### 2. 품질 평가 기준 (`eval/`)
+
+AI가 작성한 문서의 품질을 스스로 검토할 때 사용하는 기준입니다. YAML 파일에서 질문 항목과 점수 범위를 수정할 수 있습니다.
+
+- 경로: `.sduck/sduck-assets/eval/`
+- 파일: `spec.yml` (설계 평가), `plan.yml` (계획 평가), `task.yml` (결과 평가)
+
+## 📂 디렉토리 구조
+
+sduck은 모든 상태를 로컬 파일로 관리하여 Git으로 완벽하게 추적 가능합니다.
+
+```
+your-project/
+├── .sduck/
+│   ├── sduck-assets/       # ✨ 팀 표준 (템플릿, 평가 기준, 규칙 원본)
+│   │   ├── types/          # 작업 타입별 spec.md 템플릿
+│   │   ├── eval/           # 품질 평가 기준 (YAML)
+│   │   └── agent-rules/    # 에이전트별 규칙 원본
+│   └── sduck-workspace/    # 📝 작업 이력 (Git 추적 권장)
+│       └── 20260319-1000-feature-login/
+│           ├── meta.yml    # 작업 상태 관리 (status, timestamps)
+│           ├── spec.md     # 요구사항 명세서 또는 minimal spec
+│           └── plan.md     # 상세 구현 계획서 또는 minimal plan
+├── CLAUDE.md               # Claude Code용 규칙
+└── AGENT.md                # Codex/OpenCode용 규칙
+```
+
+`meta.yml`에는 최소 아래 상태 정보가 들어갑니다.
+
+```yaml
+status: PENDING_SPEC_APPROVAL | SPEC_APPROVED | IN_PROGRESS | DONE
+spec:
+  approved: <boolean>
+plan:
+  approved: <boolean>
+steps:
+  total: <number | null>
+  completed: [<step numbers>]
+completed_at: <timestamp | null>
+```
+
+## 🤖 지원 에이전트 (Rule Generation)
+
+`sduck init` 시 각 에이전트의 특성에 맞는 규칙 파일을 생성합니다.
+
+| 에이전트         | 생성 파일             | 특징                             |
+| ---------------- | --------------------- | -------------------------------- |
+| Claude Code      | `CLAUDE.md`           | 프로젝트 루트 지침으로 자동 로드 |
+| Cursor           | `.cursor/rules/*.mdc` | Cursor 전용 Rule 파일로 동작     |
+| Codex / OpenCode | `AGENT.md`            | 공용 에이전트 규칙 파일          |
+| Gemini CLI       | `GEMINI.md`           | 구글 제미나이 에이전트용 지침    |
+| Antigravity      | `.agents/rules/*.md`  | Antigravity 에이전트 전용 지침   |
+
+## 🤝 기여하기
+
+1. 이 리포지토리를 포크합니다.
+2. 새로운 브랜치를 생성합니다 (`git checkout -b feature/amazing-feature`).
+3. 변경 사항을 커밋합니다 (`git commit -m 'feat: Add amazing feature'`).
+4. Pull Request를 생성합니다.
+
+## 📄 라이선스
+
+이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.