@simplysm/sd-claude 13.0.85 → 13.0.87

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

@@ -1,165 +1,159 @@
 ---
 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 방식의 세부 구현 계획을 수립한다.
 
-## MANDATORY RULE — ONE QUESTION PER AskUserQuestion CALL
+## 1. 인자 파싱
 
-**Every AskUserQuestion call MUST have exactly 1 item in the `questions` array. NEVER bundle 2+ questions.**
+`$ARGUMENTS`를 분석하여 호출 방식을 결정한다.
 
-WRONG — bundling multiple questions:
-```
-questions: [
-  { question: "Which API style?" ... },
-  { question: "Which styling approach?" ... },
-  { question: "What default value?" ... }
-]
-```
+### 1-1. spec/audit 파일 경로 (+ 선택적 R번호)
 
-RIGHT — one question per call, sequential:
-```
-// Call 1
-questions: [{ question: "Which API style?" ... }]
-// Wait for answer → apply → re-extract unclear items
-// Call 2
-questions: [{ question: "Which styling approach?" ... }]
-// Wait for answer → apply → re-extract unclear items
-// Call 3
-questions: [{ question: "What default value?" ... }]
-```
+`$ARGUMENTS`에 `.md`로 끝나는 경로가 포함된 경우:
 
-**Violating this rule makes the output unusable. There is NO exception.**
+- 해당 파일을 Read한다
+- 경로 뒤에 `R숫자` 또는 숫자만 있으면 해당 R항목만 대상으로 한다
+    - 예: `.tasks/260314143000_example/spec.md R2` → R2만 대상
+    - 예: `.tasks/260314143000_example/spec.md 3` → R3만 대상
+- 경로만 있으면 전체 요구사항을 대상으로 한다
 
----
+### 1-2. 인자 없음
 
-## 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.
+- 현재 대화 맥락에서 spec/audit 내용을 파악한다
+- 대화에도 spec/audit가 없으면 AskUserQuestion으로 spec 또는 review 파일 경로, 또는 요구사항을 요청한다
 
----
+### 1-3. 간단한 요구사항 텍스트
 
-## Step 2: Plan Generation + Clarification Loop
+위 조건에 해당하지 않으면 (`.md` 경로가 아닌 일반 텍스트):
 
-### 2-1. Draft Creation
+- spec/audit 없이 해당 텍스트를 요구사항으로 직접 사용한다
+- 이 경우 spec/audit 참조 없이 바로 plan을 수립한다
 
-Draft the plan. **Every implementation item MUST be structured as 3 sub-steps: RED → Implement → GREEN.** NEVER skip or merge these sub-steps regardless of task simplicity.
+## 2. 요구사항 분석 및 작업 계획
 
-Classify the task first, then apply the matching TDD approach:
+요구사항을 독립적 기능 단위로 작업을 분리하고, 각 작업의 유형을 분류하여 테스트 전략을 결정한다.
 
-**If code + test env exists:**
-1. **RED** — Write a failing test file, run it → confirm FAIL
-2. **Implement** — Write the minimum code to pass
-3. **GREEN** — Run the test → confirm PASS
+- 각 작업은 하나의 독립적인 TDD 사이클로 처리할 수 있는 크기여야 한다
+- 작업 간 의존성이 있으면 의존성을 명시한다
 
-**If code + no test env:**
-1. **RED** — Define a CLI/dry-run command, run it → confirm FAIL
-2. **Implement** — Write the minimum code to pass
-3. **GREEN** — Run the same command → confirm PASS
+**작업 유형별 테스트 전략:**
 
