orchestrate

name	orchestrate
description	완성된 설계·운영자 결정을 받아 워커 스폰부터 완료 검증까지 전체 루프를 끝까지 구동할 때 사용. spawn-worker(스폰 기계학) 위층의 진입점 스킬 — 입력 확인·기록·worktree·브리프·스폰·착지검증·완료검증·회수를 순서대로 수행한다. 트리거 - "이 설계/계획을 워커로 진행해줘", "orchestrate로 진행", "워커 굴려서 끝까지 가줘".

orchestrate — 설계→워커 실행 전체 루프 진입점

ROB-NNN 은 비공개 이슈 트래커 참조이며, 각 규칙 옆 본문이 근거를 자립 설명한다.

🔴 도메인 오버레이: $AGENT_SKILLS_DOMAIN/orchestrate.md 가 존재하면 이 스킬을 적용하기 전에 반드시 먼저 읽어라. 없으면 아래 추상 규칙만 적용한다.

원칙: 이 스킬은 스폰 기계학이 아니다. spawn-worker가 "어떻게 띄우나"를 정의한다면, orchestrate는 "완성된 설계 + 운영자 결정이 있을 때 그 위층에서 루프 전체를 순서대로 구동하는 절차"다. §4(스폰)는 spawn-worker를 그대로 호출하고, 이 스킬 고유의 부가가치는 §0(입력 확인)·§1(기록)·§5(완료 검증)·§6(회수·기록)에 있다.

§0. 입력 확인 — 비면 추측하지 말고 물어라

아래 4가지가 갖춰지지 않은 채로 시작하지 않는다. 빠진 항목은 운영자에게 되묻는다 — 빈칸을 스스로 채우고 진행하면 나중에 재작업으로 돌아온다(§6 근거 절 참조).

1. 설계/계획 본문 — 보통 오케스트레이터 자신이 이미 작성한 상태다. 없으면 먼저 설계부터 완성시키고(이 스킬의 범위 밖), 그 다음에 진입한다.
2. 운영자 결정 — 워커 범위의 in/out, 그리고 되돌릴 수 없는 동작 변화가 있다면 그에 대한 명시적 승인. "대충 진행해도 될 것 같다"는 승인이 아니다 — 승인 대상을 구체적으로 짚어서 확인한다.
3. 브랜치 전략 — 통합(feature) 브랜치로 여러 워커·여러 PR을 모을지, 기준 브랜치로 바로 향할지. 실험적이거나 다PR이 예상되면 통합 브랜치, 단발 픽스면 기준 브랜치 직행. 이 결정이 없으면 워커마다 제각각의 base를 잡아 나중에 합치기가 어려워진다.
4. 검증 급소 — "무엇이 통과하면 진짜 고쳐진 것인가"를 미리 정의한다. 가능하면 수정 전 코드에서 실패하는 테스트 형태로 잡아라 — 수정 후 통과만 확인하면 애초에 아무것도 검증하지 않는 테스트였을 위험을 배제하지 못한다.

§1. 기록 먼저

실행에 들어가기 전에 트래커(이 기기의 CLAUDE.md 상시 규칙을 따른다)에 설계와 §0의 운영자 결정을 기록한다. 워커 브리프에는 그 기록의 링크만 넣는다 — 설계 전문을 브리프에 복붙하지 않는다(브리프와 트래커가 따로 놀면 어느 쪽이 정본인지 불명확해진다).

§2. worktree

워커 1명 = worktree 1개. 공유하지 않는다(동시 커밋 충돌·서로의 변경을 지우는 사고로 이어진다). 브랜치는 §0-③에서 정한 전략을 그대로 따른다. 브리프의 완료 정의에는 PR base를 명시한다 — 명시가 없으면 워커가 기본 브랜치로 PR을 잡아버리는 사고를 막지 못한다.

§3. 브리프

형식은 spawn-worker의 브리프 작성 절차를 그대로 따르되, 다음을 반드시 지킨다:

• 수용조건은 지시와 1:1 대응. 브리프에 적은 지시 하나하나에 대응하는 수용조건이 있어야 한다. 대응이 없는 지시는 아무도 확인하지 않으므로 없는 것과 같다.
• 각 수용조건은 실제 출력 원문을 요구한다. "통과함", "확인함" 같은 서술은 수용조건이 아니다 — 명령과 그 출력을 그대로 붙이게 한다.
• §0-④에서 정한 검증 급소를 수용조건으로 명시한다. 검증 급소가 브리프 어딘가의 산문으로만 존재하면 워커가 놓친다.
• 완료 정의 = PR까지다. 머지는 금지. 완료 보고에는 push한 SHA를 포함시키고, 오케스트레이터는 git ls-remote로 그 SHA가 실재하는지 대조한다.
• 배포·운영 몫은 분리 기재. "배포 후 확인해야 할 것"은 워커의 완료 조건에 넣지 않고 별도 항목("배포 후 확인")으로 분리한다 — 섞으면 워커가 배포 권한이 없는데도 배포를 시도하거나, 반대로 배포 후 확인이 통째로 누락된다.

