iop/agent-ops/skills/project/orchestrate-agent-task-loop/SKILL.md

name	description
orchestrate-agent-task-loop	agent-task의 작업들 실행해 요청 시 활성 PLAN/CODE_REVIEW 루프를 무인 실행한다. 번호와 선행 complete.log를 기준으로 준비된 작업을 병렬 dispatch하고, lane/G별 Codex·Claude·agy·Pi worker, Pi 자가검증, Codex 공식 리뷰, cloud context 승격을 끝날 때까지 반복할 때 사용한다.

Orchestrate Agent Task Loop

목적

agent-task/의 file-based 상태 계약을 감시하고 준비된 PLAN 구현부터 공식 코드 리뷰와 후속 PLAN까지 자동으로 수렴시킨다. 파일명·의존성·슬롯·세션 locator는 스크립트가 판별하고, 구현과 리뷰의 의미 판단은 각 CLI agent가 맡는다.

언제 호출할지

• 활성 PLAN-*-G??.md 작업들을 번호·의존성 순서로 무인 실행할 때
• 독립적인 split subtask들을 가능한 범위에서 병렬 실행할 때
• Pi 작업에 자가검증을 한 번 추가하고 모든 공식 리뷰를 Codex로 반복할 때
• cloud worker의 context/quota/model 오류를 상위 CLI가 native session을 찾아 이어받게 할 때

입력

• workspace: agent-task/가 있는 신뢰된 repository root (선택, 기본값: 현재 디렉터리)
• task_group: 특정 agent-task/<task_group>만 실행할 때의 이름 (선택)
• dry_run: 실제 CLI를 시작하지 않고 상태·route·의존성만 검사 (선택)
• retry_blocked: 이전 dispatcher 실행에서 차단된 같은 PLAN을 명시적으로 다시 시도 (선택)

먼저 확인할 것

• agent-ops/skills/common/plan/SKILL.md와 agent-ops/skills/common/code-review/SKILL.md의 현재 상태 계약을 읽는다.
• codex, claude, agy, pi가 PATH에 있고 로그인·provider 설정이 유효한지 확인한다.
• 자동 승인은 현재 workspace 안의 PLAN 실행에만 허용되며, 외부 시스템 변경이나 파괴적 작업으로 범위를 넓히지 않는다.
• 다른 dispatcher가 같은 workspace를 실행 중이지 않은지 확인한다. 스크립트의 workspace lock 실패를 우회하지 않는다.
• 첫 실행 전 --dry-run으로 active task 분류와 dependency 상태를 확인한다.

Route 계약

PLAN route	Worker
local-G01~local-G05	Pi iop/ornith:35b, thinking high
local-G06~local-G08	Pi iop/laguna-s:2.1, thinking high
local-G09~local-G10	Claude claude-opus-4-8, effort xhigh
cloud-G01~cloud-G02	agy Gemini 3.5 Flash (Low)
cloud-G03~cloud-G04	agy Gemini 3.5 Flash (Medium)
cloud-G05~cloud-G06	agy Gemini 3.5 Flash (High)
cloud-G07~cloud-G08	Claude claude-opus-4-8, effort xhigh
cloud-G09~cloud-G10	Codex gpt-5.6-sol, reasoning xhigh
모든 CODE_REVIEW-*	Codex gpt-5.6-sol, reasoning xhigh

동시 실행 제한:

• Pi ornith:35b: 3
• Pi laguna-s:2.1: 2
• agy: 1
• 공식 Codex review: 1
• 공유 checkout에서는 worker/selfcheck 실행 중 공식 review를 시작하지 않는다.
• PLAN의 수정 파일 요약에서 write-set이 겹치는 task: 직렬화
• 수정 파일 요약이 없거나 root 파일을 포함한 write-set을 확정할 수 없는 PLAN: 실행 차단

Prompt 계약

제어 프롬프트는 영어로 통일하고 절대경로만 넣으며 아래 문장을 불필요하게 확장하지 않는다.

• Cloud/Claude/Codex worker: Read {PLAN_PATH} and complete the task. Final in Korean.
• Pi worker: Think in English. Final in Korean. Read {PLAN_PATH} and complete the task.
• Pi 자가검증: Think in English. Final in Korean. This is a self-check of completed work, not a review. Read {PLAN_PATH} and finish any missing work. Recheck and fix your work. Read {CODE_REVIEW_PATH} and fill any missing implementation fields.
• 공식 review: Read {CODE_REVIEW_PATH} and start the review. Final in Korean.

승격 attempt에는 Continue from {LOCATOR_PATH}. Check the saved context and current workspace. Final in Korean.을 사용한다. 모델에게 handoff 요약 작성을 요구하지 않는다.

실행 절차

1. 상태 점검

   • 다음 명령으로 active task, route, stage, dependency를 출력한다.

     python3 agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py --dry-run
     

   • NN_...은 즉시 후보이고, NN+PP[,QQ...]_...은 같은 task group의 각 predecessor complete.log가 active 또는 좁은 archive lookup에서 하나씩 확인되어야 한다.

   • 숫자 자체를 암묵적 dependency로 해석하지 않는다.