-**If non-code (config, docs, prompts, SKILL.md, etc.):**
-Prompt/config files cannot be unit-tested. Use **Agent behavioral simulation**: launch an Agent that reads the file and naturally follows its instructions with a sample task. **Do NOT tell the Agent what behavior you are testing** (this biases the result and invalidates the test).
-1. **RED** — `git stash` your changes → launch Agent with a sample task against the **original** file → confirm the Agent's output shows the **problematic** behavior (FAIL)
-2. **Implement** — `git stash pop` to restore changes, then apply your edits
-3. **GREEN** — launch same Agent with the same task against the **modified** file → confirm the Agent's output shows the **desired** behavior (PASS). If FAIL → fix implementation → re-run GREEN until PASS.
+| 작업 유형                 | 테스트 전략                                                  |
+|-----------------------|---------------------------------------------------------|
+| 코드 작업 (로직)            | 프로젝트 테스트 환경(vitest) 확인 → 있으면 테스트 코드 작성 계획               |
+| 코드 작업 (로직, 테스트 환경 없음) | subagent를 통한 직접 테스트 방안 계획 (sd-plan-dev에서 `_test.md` 작성) |
+| 코드 작업 (비로직, 텍스트 변경 등) | 테스트 생략 가능                                               |
+| 비코드 작업 (LLM용 문서)      | subagent를 통한 테스트 방안 계획 (sd-plan-dev에서 `_test.md` 작성)    |
+| 비코드 작업 (일반 문서)        | 테스트 생략 가능                                               |
 
-### 2-2. Clarification Cycle
+**테스트 시나리오 작성 원칙:**
 
-**This is a single-item loop. Each iteration handles exactly ONE unclear item, then restarts from scratch.**
+- 테스트는 **상태(정적)가 아닌 동작**을 검증한다
+    - 상태 (X): "파일에 특정 텍스트가 적혀있는지 확인" → 정적 검사에 불과
+    - 현상 (O): "실행했을 때 기대한 동작이 나타나는지 확인" → 실제 동작 검증
+- 예: LLM용 문서 테스트 시 "SKILL.md에 '테스트 재실행' 문구가 있는지"가 아니라 "LLM이 SKILL.md를 따라 실행했을 때 실제로 테스트를 재실행하는지"를
+  검증한다
 
-1. **Extract**: Compare the plan against all 12 "Ambiguity Criteria" below → enumerate unclear items.
-   - 0 unclear items → **STOP this loop. Go to Step 2.5.**
-2. **Dependency analysis**: Identify dependencies. ("A must be decided before B" → B depends on A)
-3. **Ask exactly ONE question**: Pick the single most important item with no unresolved dependencies.
-   a. Present a brief explanation of why this item is unclear.
-   b. Call AskUserQuestion with `questions` array containing **exactly 1 item**. Include 2-5 options.
-   c. **STOP and WAIT** for the user's answer. Do NOT plan, prepare, or output anything about the next question.
-4. **Apply**: Incorporate the answer into the plan.
-5. **RESTART from step 1** — re-extract ALL unclear items from scratch. The previous answer may have resolved multiple items or created new ones. Never assume the remaining questions are still valid.
+## 3. 첨부파일 수집
 
-**NEVER ask 2+ questions before restarting the loop. NEVER plan ahead for "the next question". Each loop iteration = 1 Extract + 1 Question + 1 Answer.**
+대화 중 등장한 파일을 수집하여 보존한다.
+첨부파일이 없으면 이 단계를 건너뛴다.
 
-### Ambiguity Criteria
+**대상 파일:**
 
-> **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.
->
-> **Exception — implementation details are NOT unclear items**: Technical decisions about HOW to achieve the goal (code placement, internal structure, naming conventions, file organization, etc.) are Claude's engineering judgment. Only user-facing requirements (WHAT behavior the user wants) should be classified as unclear. If the user did not specify it and it is purely a technical approach decision, Claude decides — do NOT ask the user.
+- 사용자가 직접 첨부한 파일 (이미지, 문서 등)
+- 스킬(sd-document, sd-email-analyze 등)이 분석 과정에서 추출/생성한 파일 (추출 이미지 등)
 
-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).
+**처리:**
 
-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
+1. plan 저장 디렉토리의 `attachments/` 폴더를 생성한다
+2. 대상 파일을 `attachments/`로 복사한다
+3. 후속 초안 작성 단계에서 적절한 위치에 링크를 배치한다:
+    - 이미지: `![{파일명}](attachments/{파일명})`
+    - 기타 파일: `[{파일명}](attachments/{파일명})`
+    - 배치 위치: 관련 작업 근처
 
----
+## 4. 구현계획서 초안 작성
 
