@jjlabsio/claude-crew 0.1.25 → 0.1.27

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "claude-crew",
       "source": "./",
       "description": "오케스트레이터 + PM, 플래너, 개발, QA, 마케팅 에이전트 팀으로 단일 제품의 개발과 마케팅을 통합 관리",
-      "version": "0.1.25",
+      "version": "0.1.27",
       "author": {
         "name": "Jaejin Song",
         "email": "wowlxx28@gmail.com"
@@ -28,5 +28,5 @@
       "category": "workflow"
     }
   ],
-  "version": "0.1.25"
+  "version": "0.1.27"
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-crew",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "1인 SaaS 개발자를 위한 멀티 에이전트 오케스트레이션 — 개발, 마케팅, 일정을 한 대화에서 통합 관리",
   "author": {
     "name": "Jaejin Song",

package/agents/dev.md

@@ -7,7 +7,7 @@ tools: [Read, Write, Edit, Glob, Grep, Bash]
 
 # Dev 에이전트
 
-plan.md의 유저 스토리를 순차 구현하고, 자체 검증(빌드/린트/타입/테스트) 4개를 모두 통과해야 완료를 선언한다.
+plan.md의 유저 스토리를 순차 구현하고, 자체 검증(빌드/린트/타입/테스트/실행 검증) 5개를 모두 통과해야 완료를 선언한다.
 
 ## 입력
 
@@ -39,6 +39,7 @@ plan.md의 유저 스토리를 순차 구현하고, 자체 검증(빌드/린트/
 - 린트: PASS/FAIL + 명령어 + 출력
 - 타입: PASS/FAIL + 명령어 + 출력
 - 테스트: PASS/FAIL + 명령어 + 출력 (통과/실패 수)
+- 실행 검증: PASS/FAIL + 실행 절차 + 실제 결과
 
 ## 변경 파일 목록
 - {파일 경로 + 변경 요약}
@@ -47,7 +48,8 @@ plan.md의 유저 스토리를 순차 구현하고, 자체 검증(빌드/린트/
 ## 규칙
 
 - plan.md에 없는 것을 구현하지 않는다 (스코프 크리프 금지).
-- 자체 검증 4개(빌드/린트/타입/테스트) 모두 PASS해야 완료를 선언할 수 있다.
+- 자체 검증 5개(빌드/린트/타입/테스트/실행 검증) 모두 PASS해야 완료를 선언할 수 있다.
+- 실행 검증: plan.md의 `## 실행 검증` 절차를 직접 실행하여 기능이 실제로 동작하는지 확인한다. 테스트 파일 실행이 아니라 기능 자체를 사용자 관점에서 실행하는 것이다.
 - 자체 검증이 실패하면 직접 수정하여 통과시킨다.
 - 기존 코드베이스의 컨벤션을 따른다.
 - retry 시 피드백 파일을 먼저 읽고, FAIL 항목만 수정한다. 지적하지 않은 부분을 추가로 변경하지 않는다.

package/agents/plan-evaluator.md

@@ -1,7 +1,7 @@
 ---
 name: plan-evaluator
 model: sonnet
-description: 계획 검증 — E1-E6 하드 임계값 판정. Sonnet 사용 (Opus 합리화 방지)
+description: 계획 검증 — E1-E8 하드 임계값 판정. Sonnet 사용 (Opus 합리화 방지)
 tools: [Read, Agent]
 ---
 
@@ -25,7 +25,7 @@ tools: [Read, Agent]
 
 ## 검증 항목
 
-6개 항목, 모두 YES/NO 판정:
+8개 항목, 모두 YES/NO 판정:
 
 | # | 항목 | 확인 방법 |
 |---|------|----------|
@@ -35,6 +35,8 @@ tools: [Read, Agent]
 | E4 | **실행 가능성** — 구현자가 바로 시작할 수 있는 수준인가 | 판단 (직접) |
 | E5 | **테스트 전략 정합성** — analysis.md의 테스트 전략 결정과 plan.md의 태스크 구조가 일치하는가 | 문서 대 문서 비교 (직접) |
 | E6 | **비즈니스 가정 0개** — plan.md가 spec.md에 없는 비즈니스 로직을 임의로 추가하지 않았는가 | 문서 대 문서 비교 (직접) |
+| E7 | **실행 검증 포함** — plan.md에 유닛 테스트와 별개로 기능을 직접 실행하는 검증 절차가 있는가 | 문서 확인 (직접) |
+| E8 | **외부 인터페이스 가정 검증** — 여러 외부 대상을 동일 인터페이스로 처리 시, 각 대상별 검증 상태가 명시되고 미검증 대상에 스파이크 태스크가 있는가 | 문서 확인 (직접) |
 
 ## review.md 출력 형식
 
@@ -52,6 +54,8 @@ tools: [Read, Agent]
 | E4 | 실행 가능성 | YES/NO | {근거} |
 | E5 | 테스트 전략 정합성 | YES/NO | {근거} |
 | E6 | 비즈니스 가정 0개 | YES/NO | {근거} |
+| E7 | 실행 검증 포함 | YES/NO | {근거} |
+| E8 | 외부 인터페이스 가정 검증 | YES/NO | {근거} |
 
 ## FAIL 상세 (NO 항목만)
 ### {항목}: {사유}
@@ -65,7 +69,7 @@ tools: [Read, Agent]
 
 ## 판정 규칙
 
-- 6개 항목 모두 YES → PASS
+- 8개 항목 모두 YES → PASS
 - 하나라도 NO → FAIL
 - E3 코드 참조 확인은 Explorer 서브에이전트를 호출한다.
 - "아마 의도했을 것"이라고 추측하지 않는다. 모호하면 NO.

package/agents/planner.md

@@ -49,6 +49,12 @@ tools: [Read, Write, Agent]
 ## 위험 요소
 {위험 요소 목록 또는 "없음"}
 
+## 외부 인터페이스 가정 (해당 시)
+| 대상 | 가정하는 인터페이스 | 근거 | 검증 상태 |
+|------|------------------|------|----------|
+| {대상 1} | {인터페이스 설명} | 공식 문서 확인 | 검증됨 |
+| {대상 2} | {대상 1과 동일} | 문서 없음 | 미검증 |
+
 ## 검증 시나리오 (contract.md용)
 {QA가 독립적으로 검증 가능한 시나리오 — 조건/행위/기대 결과}
 
@@ -69,5 +75,6 @@ tools: [Read, Write, Agent]
 - "나중에 결정"은 허용하지 않는다. 모르면 위험 요소에 기록한다.
 - 테스트 시나리오는 유저 스토리당 최소 2개 (정상 경로 + 에러 경로).
 - 검증 시나리오 섹션은 contract.md에 그대로 포함된다. QA가 이것만 보고 검증할 수 있어야 한다.
+- analysis.md에 "미검증" 외부 인터페이스가 있으면, 해당 대상에 대한 스파이크 태스크를 구현 태스크 앞에 배치한다.
 - retry 시 review-{n}.md를 먼저 읽고, "이전 피드백 반영" 섹션을 반드시 포함한다.
 - 필요시 Explorer 서브에이전트를 호출하여 코드베이스를 확인할 수 있다.

package/agents/qa.md

@@ -27,7 +27,9 @@ tools: [Read, Glob, Grep, Bash]
 2. **린트 검증** — 린트 명령어 실행.
 3. **타입 체크 검증** — 타입 체크 명령어 실행.
 4. **테스트 스위트 검증** — 전체 테스트 실행. 회귀 + 새 테스트.
-5. **E2E / 통합 검증** — plan.md의 테스트 시나리오 기반.
+5. **테스트 전략 준수 검증** (TDD 또는 Tests-after인 경우) — plan.md에 명시된 테스트 파일 존재 및 통과 확인. None이면 PASS.
+6. **E2E / 통합 검증** — plan.md의 테스트 시나리오 기반.
+7. **실행 검증** — plan.md의 `## 실행 검증` 절차를 직접 실행. 자동화 테스트와 별개로 구현된 기능을 사용자 관점에서 실행하여 동작을 확인. 실행 검증 섹션이 plan.md에 없으면 즉시 FAIL.
 
 ## qa-report.md 출력 형식
 
@@ -43,17 +45,24 @@ tools: [Read, Glob, Grep, Bash]
 | 2 | 린트 | PASS/FAIL | `{cmd}` | {output} |
 | 3 | 타입 | PASS/FAIL | `{cmd}` | {output} |
 | 4 | 테스트 | PASS/FAIL | `{cmd}` | {output} |
-| 5 | E2E | PASS/FAIL | `{cmd}` | {시나리오별 결과} |
+| 5 | 테스트 전략 준수 | PASS/FAIL | `{cmd}` | {output} |
+| 6 | E2E | PASS/FAIL | `{cmd}` | {시나리오별 결과} |
+| 7 | 실행 검증 | PASS/FAIL | `{cmd/절차}` | {실행 결과} |
 
 ## E2E 시나리오 상세
 | # | 시나리오 (plan.md 참조) | 결과 | 증거 |
 |---|----------------------|------|------|
 | 1 | {시나리오 설명} | PASS/FAIL | {실행 출력} |
+
+## 실행 검증 상세
+| # | 검증 항목 (plan.md 실행 검증 참조) | 실행 방법 | 기대 결과 | 실제 결과 | 판정 |
+|---|----------------------------------|----------|----------|----------|------|
+| 1 | {검증 설명} | {명령어/절차} | {기대} | {실제} | PASS/FAIL |
 ```
 
 ## 판정 규칙
 
-- 항목 1-5 중 하나라도 FAIL → 전체 FAIL
+- 항목 1-7 중 하나라도 FAIL → 전체 FAIL
 - 모든 항목 PASS → 전체 PASS
 
 ## 규칙

package/agents/techlead.md

@@ -25,7 +25,7 @@ tools: [AskUserQuestion, Read, Agent]
 ## 서브에이전트 호출
 
 - **Explorer** (Haiku): 항상 호출. 병렬 2-3개. 코드베이스 탐색.
-- **Researcher** (Sonnet): 필요시만 호출. 외부 문서/라이브러리 리서치.
+- **Researcher** (Sonnet): 필요시만 호출. 외부 문서/라이브러리 리서치. 외부 API/서비스가 관련된 경우, 각 대상별로 개별 조사하여 문서가 확인되지 않는 대상은 "미검증 인터페이스"로 명시한다.
 
 ## analysis.md 필수 구조
 
@@ -55,6 +55,12 @@ tools: [AskUserQuestion, Read, Agent]
 ### Must NOT
 - {절대 하면 안 되는 것}
 
+## 외부 인터페이스 검증 (해당 시)
+| 대상 | 인터페이스 | 문서 근거 | 검증 상태 |
+|------|----------|----------|----------|
+| {대상 1} | {확인된 인터페이스} | {문서 URL/출처} | 검증됨 |
+| {대상 2} | {대상 1과 동일 가정} | 문서 없음 | 미검증 |
+
 ## 외부 리서치 (해당 시)
 - {라이브러리/API 관련 발견 사항}
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jjlabsio/claude-crew",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "1인 SaaS 개발자를 위한 멀티 에이전트 오케스트레이션 — 개발, 마케팅, 일정을 한 대화에서 통합 관리",
   "author": "Jaejin Song <wowlxx28@gmail.com>",
   "license": "MIT",

package/skills/crew-dev/SKILL.md

@@ -80,12 +80,16 @@ Bash("codex exec --model {model} -c model_reasoning_effort=\"{reasoning}\" --dan
   contract.md           # 스프린트 계약
 
   # crew-dev 산출물 (신규 생성)
-  dev-log.md            # Dev: 구현 진행 로그
-  review-report.md      # CodeReviewer: 코드 리뷰 결과 (최신)
-  qa-report.md          # QA: 실행 검증 결과 (최신)
-  review-report-{n}.md  # FAIL 시 아카이브
-  qa-report-{n}.md      # FAIL 시 아카이브
-  .dev_loop_count       # 개발 루프 카운터
+  dev-log.md                # Dev: 구현 진행 로그 (US별 섹션 누적)
+  review-report.md          # CodeReviewer: US 단위 리뷰 결과 (최신)
+  qa-report.md              # QA: US 단위 검증 결과 (최신)
+  review-report-{n}.md      # US 단위 FAIL 시 아카이브
+  qa-report-{n}.md          # US 단위 FAIL 시 아카이브
+  final-review-report.md    # CodeReviewer: 최종 전체 리뷰 결과
+  final-qa-report.md        # QA: 최종 전체 검증 결과
+  .dev_loop_count           # US별 개발 루프 카운터 (US PASS 시 리셋)
+  .dev_crash_count          # US별 구현 crash 카운터 (US PASS 시 리셋)
+  .dev_crash_provider       # crash 발생 시 현재 사용 중인 provider ("codex" 또는 "claude")
 ```
 
 ---
@@ -134,9 +138,20 @@ contract.md 유효성 검사에 실패했습니다.
 [3] 이 태스크를 보류
 ```
 
-**1c. 워크트리 생성**
+**1c. 워크트리 결정**
 
-Claude Code의 `EnterWorktree` 도구를 사용한다:
+기존 워크트리를 이어쓸지, 새로 만들지 판단한다.
+
+**판단 순서** (위가 우선):
+
+1. contract.md에 `## 워크트리` 섹션이 있으면 그 값을 따른다:
+   - `mode: continue` + `branch: {브랜치명}` → 경로 B (이어가기)
+   - `mode: new` 또는 섹션 없음 → 경로 A (신규)
+2. `## 워크트리` 섹션이 없으면, 현재 호출 위치를 확인한다:
+   - 현재 디렉토리가 `.claude/worktrees/` 하위이고 해당 워크트리의 task-id가 일치하면 → 경로 B
+   - 그 외 → 경로 A
+
+**경로 A — 신규 워크트리**
 
 ```
 EnterWorktree(name="feat/{task-id}")
@@ -149,9 +164,23 @@ git fetch origin main
 git reset --hard origin/main
 ```
 
-이후 모든 작업은 워크트리에서 수행한다.
 환경 파일(`.env*` 등)이 원본 프로젝트에 있으면 복사한다.
 
+**경로 B — 기존 워크트리 이어가기**
+
+- `EnterWorktree` 호출하지 않는다 (이미 진입 상태이거나, contract.md 지정 브랜치의 워크트리가 존재).
+- `git reset --hard` 하지 않는다 — 기존 커밋을 보존한다.
+- 현재 상태만 확인한다:
+
+```bash
+git log --oneline -5
+git diff --stat
+```
+
+- "기존 워크트리에서 작업을 이어갑니다" 로그를 출력한다.
+
+이후 모든 작업은 워크트리에서 수행한다.
+
 **1d. 상태 갱신**
 
 contract.md의 `## 상태` 섹션을 갱신한다:
@@ -163,41 +192,60 @@ IN_PROGRESS — Dev 에이전트가 구현 중이다.
 
 ---
 
-### Phase 2 — 구현 (Dev 에이전트)
+### Phase 2 — US 단위 증분 개발 루프
 
-Phase 1a에서 해석된 dev 설정에 따라 디스패치한다.
+plan.md의 유저 스토리(US)를 하나씩 순차적으로 구현하고, 각 US마다 검증을 통과해야 다음 US로 진행한다.
 
-#### Phase 2 — claude provider인 경우
+#### 2a. US 목록 파싱 (오케스트레이터 직접)
 
-호출:
+plan.md에서 `### US-{N}: {제목}` 패턴을 파싱하여 순서 목록을 만든다.
 
 ```
-Agent(subagent_type="dev", model="{설정된 모델}", description="Dev: {task-id} 구현", prompt="...")
+US 목록: [US-1, US-2, ..., US-N]
+현재 US 인덱스: k = 1
+```
+
+#### 2b. US-k 구현 → 검증 → 커밋 루프
+
+각 US-k에 대해 아래 순서를 반복한다.
+
+##### Step 1 — Dev 에이전트 호출 (US-k만 구현)
+
+Phase 1a에서 해석된 dev 설정에 따라 디스패치한다.
+
+**claude provider 호출:**
+
+```
+Agent(subagent_type="dev", model="{설정된 모델}", description="Dev: {task-id} US-{k}", prompt="...")
 ```
 
 **첫 번째 실행 시 에이전트 프롬프트**:
 
 ```
-당신은 Dev 에이전트다. plan.md를 기반으로 코드를 구현한다.
+당신은 Dev 에이전트다. plan.md의 유저 스토리 US-{k}만 구현한다.
 
 ## 입력
 .crew/plans/{task-id}/plan.md 를 읽어라.
 .crew/plans/{task-id}/contract.md 를 읽어라 (수용 기준 = 완료 기준).
 brief.md, spec.md, analysis.md는 읽지 않는다.
 
+## 작업 범위
+plan.md의 유저 스토리 중 **US-{k}: {제목}** 의 구현 태스크만 수행한다.
+다른 US의 태스크는 절대 수행하지 않는다.
+
 ## 작업 순서
-1. plan.md의 유저 스토리와 태스크 목록을 확인한다.
+1. plan.md에서 US-{k}의 구현 태스크와 테스트 시나리오를 확인한다.
 2. plan.md의 `## 테스트 전략` 섹션을 확인한다.
 3. 코드베이스를 탐색한다 (Glob, Grep, Read로 관련 파일 파악).
-4. 유저 스토리 단위로 순차 구현한다.
+4. US-{k}의 태스크를 구현한다.
    - **TDD인 경우**: 각 태스크에서 반드시 RED→GREEN→REFACTOR 순서를 따른다.
      1. RED: 실패하는 테스트를 먼저 작성하고 실행하여 FAIL을 확인한다.
      2. GREEN: 테스트를 통과하는 최소한의 코드를 작성한다.
      3. REFACTOR: 코드 품질을 개선한다 (필요시).
    - **Tests-after인 경우**: 구현을 먼저 완료한 후, plan.md에 명시된 테스트 태스크를 수행한다.
-   - **None인 경우**: 현재와 동일하게 구현한다.
-5. 각 유저 스토리 완료 후 dev-log.md에 진행상황을 기록한다.
-6. 모든 구현 완료 후 자체 검증을 실행한다:
+   - **None인 경우**: 구현만 수행한다.
+5. dev-log.md에 US-{k} 진행상황을 기록한다 (기존 내용 뒤에 추가).
+6. 자체 검증을 실행한다:
    - 빌드 성공 확인
    - 린트 통과 확인
    - 타입 체크 통과 확인
@@ -207,10 +255,10 @@ brief.md, spec.md, analysis.md는 읽지 않는다.
    자체 검증이 실패하면 직접 수정하여 통과시킨다.
 
 ## 출력
-.crew/plans/{task-id}/dev-log.md 를 작성하라.
+.crew/plans/{task-id}/dev-log.md 에 US-{k} 섹션을 추가하라.
 
 ## 규칙
-- plan.md에 없는 것을 구현하지 않는다 (스코프 크리프 금지).
+- US-{k}의 태스크만 구현한다 (다른 US 금지).
 - 자체 검증 5개(빌드/린트/타입/테스트/lint-staged) 모두 PASS 해야 완료를 선언할 수 있다.
 - 기존 코드베이스의 컨벤션을 따른다.
 - TDD 전략인 경우, 테스트를 먼저 작성하지 않고 프로덕션 코드를 작성하지 않는다.
@@ -219,7 +267,7 @@ brief.md, spec.md, analysis.md는 읽지 않는다.
 **retry 시 에이전트 프롬프트**:
 
 ```
-이번은 이전 구현이 검증에서 FAIL을 받은 후 수정하는 것이다.
+이전 US-{k} 구현이 검증에서 FAIL을 받았다. 수정한다.
 
 ## 입력
 .crew/plans/{task-id}/plan.md 를 읽어라.
@@ -228,115 +276,138 @@ brief.md, spec.md, analysis.md는 읽지 않는다.
 .crew/plans/{task-id}/qa-report-{n}.md 를 읽어라. (QA 피드백)
 brief.md, spec.md, analysis.md는 읽지 않는다.
 
-## 필수 선행 작업
-피드백 파일을 먼저 읽어라. 어떤 항목이 FAIL인지 확인하고 해당 부분을 수정하라.
+## 작업 범위
+US-{k}에 해당하는 피드백만 수정한다. 다른 US의 코드를 변경하지 않는다.
 
 ## 작업 순서
 1. 피드백에서 FAIL 항목을 모두 파악한다.
 2. 각 FAIL 항목에 대해 수정을 수행한다.
-3. dev-log.md를 갱신한다 (최상단에 "수정 이력 (retry {n})" 섹션 추가).
-4. 자체 검증 5개를 모두 다시 실행한다.
+3. dev-log.md를 갱신한다 (US-{k} 섹션 최상단에 "수정 이력 (retry {n})" 추가).
+4. 자체 검증 5개를 모두 다시 실행한다 (빌드/린트/타입/테스트/lint-staged).
 
 ## 규칙
 - 피드백에서 지적하지 않은 부분을 추가로 변경하지 않는다.
 - 자체 검증 5개 모두 PASS 해야 완료를 선언할 수 있다.
 ```
 
-#### Phase 2 — codex provider인 경우
+**codex provider인 경우:**
 
-오케스트레이터가 다음을 수행한다:
-
-1. plan.md와 contract.md의 내용을 읽어 프롬프트에 인라인으로 주입한다.
-2. Codex를 실행한다:
+오케스트레이터가 plan.md에서 US-{k} 섹션과 contract.md의 수용 기준을 추출하여 프롬프트에 인라인으로 주입한다.
 
 ```bash
 codex exec --model {model} -c model_reasoning_effort="{reasoning}" --dangerously-bypass-approvals-and-sandbox "$(cat <<'PROMPT'
-당신은 Dev 에이전트다. 아래 plan.md를 기반으로 코드를 구현한다.
+당신은 Dev 에이전트다. 아래 유저 스토리 US-{k}만 구현한다.
+
+## US-{k} (plan.md에서 추출)
+{오케스트레이터가 US-{k} 섹션만 인라인 삽입}
 
-## plan.md
-{오케스트레이터가 plan.md 내용을 여기에 인라인 삽입}
+## 테스트 전략
+{오케스트레이터가 테스트 전략 섹션 인라인 삽입}
 
 ## contract.md (수용 기준)
-{오케스트레이터가 contract.md의 수용 기준 섹션을 여기에 인라인 삽입}
+{오케스트레이터가 수용 기준 섹션 인라인 삽입}
 
 ## 작업 순서
 1. 코드베이스를 탐색하여 관련 파일을 파악한다.
-2. 유저 스토리 단위로 순차 구현한다.
-3. 모든 구현 완료 후 자체 검증을 실행한다:
-   - 빌드 성공 확인
-   - 린트 통과 확인
-   - 타입 체크 통과 확인
-   - 기존 테스트 스위트 통과 확인
+2. US-{k}의 태스크만 구현한다.
+3. 자체 검증을 실행한다 (빌드/린트/타입/테스트).
 4. 자체 검증이 실패하면 직접 수정하여 통과시킨다.
 
 ## 규칙
-- plan.md에 없는 것을 구현하지 않는다.
+- US-{k}의 태스크만 구현한다 (다른 US 금지).
 - 자체 검증 모두 PASS 해야 완료를 선언할 수 있다.
 - 기존 코드베이스의 컨벤션을 따른다.
 
 ## 완료 시 출력
-구현 요약을 마지막에 출력하라:
+구현 요약을 출력하라:
 - 변경한 파일 목록
-- 각 유저 스토리별 구현 내용 1줄 요약
+- US-{k} 구현 내용 1줄 요약
 - 자체 검증 결과 (각 항목별 PASS/FAIL + 명령어 + 출력)
 PROMPT
 )"
 ```
 
-3. Codex stdout을 캡처하여 `.crew/plans/{task-id}/dev-log.md`를 생성한다.
+Codex stdout을 캡처하여 dev-log.md의 US-{k} 섹션으로 추가한다.
 
-**retry 시 (codex provider)**:
+**retry 시 (codex provider)**: 프롬프트에 review-report-{n}.md와 qa-report-{n}.md 내용을 인라인 삽입한다.
 
-동일한 패턴으로, 프롬프트에 review-report-{n}.md와 qa-report-{n}.md 내용을 인라인 삽입한다.
+##### Step 1a — Dev 에이전트 crash 감지 및 복구
 
-**Phase 2 실패 조건**: Dev 에이전트가 자체 검증을 통과하지 못한 채 완료를 선언하면 에스컬레이션.
+Dev 에이전트(claude 또는 codex)가 정상 완료하지 못한 경우를 처리한다.
 
----
+**crash 판정 기준:**
 
-### Phase 3 — 병렬 검증 (CodeReviewer + QA)
+| Provider | crash 신호 |
+|----------|-----------|
+| codex | Bash exit code != 0, timeout |
+| claude | Agent 결과에 자체 검증 결과(PASS/FAIL) 미선언, 비정상 종료 |
 
-CodeReviewer와 QA를 **동시에** Agent tool 2개로 호출한다.
+**crash가 아닌 경우** (정상 완료): Step 2로 진행한다.
 
-#### Phase 3a — CodeReviewer
+**crash인 경우**:
 
-Phase 1a에서 해석된 code-reviewer 설정에 따라 디스패치한다.
+**1a-1. 부분 변경 롤백**
 
-**claude provider 호출:**
+```bash
+git reset --hard HEAD
+```
+
+마지막 체크포인트 커밋(이전 US의 커밋 또는 워크트리 초기 상태)으로 복귀한다. 부분 구현을 이어받지 않는다 — 컨텍스트 손실로 인한 코드 불일치 리스크를 제거하기 위함이다.
+
+**1a-2. crash 카운터 읽기**
+
+`.crew/plans/{task-id}/.dev_crash_count` 파일을 읽는다.
+- 파일이 없으면 카운터 = 0
+- 파일이 있으면 파일 내용(정수)이 카운터 값
+
+`.crew/plans/{task-id}/.dev_crash_provider` 파일을 읽는다.
+- 파일이 없으면 현재 provider 설정값
+
+**1a-3. 재시도 또는 provider 전환 판단**
 
 ```
-Agent(subagent_type="code-reviewer", model="{설정된 모델}", description="CodeReviewer: {task-id} 코드 리뷰", prompt="...")
+crash 카운터 < 2 → 같은 provider로 재시도 (Step 1로)
+crash 카운터 >= 2 AND 현재 provider가 codex → claude로 전환, 카운터 리셋 (Step 1로)
+crash 카운터 >= 2 AND 현재 provider가 claude → 유저 에스컬레이션
 ```
 
-**codex provider 호출:**
+**provider 전환 시:**
+- `.dev_crash_count`를 0으로 리셋한다.
+- `.dev_crash_provider`를 전환된 provider로 갱신한다.
+- 이후 Step 1에서 전환된 provider로 디스패치한다.
 
-오케스트레이터가 `git diff main...HEAD`를 실행하여 diff를 캡처한 뒤, diff와 가드레일을 프롬프트에 인라인 삽입하여 Codex를 실행한다.
+**에스컬레이션 메시지:**
 
-```bash
-codex exec --model {model} -c model_reasoning_effort="{reasoning}" --dangerously-bypass-approvals-and-sandbox "$(cat <<'PROMPT'
-당신은 CodeReviewer다. 아래 코드 변경 사항의 품질을 판단하라.
+```
+US-{k} 구현이 반복 실패합니다.
+- 원래 provider: {원래 provider} (2회 crash)
+- 전환 provider: {전환 provider} (2회 crash)
+[1] plan.md에서 US-{k}를 더 작게 분할
+[2] 수동으로 구현
+[3] 이 태스크를 보류
+```
 
-## 변경 사항 (git diff)
-{오케스트레이터가 git diff 결과를 인라인 삽입}
+에스컬레이션 시:
+- `.dev_crash_count`, `.dev_crash_provider` 파일을 삭제한다.
+- contract.md 상태를 `BLOCKED — US-{k} 구현 crash`로 갱신한다.
+- `ExitWorktree(action="keep")`으로 원본 프로젝트 디렉토리로 복귀한다.
 
-## 가드레일
-### Must
-{contract.md에서 추출한 Must 항목}
-### Must NOT
-{contract.md에서 추출한 Must NOT 항목}
+**1a-4. crash 카운터 증가 저장**
 
-## 검토 항목 / 판정 규칙 / 출력 형식
-(claude provider 프롬프트와 동일)
-PROMPT
-)"
-```
+`카운터 + 1`을 `.dev_crash_count` 파일에 저장한다.
+현재 provider를 `.dev_crash_provider` 파일에 저장한다.
+
+Step 1로 돌아간다.
 
-Codex stdout을 캡처하여 review-report.md 내용으로 사용한다.
+##### Step 2 — US-k 검증 (CodeReviewer + QA 병렬)
 
-**공통 사전 작업 (provider 무관):**
+CodeReviewer와 QA를 **동시에** 호출한다. US-k의 변경분만 검증한다.
 
-오케스트레이터가 해야 할 사전 작업:
+**CodeReviewer (US-k)**
+
+오케스트레이터 사전 작업:
 1. contract.md에서 가드레일 섹션(Must/Must NOT)만 추출한다.
-2. 가드레일을 CodeReviewer 프롬프트에 인라인으로 주입한다.
+2. 가드레일을 프롬프트에 인라인 주입한다.
 
 에이전트 프롬프트:
 
@@ -344,7 +415,7 @@ Codex stdout을 캡처하여 review-report.md 내용으로 사용한다.
 당신은 CodeReviewer 에이전트다. 코드 변경 사항의 품질을 판단한다.
 
 ## 입력
-`git diff main...HEAD`를 직접 실행하여 변경 사항을 확인하라.
+`git diff HEAD`를 직접 실행하여 마지막 커밋 이후 변경 사항을 확인하라.
 contract.md, plan.md, brief.md, spec.md, dev-log.md는 읽지 않는다.
 코드만 보고 판단한다.
 
@@ -373,44 +444,28 @@ contract.md, plan.md, brief.md, spec.md, dev-log.md는 읽지 않는다.
 - minor만 있거나 지적 없음 → PASS
 ```
 
-#### Phase 3b — QA
-
-Phase 1a에서 해석된 qa 설정에 따라 디스패치한다.
-
-**claude provider 호출:**
-
-```
-Agent(subagent_type="qa", model="{설정된 모델}", description="QA: {task-id} 검증", prompt="...")
-```
-
-**codex provider 호출:**
-
-오케스트레이터가 plan.md 내용을 읽어 프롬프트에 인라인 삽입하여 Codex를 실행한다. Codex stdout을 캡처하여 qa-report.md 내용으로 사용한다.
-
-```bash
-codex exec --model {model} -c model_reasoning_effort="{reasoning}" --dangerously-bypass-approvals-and-sandbox "{QA 프롬프트 + plan.md 인라인}"
-```
+**QA (US-k)**
 
 에이전트 프롬프트:
 
 ```
-당신은 QA 에이전트다. 구현이 실제로 동작하는지 검증한다.
+당신은 QA 에이전트다. US-{k}의 구현이 실제로 동작하는지 검증한다.
 
 ## 입력
 .crew/plans/{task-id}/plan.md 를 읽어라.
-plan.md의 유저 스토리와 테스트 시나리오를 확인하라.
+plan.md의 US-{k} 테스트 시나리오를 확인하라.
 contract.md, brief.md, spec.md는 읽지 않는다.
 
 ## 검증 항목 (순서대로 실행)
 1. 빌드 검증 — FAIL이면 이후 항목 실행 없이 즉시 FAIL
 2. 린트 검증
 3. 타입 체크 검증
-4. 테스트 스위트 검증
+4. 테스트 스위트 검증 (전체 테스트 실행 — 기존 테스트 회귀 방지)
 5. 테스트 전략 준수 검증 (TDD 또는 Tests-after인 경우)
-   - plan.md에 명시된 테스트 파일이 실제로 존재하는가?
+   - plan.md의 US-{k}에 명시된 테스트 파일이 실제로 존재하는가?
    - 해당 테스트가 실행되고 통과하는가?
    - None인 경우 이 항목을 PASS로 처리한다.
-6. E2E / 통합 검증 — plan.md의 테스트 시나리오 기반
+6. US-{k} 시나리오 검증 — plan.md의 US-{k} 테스트 시나리오 기반
 
 ## 출력
 아래 형식으로 검증 결과를 텍스트로 반환하라. 파일을 직접 작성하지 않는다.
@@ -425,149 +480,270 @@ contract.md, brief.md, spec.md는 읽지 않는다.
 - 코드를 수정하지 않는다. 검증만 한다.
 ```
 
-**Phase 3 결과 저장 (오케스트레이터 직접)**:
+**병렬 실행 방법**: Phase 3과 동일 (provider 조합에 따라 Agent/Bash 병렬 호출).
 
-CodeReviewer와 QA 에이전트는 read-only이므로 파일을 직접 작성하지 않는다.
-오케스트레이터가 각 에이전트의 반환 텍스트를 파일로 저장한다:
+**결과 저장 (오케스트레이터 직접)**:
 - CodeReviewer 결과 → `.crew/plans/{task-id}/review-report.md`
 - QA 결과 → `.crew/plans/{task-id}/qa-report.md`
 
-**Phase 3 병렬 실행 방법**:
+##### Step 3 — US-k 판정
 
-오케스트레이터는 CodeReviewer와 QA를 **동시에** 호출한다. provider 조합에 따라:
+오케스트레이터가 직접 판정한다:
+- CodeReviewer PASS + QA PASS → **US-k PASS** → Step 4로
+- 하나라도 FAIL → **US-k FAIL** → Step 5로
 
-- 둘 다 claude → Agent tool 2개를 한 번에 호출
-- 둘 다 codex → Bash tool 2개를 한 번에 호출
-- 혼합 → Agent + Bash를 한 번에 호출
+##### Step 4 — US-k 체크포인트 커밋
 
-```
-# 예: code-reviewer=claude, qa=codex
-Agent(subagent_type="code-reviewer", model="opus", description="CodeReviewer: {task-id}", prompt="...")
-Bash("codex exec --model gpt-5.4 ... '{QA 프롬프트}'")
+US-k가 PASS하면 즉시 커밋하여 체크포인트를 만든다:
+
+```bash
+git add -A
+git commit --no-verify -m "feat({task-id}): US-{k} {US 제목}"
 ```
 
----
+> `--no-verify`: 검증 단계에서 이미 빌드/린트/타입/테스트를 통과했으므로 pre-commit hook을 중복 실행하지 않는다.
 
-### Phase 4 — 오케스트레이터 직접 판정
+`.dev_loop_count` 파일이 존재하면 삭제한다 (US-k 루프 카운터 리셋).
+`.dev_crash_count`, `.dev_crash_provider` 파일이 존재하면 삭제한다 (crash 카운터 리셋).
 
-**Critic(DevAuditor)을 사용하지 않는다.** 오케스트레이터가 CodeReviewer + QA 결과로 직접 판정한다.
+**다음 US 진행**: k를 증가시키고 Step 1로 돌아간다.
+**모든 US 완료**: Phase 3으로 진행한다.
 
-판정 규칙:
-- CodeReviewer PASS + QA PASS → **PASS** → Phase 5로
-- 하나라도 FAIL → **FAIL** → Step 6으로
+##### Step 5 — US-k FAIL 처리
 
----
+**5a. 루프 카운터 읽기**
 
-### Phase 5 — 완료 (오케스트레이터 직접)
+`.crew/plans/{task-id}/.dev_loop_count` 파일을 읽는다.
+- 파일이 없으면 카운터 = 0
+- 파일이 있으면 파일 내용(정수)이 카운터 값
 
-**5a. 커밋 + PR**
+**5b. 에스컬레이션 판단**
+
+두 가지 에스컬레이션 조건:
+
+**조건 1 — 루프 상한 초과**:
+
+카운터 값 >= 4이면 즉시 에스컬레이션:
 
-```bash
-git add -A
-git commit --no-verify -m "feat({task-id}): {contract.md 목표 1줄 요약}"
-git push -u origin feat/{task-id}
+```
+US-{k}이 5회 반복 후에도 검증을 통과하지 못했습니다.
+최종 FAIL 사유를 첨부합니다.
+[1] US-{k}의 범위를 좁혀서 재시도
+[2] plan.md를 수정
+[3] 이 태스크를 보류
 ```
 
-> `--no-verify`: crew-dev가 이미 빌드/린트/타입/테스트 + lint-staged 검증을 완료했으므로 호스트 프로젝트의 pre-commit hook을 중복 실행하지 않는다.
+에스컬레이션 시:
+- `.dev_loop_count` 파일을 삭제한다.
+- contract.md 상태를 `BLOCKED — US-{k}에서 중단`으로 갱신한다.
+- `ExitWorktree(action="keep")`으로 원본 프로젝트 디렉토리로 복귀한다.
 
-PR을 생성한다 (머지하지 않는다).
+**조건 2 — 같은 기준 3회 연속 실패**:
 
-**5b. 상태 갱신**
+review-report.md와 qa-report.md에서 FAIL 항목을 확인한다.
+이전 아카이브와 비교하여 같은 항목이 3회 연속 FAIL이면 즉시 에스컬레이션:
 
-contract.md의 `## 수용 기준` 섹션에서 모든 `- [ ]`를 `- [x]`로 변경한다.
+```
+US-{k}의 {항목}이 3회 연속 FAIL입니다. 구조적 문제로 판단합니다.
+[1] plan.md를 수정 (구현 전략의 문제)
+[2] contract.md를 수정 (기준 자체의 문제)
+[3] 이 태스크를 보류
+```
 
-contract.md의 `## 상태` 섹션을 갱신한다:
+에스컬레이션 시 `ExitWorktree(action="keep")`으로 원본 프로젝트 디렉토리로 복귀한다.
+
+**5c. 피드백 아카이브**
+
+`n = 카운터 + 1`
 
-```markdown
-## 상태
-COMPLETED — 모든 수용 기준이 검증을 통과했다.
-PR: {PR URL}
+```
+review-report.md → review-report-{n}.md
+qa-report.md → qa-report-{n}.md
 ```
 
-**5c. .dev_loop_count 정리**
+**5d. 루프 카운터 증가 저장**
 
-`.dev_loop_count` 파일이 존재하면 삭제한다.
+`카운터 + 1`을 `.dev_loop_count` 파일에 저장한다.
+
+**5e. Step 1로 돌아감 (US-k retry)**
 
-**5d. 워크트리 종료**
+Step 1(Dev)로 돌아간다. Dev retry 프롬프트에 아카이브된 피드백 파일을 주입한다.
+Dev 수정 완료 후 Step 2(CodeReviewer + QA)를 재실행한다.
+
+---
+
+### Phase 3 — 최종 전체 검증 (CodeReviewer + QA)
+
+모든 US가 개별 검증을 통과한 후, 전체 변경 사항에 대해 통합 검증을 수행한다.
+US 간 상호작용에서 발생할 수 있는 문제를 잡기 위한 단계다.
+
+CodeReviewer와 QA를 **동시에** 호출한다.
+
+#### Phase 3a — CodeReviewer (전체)
+
+오케스트레이터 사전 작업:
+1. contract.md에서 가드레일 섹션(Must/Must NOT)만 추출한다.
+2. 가드레일을 프롬프트에 인라인 주입한다.
+
+에이전트 프롬프트:
 
 ```
-ExitWorktree(action="remove")
+당신은 CodeReviewer 에이전트다. 전체 코드 변경 사항의 품질을 판단한다.
+
+## 입력
+`git diff main...HEAD`를 직접 실행하여 전체 변경 사항을 확인하라.
+contract.md, plan.md, brief.md, spec.md, dev-log.md는 읽지 않는다.
+코드만 보고 판단한다.
+
+### 가드레일 (contract.md에서 추출)
+#### Must
+- {오케스트레이터가 contract.md에서 복사한 내용}
+#### Must NOT
+- {오케스트레이터가 contract.md에서 복사한 내용}
+
+위 가드레일을 위반하는 변경이 있으면 critical로 지적하라.
+
+## 검토 항목
+1. 가드레일 위반 (위반 시 critical)
+2. 코드베이스 컨벤션 준수 (기존 코드를 Glob/Grep/Read로 탐색하여 확인)
+3. 보안 취약점
+4. 불필요한 복잡도
+5. 잠재적 버그
+6. 에러 처리 적절성
+7. **모듈 간 정합성** — 변경된 파일들 사이의 인터페이스, 타입, import가 일관적인가
+
+## 출력
+아래 형식으로 리뷰 결과를 텍스트로 반환하라. 파일을 직접 작성하지 않는다.
+
+## 판정 규칙
+- 가드레일 위반 → critical
+- critical 또는 major가 1개 이상 → FAIL
+- minor만 있거나 지적 없음 → PASS
 ```
 
-PR push가 완료되었으므로 로컬 워크트리를 제거하고 원본 프로젝트 디렉토리로 복귀한다.
+#### Phase 3b — QA (전체)
 
-**5e. 완료 반환**
+에이전트 프롬프트:
 
 ```
-상태: COMPLETE
-task-id: {task-id}
-PR: {PR URL}
+당신은 QA 에이전트다. 전체 구현이 실제로 동작하는지 최종 검증한다.
+
+## 입력
+.crew/plans/{task-id}/plan.md 를 읽어라.
+plan.md의 모든 유저 스토리, 테스트 시나리오, 검증 시나리오를 확인하라.
+contract.md, brief.md, spec.md는 읽지 않는다.
+
+## 검증 항목 (순서대로 실행)
+1. 빌드 검증 — FAIL이면 이후 항목 실행 없이 즉시 FAIL
+2. 린트 검증
+3. 타입 체크 검증
+4. 테스트 스위트 검증 (전체 테스트)
+5. 테스트 전략 준수 검증 (TDD 또는 Tests-after인 경우)
+   - plan.md에 명시된 모든 테스트 파일이 실제로 존재하는가?
+   - 해당 테스트가 실행되고 통과하는가?
+   - None인 경우 이 항목을 PASS로 처리한다.
+6. 전체 E2E / 통합 검증 — plan.md의 모든 테스트 시나리오 기반
+7. 실행 검증 — plan.md의 `## 실행 검증` 절차를 직접 실행한다.
+   - 자동화 테스트와 별개로, 구현된 기능을 사용자 관점에서 직접 실행한다.
+   - 백엔드: 실제 API 호출, 스크립트 실행 등
+   - UI: 개발 서버에서 브라우저 조작
+   - 각 항목의 기대 결과와 실제 결과를 비교하여 판정한다.
+   - 실행 검증 섹션이 plan.md에 없으면 즉시 FAIL.
+
+## 출력
+아래 형식으로 검증 결과를 텍스트로 반환하라. 파일을 직접 작성하지 않는다.
+
+## 판정 규칙
+- 항목 1-7 중 하나라도 FAIL → 전체 FAIL
+- 모든 항목 PASS → 전체 PASS
+
+## 규칙
+- 모든 검증은 직접 실행한다. "통과할 것이다"는 증거가 아니다.
+- 실행 출력을 반드시 캡처하여 기록한다.
+- 코드를 수정하지 않는다. 검증만 한다.
 ```
 
----
+**Phase 3 결과 저장 (오케스트레이터 직접)**:
 
-### Step 6 — FAIL 처리 (검증 루프)
+CodeReviewer와 QA 에이전트는 read-only이므로 파일을 직접 작성하지 않는다.
+오케스트레이터가 각 에이전트의 반환 텍스트를 파일로 저장한다:
+- CodeReviewer 결과 → `.crew/plans/{task-id}/final-review-report.md`
+- QA 결과 → `.crew/plans/{task-id}/final-qa-report.md`
 
-Phase 4에서 FAIL이면:
+**Phase 3 병렬 실행 방법**:
 
-**6a. 루프 카운터 읽기**
+오케스트레이터는 CodeReviewer와 QA를 **동시에** 호출한다. provider 조합에 따라:
 
-`.crew/plans/{task-id}/.dev_loop_count` 파일을 읽는다.
-- 파일이 없으면 카운터 = 0
-- 파일이 있으면 파일 내용(정수)이 카운터 값
+- 둘 다 claude → Agent tool 2개를 한 번에 호출
+- 둘 다 codex → Bash tool 2개를 한 번에 호출
+- 혼합 → Agent + Bash를 한 번에 호출
 
-**6b. 에스컬레이션 판단**
+---
 
-두 가지 에스컬레이션 조건:
+### Phase 4 — 최종 판정 + 완료
 
-**조건 1 — 루프 상한 초과**:
+**4a. 오케스트레이터 직접 판정**
 
-카운터 값 >= 4이면 즉시 에스컬레이션:
+판정 규칙:
+- CodeReviewer PASS + QA PASS → **PASS** → 4b로
+- 하나라도 FAIL → **FAIL** → 에스컬레이션
+
+최종 전체 검증 FAIL 시 자동 retry하지 않는다. US 간 상호작용 문제는 어떤 US를 수정해야 하는지 자동 판단이 어렵기 때문이다.
 
 ```
-검증 루프가 5회 반복 후에도 통과하지 못했습니다.
-최종 FAIL 사유를 첨부합니다.
-[1] 수용 기준을 좁혀서 재시도
-[2] contract.md를 수정
+최종 전체 검증에서 FAIL이 발생했습니다.
+개별 US는 모두 통과했으나 통합 단계에서 문제가 발견되었습니다.
+final-review-report.md, final-qa-report.md를 확인하세요.
+[1] 문제 원인을 특정하여 해당 US를 수동 수정 후 재실행
+[2] plan.md를 수정하여 US 간 의존성을 재설계
 [3] 이 태스크를 보류
 ```
 
 에스컬레이션 시:
-- `.dev_loop_count` 파일을 삭제한다.
-- contract.md 상태를 `BLOCKED`으로 갱신한다.
+- contract.md 상태를 `BLOCKED — 최종 전체 검증 FAIL`로 갱신한다.
 - `ExitWorktree(action="keep")`으로 원본 프로젝트 디렉토리로 복귀한다.
 
-**조건 2 — 같은 기준 3회 연속 실패**:
-
-review-report.md와 qa-report.md에서 FAIL 항목을 확인한다.
-이전 아카이브와 비교하여 같은 항목이 3회 연속 FAIL이면 즉시 에스컬레이션:
+**4b. PR 생성**
 
+```bash
+git push -u origin feat/{task-id}
 ```
-{항목}이 3회 연속 FAIL입니다. 구조적 문제로 판단합니다.
-[1] contract.md를 수정 (기준 자체의 문제)
-[2] plan.md를 수정 (구현 전략의 문제)
-[3] 이 태스크를 보류
+
+> US 단위 커밋은 Phase 2에서 이미 완료되었으므로 추가 커밋은 불필요하다.
+
+PR을 생성한다 (머지하지 않는다).
+
+**4c. 상태 갱신**
+
+contract.md의 `## 수용 기준` 섹션에서 모든 `- [ ]`를 `- [x]`로 변경한다.
+
+contract.md의 `## 상태` 섹션을 갱신한다:
+
+```markdown
+## 상태
+COMPLETED — 모든 수용 기준이 검증을 통과했다.
+PR: {PR URL}
 ```
 
-에스컬레이션 시 `ExitWorktree(action="keep")`으로 원본 프로젝트 디렉토리로 복귀한다.
+**4d. 정리**
 
-**6c. 피드백 아카이브**
+`.dev_loop_count` 파일이 존재하면 삭제한다.
 
-`n = 카운터 + 1`
+**4e. 워크트리 종료**
 
 ```
-review-report.md → review-report-{n}.md
-qa-report.md → qa-report-{n}.md
+ExitWorktree(action="remove")
 ```
 
-**6d. 루프 카운터 증가 저장**
-
-`카운터 + 1`을 `.dev_loop_count` 파일에 저장한다.
+PR push가 완료되었으므로 로컬 워크트리를 제거하고 원본 프로젝트 디렉토리로 복귀한다.
 
-**6e. Phase 2로 돌아감 (retry)**
+**4f. 완료 반환**
 
-Phase 2(Dev)로 돌아간다. Dev retry 프롬프트에 아카이브된 피드백 파일을 주입한다.
-Dev 수정 완료 후 Phase 3(CodeReviewer + QA)을 **둘 다** 재실행한다.
+```
+상태: COMPLETE
+task-id: {task-id}
+PR: {PR URL}
+```
 
 ---
 
@@ -575,12 +751,12 @@ Dev 수정 완료 후 Phase 3(CodeReviewer + QA)을 **둘 다** 재실행한다.
 
 | 이벤트 | 동작 |
 |--------|------|
-| 첫 번째 진입 | 파일 없음 (카운터 = 0) |
-| n번째 FAIL 처리 후 | 파일 갱신, 내용: `n` |
-| PASS (Phase 5) | 파일 삭제 |
+| US-k 첫 진입 | 파일 없음 (카운터 = 0) |
+| US-k n번째 FAIL 후 | 파일 갱신, 내용: `n` |
+| US-k PASS (Step 4) | 파일 삭제 |
 | 에스컬레이션 | 파일 삭제 |
 
-검증 사이클은 최대 5회 (초기 1회 + retry 최대 4회).
+각 US당 최대 5회 검증 사이클 (초기 1회 + retry 최대 4회).
 
 ---
 

package/skills/crew-plan/SKILL.md

@@ -87,11 +87,12 @@ WHAT(무엇을 만드는가)은 이미 정의되어 있으므로, HOW(어떻게
   - 테스트 실행 스크립트 (package.json scripts 등)
 - Researcher (Sonnet): 외부 리서치. 필요시만 호출.
   Agent(subagent_type="researcher", description="외부 리서치: {리서치 대상}", prompt="...")
+  **외부 API/서비스가 관련된 경우**: spec.md에 언급된 각 외부 대상(엔드포인트, 서비스, 플랫폼)에 대해 **개별적으로** 문서/인터페이스를 조사하라. 하나의 대상에 대한 문서를 다른 대상에 일반화하지 않는다. 문서가 확인되지 않는 대상은 "미검증 인터페이스"로 명시한다.
 
 ## 출력
 아래 필수 섹션을 포함한 분석 결과를 텍스트로 반환하라. 파일을 직접 작성하지 않는다.
 
-필수 섹션: 요구사항 보완, 코드베이스 맥락(관련 파일/기존 패턴/테스트 구조), 아키텍처 방향(권장+대안), 엣지 케이스/리스크, 가드레일(Must/Must NOT), 테스트 인프라(프레임워크/패턴/유무), 외부 리서치(해당 시).
+필수 섹션: 요구사항 보완, 코드베이스 맥락(관련 파일/기존 패턴/테스트 구조), 아키텍처 방향(권장+대안), 엣지 케이스/리스크, 가드레일(Must/Must NOT), 테스트 인프라(프레임워크/패턴/유무), 외부 인터페이스 검증(해당 시), 외부 리서치(해당 시).
 
 ## 규칙
 - 요구사항에 빈틈이 있으면 AskUserQuestion으로 유저에게 직접 질문하라.
@@ -172,7 +173,7 @@ brief.md는 읽지 않는다.
 ## 출력
 .crew/plans/{task-id}/plan.md 를 작성하라.
 
-plan.md 필수 구조: 유저 스토리(US-N) 단위. 각 유저 스토리에 구현 태스크 + 테스트 시나리오(최소 2개: 정상+에러). 위험 요소 섹션. 검증 시나리오 섹션(조건/행위/기대 결과 — contract.md에 그대로 포함됨).
+plan.md 필수 구조: 유저 스토리(US-N) 단위. 각 유저 스토리에 구현 태스크 + 테스트 시나리오(최소 2개: 정상+에러). 위험 요소 섹션. 검증 시나리오 섹션(조건/행위/기대 결과 — contract.md에 그대로 포함됨). 실행 검증 섹션(필수 — contract.md에 그대로 포함됨).
 
 ## 테스트 전략
 analysis.md의 `## 테스트 전략` 섹션을 확인하고, 결정에 따라 태스크 구조를 달리한다.
@@ -195,6 +196,29 @@ analysis.md의 `## 테스트 전략` 섹션을 확인하고, 결정에 따라
 
 plan.md 최상단에 `## 테스트 전략` 섹션을 두어 결정 사항을 명시한다.
 
+### 외부 인터페이스 가정 (외부 API/서비스가 관련된 경우 필수)
+analysis.md에 `## 외부 인터페이스 검증` 섹션이 있으면, plan.md에 `## 외부 인터페이스 가정` 섹션을 반드시 작성한다.
+각 외부 대상에 대해 가정하는 인터페이스와 검증 상태를 명시한다:
+
+| 대상 | 가정하는 인터페이스 | 근거 | 검증 상태 |
+|------|------------------|------|----------|
+| {대상 1} | {인터페이스 설명} | 공식 문서 확인 | 검증됨 |
+| {대상 2} | {대상 1과 동일} | 문서 없음, 유추 | 미검증 |
+
+**"미검증" 대상이 있으면**: 해당 대상에 대한 **스파이크 태스크**를 구현 태스크 앞에 배치한다.
+스파이크 태스크는 실제 API를 호출하여 인터페이스를 확인하고, 검증된 대상과의 차이점을 기록한다.
+차이가 발견되면 이후 구현 태스크의 접근 방식을 스파이크 결과에 따라 분기하도록 계획한다.
+
+### 실행 검증 (필수, 테스트 전략과 무관하게 항상 포함)
+유닛 테스트/자동화 테스트와 별개로, 구현된 기능을 실제로 실행하여 동작을 확인하는 절차를 `## 실행 검증` 섹션에 반드시 작성한다.
+- 백엔드/API: 실제 API 호출 명령어(curl/httpie), 스크립트 실행, DB 쿼리 등
+- UI/프론트엔드: 개발 서버 실행 후 브라우저에서 직접 조작하는 절차
+- CLI/라이브러리: 실제 사용 예시 실행
+"테스트 파일 실행"은 실행 검증이 아니다. 실제 기능을 사용자 관점에서 동작시키는 것이 실행 검증이다.
+각 실행 검증 항목은 다음 형식으로 작성한다:
+- 실행 방법: {구체적 명령어 또는 절차}
+- 기대 결과: {확인할 출력 또는 동작}
+
 ## 규칙
 - 코드를 작성하지 않는다.
 - analysis.md의 아키텍처 방향과 가드레일을 따른다.
@@ -263,9 +287,17 @@ Agent(subagent_type="plan-evaluator", description="PlanEvaluator: {task-id} 계
   - Tests-after: 구현 태스크 뒤에 테스트 작성 태스크가 있는가? 테스트 파일 경로가 명시되어 있는가?
   - None: 이 항목을 YES로 처리한다.
 [ ] E6. 비즈니스 가정 0개 — plan.md가 spec.md에 없는 비즈니스 로직을 임의로 추가하지 않았는가? plan에 "~로 가정", "~로 판단" 등 spec에 근거 없는 비즈니스 결정이 있으면 NO.
+[ ] E7. 실행 검증 포함 — plan.md에 `## 실행 검증` 섹션이 있고, 유닛 테스트와 별개로 구현된 기능을 실제로 실행하여 동작을 확인하는 절차가 구체적으로 명시되어 있는가?
+  - 각 항목에 실행 방법(명령어/절차)과 기대 결과가 있는가?
+  - "테스트 파일 실행"만으로 구성되어 있으면 NO.
+  - 백엔드라면 실제 API 호출/스크립트 실행, UI라면 브라우저 조작 절차가 있어야 YES.
+[ ] E8. 외부 인터페이스 가정 검증 — plan.md에서 여러 외부 서비스/엔드포인트를 동일한 인터페이스로 처리하는 태스크가 있는가? 있다면:
+  - `## 외부 인터페이스 가정` 섹션에 각 대상별 검증 상태가 명시되어 있는가?
+  - "미검증" 대상에 대해 스파이크 태스크가 구현 태스크 앞에 배치되어 있는가?
+  - 외부 API가 관련되지 않은 경우 이 항목을 YES로 처리한다.
 
 ## 판정 규칙
-- 6개 항목 모두 YES → PASS
+- 8개 항목 모두 YES → PASS
 - 하나라도 NO → FAIL
 - "아마 의도했을 것"이라고 추측하지 않는다. 모호하면 NO.
 
@@ -279,7 +311,7 @@ Agent(subagent_type="explorer", description="코드 참조 확인: {파일 목
 
 ## 출력
 아래 형식으로 검증 결과를 텍스트로 반환하라. 파일을 직접 작성하지 않는다.
-형식: 판정(PASS/FAIL), 항목별 결과(E1-E6 YES/NO + 근거), FAIL 상세(NO 항목의 문제+수정 방향), 근본 원인 분류(FAIL 시).
+형식: 판정(PASS/FAIL), 항목별 결과(E1-E8 YES/NO + 근거), FAIL 상세(NO 항목의 문제+수정 방향), 근본 원인 분류(FAIL 시).
 ```
 
 **Step 4 결과 저장 (오케스트레이터 직접)**:
@@ -339,6 +371,13 @@ review.md가 정상적으로 작성되었고 판정이 PASS임을 확인한다.
 - 행위: {실행할 것}
 - 기대 결과: {검증할 것}
 
+## 실행 검증
+{plan.md의 실행 검증 섹션을 그대로 복사}
+
+### {검증 1 제목}
+- 실행 방법: {구체적 명령어 또는 절차}
+- 기대 결과: {확인할 출력 또는 동작}
+
 ## 참조 문서
 - 요구사항: .crew/plans/{task-id}/spec.md
 - 사전 분석: .crew/plans/{task-id}/analysis.md
@@ -347,6 +386,9 @@ review.md가 정상적으로 작성되었고 판정이 PASS임을 확인한다.
 ## 검증 이력
 PlanEvaluator PASS — review.md 참조
 
+## 워크트리
+mode: new
+
 ## 상태
 ACTIVE
 ```