@sduck/sduck-cli 0.1.2 → 0.1.4

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

@@ -0,0 +1,5 @@
+# Antigravity Instructions
+
+- Follow the repository SDD workflow exactly.
+- Use this workspace rule file together with the shared SDD workflow block.
+- 승인된 spec.md/plan.md를 수정하지 않는다. 요구사항이 바뀌면 새 태스크를 시작한다.

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

@@ -0,0 +1,19 @@
+이 프로젝트는 **Spec-Driven Development(SDD)** 워크플로우를 따른다.
+`sduck` CLI가 없으므로 Claude가 직접 파일을 생성하고 상태를 관리한다.
+워크플로우 구조와 규칙은 `sduck` CLI와 동일하다.
+
+## 절대 규칙
+
+다음 두 가지 승인은 절대 Claude가 직접 처리하지 않는다.
+
+- **스펙 승인**은 사용자가 명시적으로 승인해야 한다
+- **플랜 승인**은 사용자가 명시적으로 승인해야 한다
+
+승인 전에는 어떤 코드도 작성하지 않는다.
+승인된 spec.md/plan.md를 수정하지 않는다. 요구사항이 바뀌면 새 태스크를 시작한다.
+
+## 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,19 @@
+이 프로젝트는 **Spec-Driven Development(SDD)** 워크플로우를 따른다.
+생성된 `AGENT.md`는 codex 계열 도구가 참고할 project-level instruction context다.
+워크플로우 구조와 규칙은 `sduck` CLI와 동일하다.
+
+## 절대 규칙
+
+다음 두 가지 승인은 에이전트가 직접 처리하지 않는다.
+
+- **스펙 승인**은 사용자가 명시적으로 승인해야 한다
+- **플랜 승인**은 사용자가 명시적으로 승인해야 한다
+
+승인 전에는 어떤 코드도 작성하지 않는다.
+승인된 spec.md/plan.md를 수정하지 않는다. 요구사항이 바뀌면 새 태스크를 시작한다.
+
+## 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,94 @@
+# SDD Workflow Rules
+
+## ⚠️ CRITICAL: 상태별 파일 접근 제한
+
+- 코드를 작성하기 전에 반드시 `.sduck/sduck-workspace/`의 활성 태스크 `meta.yml`을 읽고 `status`를 확인한다.
+- `IN_PROGRESS` 상태에서만 구현 코드를 작성할 수 있다.
+- 승인된 `spec.md`/`plan.md`는 수정하지 않는다. 요구사항이 바뀌면 새 태스크를 시작한다.
+- `spec.md` 또는 `plan.md`를 작성한 직후라도, 사용자가 승인하기 전까지 구현하지 않는다.
+- "같은 세션"이라는 이유로 승인을 생략하지 않는다.
+
+| 상태 | spec.md | plan.md | 구현 파일 |
+|---|---|---|---|
+| PENDING_SPEC_APPROVAL | 허용 | 허용 | 차단 |
+| SPEC_APPROVED | 차단 | 허용 | 차단 |
+| IN_PROGRESS | 차단 | 차단 | 허용 |
+| DONE | 차단 | 차단 | 차단 |
+
+## 디렉토리 구조
+
+에이전트는 아래 경로를 기준으로 `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,12 @@
+---
+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.
+- 승인된 spec.md/plan.md를 수정하지 않는다. 요구사항이 바뀌면 새 태스크를 시작한다.

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

@@ -0,0 +1,19 @@
+이 프로젝트는 **Spec-Driven Development(SDD)** 워크플로우를 따른다.
+`GEMINI.md`는 Gemini CLI가 직접 파일을 생성하고 상태를 관리할 때 참고하는 project-level instruction context다.
+워크플로우 구조와 규칙은 `sduck` CLI와 동일하다.
+
+## 절대 규칙
+
+다음 두 가지 승인은 절대 에이전트가 직접 처리하지 않는다.
+
+- **스펙 승인**은 사용자가 명시적으로 승인해야 한다
+- **플랜 승인**은 사용자가 명시적으로 승인해야 한다
+
+승인 전에는 어떤 코드도 작성하지 않는다.
+승인된 spec.md/plan.md를 수정하지 않는다. 요구사항이 바뀌면 새 태스크를 시작한다.
+
+## 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/hooks/sdd-guard.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# sduck SDD guard hook for Claude Code
+# Enforces the state-based file access matrix via PreToolUse hook.
+# Exit 0 = allow, Exit 2 = block (message sent to Claude via stderr)
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# No file path (e.g. Bash tool) → allow
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+# Resolve relative to cwd
+CWD=$(echo "$INPUT" | jq -r '.cwd // empty')
+if [[ -z "$CWD" ]]; then
+  exit 0
+fi
+
+# Find sduck workspace
+WORKSPACE_DIR="$CWD/.sduck/sduck-workspace"
+if [[ ! -d "$WORKSPACE_DIR" ]]; then
+  exit 0
+fi
+
+# Always-allowed paths (relative check)
+REL_PATH="${FILE_PATH#"$CWD"/}"
+
+# Always allow: meta.yml, sduck assets, agent rule files, editor configs
+case "$REL_PATH" in
+  */meta.yml|.sduck/sduck-assets/*|.sduck/sduck-archive/*|\
+  CLAUDE.md|AGENT.md|GEMINI.md|\
+  .cursor/*|.agents/*|.claude/*|\
+  .serena/*)
+    exit 0
+    ;;
+esac
+
+# Find the most recent active task (non-DONE)
+STATUS=""
+TASK_DIR=""
+for dir in "$WORKSPACE_DIR"/*/; do
+  [[ -d "$dir" ]] || continue
+  META="$dir/meta.yml"
+  [[ -f "$META" ]] || continue
+
+  TASK_STATUS=$(grep -m1 '^status:' "$META" | sed 's/^status:[[:space:]]*//')
+
+  case "$TASK_STATUS" in
+    PENDING_SPEC_APPROVAL|SPEC_APPROVED|PENDING_PLAN_APPROVAL|IN_PROGRESS)
+      STATUS="$TASK_STATUS"
+      TASK_DIR="$dir"
+      ;;
+    DONE)
+      # Track DONE as fallback if no active task found
+      if [[ -z "$STATUS" ]]; then
+        STATUS="DONE"
+        TASK_DIR="$dir"
+      fi
+      ;;
+  esac
+done
+
+# No task at all → allow
+if [[ -z "$STATUS" ]]; then
+  exit 0
+fi
+
+# Check if the file is spec.md or plan.md (within the task workspace)
+IS_SPEC=false
+IS_PLAN=false
+case "$REL_PATH" in
+  */spec.md|spec.md) IS_SPEC=true ;;
+  */plan.md|plan.md) IS_PLAN=true ;;
+esac
+
+# Apply the state-based access matrix
+case "$STATUS" in
+  PENDING_SPEC_APPROVAL)
+    # spec.md, plan.md → allow; implementation files → block
+    if $IS_SPEC || $IS_PLAN; then
+      exit 0
+    fi
+    echo "⛔ [sduck] 현재 상태: $STATUS — 스펙 승인 전에는 구현 코드를 작성할 수 없습니다. \`sduck spec approve\`를 먼저 실행하세요." >&2
+    exit 2
+    ;;
+  SPEC_APPROVED|PENDING_PLAN_APPROVAL)
+    # plan.md → allow; spec.md, implementation files → block
+    if $IS_PLAN; then
+      exit 0
+    fi
+    if $IS_SPEC; then
+      echo "⛔ [sduck] 현재 상태: $STATUS — 승인된 스펙은 수정할 수 없습니다. 요구사항이 바뀌었다면 새 태스크를 시작하세요." >&2
+      exit 2
+    fi
+    echo "⛔ [sduck] 현재 상태: $STATUS — 플랜 승인 전에는 구현 코드를 작성할 수 없습니다. \`sduck plan approve\`를 먼저 실행하세요." >&2
+    exit 2
+    ;;
+  IN_PROGRESS)
+    # implementation files → allow; spec.md, plan.md → block
+    if $IS_SPEC; then
+      echo "⛔ [sduck] 현재 상태: IN_PROGRESS — 승인된 스펙은 수정할 수 없습니다. 요구사항이 바뀌었다면 새 태스크를 시작하세요." >&2
+      exit 2
+    fi
+    if $IS_PLAN; then
+      echo "⛔ [sduck] 현재 상태: IN_PROGRESS — 승인된 플랜은 수정할 수 없습니다. 요구사항이 바뀌었다면 새 태스크를 시작하세요." >&2
+      exit 2
+    fi
+    exit 0
+    ;;
+  DONE)
+    # everything blocked except always-allowed paths (already handled above)
+    if $IS_SPEC || $IS_PLAN; then
+      echo "⛔ [sduck] 현재 상태: DONE — 완료된 태스크의 문서는 수정할 수 없습니다. \`sduck start\`로 새 태스크를 시작하세요." >&2
+      exit 2
+    fi
+    echo "⛔ [sduck] 현재 상태: DONE — 새 코드를 작성하려면 \`sduck start\`로 새 태스크를 시작하세요." >&2
+    exit 2
+    ;;
+esac
+
+exit 0

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

@@ -0,0 +1,19 @@
+이 프로젝트는 **Spec-Driven Development(SDD)** 워크플로우를 따른다.
+`sduck` CLI가 없으므로 opencode가 직접 파일을 생성하고 상태를 관리한다.
+워크플로우 구조와 규칙은 `sduck` CLI와 동일하다.
+
+## 절대 규칙
+
+다음 두 가지 승인은 절대 opencode가 직접 처리하지 않는다.
+
+- **스펙 승인**은 사용자가 명시적으로 승인해야 한다
+- **플랜 승인**은 사용자가 명시적으로 승인해야 한다
+
+승인 전에는 어떤 코드도 작성하지 않는다.
+승인된 spec.md/plan.md를 수정하지 않는다. 요구사항이 바뀌면 새 태스크를 시작한다.
+
+## 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. 참고 자료
+
+-