multi-agent-mux/PLAN_LOOP.md

📑 자율 반복 정제 루프 스킬 (multi-agent-mux-loop) 개발 계획서

이 문서는 멀티 에이전트 자율 오케스트레이션 루프(multi-agent-mux-loop)의 최종 안전/가드레일 옵션 규격을 포함하여 완벽하게 정제된 마스터 계획서입니다. 리뷰어 에이전트들의 교차 2차 피드백(Verdict 파싱, 자가 리뷰 방지, 타임아웃 보강)을 완벽하게 수렴하여 정교하게 갱신되었습니다.

---

1. ⚙️ 최종 스킬 명령 및 전체 옵션 세트 명세 (CLI Spec)

$ bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \
    [--plan] \
    [--plan-talk N] \
    [--reviewer "reviewer-1,reviewer-2"] \
    [--all-reviewer] \
    [--max-loop N] \
    [--verbose] \
    [--cleanup] \
    --target-agent "canary-projects-multi-agent-mux-creator-claude" \
    --task "수행할 작업 목표"

📥 옵션 상세 리스트 및 가드레일 제약

옵션명	기본값	분류	역할 및 안전 조치
--plan	비활성	기능	Planner 에이전트를 기동하여 협력 계획 수립 및 토론 단계 개시.
--plan-talk N	1	안전	플래너-작업자 간 토론 왕복 횟수 상한선. 토큰 낭비 무한 토론 차단.
--reviewer "A,B"	비활성	기능	지정된 peer 리뷰어 에이전트 세션(들)에 피드백 루프 의뢰 (주 작업자 세션은 강제 제외).
--all-reviewer	비활성	기능	레지스트리 상의 모든 role: reviewer 세션들을 전수 자동 수집하여 의뢰 (주 작업자 세션은 강제 제외).
--max-loop N	3	안전 (필수)	반려(NOT PASS) 시 최대 수정 횟수 제한. 토큰 비용 폭주 방지 가드레일.
--verbose	비활성	편의	단계별 타임라인 진행 상태 및 잡 매핑 로그의 실시간 상세 출력.
--cleanup	비활성	편의	루프 완료 후 성공한 임시 잡 파일(.mam/jobs/)들의 자동 클린업 청소.
--target-agent	(필수)	인프라	구현을 처리할 주 개발자(Creator) 세션 이름 명시.
--task	(필수)	인프라	자율 루프에 전달할 최종 구현 지시사항 텍스트.

---

🔄 2. 자율 오케스트레이션 상세 파이프라인 (Sequence Flow)

sequenceDiagram
    autonumber
    actor User as 사용자 / run_loop.sh
    participant Plan as Planner Claude
    participant Dev as Creator Claude
    participant Rev as Reviewer Agents

    User->>User: run_loop.sh 기동 (옵션 세트 검증 및 대상 예외 필터링)
    
    %% Planning & Challenge discussion
    alt --plan 지정 시
        User->>Plan: delegate-job (계획 수립 지시)
        Plan-->>User: 계획서 도출 완료
        loop 지정된 --plan-talk 횟수 동안 반복 (기본 1회)
            User->>Dev: delegate-job (계획서 비판적 검토 및 이의제기 지시)
            Dev->>Plan: 계획서의 맹점 1가지 이상 Challenge 메일 교환
            Plan-->>Dev: 수정 반영 및 최종 계획 합의
        end
    else --plan 미지정
        User->>Dev: Self-planning 지시 (스스로 계획 세워 즉시 시작)
    fi
    
    %% Execution
    User->>Dev: delegate-job (작업 지시)
    Dev-->>User: 구현 완료 (git diff 발생)
    
    %% Peer-Review Loop with Max-Loop constraint
    loop 최대 --max-loop 횟수 동안 반복 (기본 3회)
        alt 리뷰어 옵션 지정 시 (--reviewer or --all-reviewer)
            User->>Rev: delegate-job (정식 peer 코드 리뷰 위임)
            Rev-->>User: [VERDICT: PASS] 또는 [VERDICT: NOT PASS] 태그 리포트 제출
            alt 100% PASS 충족 시
                Note over User,Rev: 루프 즉시 탈출 (성공)
            else NOT PASS 검출 시
                User->>Dev: 피드백 전달 및 수정 지시 (피드백 난이도에 따라 Planner 우회 계획 갱신 적용)
            end
        else 리뷰어 미지정
            User->>Dev: Self-Review 지시 (자가 검증 및 자율 종결)
        fi
    end

    %% Cleanup & Final Report
    alt --cleanup 지정 시
        User->>User: 임시 잡 폴더 청소
    end
    User-->>User: 최종 결과 요약 출력 및 마감

---

🛠️ 3. 개발 로직 및 안전 파싱 체크포인트

1) Verdict 판정 파서 안전 가이드라인 (Fail-Closed & Precedence)

• NOT PASS 우선권: 리뷰 리포트 본문 내에 [VERDICT: NOT PASS] 가 단 한 번이라도 등장하면, [VERDICT: PASS] 문구 존재 여부와 상관없이 무조건 NOT PASS로 처리하여 오독 필터링을 방지합니다.
• Fail-Closed 기본 실패주의: 태그 누락이나 malformed 리포트로 인해 두 토큰이 모두 스캔되지 않을 경우, 통과시키지 않고 NOT PASS(실패) 로 취급하여 루프 무한 기동 및 맹점 통과를 원천 차단합니다.
• 템플릿 명시: 리뷰어 위임 잡 발행 시, 최종 결과 요약 행에 정형화된 태그 [VERDICT: PASS] 혹은 [VERDICT: NOT PASS]를 리포트 본문 하단에 반드시 기재하도록 프롬프트 템플릿에 명시적으로 추가합니다.

2) 자가 리뷰 방지 가드 (Exclusion Rule)

• --all-reviewer 혹은 --reviewer 목록을 소집할 때, 해당 작업을 수행한 대상 개발자 세션인 $TARGET_AGENT 는 리뷰어 매핑 목록에서 강제로 배제(Exclude) 하도록 파싱 쉘 스크립트에서 필터링을 적용합니다.

3) 쉘 예외 처리 및 대기 타임아웃 (Error Guard & Timeout)

• grep -oP 나 find | head 시 매칭이 없을 때 set -eo pipefail에 의해 쉘 스크립트 전체가 비명횡사하지 않도록 || true 가드 및 공백 체크문을 엄밀히 적용합니다.
• wait_for_job 함수 실행 시 타임아웃 가드레일(WAIT_TIMEOUT, 기본값 3600초)을 명시적으로 설계하여 무한 루프 행(Hang) 현상을 차단합니다.