-## Step 2.5: Final Verification (Required Before Declaring No Ambiguities)
+분석 결과를 바탕으로 아래 고정 구조의 구현계획서 초안을 작성한다.
+불명확한 부분이 있더라도 최선의 판단으로 초안을 완성한다.
 
-**Immediately before** declaring "no ambiguities", you must perform the following:
+```markdown
+# 구현계획서: {제목}
 
-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.
+**참조 문서:** `{참조 문서 경로}` {R번호}
+**대상:** `{대상 파일/패키지 경로}` {신규 작성/수정}
+**작업 유형:** {유형} → {테스트 전략 요약}
 
----
+## 작업 분석
 
-## Step 3: Final Output
+{요구사항을 기능 단위로 분리한 결과}
 
-Once all unclear items have been resolved, present the completed plan to the user and request implementation approval via AskUserQuestion.
+## TDD 계획
 
-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)
+### RED Phase: {테스트 파일명} 작성 및 실패 확인
 
----
+{테스트 시나리오 목록}
 
-## Step 4: Post-Implementation Guidance
+### GREEN Phase: {구현 대상} 작성
 
-If the user approves implementation, implement according to the plan. Follow the TDD approach defined in Step 2-1 for the task type. **Do NOT proceed to the next item until the current item reaches GREEN.**
+{구현 계획 상세}
 
-### TDD Execution Rules
+구현 후 테스트 재실행하여 통과 확인
 
-**RED and GREEN must be actually executed. NEVER skip or substitute them.**
+### Refactor Phase
 
-- "User already confirmed the issue" is NOT a valid RED. Run the test yourself.
-- "Needs a separate session to verify" is NOT a valid GREEN. Run the test yourself.
-- If GREEN fails → fix the implementation → re-run GREEN. Repeat until it passes.
+`/simplify` 하여 품질 개선 → 테스트 재실행하여 통과 확인
+```
 
-Once all items are complete, output the following guidance. Include only the items whose conditions are met, numbered sequentially:
+**참조 문서 표기 규칙:**
 
-| Condition | Recommendation |
-|-----------|----------------|
-| Code changes exist | `/sd-check` — Type check + lint + test inspection and auto-fix |
-| Code changes exist | `/sd-simplify` — Simplification review of changed code |
-| Public API changed (exports, public methods/properties, component props, etc.) | `/sd-readme` — Update README documentation |
-| Always | `/sd-commit` — Commit changes |
+- spec/audit 파일 경로로 호출된 경우: `**참조 문서:** {경로} {R번호}` 형식으로 상단에 명시
+- 현재 대화의 spec/audit인 경우: `**참조 문서:** 현재 대화의 spec/audit` 으로 명시
+- spec/audit 없이 호출된 경우: `**참조 문서:**` 줄 생략
 
-Example (all conditions met):
-```
-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-readme — Update README documentation
-4. /sd-commit — Commit changes
-```
+**다중 작업인 경우:**
+
+- 작업별로 `## 작업 1: {제목}`, `## 작업 2: {제목}` ... 으로 구분하고 각 작업 내에 작업 유형, TDD 계획 포함
+- 작업 간 의존성이 있으면 `## 작업 의존성` 섹션에 명시
+
+## 5. 초안 기반 검토 질문
+
+초안은 사용자에게 출력하지 않는다 (최종본이 파일로 저장되므로 대화창 출력은 불필요).
+불명확하거나 확인이 필요한 부분이 있으면 다음 프로세스를 반복한다:
+
+1. 초안의 특정 부분을 인용하며 **자세한 설명을 텍스트로 먼저 출력**한다
+    - "초안에서 X를 Y로 계획했는데, Z 방식도 고려할 수 있습니다" 형식으로 구체적으로 질문한다
+    - 선택지 각각의 장단점, 트레이드오프를 설명한다
+2. AskUserQuestion을 **1개만** 호출한다 (한번에 하나씩만 질문)
+3. 답변을 반영하여 초안을 수정한다
+4. 추가 확인이 필요하면 1번으로 돌아간다
+
+불명확한 점이 없거나 충분히 확인되면 질문을 종료하고 파일 저장으로 넘어간다.
+
+## 6. 파일 저장
+
+- spec/audit 파일 기반 호출: 해당 문서와 동일 디렉토리에 저장. 전체면 `plan.md`, 특정 R항목이면 `{R번호}_plan.md` (예:
+  `R2_plan.md`). spec이 서브디렉토리(`{R번호}/spec.md`)에 있는 경우에도 동일 규칙 적용 (해당 서브디렉토리에 저장)
+- 현재 대화의 spec/audit 기반이고 파일 경로가 있는 경우: 해당 문서와 동일 디렉토리에 저장. 파일명 규칙 동일
+- spec/audit 없이 호출된 경우: 새 디렉토리 `.tasks/{yyMMddHHmmss}_{topic}/plan.md` 생성 (`yyMMddHHmmss`는 Bash
+  `date +%y%m%d%H%M%S`, `{topic}`은 영문 kebab-case)
+
+## 7. 완료 안내
+
+문서 작성이 완료되면 다음을 출력한다:
+
+- 완성된 문서의 파일 경로
+- 사용자에게 직접 문서를 확인할 것을 권장
+- 다음 단계 안내:
+  ```
+  /sd-plan-dev
+  /sd-plan-dev --worktree   # 별도 worktree에서 격리 실행
+  ```

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

