@simplysm/sd-claude 13.0.84 → 13.0.86

package/claude/skills/sd-document/extract_pdf.py

@@ -1,7 +1,8 @@
 #!/usr/bin/env python3
 """Extract text, tables, and images from PDF files page by page."""
 
-import sys
+import struct
+import logging
 from _common import (
     setup_encoding, make_output_paths, print_header, save_image,
     print_image_summary, run_cli, normalize_cell,
@@ -40,35 +41,26 @@ def extract(file_path):
                         print("| " + " | ".join(cells) + " |")
                     print()
 
-    # Image extraction (pypdf)
+    # Image extraction (pypdf page.images API)
+    logging.getLogger("pypdf").setLevel(logging.ERROR)
     reader = PdfReader(file_path)
     for page_num, page in enumerate(reader.pages, 1):
-        if "/XObject" not in (page.get("/Resources") or {}):
-            continue
-        xobjects = page["/Resources"]["/XObject"].get_object()
-        for obj_name in xobjects:
-            obj = xobjects[obj_name].get_object()
-            if obj.get("/Subtype") == "/Image":
-                img_idx += 1
-                filters = obj.get("/Filter", "")
-                if isinstance(filters, list):
-                    filters = filters[0] if filters else ""
-                filter_str = str(filters)
-                ext = "png"
-                if "/DCTDecode" in filter_str:
-                    ext = "jpg"
-                elif "/JPXDecode" in filter_str:
-                    ext = "jp2"
-                try:
-                    img_path = save_image(out_dir, img_idx, obj.get_data(), ext)
-                except Exception as exc:
-                    print(f"Warning: failed to decode image {img_idx}: {exc}", file=sys.stderr)
-                    img_path = save_image(out_dir, img_idx, obj._data if hasattr(obj, "_data") else b"", "bin")
-                print(f"[IMG] (page={page_num}) {img_path}")
+        for img in page.images:
+            data = img.data
+            # Filter small mask/decorative images by checking PNG IHDR dimensions
+            if data[:4] == b'\x89PNG' and len(data) >= 24:
+                w = struct.unpack('>I', data[16:20])[0]
+                h = struct.unpack('>I', data[20:24])[0]
+                if w <= 4 or h <= 4:
+                    continue
+            ext = img.name.rsplit('.', 1)[-1] if '.' in img.name else "png"
+            img_idx += 1
+            img_path = save_image(out_dir, img_idx, data, ext)
+            print(f"[IMG] (page={page_num}) {img_path}")
 
     print()
     print_image_summary(img_idx, out_dir)
 
 
 if __name__ == "__main__":
-    run_cli(extract, "extract_pdf.py", {"pdfplumber": "pdfplumber", "pypdf": "pypdf"})
+    run_cli(extract, "extract_pdf.py", {"pdfplumber": "pdfplumber", "pypdf": "pypdf", "Pillow": "PIL"})

package/claude/skills/sd-document/extract_pptx.py

@@ -1,7 +1,6 @@
 #!/usr/bin/env python3
 """Extract text and images from PPTX files with per-slide coordinates."""
 
-import sys
 from _common import (
     setup_encoding, make_output_paths, print_header, save_image,
     ext_from_content_type, print_image_summary, run_cli,

package/claude/skills/sd-document/extract_xlsx.py

@@ -1,7 +1,6 @@
 #!/usr/bin/env python3
 """Extract data and images from XLSX files with cell positions."""
 
-import sys
 from _common import (
     setup_encoding, make_output_paths, print_header, save_image,
     print_image_summary, run_cli,
@@ -24,12 +23,11 @@ def extract(file_path):
         print(f"## Sheet: {sheet_name}\n")
 
         # Data extraction
-        rows = list(ws.iter_rows(values_only=False))
-        if not rows:
+        if ws.max_row is None or ws.max_row == 0:
             print("(empty sheet)\n")
             continue
 
-        for row in rows:
+        for row in ws.iter_rows(values_only=False):
             cells = []
             for cell in row:
                 val = cell.value

package/claude/skills/sd-email-analyze/SKILL.md

@@ -1,44 +1,54 @@
 ---
 name: sd-email-analyze
-description: Used when requesting "email file analysis", "email content extraction", "attachment extraction", or "email summary" for .eml or .msg files.
+description: 이메일 파일(.eml/.msg)을 분석하여 헤더, 본문, 인라인 이미지, 첨부파일을 추출. 사용자가 .eml/.msg 파일의 내용 확인이나 분석을 요청할 때 사용
+argument-hint: "<이메일 파일 경로>"
 ---
 
-# SD Email Analyze — Email File Analysis and Content Extraction
+# sd-email-analyze: 이메일 파일 분석 및 내용 추출
 
-Parses `.eml` and `.msg` (Outlook) email files to extract and analyze mail headers, body text, inline images, and attachments.
+`.eml` 및 `.msg`(Outlook) 이메일 파일을 파싱하여 메일 헤더, 본문, 인라인 이미지, 첨부파일을 추출하고 분석한다.
 
-ARGUMENTS: Email file path (required). Specify a `.eml` or `.msg` file path.
+## 1. 인자 파싱
 
----
+`$ARGUMENTS`에서 이메일 파일 경로를 추출한다.
+- `$ARGUMENTS`가 비어있으면 현재 대화 맥락에서 이메일 파일 경로를 파악한다. 대화 맥락도 없으면 AskUserQuestion으로 파일 경로를 요청한다
+- 지원 형식: `.eml`, `.msg`
+- 파일이 존재하지 않거나 지원하지 않는 확장자이면 AskUserQuestion으로 올바른 경로를 요청한다
 
-## Step 1: Parse the Email File
+## 2. 이메일 파일 파싱
 
-Extract the email file path from ARGUMENTS and run the following command:
+다음 명령을 실행하여 이메일 파일을 파싱한다:
 
 ```bash
-python .claude/skills/sd-email-analyze/email-analyzer.py <email_file_path>
+python ${CLAUDE_SKILL_DIR}/email-analyzer.py <이메일_파일_경로>
 ```
 
-- On first run, `extract-msg` is automatically installed.
-- The output is a markdown report printed to stdout, and extracted files are saved to the `<email_file_name>_files/` directory.
+- 최초 실행 시 `extract-msg` 패키지가 자동 설치된다
+- 출력은 마크다운 리포트(stdout)이며, 추출된 파일은 `<이메일_파일명>_files/` 디렉토리에 저장된다
+
+### 출력 구조
+
+| 섹션 | 내용 |
+|------|------|
+| Email Info | Subject, From, To, CC, Date, 첨부파일 수 |
+| Body | 본문 텍스트 (plain text 우선, 없으면 HTML 스트립) |
+| Inline Images | 저장된 인라인 이미지 파일 경로 테이블 |
+| Attachments | 저장된 첨부파일 경로 테이블 |
 
-### Output Structure
+## 3. 추출 파일 분석
 
-1. **Mail Info Table**: Subject, From, To, CC, Date, Count
-2. **Body Text**: Plain text (if plain text is unavailable, HTML tags are stripped)
-3. **Inline Images**: Table of saved file paths
-4. **Attachments**: Table of saved file paths
+2단계 출력의 파일 경로를 확인하고 다음을 수행한다. 인라인 이미지 확인과 첨부파일 분석은 독립적이므로 가능한 한 병렬로 수행한다.
 
-## Step 2: Analyze Extracted Files
+### 인라인 이미지
 
-Check the extracted file paths from the Step 1 output and perform the following:
+Read 도구로 각 저장 경로의 이미지를 확인한다.
 
-1. **Inline Images**: Use the **Read** tool to view each saved path
-2. **Attachments**: Use the **Read** tool (for images) or the **sd-document** skill script (for DOCX, XLSX, PPTX, PDF)
+### 첨부파일
 
-### Inline Image Processing
+- 이미지 파일: Read 도구로 확인
+- 문서 파일(DOCX, XLSX, PPTX, PDF): `/sd-document` 스킬로 분석
 
-Images are extracted from two sources:
+## 4. 완료 안내
 
-1. **CID Images**: MIME parts with a Content-ID (referenced via `cid:` in HTML)
-2. **Data URI Images**: Base64-encoded images within HTML (`data:image/...;base64,...`)
+분석이 완료되면 다음을 출력한다:
+- 3단계에서 수행한 파일별 분석 결과 요약 (2단계에서 이미 출력된 이메일 기본 정보는 반복하지 않는다)

package/claude/skills/sd-init/SKILL.md

@@ -1,133 +1,152 @@
 ---
 name: sd-init
-description: Used when requesting "initialize", "init", "sd-init", "generate CLAUDE.md", etc.
+description: 프로젝트 설정 파일을 분석하여 CLAUDE.md를 자동 생성. 사용자가 CLAUDE.md 생성이나 갱신을 요청할 때 사용
+argument-hint: ""
 ---
 
-# SD Init — Auto-generate CLAUDE.md
+# sd-init: CLAUDE.md 자동 생성
 
-Analyze the project and auto-generate CLAUDE.md. Overwrite if the file already exists.
+프로젝트를 분석하여 CLAUDE.md를 생성한다. 기존 파일이 있으면 비교하여 병합한다.
 
----
+1~3단계는 독립적이므로 병렬로 수행할 수 있다.
 
-## Step 1: Detect Package Manager
+## 1. 패키지 매니저 감지
 
-Determine the PM from the lock file in the project root:
+프로젝트 루트의 lock 파일로 패키지 매니저를 판별한다:
 
 1. `pnpm-lock.yaml` → pnpm
 2. `yarn.lock` → yarn
-3. Otherwise → npm
+3. `bun.lock` 또는 `bun.lockb` → bun
+4. 그 외 → npm
+
+## 2. 스크립트 분석
 
-## Step 2: Analyze Scripts
+`package.json`의 `scripts` 섹션을 Read하고, 각 스크립트가 실행하는 CLI 도구를 분석한다.
 
-Read the `scripts` in `package.json`, and for each CLI tool invoked by a script, run `--help` or similar help commands via Bash to identify available arguments and flags.
+- 잘 알려진 도구(`tsc`, `vitest`, `eslint`, `prettier`, `playwright` 등)를 직접 실행하는 경우: 실행 내용을 그대로 기록
+- 프로젝트 내부 CLI나 커스텀 스크립트(예: `tsx packages/.../cli.ts`)를 실행하는 경우: Bash로 `--help`를 붙여 실행(timeout 5초)하여 사용 가능한 서브커맨드와 주요 옵션을 파악. 실패하면 scripts 내용만 기록
 
-Based on the gathered information, group scripts by category (development, build, test, lint, etc.), and organize the basic usage and key flag examples for each script.
+이 단계에서는 정보 수집만 수행한다. 최종 포맷팅은 4단계에서 한다.
 
-## Step 3: Analyze Coding Rules
+## 3. 코딩룰 분석
 
-Find and read the following config files from the project root (only those that exist):
+프로젝트 루트에서 다음 설정 파일을 찾아 존재하는 것만 Read한다:
 
-- ESLint: `eslint.config.*`, `.eslintrc.*`, `packages/*/eslint.*`, etc.
+- ESLint: 프로젝트 루트의 `eslint.config.*`, `.eslintrc.*`
 - Prettier: `.prettierrc*`, `prettier.config.*`
 - EditorConfig: `.editorconfig`
-- TypeScript: `compilerOptions` in the root `tsconfig.json` that affect code style, such as `strict`, `noImplicitAny`, etc.
+- TypeScript: 루트 `tsconfig.json`의 `compilerOptions`
 - Stylelint: `.stylelintrc*`, `stylelint.config.*`
 
-Summarize only the frequently violated rules that Claude is likely to suggest incorrectly — keep it highly concise.
+다음 기준으로 규칙을 선별하여 요약한다:
+- 기본값과 다른 설정 (예: `verbatimModuleSyntax: true`)
+- error 레벨의 비표준 규칙 (예: `no-console: error`)
+- 특정 API 사용 금지/강제 규칙 (예: `Buffer` 금지 → `Uint8Array` 사용)
 
-## Step 4: Generate CLAUDE.md
+## 4. CLAUDE.md 생성
 
-Combine the information above and write `CLAUDE.md` in the project root:
+1~3단계에서 수집한 정보를 종합하여 CLAUDE.md 내용을 생성한다. 이미 읽은 파일은 다시 읽지 않는다.
 
-- **Project info**: `name` and `description` from `package.json`
-- **PM**: Package manager detected in Step 1
-- **Monorepo structure**: If a `workspaces` field or `pnpm-workspace.yaml` exists, briefly describe the workspace paths
-- **Tech stack**: Identify key technologies (frameworks, bundlers, test tools, etc.) from `dependencies`/`devDependencies` and describe them very briefly
-- **Commands**: Script usage organized in Step 2
-- **Coding rules**: Rules from Step 3 that Claude should follow. Write as a `## Coding Rules` section
+포함할 내용:
 
-### Reference Example
+- **프로젝트 정보**: `package.json`의 `name`, `description`, 패키지 매니저
+- **모노레포 구조**: `workspaces` 필드나 `pnpm-workspace.yaml`이 있으면 워크스페이스 경로를 간략히 기술
+- **기술 스택**: `dependencies`/`devDependencies`에서 프레임워크, 번들러, 테스트 도구 등 주요 라이브러리를 나열 (최대 10개)
+- **명령어**: 2단계에서 수집한 스크립트를 카테고리별로 bash 코드블록에 사용 예시로 포맷팅
+- **코딩룰**: 3단계에서 선별한 규칙을 불릿 리스트로 작성
 
-Below is an example of a well-written CLAUDE.md. Do not copy the format verbatim — adapt it flexibly to the project's characteristics.
+### 참고 예시
 
-```markdown
+아래 예시의 **섹션 구성과 포맷팅 스타일**(bash 코드블록, 인라인 주석, 불릿 리스트)을 따르되, 내용은 대상 프로젝트에 맞게 작성한다. 예시에 없는 섹션을 추가하거나, 프로젝트에 해당하지 않는 섹션은 생략할 수 있다.
+
+````markdown
 # Simplysm
 
-pnpm monorepo. Package paths: `packages/*`, tests: `tests/*`
+pnpm 모노레포. 패키지 경로: `packages/*`, 테스트: `tests/*`
 
-## Commands
+## 명령어
 
-All commands internally run `pnpm sd-cli <command>`. The `--debug` flag is available for all commands.
-If `[targets..]` is not specified, all packages defined in `sd.config.ts` are targeted.
-Targets are specified by package path (e.g., `packages/core-common`, `tests/orm`).
+모든 명령어는 내부적으로 `pnpm sd-cli <command>`를 실행한다. `--debug` 플래그를 모든 명령어에 사용할 수 있다.
+`[targets..]`를 지정하지 않으면 `sd.config.ts`에 정의된 모든 패키지가 대상이 된다.
+대상은 패키지 경로로 지정한다 (예: `packages/core-common`, `tests/orm`).
 
-### Development
+### 개발
 
-​```bash
-pnpm dev [targets..]                     # Run client+server packages in dev mode
-pnpm dev packages/solid-demo             # Dev mode for a specific package only
-pnpm dev -o key=value                    # Pass options to sd.config.ts
+```bash
+pnpm dev [targets..]                     # 클라이언트+서버 패키지를 개발 모드로 실행
+pnpm dev packages/solid-demo             # 특정 패키지만 개발 모드로 실행
+pnpm dev -o key=value                    # sd.config.ts에 옵션 전달
 
-pnpm watch [targets..]                   # Watch mode for library package builds
-pnpm watch packages/core-common          # Watch a specific package only
-​```
+pnpm watch [targets..]                   # 라이브러리 패키지 빌드 watch 모드
+pnpm watch packages/core-common          # 특정 패키지만 watch
+```
 
-### Build & Deploy
+### 빌드 & 배포
 
-​```bash
-pnpm build [targets..]                   # Production build
-pnpm build packages/solid                # Build a specific package only
+```bash
+pnpm build [targets..]                   # 프로덕션 빌드
+pnpm build packages/solid                # 특정 패키지만 빌드
 
-pnpm pub [targets..]                     # Build then deploy (npm/sftp)
-pnpm pub --no-build                      # Deploy only, skip build
-pnpm pub --dry-run                       # Simulate without actual deployment
-​```
+pnpm pub [targets..]                     # 빌드 후 배포 (npm/sftp)
+pnpm pub --no-build                      # 빌드 없이 배포만
+pnpm pub --dry-run                       # 실제 배포 없이 시뮬레이션
+```
 
-### Code Quality Checks
+### 코드 품질 검사
 
-​```bash
-pnpm typecheck [targets..]               # TypeScript type check
-pnpm lint [targets..]                    # Run ESLint + Stylelint
-pnpm lint:fix [targets..]               # Auto-fix lint issues (--fix)
-pnpm check [targets..]                   # Full check (typecheck + lint + test in parallel)
-pnpm vitest [targets..]                  # vitest watch mode
-pnpm vitest run [targets..]              # Run tests once
-​```
+```bash
+pnpm typecheck [targets..]               # TypeScript 타입 검사
+pnpm lint [targets..]                    # ESLint + Stylelint 실행
+pnpm lint:fix [targets..]               # 린트 이슈 자동 수정 (--fix)
+pnpm check [targets..]                   # 전체 검사 (타입 검사 + 린트 + 테스트 병렬 실행)
+pnpm vitest [targets..]                  # vitest watch 모드
+pnpm vitest run [targets..]              # 테스트 1회 실행
+```
 
-## Architecture
+## 아키텍처
 
-Dependency direction: top → bottom. `core-common` is a leaf package with no internal dependencies.
+의존 방향: 위 → 아래. `core-common`은 내부 의존성이 없는 리프 패키지이다.
 
-​```
-Apps:     solid-demo (client) / solid-demo-server (server)
+```
+앱:       solid-demo (클라이언트) / solid-demo-server (서버)
 UI:       solid (SolidJS + Tailwind)
-Service:  service-server (Fastify) / service-client / service-common
+서비스:   service-server (Fastify) / service-client / service-common
 ORM:      orm-node (MySQL/PostgreSQL/MSSQL) / orm-common
-Core:     core-common (neutral) / core-browser / core-node
-Tools:    sd-cli, lint, excel, storage, sd-claude, mcp-playwright
-​```
+코어:     core-common (중립) / core-browser / core-node
+도구:     sd-cli, lint, excel, storage, sd-claude, mcp-playwright
+```
 
+## 통합 테스트
 
-## Integration Tests
+`tests/` 폴더에 위치한다. `pnpm vitest run tests/orm` 등으로 실행한다.
 
-Located in the `tests/` folder. Run with `pnpm vitest run tests/orm`, etc.
+- `tests/orm` — DB 연결, DbContext, escape 테스트 (MySQL, PostgreSQL, MSSQL). Docker 필요.
+- `tests/service` — 서비스 클라이언트-서버 통신 테스트.
 
-- `tests/orm` — DB connection, DbContext, escape tests (MySQL, PostgreSQL, MSSQL). Requires Docker.
-- `tests/service` — Service client-server communication tests.
+## 코딩룰
 
-## Coding Rules
+- `import type` 필수 (`verbatimModuleSyntax`), `#private` 금지 → `private` 키워드 사용
+- `console.*` 금지, `if (str)` 금지 → 명시적 비교 `str !== ""` 사용 (nullable boolean/object는 허용)
+- `Buffer` 금지 → `Uint8Array`, `events` 금지 → `@simplysm/core-common`의 `EventEmitter` 사용
+- SolidJS: props 구조분해 금지, `.map()` 대신 `<For>` 사용, `className` 대신 `class` 사용
+- Prettier: 100자, 2칸 들여쓰기, 세미콜론, trailing comma, LF
+````
 
-- `import type` required (`verbatimModuleSyntax`), `#private` forbidden → use `private` keyword
-- `console.*` forbidden, `if (str)` forbidden → use explicit comparison `str !== ""` (nullable boolean/object allowed)
-- `Buffer` forbidden → `Uint8Array`, `events` forbidden → `EventEmitter` from `@simplysm/core-common`
-- SolidJS: no props destructuring, use `<For>` instead of `.map()`, use `class` instead of `className`
-- Prettier: 100 chars, 2-space indent, semicolons, trailing comma, LF
-```
+## 5. 기존 CLAUDE.md와 병합
 
-## Step 5: Completion Notice
+- 기존 `CLAUDE.md`가 없으면 4단계의 결과를 그대로 저장한다
+- 기존 `CLAUDE.md`가 있으면:
+  1. 기존 파일을 Read한다
+  2. 4단계에서 생성한 새 내용과 기존 내용을 섹션(`##` 헤딩) 단위로 비교한다
+  3. 병합 규칙:
+     - 4단계에서 생성한 섹션과 동일 주제의 기존 섹션이 있으면 → 새 내용으로 교체
+     - 기존에만 있고 4단계에서 생성하지 않은 섹션 → 그대로 보존
+     - 기존 섹션의 위치를 유지하되, 새로 추가된 섹션은 관련 섹션 근처에 배치
 
-When generation is complete, output the following:
+## 6. 완료 안내
 
-```
-CLAUDE.md has been generated. Run /sd-commit to commit.
-```
+저장이 완료되면 생성/업데이트된 파일 경로를 출력한다.
+
+## 7. 커밋
+
+수정된 파일이 있으면 `/sd-commit`을 실행하여 자동 커밋한다.

package/claude/skills/sd-plan/SKILL.md

@@ -1,104 +1,129 @@
 ---
 name: sd-plan
-description: This skill is used when the user requests "make a plan", "create a plan", "sd-plan", "implementation plan", "work plan", etc.
+description: 요구분석서 또는 점검 결과를 기반으로 TDD 방식의 구현계획서를 작성. 사용자가 구현계획/plan 작성을 요청할 때 사용
+argument-hint: "<spec/audit 파일 경로 [R번호]> 또는 <간단한 요구사항>"
 ---
 
-# SD Plan — Clear Plan Generation
+# sd-plan: 구현계획서 작성
 
-Receives a task request from the user, generates an initial plan, then iteratively reviews and asks questions about unclear parts to produce a perfectly clear plan.
+요구분석서(spec) 또는 점검 결과(audit)를 기반으로 TDD 방식의 세부 구현 계획을 수립한다.
 
----
+## 1. 인자 파싱
 
-## Step 1: Input Verification
+`$ARGUMENTS`를 분석하여 호출 방식을 결정한다.
 
-- Obtain the task description in the following priority order:
-  1. **Task request**: The task description provided by the user when invoking the skill
-  2. **Current conversation**: If no task request is provided, determine the task from the current conversation context
-  3. **AskUserQuestion**: If neither of the above is sufficient, ask "What task should I create a plan for? Please describe the task."
-- Proceed to Step 2 after obtaining a sufficient task description.
+### 1-1. spec/audit 파일 경로 (+ 선택적 R번호)
 
----
+`$ARGUMENTS`에 `.md`로 끝나는 경로가 포함된 경우:
+- 해당 파일을 Read한다
+- 경로 뒤에 `R숫자` 또는 숫자만 있으면 해당 R항목만 대상으로 한다
+  - 예: `.tasks/260314143000_example/spec.md R2` → R2만 대상
+  - 예: `.tasks/260314143000_example/spec.md 3` → R3만 대상
+- 경로만 있으면 전체 요구사항을 대상으로 한다
 
-## Step 2: Plan Generation + Clarification Loop
+### 1-2. 인자 없음
 
-### 2-1. Draft Creation
+`$ARGUMENTS`가 비어있으면:
+- 현재 대화 맥락에서 spec/audit 내용을 파악한다
+- 대화에도 spec/audit가 없으면 AskUserQuestion으로 spec 또는 review 파일 경로, 또는 요구사항을 요청한다
 
-Draft the plan. Always follow TDD principles:
-- For code tasks → Write test code first
-- For non-code tasks → Define a self-verification checklist first
-- For code tasks where the project has no test environment set up → Propose verification methods such as CLI or dry-run
+### 1-3. 간단한 요구사항 텍스트
 
-### 2-2. Clarification Cycle
+위 조건에 해당하지 않으면 (`.md` 경로가 아닌 일반 텍스트):
+- spec/audit 없이 해당 텍스트를 요구사항으로 직접 사용한다
+- 이 경우 spec/audit 참조 없이 바로 plan을 수립한다
 
-Repeat the following **until there are 0 unclear items**:
+## 2. 요구사항 분석 및 작업 계획
 
-1. **Extract**: Compare the plan against all 12 "Ambiguity Criteria" listed below and enumerate all unclear items.
-2. **Dependency analysis**: Identify dependencies between items. ("A must be decided before B can be asked" → B depends on A)
-3. **Ask**: For items with no dependencies, use AskUserQuestion with **exactly one question per tool call**. Provide 2-5 options for each question.
-   - For each item, repeat "present one explanation -> AskUserQuestion"
-4. **Apply**: Incorporate all answers to update the plan, then return to step 1.
+요구사항을 독립적 기능 단위로 작업을 분리하고, 각 작업의 유형을 분류하여 테스트 전략을 결정한다.
+- 각 작업은 하나의 독립적인 TDD 사이클로 처리할 수 있는 크기여야 한다
+- 작업 간 의존성이 있으면 의존성을 명시한다
 
-0 unclear items → Move to **Step 2.5 Final Verification**.
+**작업 유형별 테스트 전략:**
 
-### Ambiguity Criteria
+| 작업 유형 | 테스트 전략 |
+|----------|-----------|
+| 코드 작업 (로직) | 프로젝트 테스트 환경(vitest) 확인 → 있으면 테스트 코드 작성 계획 |
+| 코드 작업 (로직, 테스트 환경 없음) | subagent를 통한 직접 테스트 방안 계획 (sd-plan-dev에서 `_test.md` 작성) |
+| 코드 작업 (비로직, 텍스트 변경 등) | 테스트 생략 가능 |
+| 비코드 작업 (LLM용 문서) | subagent를 통한 테스트 방안 계획 (sd-plan-dev에서 `_test.md` 작성) |
+| 비코드 작업 (일반 문서) | 테스트 생략 가능 |
 
-> **Core principle**: Anything not explicitly stated by the user and not confirmed in the codebase is **treated as speculation/assumption** and classified as an unclear item. Even if Claude wrote it confidently, it is unclear if the source is unverified.
+**테스트 시나리오 작성 원칙:**
+- 테스트는 **상태(정적)가 아닌 동작**을 검증한다
+  - 상태 (X): "파일에 특정 텍스트가 적혀있는지 확인" → 정적 검사에 불과
+  - 현상 (O): "실행했을 때 기대한 동작이 나타나는지 확인" → 실제 동작 검증
+- 예: LLM용 문서 테스트 시 "SKILL.md에 '테스트 재실행' 문구가 있는지"가 아니라 "LLM이 SKILL.md를 따라 실행했을 때 실제로 테스트를 재실행하는지"를 검증한다
 
-Compare against all 12 items below **during every review**. To skip an item as "not applicable", there must be concrete evidence (user statement or codebase confirmation).
+## 3. 구현계획서 초안 작성
 
-1. **Unstated user assumptions**: Decisions filled in by Claude that the user did not specify
-2. **Lack of specificity**: Expressions like "handle appropriately", "as needed" without explaining HOW
-3. **Ambiguous scope**: IN/OUT scope is not defined
-4. **Unspecified behavior**: Errors, invalid inputs, default values, etc. are not specified
-5. **Unknown constraints**: Performance, compatibility, or platform requirements are unclear
-6. **Missing edge cases**: Boundary conditions, concurrency, empty states, etc.
-7. **Vague file/function references**: "Modify related files" without specific paths
-8. **Unclear ordering/dependencies**: Precedence between steps is not specified
-9. **Speculative expressions**: "Probably", "might be", "TBD", "???", etc.
-10. **Missing integration details**: API contracts, data formats, interfaces are undefined
-11. **No failure/rollback strategy**: No response plan for failures
-12. **Undefined verification methods**: No verification method corresponding to an implementation step
+분석 결과를 바탕으로 아래 고정 구조의 구현계획서 초안을 작성한다.
+불명확한 부분이 있더라도 최선의 판단으로 초안을 완성한다.
 
----
+```markdown
+# 구현계획서: {제목}
 
-## Step 2.5: Final Verification (Required Before Declaring No Ambiguities)
+**참조 문서:** `{참조 문서 경로}` {R번호}
+**대상:** `{대상 파일/패키지 경로}` {신규 작성/수정}
+**작업 유형:** {유형} → {테스트 전략 요약}
 
-**Immediately before** declaring "no ambiguities", you must perform the following:
+## 작업 분석
 
-1. Re-read **every step of the plan from beginning to end**, comparing against the 12 criteria one more time.
-2. Pay special attention to the following:
-   - Are there any parts that Claude decided on its own without user confirmation?
-   - Do all definitive statements (e.g., "will do X", "will handle as Y") have supporting evidence from user statements or the codebase?
-   - Are there any places missing specific file paths, function names, or data structures?
-3. If **even one** unclear item is found during this verification, return to the question cycle in Step 2.
-4. If truly none remain → Move to Step 3.
+{요구사항을 기능 단위로 분리한 결과}
 
----
+## TDD 계획
 
-## Step 3: Final Output
+### RED Phase: {테스트 파일명} 작성 및 실패 확인
 
-Once all unclear items have been resolved, present the completed plan to the user and request implementation approval via AskUserQuestion.
+{테스트 시나리오 목록}
 
-If the user approves, Write the plan to `.tmp/plans/${TS}_{topic}.md`.
-- Generate the timestamp first: `TS=$(date +%y%m%d%H%M%S)`
-- Filename example: `260311143052_add-progress-component.md`
-- `{topic}`: Short kebab-case based on the task content (e.g., add-progress-component)
+### GREEN Phase: {구현 대상} 작성
 
----
+{구현 계획 상세}
 
-## Step 4: Post-Implementation Guidance
+구현 후 테스트 재실행하여 통과 확인
 
-If the user approves implementation, implement according to the plan. Once implementation is complete, output the following guidance:
+### Refactor Phase
 
-- **If code changes are included**:
-  ```
-  Implementation is complete. It is recommended to run the following steps in order:
-  1. /sd-check — Type check + lint + test inspection and auto-fix
-  2. /sd-simplify — Simplification review of changed code
-  3. /sd-commit — Commit changes
-  ```
+`/simplify` 하여 품질 개선 → 테스트 재실행하여 통과 확인
+```
+
+**참조 문서 표기 규칙:**
+- spec/audit 파일 경로로 호출된 경우: `**참조 문서:** {경로} {R번호}` 형식으로 상단에 명시
+- 현재 대화의 spec/audit인 경우: `**참조 문서:** 현재 대화의 spec/audit` 으로 명시
+- spec/audit 없이 호출된 경우: `**참조 문서:**` 줄 생략
+
+**다중 작업인 경우:**
+- 작업별로 `## 작업 1: {제목}`, `## 작업 2: {제목}` ... 으로 구분하고 각 작업 내에 작업 유형, TDD 계획 포함
+- 작업 간 의존성이 있으면 `## 작업 의존성` 섹션에 명시
+
+## 4. 초안 기반 검토 질문
+
+초안은 사용자에게 출력하지 않는다 (최종본이 파일로 저장되므로 대화창 출력은 불필요).
+불명확하거나 확인이 필요한 부분이 있으면 다음 프로세스를 반복한다:
+
+1. 초안의 특정 부분을 인용하며 **자세한 설명을 텍스트로 먼저 출력**한다
+   - "초안에서 X를 Y로 계획했는데, Z 방식도 고려할 수 있습니다" 형식으로 구체적으로 질문한다
+   - 선택지 각각의 장단점, 트레이드오프를 설명한다
+2. AskUserQuestion을 **1개만** 호출한다 (한번에 하나씩만 질문)
+3. 답변을 반영하여 초안을 수정한다
+4. 추가 확인이 필요하면 1번으로 돌아간다
+
+불명확한 점이 없거나 충분히 확인되면 질문을 종료하고 파일 저장으로 넘어간다.
+
+## 5. 파일 저장
+
+- spec/audit 파일 기반 호출: 해당 문서와 동일 디렉토리에 저장. 전체면 `plan.md`, 특정 R항목이면 `{R번호}_plan.md` (예: `R2_plan.md`)
+- 현재 대화의 spec/audit 기반이고 파일 경로가 있는 경우: 해당 문서와 동일 디렉토리에 저장. 파일명 규칙 동일
+- spec/audit 없이 호출된 경우: 새 디렉토리 `.tasks/{yyMMddHHmmss}_{topic}/plan.md` 생성 (`yyMMddHHmmss`는 Bash `date +%y%m%d%H%M%S`, `{topic}`은 영문 kebab-case)
+
+## 6. 완료 안내
 
-- **If no code changes are involved** (configuration, documentation, etc.):
+문서 작성이 완료되면 다음을 출력한다:
+- 완성된 문서의 파일 경로
+- 사용자에게 직접 문서를 확인할 것을 권장
+- 다음 단계 안내:
   ```
-  Implementation is complete. Run /sd-commit to commit the changes.
+  /sd-plan-dev
+  /sd-plan-dev --worktree   # 별도 worktree에서 격리 실행
   ```