toki
c90bb755a9
- Refactor plan, code-review, finalize-task-routing, refine-local-plans, router skills - Add agent-workflow-loop-orchestration skill and plan agent configs - Update roadmap: knowledge-tool-optimization milestones, stream-evidence-gate-core SDD - Add stream-evidence-gate-core task, archive, and Go streamgate package - Update dev-test inventory (edge/node smoke), agent-contract, edge-local-dev-guide - Deprecate USER_REVIEW for output-validation-filters SDD
154 lines
9.5 KiB
Markdown
154 lines
9.5 KiB
Markdown
---
|
|
name: orchestrate-agent-task-loop
|
|
description: 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를 출력한다.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
python3 agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py
|
|
```
|
|
|
|
- 특정 task group:
|
|
|
|
```bash
|
|
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 파일을 직접 이동하거나 덮어쓰지 않은 채 원인만 보고한다.
|
|
|
|
## 출력 형식
|
|
|
|
```text
|
|
------------------------------------------
|
|
작업시작: 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`를 자동 해소하거나 사용자 결정을 추측하지 않는다.
|