@jjlabsio/claude-crew 0.1.33 → 0.1.35

package/skills/crew-plan/SKILL.md

@@ -8,7 +8,7 @@ description: TechLead + Planner + PlanEvaluator 계획 파이프라인 — contr
 crew-interview가 생성한 spec.md를 입력으로 받아 **HOW(어떻게 만드는가)**를 결정하고 `contract.md`를 생성한다.
 `contract.md`가 생성되어야 crew-dev가 시작할 수 있다.
 
-에이전트 간 소통은 파일을 통해서만 이루어진다. 에이전트의 추론 과정은 다른 에이전트에게 전달되지 않는다.
+에이전트 간 소통은 파일 산출물과 중앙 `crew-agent-runner` 스킬의 dispatch 계약을 통해서만 이루어진다. 에이전트의 추론 과정은 다른 에이전트에게 전달되지 않는다.
 
 ---
 
@@ -40,491 +40,275 @@ crew-interview가 생성한 spec.md를 입력으로 받아 **HOW(어떻게 만
 
 ## 실행 순서
 
-TechLead, Planner, PlanEvaluator, Explorer, Researcher는 모두 provider 설정 대상이다. 오케스트레이터는 **반드시 Step 1a에서 provider 설정을 먼저 해석한 뒤**, 각 단계의 디스패치를 분기한다. 본 문서에 등장하는 `runAgent(role, prompt, providerConfig)` 표기는 모두 의사코드이며, 실제로는 Step 1a의 해석 테이블과 각 Step의 분기 규칙대로 `Agent` 또는 `Bash(crew-codex-companion)`를 직접 호출한다.
+각 에이전트 단계는 중앙 `crew-agent-runner` 스킬의 dispatch 절차로 실행한다. 이 문서는 역할, 입력, 기대 산출물, 검증 기준만 정의하며 실행 방식은 runner 계약을 따른다.
 
-- Claude provider이면 기존 Claude Code `Agent` 호출을 사용한다.
-- Codex provider이면 read-only companion task를 사용하고, 산출물은 `<crew-agent-result>.artifact`로 반환받아 오케스트레이터가 `.crew/` 파일에 저장한다.
-- Codex TechLead/Planner가 Explorer/Researcher가 필요하면 직접 호출하지 않고 `needs_agent`를 반환한다. 오케스트레이터가 요청된 에이전트를 실행한 뒤 결과를 원래 Codex thread에 `--resume-last`로 주입한다.
+## 공통 에이전트 실행 인터페이스
 
-### Step 1 — 환경 준비 (오케스트레이터 직접)
+crew-plan의 모든 에이전트 실행은 역할이나 step과 무관하게 아래 인터페이스만 사용한다.
+오케스트레이터는 `techlead`, `planner`, `plan-evaluator`, 후속 요청 role을 실행할 때마다 이 순서를 반복한다.
 
-**1a. Provider 설정 로드**
+1. `{ role, taskId, inputs, instruction, successGate, failureHandling }` 형태의 `request-file`을 작성한다.
+2. `node "$CLAUDE_PLUGIN_ROOT/scripts/crew-agent-runner.mjs" prepare --role <role> --request-file <request-file> --json`을 실행한다.
+3. `action == dispatch`이면 prepare가 반환한 command를 실행하고 AgentResult를 처리한다.
+4. `action == agent`이면 prepare가 반환한 `subagent_type`, `model`, `prompt`로 runner 계약의 Claude 경로를 실행하고 AgentResult로 정규화한다.
 
-이 단계를 건너뛰지 않는다. 어떤 단계든 에이전트 호출 직전에 1a의 해석 테이블이 출력되어 있어야 한다.
+이 순서를 생략하고 직접 하위 에이전트를 호출하지 않는다.
+provider 선택, 런타임 선택, AgentResult 반환 형식, 후속 입력 주입, retry/fallback/escalate 판단은 모두 중앙 runner 계약을 따른다.
 
-cascading 해석:
+### Step 1 — spec.md 검증
 
-1. `${CLAUDE_PLUGIN_ROOT}/data/provider-catalog.json`을 읽어 `agent_defaults`와 `agent_runtime`을 로드한다.
-2. `~/.claude/crew/config.json`이 있으면 `providers.{role}` 필드로 user-level 오버라이드를 적용한다.
-3. `{projectRoot}/.crew/config.json`이 있으면 `providers.{role}` 필드로 project-level 오버라이드를 다시 적용한다 (최우선).
-4. 본 스킬의 적용 대상 role은 `techlead`, `planner`, `plan-evaluator`, `explorer`, `researcher` 다섯 개다. 각 role의 `{provider, model, reasoning?, codex_sandbox}` 값을 결정한다.
+role: orchestrator
 
-Codex 가용성 확인: 해석 결과 중 codex provider가 하나라도 있으면 `which codex`(또는 `bash -lc 'command -v codex'`)로 가용성을 확인한다. codex가 없으면 해당 role을 catalog default(claude/{model})로 폴백하고 경고를 출력한다.
+inputs:
+- `.crew/plans/{task-id}/spec.md`
 
-해석 테이블 출력 (필수): 해석 결과를 다음 형식으로 stdout에 인쇄한다. 이 테이블이 출력되지 않은 채 1b 이후로 진행하지 않는다.
+output:
+- spec gate result → continue 또는 ESCALATE
 
-```
-provider 해석:
-- techlead: {provider} / {model}{reasoning이 있으면 / {reasoning}} ({codex_sandbox})
-- planner: {provider} / {model}{...}
-- plan-evaluator: {provider} / {model}{...}
-- explorer: {provider} / {model}{...}
-- researcher: {provider} / {model}{...}
-```
-
-이후 Step 2/3/4의 디스패치는 이 테이블의 값을 기준으로 한다.
-
-**1b. spec.md 유효성 검사**
+role instructions:
+- spec.md가 존재하고 비어 있지 않은지 확인한다.
+- WHAT(무엇을 만드는가)은 spec.md에 이미 정의되어 있어야 한다.
+- spec.md가 없거나 비어 있으면 crew-interview 실행, spec.md 직접 보완, 태스크 보류 중 하나를 선택하도록 에스컬레이션한다.
 
-`.crew/plans/{task-id}/spec.md`를 확인한다.
+success gate:
+- spec.md가 존재한다.
+- spec.md가 비어 있지 않다.
 
-**게이트**: spec.md가 존재하고 비어 있지 않음을 확인한다.
-실패 시 즉시 에스컬레이션:
-
-```
-spec.md가 없거나 비어 있습니다. crew-interview를 먼저 실행해야 합니다.
-[1] crew-interview를 실행하여 spec.md를 생성
-[2] spec.md를 직접 작성하여 재시도
-[3] 이 태스크를 보류
-```
+failure handling:
+- spec gate 실패 시 즉시 ESCALATE.
+- retry/escalate 규칙은 contract.policy에 따른다.
 
 ---
 
-### Step 2 — TechLead 에이전트 실행
+### Step 2 — TechLead 실행
 
-**provider/model**: Step 1a의 해석 테이블에서 `techlead`의 값을 사용한다. catalog default는 `agent_defaults.techlead`(claude/opus)이지만, user/project config가 우선한다.
+중앙 `crew-agent-runner` 스킬의 dispatch 절차로 실행한다.
 
-해석 테이블의 provider 값에 따라 분기 디스패치한다:
+role: techlead
 
-- **claude**:
-  ```
-  Agent(subagent_type="techlead", model="{model}", description="TechLead: {task-id} 사전 분석", prompt="...")
-  ```
-- **codex**:
-  ```bash
-  node "${CLAUDE_PLUGIN_ROOT}/scripts/crew-codex-companion.mjs" task --json --expect-crew-result --model {model} --effort {reasoning} --prompt-file {promptFile}
-  ```
-  - `agent_runtime.techlead.codex_sandbox`가 `workspace-write`인 경우에만 `--write`를 추가한다 (plan 단계 에이전트는 모두 read-only).
-  - Codex는 `.crew/`에 직접 접근하지 않으므로, `spec.md` 내용을 `{promptFile}`에 인라인 주입한다.
-  - 마지막 `<crew-agent-result>` 블록의 `artifact`를 추출하여 Step 2 결과 저장에 사용한다.
+inputs:
+- `.crew/plans/{task-id}/spec.md`
 
-에이전트 프롬프트 (claude/codex 공통, codex의 경우 `{promptFile}`에 그대로 주입):
+output:
+- complete.artifact → `.crew/plans/{task-id}/analysis.md`
 
-```
-당신은 TechLead 에이전트다. 사전 분석을 수행하고 아키텍처 방향을 판단한다.
-
-## 입력
-.crew/plans/{task-id}/spec.md 를 읽어라.
-
-spec.md에는 목표, 스코프 경계, 유저 플로우, UI 구조, 비즈니스 규칙, 수용 기준이 포함되어 있다.
-WHAT(무엇을 만드는가)은 이미 정의되어 있으므로, HOW(어떻게 만드는가)에 집중하라.
-
-## 서브에이전트 호출
-- Explorer (Haiku): 코드베이스 탐색. 항상 호출. 병렬 2-3개로 호출하라.
-  runAgent(role="explorer", description="코드베이스 탐색: {탐색 대상}", prompt="...")
-  **필수 탐색 항목**: 테스트 인프라도 반드시 탐색한다. Explorer 중 1개는 다음을 확인:
-  - 테스트 프레임워크 설정 파일 (jest.config.*, vitest.config.*, pytest.ini 등)
-  - 대표적인 테스트 파일 2-3개의 패턴
-  - 커버리지 설정 여부
-  - 테스트 실행 스크립트 (package.json scripts 등)
-- Researcher (Sonnet): 외부 리서치. 필요시만 호출.
-  runAgent(role="researcher", description="외부 리서치: {리서치 대상}", prompt="...")
-  **외부 API/서비스가 관련된 경우**: spec.md에 언급된 각 외부 대상(엔드포인트, 서비스, 플랫폼)에 대해 **개별적으로** 문서/인터페이스를 조사하라. 하나의 대상에 대한 문서를 다른 대상에 일반화하지 않는다. 문서가 확인되지 않는 대상은 "미검증 인터페이스"로 명시한다.
-
-## 출력
-아래 필수 섹션을 포함한 분석 결과를 텍스트로 반환하라. 파일을 직접 작성하지 않는다.
-
-필수 섹션: 요구사항 보완, 코드베이스 맥락(관련 파일/기존 패턴/테스트 구조), 아키텍처 방향(권장+대안), 엣지 케이스/리스크, 가드레일(Must/Must NOT), 테스트 인프라(프레임워크/패턴/유무), 외부 인터페이스 검증(해당 시), 외부 리서치(해당 시).
-
-## 규칙
-- 요구사항에 빈틈이 있으면 AskUserQuestion으로 유저에게 직접 질문하라.
-- 탐색(양)은 서브에이전트에게, 판단(질)은 직접.
-```
-
-**Step 2 결과 저장 (오케스트레이터 직접)**:
+role instructions:
+- 사전 분석을 수행하고 아키텍처 방향을 판단한다.
+- WHAT은 이미 정의되어 있으므로 HOW에 집중한다.
+- 코드베이스 맥락, 관련 파일, 기존 패턴, 테스트 구조를 확인한다.
+- Explorer 역할의 탐색이 필요한 경우 runner 계약의 후속 요청 형식으로 코드베이스 탐색을 요청한다.
+- 테스트 인프라 탐색은 필수다. 프레임워크 설정, 대표 테스트 파일, 커버리지 설정, 테스트 실행 스크립트를 확인한다.
+- 외부 API/서비스가 관련된 경우 Researcher 역할의 조사가 필요한 항목을 분리해 요청한다.
+- 외부 대상마다 문서와 인터페이스를 개별 확인하고, 확인되지 않은 대상은 "미검증 인터페이스"로 명시한다.
+- 요구사항에 빈틈이 있으면 blocked user 상태로 질문과 선택지를 반환한다.
+- 필수 섹션: 요구사항 보완, 코드베이스 맥락, 아키텍처 방향, 엣지 케이스/리스크, 가드레일(Must/Must NOT), 테스트 인프라, 외부 인터페이스 검증(해당 시), 외부 리서치(해당 시).
 
-TechLead 에이전트는 read-only이므로 파일을 직접 작성하지 않는다.
-오케스트레이터가 TechLead의 반환 텍스트를 `.crew/plans/{task-id}/analysis.md`로 저장한다.
+success gate:
+- analysis.md 산출물이 생성될 수 있는 complete.artifact가 있다.
+- 가드레일 섹션이 비어 있지 않다.
+- 테스트 인프라 섹션이 프레임워크/패턴/유무를 명시한다.
 
-**실패 조건**: analysis.md가 없거나 가드레일 섹션이 비어 있으면 즉시 에스컬레이션.
+failure handling:
+- analysis 산출물이 없거나 가드레일이 비어 있으면 ESCALATE.
+- retry/escalate 규칙은 contract.policy에 따른다.
 
 ---
 
-### Step 2.5 — 테스트 전략 결정 (오케스트레이터 직접)
-
-TechLead의 analysis.md에서 테스트 인프라 섹션을 확인한 후, 오케스트레이터가 유저에게 테스트 전략을 질문한다.
-
-**테스트 인프라가 있는 경우**:
-
-```
-테스트 인프라가 감지되었습니다: {프레임워크명}
-테스트 전략을 선택하세요:
-[1] TDD — 각 태스크를 RED(실패 테스트) → GREEN(최소 구현) → REFACTOR로 구성
-[2] Tests-after — 구현 태스크 완료 후 테스트 태스크 추가
-[3] None — 자동화 테스트 없음 (QA 에이전트 검증만)
-```
+### Step 2.5 — 테스트 전략 결정
 
-**테스트 인프라가 없는 경우**:
+role: orchestrator
 
-```
-테스트 인프라가 감지되지 않았습니다.
-테스트 전략을 선택하세요:
-[1] TDD — 테스트 인프라 셋업 후 RED → GREEN → REFACTOR로 구현
-[2] Tests-after — 테스트 인프라 셋업 후 구현 완료 뒤 테스트 추가
-[3] None — 자동화 테스트 없음 (QA 에이전트 검증만)
-```
+inputs:
+- `.crew/plans/{task-id}/analysis.md`
 
-[1] 또는 [2] 선택 시 인프라가 없으면 추가 질문:
+output:
+- selected test strategy → `.crew/plans/{task-id}/analysis.md`의 `## 테스트 전략` 섹션
 
-```
-테스트 프레임워크를 선택하세요:
-[1] vitest  [2] jest  [3] bun test  [4] pytest  [5] 기타 (직접 입력)
-```
+role instructions:
+- TechLead의 테스트 인프라 섹션을 기준으로 유저에게 테스트 전략을 선택하게 한다.
+- 테스트 인프라가 있으면 TDD, Tests-after, None 중 하나를 선택하게 한다.
+- 테스트 인프라가 없고 TDD 또는 Tests-after를 선택하면 vitest, jest, bun test, pytest, 기타 중 하나를 선택하게 한다.
+- 선택 결과를 analysis.md 하단의 `## 테스트 전략` 섹션으로 기록한다.
 
-**결과 기록**: 선택된 테스트 전략을 analysis.md 하단에 추가한다:
+success gate:
+- 결정 값이 TDD, Tests-after, None 중 하나다.
+- 프레임워크 값이 기존 감지 결과 또는 유저 선택으로 명시된다.
+- 인프라 셋업 필요 여부가 YES 또는 NO로 명시된다.
 
-```markdown
-## 테스트 전략
-- 결정: {TDD | Tests-after | None}
-- 프레임워크: {기존 감지된 프레임워크 또는 유저 선택}
-- 인프라 셋업 필요: {YES | NO}
-```
+failure handling:
+- 유저 선택이 없으면 blocked user 상태로 보류한다.
+- retry/escalate 규칙은 contract.policy에 따른다.
 
 ---
 
-### Step 3 — Planner 에이전트 실행
-
-**provider/model**: Step 1a의 해석 테이블에서 `planner`의 값을 사용한다. catalog default는 `agent_defaults.planner`(claude/opus)이지만, user/project config가 우선한다.
-
-해석 테이블의 provider 값에 따라 분기 디스패치한다:
-
-- **claude**:
-  ```
-  Agent(subagent_type="planner", model="{model}", description="Planner: {task-id} 구현 계획", prompt="...")
-  ```
-- **codex**:
-  ```bash
-  node "${CLAUDE_PLUGIN_ROOT}/scripts/crew-codex-companion.mjs" task --json --expect-crew-result --model {model} --effort {reasoning} --prompt-file {promptFile}
-  ```
-  - `agent_runtime.planner.codex_sandbox`가 `workspace-write`인 경우에만 `--write` 추가 (Planner는 read-only).
-  - 첫 번째 실행 시 `spec.md` + `analysis.md`를 `{promptFile}`에 인라인 주입한다. retry 시 추가로 `review-{n}.md`를 주입한다.
-  - Planner는 plan.md 작성을 직접 수행해야 하나, codex provider는 `.crew/`에 쓰지 않으므로 `artifact`로 plan.md 본문 텍스트를 반환받아 오케스트레이터가 저장한다.
-
-**첫 번째 실행 시 에이전트 프롬프트**:
-
-```
-당신은 Planner 에이전트다. 구현 계획을 작성한다.
-
-## 입력
-.crew/plans/{task-id}/spec.md 를 읽어라.
-.crew/plans/{task-id}/analysis.md 를 읽어라.
-brief.md는 읽지 않는다.
-
-## 출력
-.crew/plans/{task-id}/plan.md 를 작성하라.
-
-plan.md 필수 구조: 유저 스토리(US-N) 단위. 각 유저 스토리에 구현 태스크 + 테스트 시나리오(최소 2개: 정상+에러). 위험 요소 섹션. 검증 시나리오 섹션(조건/행위/기대 결과 — contract.md에 그대로 포함됨). 실행 검증 섹션(필수 — contract.md에 그대로 포함됨).
-
-## 테스트 전략
-analysis.md의 `## 테스트 전략` 섹션을 확인하고, 결정에 따라 태스크 구조를 달리한다.
-
-### TDD인 경우
-- 인프라 셋업이 필요하면 첫 번째 태스크로 "테스트 인프라 셋업"을 추가한다.
-- 각 유저 스토리의 구현 태스크를 다음 순서로 구성한다:
-  1. RED — 실패하는 테스트 작성 (테스트 파일 경로 명시)
-  2. GREEN — 테스트를 통과하는 최소한의 코드 작성
-  3. REFACTOR — 코드 품질 개선 (필요시)
-- 각 태스크의 수용 기준에 포함: `테스트 파일: {경로}`, `테스트 실행 결과: PASS`
-
-### Tests-after인 경우
-- 인프라 셋업이 필요하면 첫 번째 태스크로 "테스트 인프라 셋업"을 추가한다.
-- 구현 태스크를 먼저 나열한 후, 별도의 테스트 작성 태스크를 추가한다.
-- 테스트 태스크의 수용 기준에 포함: `테스트 파일: {경로}`, `테스트 실행 결과: PASS`
-
-### None인 경우
-- 현재와 동일. 자동화 테스트 태스크 없이 검증 시나리오만 포함한다.
-
-plan.md 최상단에 `## 테스트 전략` 섹션을 두어 결정 사항을 명시한다.
-
-### 외부 인터페이스 가정 (외부 API/서비스가 관련된 경우 필수)
-analysis.md에 `## 외부 인터페이스 검증` 섹션이 있으면, plan.md에 `## 외부 인터페이스 가정` 섹션을 반드시 작성한다.
-각 외부 대상에 대해 가정하는 인터페이스와 검증 상태를 명시한다:
-
-| 대상 | 가정하는 인터페이스 | 근거 | 검증 상태 |
-|------|------------------|------|----------|
-| {대상 1} | {인터페이스 설명} | 공식 문서 확인 | 검증됨 |
-| {대상 2} | {대상 1과 동일} | 문서 없음, 유추 | 미검증 |
-
-**"미검증" 대상이 있으면**: 해당 대상에 대한 **스파이크 태스크**를 구현 태스크 앞에 배치한다.
-스파이크 태스크는 실제 API를 호출하여 인터페이스를 확인하고, 검증된 대상과의 차이점을 기록한다.
-차이가 발견되면 이후 구현 태스크의 접근 방식을 스파이크 결과에 따라 분기하도록 계획한다.
-
-### 실행 검증 (필수, 테스트 전략과 무관하게 항상 포함)
-유닛 테스트/자동화 테스트와 별개로, 구현된 기능을 실제로 실행하여 동작을 확인하는 절차를 `## 실행 검증` 섹션에 반드시 작성한다.
-- 백엔드/API: 실제 API 호출 명령어(curl/httpie), 스크립트 실행, DB 쿼리 등
-- UI/프론트엔드: 개발 서버 실행 후 브라우저에서 직접 조작하는 절차
-- CLI/라이브러리: 실제 사용 예시 실행
-"테스트 파일 실행"은 실행 검증이 아니다. 실제 기능을 사용자 관점에서 동작시키는 것이 실행 검증이다.
-각 실행 검증 항목은 다음 형식으로 작성한다:
-- 실행 방법: {구체적 명령어 또는 절차}
-- 기대 결과: {확인할 출력 또는 동작}
-
-## 규칙
+### Step 3 — Planner 실행
+
+중앙 `crew-agent-runner` 스킬의 dispatch 절차로 실행한다.
+
+role: planner
+
+inputs:
+- `.crew/plans/{task-id}/spec.md`
+- `.crew/plans/{task-id}/analysis.md`
+- retry 시 `.crew/plans/{task-id}/review-{n}.md`
+
+output:
+- complete.artifact → `.crew/plans/{task-id}/plan.md`
+
+role instructions:
+- 구현 계획을 유저 스토리(US-N) 단위로 작성한다.
+- brief.md는 입력으로 사용하지 않는다.
+- 각 유저 스토리에 구현 태스크와 테스트 시나리오를 포함한다. 테스트 시나리오는 최소 정상 1개와 에러 1개를 포함한다.
+- 위험 요소 섹션, 검증 시나리오 섹션, 실행 검증 섹션을 포함한다.
+- plan.md 최상단에 `## 테스트 전략` 섹션을 두고 analysis.md의 결정을 반영한다.
+- TDD인 경우 각 구현 태스크를 RED, GREEN, REFACTOR 순서로 구성하고 테스트 파일 경로와 테스트 실행 결과 기준을 명시한다.
+- Tests-after인 경우 구현 태스크 뒤에 별도 테스트 작성 태스크를 추가하고 테스트 파일 경로와 테스트 실행 결과 기준을 명시한다.
+- None인 경우 자동화 테스트 태스크 없이 검증 시나리오와 실행 검증을 유지한다.
+- 테스트 인프라 셋업이 필요하면 첫 번째 태스크로 테스트 인프라 셋업을 추가한다.
+- 외부 인터페이스 검증 섹션에 미검증 대상이 있으면 구현 태스크 앞에 스파이크 태스크를 배치한다.
+- 실행 검증은 사용자 관점에서 실제 기능을 동작시키는 절차여야 하며, 테스트 파일 실행만으로 대체하지 않는다.
+- retry 시 review-{n}.md의 FAIL 사유를 먼저 반영하고, 최상단에 이전 피드백 반영 섹션을 추가한다.
 - 코드를 작성하지 않는다.
 - analysis.md의 아키텍처 방향과 가드레일을 따른다.
-- spec.md에 정의된 비즈니스 규칙을 그대로 따른다. 임의로 비즈니스 결정을 추가하지 않는다.
-- 태스크 하나가 4시간 초과 시 분해한다.
-- "나중에 결정" 금지. 모르면 위험 요소에 기록.
-- 필요시 Explorer 서브에이전트를 호출할 수 있다.
-```
-
-**retry 시 에이전트 프롬프트**:
-
-```
-이번은 이전 계획이 리뷰에서 FAIL을 받은 후 재작성하는 것이다.
+- spec.md에 없는 비즈니스 결정을 추가하지 않는다.
+- 태스크 하나가 4시간을 초과하면 분해한다.
+- "나중에 결정"을 쓰지 않는다. 모르면 위험 요소에 기록한다.
 
-## 입력
-.crew/plans/{task-id}/spec.md 를 읽어라.
-.crew/plans/{task-id}/analysis.md 를 읽어라.
-.crew/plans/{task-id}/review-{n}.md 를 읽어라.
-brief.md는 읽지 않는다.
+success gate:
+- plan.md 산출물이 생성될 수 있는 complete.artifact가 있다.
+- 유저 스토리 단위 태스크 목록이 비어 있지 않다.
+- `## 테스트 전략`, 위험 요소, 검증 시나리오, 실행 검증 섹션이 있다.
+- 선택된 테스트 전략과 태스크 구조가 일치한다.
 
-## 필수 선행 작업
-review-{n}.md를 먼저 읽어라. 이전 plan이 왜 FAIL을 받았는지 확인하고, 지적된 항목을 명시적으로 수정하라.
-
-## 출력
-.crew/plans/{task-id}/plan.md 를 새로 작성하라.
-plan.md 최상단에 "이전 피드백 반영" 섹션을 추가한다.
-
-## 규칙
-- analysis.md의 아키텍처 방향과 가드레일을 따른다.
-- spec.md에 정의된 비즈니스 규칙을 그대로 따른다. 임의로 비즈니스 결정을 추가하지 않는다.
-- 피드백을 무시하거나 같은 내용으로 작성하지 않는다.
-```
-
-**실패 조건**: plan.md가 없거나 태스크 목록이 비어 있으면 즉시 에스컬레이션.
+failure handling:
+- plan 산출물이 없거나 태스크 목록이 비어 있으면 ESCALATE.
+- PlanEvaluator FAIL 이후에는 Step 6의 피드백 보존 루프를 따른다.
+- retry/escalate 규칙은 contract.policy에 따른다.
 
 ---
 
-### Step 4 — PlanEvaluator 에이전트 실행
-
-**provider/model**: Step 1a의 해석 테이블에서 `plan-evaluator`의 값을 사용한다. catalog default는 `agent_defaults.plan-evaluator`(claude/sonnet)이지만, user/project config가 우선한다.
-
-해석 테이블의 provider 값에 따라 분기 디스패치한다:
-
-- **claude**:
-  ```
-  Agent(subagent_type="plan-evaluator", model="{model}", description="PlanEvaluator: {task-id} 계획 검증", prompt="...")
-  ```
-- **codex**:
-  ```bash
-  node "${CLAUDE_PLUGIN_ROOT}/scripts/crew-codex-companion.mjs" task --json --expect-crew-result --model {model} --effort {reasoning} --prompt-file {promptFile}
-  ```
-  - PlanEvaluator는 read-only이므로 `--write`를 붙이지 않는다.
-  - `spec.md` + `analysis.md` + `plan.md`를 `{promptFile}`에 인라인 주입한다.
-  - 마지막 `<crew-agent-result>` 블록의 `artifact`를 추출하여 Step 4 결과 저장(`review.md`)에 사용한다.
-
-에이전트 프롬프트:
-
-```
-당신은 PlanEvaluator 에이전트다. 계획을 검증한다.
-
-## 입력
-.crew/plans/{task-id}/spec.md + .crew/plans/{task-id}/analysis.md + .crew/plans/{task-id}/plan.md
-이 파일만 읽는다. brief.md는 읽지 않는다.
-
-## 검증 항목 (하드 임계값)
-아래 각 항목에 YES 또는 NO로만 답한다. 부분 점수 없음.
-
-[ ] E1. 검증 시나리오 완성도 — 모든 태스크에 검증 방법이 명시되어 있는가?
-[ ] E2. spec 전체 커버리지 — spec.md의 수용 기준, 유저 플로우, UI 구조, 비즈니스 규칙이 전부 태스크로 커버되는가? (수용 기준만이 아니라 spec 전체를 검증)
-[ ] E3. 코드 참조 사실 여부 — 언급한 파일/모듈이 존재하는가? (Explorer 서브에이전트 호출)
-[ ] E4. 실행 가능성 — 구현자가 바로 시작할 수 있는 수준인가?
-[ ] E5. 테스트 전략 정합성 — analysis.md의 테스트 전략 결정과 plan.md의 태스크 구조가 일치하는가?
-  - TDD: 각 구현 태스크가 RED→GREEN→REFACTOR 순서로 구성되어 있는가? 테스트 파일 경로가 명시되어 있는가?
-  - 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로 처리한다.
-
-## 판정 규칙
-- 8개 항목 모두 YES → PASS
-- 하나라도 NO → FAIL
-- "아마 의도했을 것"이라고 추측하지 않는다. 모호하면 NO.
-
-## FAIL 시 근본 원인 분류 (필수)
-- spec 결함 (spec.md 자체가 문제) → 오케스트레이터에 알린다
-- plan 결함 (계획 구성/표현 문제) → Planner 재시도 가능
-
-## E3 코드 참조 확인
-Explorer 서브에이전트를 호출하여 plan.md에서 참조하는 파일/모듈이 존재하는지 확인하라.
-runAgent(role="explorer", description="코드 참조 확인: {파일 목록 요약}", prompt="plan.md에서 참조하는 다음 파일/모듈이 존재하는지 확인하라: {파일 목록}")
-
-## 출력
-아래 형식으로 검증 결과를 텍스트로 반환하라. 파일을 직접 작성하지 않는다.
-형식: 판정(PASS/FAIL), 항목별 결과(E1-E8 YES/NO + 근거), FAIL 상세(NO 항목의 문제+수정 방향), 근본 원인 분류(FAIL 시).
-```
-
-**Step 4 결과 저장 (오케스트레이터 직접)**:
-
-PlanEvaluator 에이전트는 read-only이므로 파일을 직접 작성하지 않는다.
-오케스트레이터가 PlanEvaluator의 반환 텍스트를 `.crew/plans/{task-id}/review.md`로 저장한다.
+### Step 4 — PlanEvaluator 실행
+
+중앙 `crew-agent-runner` 스킬의 dispatch 절차로 실행한다.
+
+role: plan-evaluator
+
+inputs:
+- `.crew/plans/{task-id}/spec.md`
+- `.crew/plans/{task-id}/analysis.md`
+- `.crew/plans/{task-id}/plan.md`
+
+output:
+- complete.artifact → `.crew/plans/{task-id}/review.md`
+
+role instructions:
+- 계획을 검증하고 PASS 또는 FAIL을 판정한다.
+- brief.md는 입력으로 사용하지 않는다.
+- 아래 8개 항목을 YES 또는 NO로만 판정한다. 부분 점수는 없다.
+- E1. 검증 시나리오 완성도: 모든 태스크에 검증 방법이 명시되어 있는가?
+- E2. spec 전체 커버리지: spec.md의 수용 기준, 유저 플로우, UI 구조, 비즈니스 규칙이 전부 태스크로 커버되는가?
+- E3. 코드 참조 사실 여부: 언급한 파일/모듈이 존재하는가?
+- E4. 실행 가능성: 구현자가 바로 시작할 수 있는 수준인가?
+- E5. 테스트 전략 정합성: analysis.md의 테스트 전략 결정과 plan.md의 태스크 구조가 일치하는가?
+- E6. 비즈니스 가정 0개: plan.md가 spec.md에 없는 비즈니스 로직을 임의로 추가하지 않았는가?
+- E7. 실행 검증 포함: 실제 기능을 사용자 관점에서 동작시키는 구체 절차가 있는가?
+- E8. 외부 인터페이스 가정 검증: 미검증 외부 대상에 대한 검증 상태와 스파이크 태스크가 있는가?
+- 8개 항목 모두 YES이면 PASS, 하나라도 NO이면 FAIL이다.
+- 모호하면 NO로 판정한다.
+- FAIL 시 근본 원인을 spec 결함 또는 plan 결함으로 분류한다.
+- 출력 형식: 판정(PASS/FAIL), 항목별 결과(E1-E8 YES/NO + 근거), FAIL 상세, 근본 원인 분류(FAIL 시).
+
+success gate:
+- review.md 산출물이 생성될 수 있는 complete.artifact가 있다.
+- 판정이 PASS 또는 FAIL로 명시된다.
+- E1-E8의 YES/NO와 근거가 모두 포함된다.
+- FAIL이면 근본 원인 분류가 포함된다.
+
+failure handling:
+- review 산출물이 없거나 판정이 없으면 ESCALATE.
+- FAIL이면 Step 6의 피드백 보존 루프를 따른다.
+- retry/escalate 규칙은 contract.policy에 따른다.
 
 ---
 
 ### Step 5 — PASS 처리
 
-PlanEvaluator PASS이면:
-
-**5a. review.md 확인**
-
-review.md가 정상적으로 작성되었고 판정이 PASS임을 확인한다.
-
-**5b. contract.md 작성 (오케스트레이터 직접)**
-
-```markdown
-# 스프린트 계약: {task-id}
-
-생성일: {date}
-
-## 목표
-{spec.md에서 추출한 한 문장}
-
-## 수용 기준
-- [ ] {spec.md의 수용 기준을 그대로 복사}
-
-## 유저 플로우
-{spec.md의 유저 플로우 섹션이 있으면 그대로 복사}
+role: orchestrator
 
-## UI 구조 및 주요 콘텐츠
-{spec.md의 UI 구조 섹션이 있으면 그대로 복사}
+inputs:
+- `.crew/plans/{task-id}/spec.md`
+- `.crew/plans/{task-id}/analysis.md`
+- `.crew/plans/{task-id}/plan.md`
+- `.crew/plans/{task-id}/review.md`
 
-## 비즈니스 규칙
-{spec.md의 비즈니스 규칙 섹션이 있으면 그대로 복사}
+output:
+- contract artifact → `.crew/plans/{task-id}/contract.md`
+- COMPLETE response
 
-## 가드레일
-### Must
-- {analysis.md에서 추출}
+role instructions:
+- review.md의 판정이 PASS인지 확인한다.
+- contract.md에는 목표, 수용 기준, 유저 플로우, UI 구조 및 주요 콘텐츠, 비즈니스 규칙, 가드레일, 테스트 전략, 검증 시나리오, 실행 검증, 참조 문서, 검증 이력, 워크트리, 상태를 포함한다.
+- 목표와 수용 기준은 spec.md의 내용을 기준으로 한다.
+- 가드레일은 analysis.md의 Must/Must NOT을 기준으로 한다.
+- 검증 시나리오와 실행 검증은 plan.md의 해당 섹션을 기준으로 한다.
+- 상태는 ACTIVE로 둔다.
+- `.loop_count`가 있으면 정리한다.
 
-### Must NOT
-- {analysis.md에서 추출}
+success gate:
+- review.md 판정이 PASS다.
+- contract.md 산출물이 생성된다.
+- contract.md 상태가 ACTIVE다.
 
-## 테스트 전략
-- 결정: {TDD | Tests-after | None}
-- 프레임워크: {프레임워크명}
-- 인프라 셋업 필요: {YES | NO}
+failure handling:
+- PASS 확인 또는 contract 생성에 실패하면 ESCALATE.
+- retry/escalate 규칙은 contract.policy에 따른다.
 
-## 검증 시나리오
-{plan.md의 검증 시나리오 섹션을 그대로 복사}
+완료 반환:
 
-### {시나리오 1 제목}
-- 조건: {사전 상태}
-- 행위: {실행할 것}
-- 기대 결과: {검증할 것}
-
-## 실행 검증
-{plan.md의 실행 검증 섹션을 그대로 복사}
-
-### {검증 1 제목}
-- 실행 방법: {구체적 명령어 또는 절차}
-- 기대 결과: {확인할 출력 또는 동작}
-
-## 참조 문서
-- 요구사항: .crew/plans/{task-id}/spec.md
-- 사전 분석: .crew/plans/{task-id}/analysis.md
-- 구현 계획: .crew/plans/{task-id}/plan.md
-
-## 검증 이력
-PlanEvaluator PASS — review.md 참조
-
-## 워크트리
-mode: new
-
-## 상태
-ACTIVE
-```
-
-**5c. .loop_count 정리**
-
-`.loop_count` 파일이 존재하면 삭제한다.
-
-**5d. 완료 반환**
-
-```
-상태: COMPLETE
-task-id: {task-id}
-contract.md 경로: .crew/plans/{task-id}/contract.md
+```json
+{
+  "status": "COMPLETE",
+  "task_id": "{task-id}",
+  "contract_path": ".crew/plans/{task-id}/contract.md"
+}
 ```
 
 ---
 
-### Step 6 — FAIL 처리 (피드백 보존 루프)
-
-PlanEvaluator FAIL이면:
-
-**6a. FAIL 원인 분류**
-
-PlanEvaluator가 review.md에 기록한 근본 원인 분류를 확인한다.
-
-- **spec 결함** (spec.md 자체가 문제):
-  - Planner를 재시도해도 고칠 수 없다.
-  - 즉시 에스컬레이션:
-
-```
-PlanEvaluator가 spec 결함을 이유로 FAIL을 냈습니다.
-Planner 재시도로는 해결할 수 없습니다.
-[1] crew-interview를 재실행하여 spec.md를 재작성
-[2] spec.md를 직접 수정
-[3] 이 태스크를 보류
-```
-
-- **plan 결함** (계획 구성/표현 문제):
-  - 피드백 보존 루프를 진행한다.
-
-**6b. 루프 카운터 읽기**
-
-`.crew/plans/{task-id}/.loop_count` 파일을 읽는다.
-- 파일이 없으면 카운터 = 0 (첫 번째 FAIL)
-- 파일이 있으면 파일 내용(정수)이 카운터 값
-
-**6c. 에스컬레이션 판단**
-
-카운터 값 >= 4이면 즉시 에스컬레이션:
-
-```
-계획 파이프라인이 5회 반복 후에도 수렴하지 않았습니다.
-현재 review.md의 FAIL 사유를 첨부합니다.
-[1] 스코프를 좁혀서 재시도
-[2] 수용 기준을 직접 수정
-[3] 이 태스크를 보류
-```
-
-에스컬레이션 시 `.loop_count` 파일을 삭제한다.
-
-**6d. 피드백 아카이브**
-
-`n = 카운터 + 1` (이번 회차 번호)
-
-```
-plan.md → plan-{n}.md 로 이름 변경
-review.md → review-{n}.md 로 이름 변경
-```
-
-**6e. 루프 카운터 증가 저장**
-
-`카운터 + 1`을 `.loop_count` 파일에 저장한다.
-
-**6f. Step 3로 돌아감 (retry)**
-
-Step 3(Planner)로 돌아간다. retry 프롬프트의 `{n}`에 Step 6d에서 계산한 값을 대입한다.
-TechLead는 재실행하지 않는다 — 기술적 사실은 변하지 않으므로 analysis.md를 재사용한다.
+### Step 6 — FAIL 처리
+
+role: orchestrator
+
+inputs:
+- `.crew/plans/{task-id}/plan.md`
+- `.crew/plans/{task-id}/review.md`
+- `.crew/plans/{task-id}/.loop_count`
+
+output:
+- archived feedback → `.crew/plans/{task-id}/plan-{n}.md`, `.crew/plans/{task-id}/review-{n}.md`
+- updated loop counter → `.crew/plans/{task-id}/.loop_count`
+- retry route → Step 3
+- 또는 ESCALATE response
+
+role instructions:
+- PlanEvaluator가 기록한 근본 원인 분류를 확인한다.
+- spec 결함이면 Planner 재시도로 해결할 수 없으므로 즉시 에스컬레이션한다.
+- plan 결함이면 피드백 보존 루프를 진행한다.
+- 루프 카운터가 없으면 0으로 본다.
+- 루프 카운터가 4 이상이면 5회 반복 후 미수렴으로 에스컬레이션하고 카운터를 정리한다.
+- 이번 회차 번호 n은 카운터 + 1이다.
+- 현재 plan.md와 review.md를 각각 plan-{n}.md, review-{n}.md로 보존한다.
+- 카운터를 n으로 갱신한다.
+- TechLead는 재실행하지 않고 Step 3 retry로 돌아간다.
+
+success gate:
+- spec 결함이면 ESCALATE가 반환된다.
+- plan 결함이고 카운터가 4 미만이면 실패 계획과 리뷰가 보존된다.
+- retry에 사용할 review-{n}.md가 존재한다.
+
+failure handling:
+- 아카이브 또는 카운터 갱신에 실패하면 ESCALATE.
+- retry/escalate 규칙은 contract.policy에 따른다.
 
 ---
 
@@ -542,38 +326,18 @@ Planner + PlanEvaluator 사이클은 최대 5회 (초기 1회 + retry 최대 4
 
 ---
 
-## 에이전트 호출 컨텍스트 규칙
-
-본 메타 규칙은 Step 1a의 해석 결과를 기준으로 적용한다. 본 문서의 `runAgent(role, prompt, providerConfig)` 표기는 의사코드이며, 실제 호출은 항상 Step 1a의 해석 테이블에서 해당 role의 provider를 확인한 뒤 아래 분기 규칙에 따라 `Agent` 또는 `Bash`로 직접 디스패치한다.
-
-- Claude provider: `Agent(subagent_type="{role}", model="{model}", description="...", prompt="...")`
-- Codex provider: `node "${CLAUDE_PLUGIN_ROOT}/scripts/crew-codex-companion.mjs" task --json --expect-crew-result --model {model} --effort {reasoning} --prompt-file {promptFile}`
-- `data/provider-catalog.json`의 `agent_runtime.{role}.codex_sandbox`가 `workspace-write`일 때만 `--write`를 붙인다. plan 단계 에이전트는 모두 read-only다.
-- Codex provider는 `.crew/` 파일을 직접 읽거나 쓰지 않는다. 필요한 `spec.md`, `analysis.md`, `plan.md`, `review-{n}.md` 내용은 오케스트레이터가 프롬프트에 인라인 주입한다.
+## 에이전트 실행 컨텍스트 규칙
 
-| 에이전트 | subagent_type | 기본 provider/model | 주입할 파일 | 차단할 파일 |
-|----------|--------------|------|------------|------------|
-| TechLead | techlead | `agent_defaults.techlead` | spec.md | — |
-| Planner (첫 번째) | planner | `agent_defaults.planner` | spec.md + analysis.md | brief.md |
-| Planner (retry) | planner | `agent_defaults.planner` | spec.md + analysis.md + review-{n}.md | brief.md |
-| PlanEvaluator | plan-evaluator | `agent_defaults.plan-evaluator` | spec.md + analysis.md + plan.md | brief.md |
+중앙 `crew-agent-runner` 스킬의 dispatch 절차를 단일 실행 경로로 사용한다. crew-plan은 실행 방식, 런타임 선택, 후속 요청 처리, 사용자 질문 처리의 세부 절차를 정의하지 않는다.
 
-**중요**: provider/model은 `.crew/config.json`, `~/.claude/crew/config.json`, `data/provider-catalog.json`의 `agent_defaults` 순서로 해석한다. Claude provider는 `Agent(subagent_type=..., model=...)`로 호출하고, Codex provider는 `scripts/crew-codex-companion.mjs task`로 호출한다.
-
-Codex provider 결과는 마지막 `<crew-agent-result>` 블록으로 파싱한다.
-
-```json
-{
-  "status": "complete | blocked_on_user | needs_agent | needs_tool | failed",
-  "artifact": "최종 산출물 또는 결과",
-  "questions": [],
-  "requests": [],
-  "summary": "짧은 요약",
-  "error": null
-}
-```
+| 단계 | role | 입력 | 차단할 입력 | 기대 산출물 |
+|------|------|------|-------------|-------------|
+| Step 2 | techlead | spec.md | — | analysis.md |
+| Step 3 | planner | spec.md + analysis.md | brief.md | plan.md |
+| Step 3 retry | planner | spec.md + analysis.md + review-{n}.md | brief.md | plan.md |
+| Step 4 | plan-evaluator | spec.md + analysis.md + plan.md | brief.md | review.md |
 
-`blocked_on_user`는 오케스트레이터가 `AskUserQuestion`으로 처리한다. `needs_agent`는 Explorer/Researcher 등 요청된 role을 `runAgent`로 실행한 뒤 결과를 원래 에이전트에 `--resume-last`로 주입한다. 한 에이전트 실행의 후속 루프는 최대 5회다.
+후속 탐색, 외부 조사, 사용자 질문, 재개 흐름은 runner가 정의한 상태 처리와 followup 계약을 따른다. 각 역할은 complete 상태의 artifact로 산출물 본문을 반환해야 한다.
 
 ---
 
@@ -592,7 +356,7 @@ Codex provider 결과는 마지막 `<crew-agent-result>` 블록으로 파싱한
 ```json
 {
   "status": "ESCALATE",
-  "phase": "spec-gate" | "techlead-fail" | "planner-fail" | "evaluator-spec-defect" | "loop-overflow",
+  "phase": "spec-gate | techlead-fail | planner-fail | evaluator-spec-defect | loop-overflow",
   "reason": "자유형 텍스트"
 }
 ```