§4. 스폰

spawn-worker 스킬의 절차를 그대로 호출한다. 이 스킬은 스폰 기계학을 재정의하지 않는다 — 아래는 이 진입점에서 특히 놓치기 쉬운 항목만 반복해 강조한다.

• 급/프로필은 scopefuel --recommend <급> 순위를 따른다.
• -w는 workspace id를 쓴다 — 신규 기기는 workspace name이 안 잡힐 수 있으므로 herdr pane list로 확인하고 넘긴다.
• wrk spawn ... --owner <자기 세션 이름>을 항상 붙인다(누락 시 회수 조회 불가 — spawn-worker §4 근거 참조).

🔴 착지 검증 필수. 스폰 명령이 정상 반환됐다고 해서 워커가 브리프를 실제로 받은 것은 아니다. 스폰 직후 herdr agent read <pane> --lines 10 --source visible로 브리프 텍스트가 화면에 실제로 보이는지 확인한다. 보이지 않으면(미착지) 재주입 후 다시 확인한다.

wrk의 OK status=done도, herdr의 정상 JSON 응답도 둘 다 착지 증거가 아니다. 둘 다 "명령이 오류 없이 끝났다"는 뜻이지 "워커가 브리프를 화면에서 봤다"는 뜻이 아니다. 착지 확인은 화면 텍스트 대조로만 성립한다.

§5. 완료 검증

워커의 자기보고는 증거가 아니다. 워커가 "완료했다"고 보고해도 오케스트레이터가 직접 산출물을 재확인하기 전에는 완료로 취급하지 않는다.

• 산출물(커밋·테스트 출력)을 오케스트레이터가 직접 재실행해서 확인한다. 워커가 붙인 출력 로그를 그대로 믿지 않는다.
• git ls-remote로 워커가 보고한 SHA가 원격에 실재하는지 대조한다.
• 검증자는 구현과 다른 family(다른 세션·다른 모델 계열)를 쓴다. 검증 급은 구현 급 이상으로 배정한다. 스폰 절차는 §4와 동일하게 spawn-worker를 따른다.
• 검증자 브리프의 중심 질문은 §0-④에서 정한 검증 급소 그대로다 — 검증자가 임의로 다른 기준을 세우지 않도록, 무엇을 확인해야 "진짜 고쳐진 것"인지 브리프에 그대로 넘긴다.

§6. 회수·기록

• job이 terminal 상태가 되면 herdr pane close로 pane을 회수하고, arbiter release를 수행한다(spawn-worker §6 절차 그대로).
• reps 계측이 설정된 기기라면 scopefuel reps add로 rounds·blockers-found·completed를 실제 있었던 그대로 기록한다. 라운드가 3번 돌았으면 3이라고 적는다 — 좋아 보이려고 축소하는 순간 이 기록을 참조하는 이후 급 배정이 오염된다.

실사고 근거

• 착지 유실 (콜드 스타트 4회 중 3회): 스폰 직후 자동 상태(OK status=done, herdr의 정상 JSON)를 착지 증거로 취급했다가, 실제 화면을 열어보니 브리프가 표시되지 않은 채 워커가 idle로 멈춰 있던 사례가 4회 중 3회였다. 자동 응답과 실제 착지는 서로 다른 신호다 → §4의 착지 검증 규칙.
• PR base 미명시 → 기본 브랜치 직행 위험: 브리프에 PR base를 명시하지 않았을 때 워커가 기본 브랜치를 향해 PR을 잡는 사고가 있었다 → §2·§3에서 PR base를 완료 정의에 명시하도록 고정.
• "통과함" 서술과 실제 출력 불일치: 브리프에 "테스트가 통과함"이라고 서술로만 요구했을 때, 워커가 실제로는 특정 픽스처만 통과시키고 실동작은 확인하지 않은 채 "통과함"으로 보고한 사례가 있었다. 픽스처 통과 ≠ 실동작 확인 → §3에서 서술이 아닌 실제 출력 원문을 요구하도록 고정.
• 같은 세션 자체검증 무효: 구현한 세션이 스스로 완료를 검증하면 같은 사각지대를 반복해서 놓친다. 검증은 항상 다른 세션·다른 모델 계열이 맡는다 → §5.