Spec Ops Pipeline (Lead-Worker)은(는) 무엇을 하나요?

SKILL_DIR = 이 파일이 포함된 디렉터리.

역할 경계 (변경 불가)

역할	허용됨	금지됨
Lead (당신)	코드 읽기/검색, 테스트/린터/빌드 실행, 명세서 작성, 리뷰 및 실행 상태(런 디렉터리 내) 기록, `worktree.sh`를 통한 워크트리 관리, 사용자의 명시적 동의 후 `migrate_to_bare.sh --apply` 실행, 체크포인트 승인 후 `sop/*` 브랜치에 승인된 작업 커밋(단계적: 단계 간에도) 및 `pr.sh open` / `pr.sh merge` 실행(`auto_merge_risk`에 따라 병합), `auto_cleanup`(또는 사용자 동의)에 따라 병합된 PR 후 정리	모든 애플리케이션 파일 편집, 생성, 삭제 또는 이동 — 메인 체크아웃 또는 Worker 워크트리에서(유일한 예외: `migrate_to_bare.sh --apply` 및 `worktree.sh sync`의 fast-forward), 수동으로 병합 충돌 해결, APPROVE되지 않은 작업 병합, `--admin` 사용 또는 브랜치 보호 우회
Worker (하위 에이전트)	완료 조건이 통과될 때까지 워크트리 내의 허용 목록 파일 편집	허용 목록 외 파일 접근, 커밋/푸시, 워크트리 외부 작업

"그냥 고치고 싶다"고? 명세서를 작성하세요.

모델 할당

Preflight runtime은 역할별 모델을 제공합니다(lead = 1단계, lead_phase2, worker, worker_light, scout). Reviewer는 lead에서 실행됩니다. 역할, 기본값, 재정의, 계층: models.md. 현재 단계의 Lead 모델이 아니라면, 사용자에게 전환 방법을 알리십시오(Claude Code의 /model, /effort). single 실행은 1단계 Lead 모델을 유지하므로 묵시적으로 계속 진행하지 마십시오.

세션 및 컨텍스트

1단계: 1단계 Lead 모델에서 0–2단계.
2단계: 3–6단계. split: 새 세션에서 2단계 Lead 모델로 재개하며, 계획, 상태 및 현재 단계의 명세서(자체 포함)만 읽습니다. single: 동일한 세션에서 계속.

session_split (환경 변수 SOP_SESSION_SPLIT): auto (기본값) = H-risk 작업, 세 개 이상의 작업 또는 staged 모드의 경우 split, 그 외 single; always → split; never → single.

체크포인트가 이를 표시합니다. 사용자가 재정의할 수 있습니다.

런 상태는 런 디렉터리(run.run_dir, <git common dir>/sop-run/)에 저장됩니다: 모든 워크트리 외부, 모든 워크트리에서 공유, 세션 간 유지. 세션 스크래치패드를 사용하지 마십시오.

명령 출력 — 모든 린트/테스트/빌드/완료 조건 명령을 bash SKILL_DIR/scripts/run_logged.sh <run dir>/logs/<slug>-<step>-<n>.log '<command>'를 통해 실행합니다(출력: exit=<rc> lines=<n> log=<path> + 실패 시 마지막 40줄). 꼬리가 실패를 설명하지 못하는 경우에만 로그를 더 읽으십시오. 전체 테스트 출력을 채팅에 넣지 마십시오.

워크플로

0. Preflight

bash SKILL_DIR/scripts/preflight.sh --agent <claude|gemini|codex> --fetch(자신의 런타임; --fetch는 먼저 원격 default_base를 업데이트함)는 하나의 JSON 줄을 출력합니다: runtime (worker, session_split 참고), config (source_worktree, default_base, provision, max_parallel, auto_merge_risk, merge_method, auto_cleanup 참고; 레이아웃), leftovers, run, pr, baseline, base_check, docker_pool. 베어 레이아웃에서는 source_worktree 내에서 Lead git/테스트 명령을 실행합니다. 다음에 대해 조치:

run.has_state: true (진행 중인 런): 사용자에게 재개할지, 정리할지(모든 작업에 사용자를 기다리는 PR이 있는 경우), 아니면 보관(worktree.sh rundir --archive)하고 새로 시작할지 물어봅니다.
leftovers (이전 런의 작업): 언급합니다.
config.offer_bare_migration: true: bash SKILL_DIR/scripts/migrate_to_bare.sh (dry run) 실행, 사용자에게 베어 리포지토리 워크트리 레이아웃으로 변환할지 물어보고, bare-layout.md 형식으로 표시합니다. 명시적 동의 시에만: migrate_to_bare.sh --apply, preflight.sh 재실행, 새 source_worktree에서 에이전트 문서 다시 읽기. 거부 또는 거절 → 표준 레이아웃.
pr.ok: false: 런은 로컬에서만 커밋합니다. 체크포인트가 이를 표시합니다. pr.into 참고. 병합 규칙: execution-plan.md.
base_check.match: false, fetch_error 또는 error: 사용자와 먼저 베이스에 동의합니다.
docker_pool.error: 사용자에게 용량을 알 수 없다고 알립니다. 그 외 docker: false: 건너뜀. 그 외 free < config.max_parallel: 경고(3단계에서 다시 확인).
baseline = git status --porcelain=v1 && git diff HEAD | sha256sum의 출력, 이미 source_worktree에서 실행됨. state.json에 보관합니다.

1. 감사 (읽기 전용)

사용자와 범위 설정(경로; 보안/성능/부채/명세서 격차).
정적으로 스캔합니다. 넓은 범위의 경우 병렬 읽기 전용 정찰(scout)으로 먼저 스위핑하고(scout.md) 그들의 리드를 확인합니다. 프로젝트의 기존 린트/테스트/타입 검사 명령을 run_logged.sh를 통해 실행하여 실측 자료를 얻습니다(로그 audit-<n>.log). 도구를 설치하거나 구성을 변경하지 마십시오.
갭 리포트 생성: file:line, 심각도, 증거, 제안된 수정 사항이 포함된 번호 매기기 결과. Worker 크기의 작업으로 그룹화하고 작고 겹치지 않는 허용 목록을 작성합니다.
여러 작업의 경우, execution-plan.md에 따라 실행 계획 초안 작성: 의존성 없음 → independent (모두 병렬); 관련 있음 → staged (의존성 순서 단계, 단계 내 병렬, 각 단계는 이전 단계의 통합 결과를 기반으로 구축).

2. 명세서 (체크포인트)

각 작업에 대해 worker-spec-template.md를 채우고 Worker 계층을 선택합니다(models.md). 에이전트 문서(AGENTS.md, CLAUDE.md, 허용 목록이 닿는 디렉터리에도 있음)에서 Repo 규칙을 채웁니다: 테스트/린트 명령, 플래그, 언어 규칙. 기억 및 worker_notes에서 리포지토리 문제점을 추가합니다. Worker는 당신의 컨텍스트를 볼 수 없습니다. 완료 조건 명령을 해당 규칙에 따라 작성합니다.
런 디렉터리(절대 워크트리가 아님)에 저장: gap-report.md, plan.md, spec-<slug>.md, <slug>.wl.
단계별 중복 검사: bash SKILL_DIR/scripts/check_scope.sh --overlap <source_worktree> <slug>.wl...; OVERLAP → 다시 분할 또는 재단계; 각 POSSIBLE을 직접 확인.
완료 조건 dry run: independent / 1단계 작업의 각 완료 조건 명령을 source_worktree에서 run_logged.sh를 통해 실행(로그 <slug>-dry-<n>.log), 명세서에서 해당 클래스 기록, BROKEN 수정(세부사항); 2단계 이상은 3단계에서.
계획 비평가: 2개 이상의 작업, staged 모드, H-risk 작업 또는 요청 시: 읽기 전용 비평가(작업이 H-risk인 경우에만 lead 모델, 그 외 lead_phase2); 각 결과를 plan-critic.md에 따라 결정. 한 라운드.
체크포인트 보고서를 표시하고 3단계 전 승인 대기, execution-plan.md §3 형식. 승인은 명시적으로 다음을 포함해야 함: staged 모드의 단계 간 로컬 커밋 및 병합; 항상 APPROVE 후 자동 커밋, 푸시, PR 및 병합 열에 따른 병합; auto_cleanup 포함 시 각 병합 후 정리; Docker 풀 라인에 prune: ask가 있을 때 worktree.sh pool --prune. §3의 표현.
단계 경계: 승인 후 <run dir>/state.json (§7)에 phase: 2 및 합의된 session을 기록, 그런 다음:
- split: 사용자에게 다음을 알림:
  
  계획이 승인되어 <run dir>에 저장되었습니다. /clear를 실행하고, 2단계 Lead로 전환(/model <lead_phase2.model>, /effort <lead_phase2.effort>)한 후, resume으로 이 스킬을 호출하세요.
  
  (Codex / Antigravity: lead_phase2에서 새 세션 시작.)
- single: 사용자에게 계획이 <run dir>에 저장되었으며 여기서 계속된다고 알리고, 모델 전환 없이 3단계로 이동(여전히 resume 가능).

재개 (2단계)

resume 시: entrypoints.md.

정리 (사용자가 병합한 후)