2. Dispatcher 실행

   • 전체 active task:

     python3 agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py
     

   • 특정 task group:

     python3 agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py --task-group <task_group>
     

   • worker는 번호순으로 예약하되 dependency와 write-set이 독립이면 병렬 실행한다.

   • Pi worker 성공, Pi 자가검증 성공, 공식 review를 각각 별도 persistent stage로 기록한다. 재시작 시 worker_done=true, selfcheck_done=false이면 worker나 review가 아니라 같은 Pi 모델의 새 자가검증 session부터 재개한다.

   • persistent state는 PLAN 첫머리의 task/plan/tag 세대를 키로 사용한다. 같은 PLAN의 체크리스트·본문 갱신은 stage를 초기화하지 않고, 후속 PLAN의 plan 번호 변경은 새 stage로 초기화한다.

   • dispatcher 실행 기록 없이 review stub의 마지막 구현 체크가 이미 완료된 작업은 review로 보낸다. dispatcher가 실행한 Pi worker 성공 기록은 자가검증 완료 전까지 review로 보내지 않는다.

   • 공식 review가 준비되어도 실행 중인 worker/selfcheck가 모두 끝나 checkout이 안정될 때까지 기다린다. review 실행 중에는 새 worker/selfcheck를 시작하지 않는다.

3. 승격과 context 복구

   • CLI의 terminal provider 오류 이벤트나 stderr에서 확인된 context/output limit, provider quota/rate limit, model unavailable만 agy -> Claude -> Codex 또는 Claude -> Codex로 승격한다. agent 응답, source, tool/test 출력의 같은 문자열은 승격 근거로 쓰지 않는다.
   • Codex가 같은 오류를 내면 locator를 전달한 새 Codex session을 한 번 실행한 뒤 차단한다.
   • timeout/crash/permission/일반 구현 오류는 자동 승격·맹목 재시도 없이 작업차단으로 남긴다.
   • Pi는 cloud 승격하지 않는다.
   • attempt identity는 <task-name>__p<plan>__<role>__aNN이다. locator에는 workspace, CLI/model, PLAN/review, session id, native session path, raw output log를 기록한다.
   • locator는 repository의 .git/agent-task-dispatcher/runs/에 둔다. .git state를 쓸 수 없는 환경에서만 ${XDG_STATE_HOME}/agent-task-dispatcher/<workspace-id>/runs/를 사용한다.

4. 리뷰 수렴

   • 공식 review는 항상 독립된 Codex one-shot session으로 하나씩 실행한다.
   • PASS archive, WARN/FAIL follow-up pair, review finalization recovery는 code-review 파일 계약에 맡긴다.
   • active pair가 남아 있으면 다시 분류하여 worker 또는 review로 보낸다.
   • 계획 write-set의 source snapshot과 review/finding artifact가 모두 동일할 때만 정체로 판정한다. 동일 상태가 반복돼도 hard limit으로 종료하지 않고 루프정체경고를 출력한 뒤 backoff한다.
   • USER_REVIEW.md, dependency ambiguity, generic CLI failure만 자동 루프를 차단한다.

실행 결과 검증

• 준비된 dependency task가 번호순으로 시작되고 독립 task만 병렬 실행됐는가
• route별 실제 CLI/model이 표와 일치하는가
• Pi 작업만 fresh-session 자가검증을 정확히 한 번 거쳤는가
• 모든 공식 review가 Codex gpt-5.6-sol xhigh로 직렬 실행됐는가
• 각 attempt locator에서 native session과 output log를 찾을 수 있는가
• PASS task가 archive되고 새로 풀린 dependent task가 이어서 시작됐는가
• 차단 시 task, 원인, locator가 출력됐는가
• 검증 실패 시: dispatcher를 중단하고 active PLAN/CODE_REVIEW 파일을 직접 이동하거나 덮어쓰지 않은 채 원인만 보고한다.

출력 형식

------------------------------------------
작업시작: 03+01_event_contract_unit_tests
------------------------------------------
model=pi/iop/ornith:35b
plan=/absolute/path/PLAN-local-G05.md
[03+01_event_contract_unit_tests][worker][a00] ...

------------------------------------------
리뷰시작: 03+01_event_contract_unit_tests
------------------------------------------
model=codex/gpt-5.6-sol xhigh
review=/absolute/path/CODE_REVIEW-local-G05.md

작업대기, 자가검증시작, 모델승격, 리뷰결과, 루프정체경고, 작업차단, 작업완료도 같은 separator 형식을 사용한다.

금지 사항

• PLAN/CODE_REVIEW lane 또는 G를 dispatcher가 재평가하거나 파일명을 바꾸지 않는다.
• predecessor index가 없는 숫자 순서를 dependency로 만들지 않는다.
• archive 전체를 탐색하거나 dependency 후보 이외의 archive 파일을 읽지 않는다.
• worker에게 공식 review, archive, complete.log 작성을 시키지 않는다.
• Pi 자가검증을 공식 review로 취급하지 않는다.
• model-authored handoff 요약에 context 복구를 의존하지 않는다.
• generic failure를 token/quota 오류로 간주해 상위 모델로 넘기지 않는다.
• USER_REVIEW.md를 자동 해소하거나 사용자 결정을 추측하지 않는다.