@@ -0,0 +1,122 @@
+---
+name: sd-plan-dev
+description: 구현계획서를 기반으로 TDD 방식의 실제 구현을 수행. 사용자가 구현계획서 기반의 코드 구현을 요청할 때 사용
+argument-hint: "<plan 파일 경로> [--worktree]"
+---
+
+# sd-plan-dev: 구현 실행
+
+구현계획서(plan)를 기반으로 TDD 사이클(RED → GREEN → Refactor)을 실행하여 실제 구현을 수행한다.
+
+## 1. 인자 파싱
+
+`$ARGUMENTS`를 분석하여 plan과 옵션을 결정한다.
+
+### 1-1. plan 파일 경로
+
+`$ARGUMENTS`에 `.md`로 끝나는 경로가 포함된 경우:
+- 해당 파일을 Read한다
+
+### 1-2. 인자 없음
+
+`$ARGUMENTS`가 비어있으면 (옵션 플래그 제외):
+- 현재 대화 맥락에서 plan 내용을 파악한다
+- 대화에도 plan이 없으면 다음을 출력하고 종료한다:
+  > 구현계획서가 없습니다. 먼저 `/sd-plan`을 실행하여 계획을 수립하세요.
+
+### 1-3. `--worktree` 옵션
+
+`$ARGUMENTS`에 `--worktree`가 포함된 경우 worktree 모드를 활성화한다.
+- 기본값: 비활성 (현행 동작)
+- 활성 시: 2단계에서 worktree 격리 실행 전략을 적용한다
+
+## 2. 작업 파악 및 실행 전략
+
+plan에서 작업 목록을 파악하고 스케줄링을 결정한다.
+
+1. plan의 `## 작업 의존성` 섹션을 확인한다 (없으면 모든 작업을 독립으로 간주)
+2. 스케줄링을 결정한다:
+   - 작업 1개: 단일 실행
+   - 독립 작업 2개 이상: 병렬 실행
+   - 의존 작업: 의존 순서대로 순차 실행
+   - 혼합: 독립 작업끼리는 병렬, 의존 체인은 순차로 조합
+
+### `--worktree` 미사용 시
+
+결정된 스케줄링에 따라 실행한다:
+- 단일 작업: 바로 3단계(TDD 사이클)로 진행
+- 병렬 실행: Agent tool로 각 작업을 별도 subagent에 위임하여 동시에 TDD 사이클 수행
+- 순차 실행: 선행 작업 완료 후 후행 작업 시작
+
+### `--worktree` 사용 시
+
+결정된 스케줄링에 따라 `isolation: "worktree"` Agent tool로 실행한다:
+- 단일 작업: worktree subagent 1개 생성 → 완료 후 4단계(merge)
+- 병렬 실행: 각 작업별 worktree subagent 병렬 생성 → 모든 subagent 완료 후 4단계에서 순차 merge
+- 순차 실행: 첫 작업 worktree subagent 생성 → 완료 후 4단계에서 merge → 현재 branch(merge 완료된 상태)를 base로 다음 작업 worktree subagent 생성 → 반복
+
+**worktree 불가 제약**: subagent 테스트(`_test.md` 기반)가 필요한 작업은 worktree subagent 안에서 Agent tool을 사용할 수 없으므로 worktree 적용 불가. 해당 작업은 worktree 없이 3단계로 직접 수행한다.
+
+**혼합 케이스** (worktree 가능 + 불가 작업 공존): worktree 가능한 작업끼리 스케줄링에 따라 worktree subagent로 실행하고, worktree 불가 작업은 모든 worktree merge 완료 후 순차 단일 수행한다. 단, 의존성에 의해 순서가 정해진 경우 그 순서를 우선한다.
+
+## 3. TDD 사이클 실행
+
+각 작업에 대해 plan의 TDD 계획을 따라 실행한다.
+
+### RED Phase: 실패하는 테스트 작성 및 실행
+
+plan의 RED Phase에 명시된 테스트 전략에 따라 분기한다:
+
+**vitest 테스트인 경우:**
+- plan의 테스트 시나리오에 따라 vitest 테스트 파일을 작성한다
+- Bash로 `vitest run {테스트 파일}` 실행하여 실패를 확인한다
+
+**subagent 테스트인 경우 (LLM용 문서, 테스트 환경 없는 코드 등):**
+- plan의 테스트 시나리오에 따라 `_test.md` 파일을 작성한다
+  - plan 파일 기반: plan 파일과 동일 디렉토리. plan이 `{R번호}_plan.md`이면 `{R번호}_test.md`, `plan.md`이면 `test.md`
+  - 현재 대화 기반 (파일 경로 없음): plan에 참조 spec 경로가 있으면 해당 디렉토리에 저장. 없으면 `.tasks/` 하위에 새 디렉토리 생성
+  - 형식: 테스트별 입력/기대출력 쌍
+- Agent tool로 subagent를 생성하여 테스트를 실행하고 실패를 확인한다
+
+**테스트 생략인 경우:**
+- RED Phase를 건너뛰고 GREEN Phase로 바로 진행한다
+
+### GREEN Phase: 최소 구현
+
+plan의 GREEN Phase에 명시된 구현 계획에 따라 최소한의 구현을 수행한다 (YAGNI 원칙).
+- 구현 후 테스트를 재실행하여 통과를 확인한다
+- vitest: Bash로 재실행
+- subagent 테스트: Agent tool로 재실행
+- 테스트 생략인 경우: 구현만 수행
+
+### Refactor Phase
+
+`/simplify 다음 파일만 리뷰: {수정한 파일 목록}` 하여 품질을 개선한다.
+- 완료 후 테스트를 재실행하여 통과를 확인한다
+- 리팩터링으로 테스트가 깨지면 수정 후 재확인한다
+
+### Commit Phase
+
+TDD 사이클(RED → GREEN → Refactor) 완료 후 1회 commit한다.
+- 작업 하나 = commit 하나
+- `--worktree` 사용 여부와 관계없이 동일하게 적용한다
+
+## 4. worktree merge (`--worktree` 활성 시)
+
+worktree subagent 완료 후 반환된 branch를 순차적으로 merge한다.
+
+**정상 흐름:**
+1. `git merge {branch}` 실행
+2. merge 완료 후 worktree를 정리한다
+3. 성공 시 다음 branch merge (또는 5단계로 진행)
+
+**conflict 발생 시:**
+1. `git merge --abort` 실행하여 working directory를 깨끗한 상태로 복원
+2. conflict 발생한 worktree 경로와 branch명을 출력
+3. AskUserQuestion으로 "직접 merge하세요" 안내 + "완료" 옵션 제시
+4. 사용자가 "완료" 선택 시 worktree를 정리하고 다음 branch merge 계속
+
+## 5. 완료 안내
+
+모든 작업의 TDD 사이클이 완료되면 다음을 출력한다:
+- 전체 작업의 구현 결과 요약 (작업별 상태)