cleanup 시: entrypoints.md.

3-5단계는 단계당 한 번 실행(independent = 단일 단계), 계획 순서대로. state.json을 최신 상태로 유지: 작업 상태를 파견 시, 각 리뷰 라운드, 승인 또는 연기 시, 그리고 단계 통합 시 업데이트.

3. 워크트리 + 파견

단계의 워크트리를 생성하기 전: bash SKILL_DIR/scripts/worktree.sh pool. docker: false → 건너뜀; error → 사용자에게 알리고, 먼저 물어봄. 그 외 free < 해당 단계의 작업 수이면, 승인에 포함된 경우에만 worktree.sh pool --prune 실행(모든 프로젝트의 사용되지 않는 Compose 네트워크를 제거하며, 재생성됨), 그렇지 않으면 사용자에게 물어봄.
각 작업에 대해: bash SKILL_DIR/scripts/worktree.sh create <slug> [--base <ref>] (1단계: --base 생략; 2단계+: --base sop-stage/<n-1>; worktree.sh path <slug> 미리보기). 출력에서 provisioned 확인; 예상 항목이 누락되면 중지. 2단계+: 파견 전에 각 작업의 완료 조건을 새 워크트리에서 run_logged.sh를 통해 dry run(경로/플래그 수정만; 그 외 물어봄).
각 명세서에 워크트리 경로와 베이스를 삽입한 후, 단계의 모든 Worker를 병렬로 파견(dispatch.md 참조), 각각 worker_tier(worker / worker_light) 모델 사용(max_parallel 제한).

4. 게이트 (작업별)

bash SKILL_DIR/scripts/check_scope.sh <worktree> <whitelist-file>이 0으로 종료되어야 함; 위반 시 Worker가 되돌림(리뷰 라운드 1회로 간주).
각 완료 조건 명령을 직접 워크트리에서 run_logged.sh를 통해 다시 실행(로그 <slug>-gate-r<round>-<n>.log); 모두 0으로 종료되어야 함.

5. 리뷰 (작업별) + 단계 장벽

review-checklist.md를 따름: diff는 lead 모델에서 검토됨(split: 읽기 전용 Reviewer 하위 에이전트, 당신이 그 결과를 확인; single: 당신) 기록된 베이스를 기준으로. 번호가 매겨진 file:line 결과와 함께 APPROVE 또는 REQUEST_CHANGES 발행; Worker와 최대 3라운드 반복한 후 사용자에게 에스컬레이션. 작업은 독립적으로 반복. light 작업이 1라운드 실패 시 worker 모델로 재파견(models.md).

independent: APPROVE 시, 커밋, 푸시, pr.sh로 PR 열기 및 자동 병합 규칙이 허용할 때 질문 없이 병합(§4a).
staged: 단계의 모든 작업이 APPROVED되면, 각각 로컬 커밋, worktree.sh integrate <n> --base <stage base> sop/<slug>... 실행, 다음 단계 전에 통합 게이트 통과(단계 워크트리에서 해당 단계의 모든 완료 조건); 충돌, 통합 실패 및 에스컬레이션: execution-plan.md. 더 진행할 단계가 있으면, state.json에서 current_stage를 다음으로 설정하고 동일 세션에서 계속. 컨텍스트가 너무 커진 경우에만 새 세션(/clear 후 resume) 제공(두 단계 실행 또는 많은 리뷰 라운드); 여기서는 안전함.

6. 종료

0단계 기준 명령을 다시 실행; 일치해야 하며, 그렇지 않으면 메인 체크아웃에서 정확히 무엇이 변경되었는지 보고 — 직접 "수정"하지 마십시오.
PR: independent PR은 이미 존재함(§5); 각각 merged, open(이유) 또는 local only로 나열. staged: 마지막 sop-stage/<n>에서 pr.sh로 단일 PR 열기(auto_merge_risk에 따라 병합, §6).
병합된 PR의 워크트리 및 브랜치 정리, worktree.sh sync, 그리고 모든 작업이 정리되면 worktree.sh rundir --archive. 승인에 auto_cleanup이 있는 경우에만 질문 없음, 그 외 먼저 물어봄. 절대 --force 사용하지 않음.
최종 요약: 해결된 결과, 연기된 결과(및 차단된 종속 항목), 상태가 포함된 브랜치/PR, 정리된 항목 및 남은 항목. 사용자를 기다리는 PR이 있으면, 병합 후 이 스킬을 cleanup으로 호출하라는 메시지로 종료.

스크립트 및 레이아웃

사용법, 종료 코드, 워크트리 경로, 프로비저닝, 구성 재정의: scripts-and-layout.md.

Spec Ops Pipeline (Lead-Worker)