--- name: multi-agent-mux-loop description: "Run an autonomous planning-execution-review loop using multiple agents (Planner, Creator, Reviewers) in the workspace. Automatically orchestrates plan discussion, code changes, and peer reviews until a unanimous PASS is achieved or the maximum iteration limit is reached." version: 4.8.8 author: godopu license: MIT platforms: [linux, macos] environments: [terminal, herdr] metadata: hermes: tags: [agent, herdr, multi-agent, loop, planning, review, orchestrator, grok, opencode, codex] related_skills: [multi-agent-mux-create, multi-agent-mux-resume, multi-agent-mux-stop, multi-agent-mux-delegate-job] prereq_skills: [multi-agent-mux-create] --- # Multi-Agent Mux Loop — Autonomous Orchestration Loop > **Companion skills**: `multi-agent-mux-create` (start), `multi-agent-mux-resume` (re-attach), `multi-agent-mux-delegate-job` (delegate). > **Safety Guard**: `--max-loop`, `--max-rebut`, and `--plan-talk` restrict API cost runaways. > **Scope Guard (O-3)**: Intercepts direct orchestrator mutations when `/multi-agent-mux-loop` is active. See [.agents/MULTI_AGENT_RULES.md #3.2](.agents/MULTI_AGENT_RULES.md#32-invocation-aware-scoped-guard-o-3). > **Single source of truth**: `./.mam/agent-sessions.yaml`. 수동 템플릿 작성 및 수동 프롬프트 환류는 폐지되었습니다. Planner, Creator, Reviewer 간의 모든 협업 피드백 루프는 본 스킬(`run_loop.sh`)만을 단독으로 사용하여 자동으로 오케스트레이션합니다. ## What this skill does Run an autonomous planning-execution-review loop using multiple agents (Planner, Creator, Reviewers) in the workspace. It supports: - **Collaborative Planning** (`--plan`, optional `--planner `, and `--plan-talk N`): Planner designs the solution, Creator challenges the plan for N turns to resolve edge cases, then implementation starts. `--planner` selects the planner session; omit it to auto-resolve the first running planner. - **Creator Self-Planning & Development** (default without `--plan`): Planner 에이전트에게 계획 작성을 위임하지 않고, 작업자(Creator: developer/writer)가 스스로 구현 계획 및 설계 수립을 포함한 개발 전 과정을 직접 진행합니다. **어떤 계획서도 자동으로 로드되지 않습니다.** - **Explicit Plan Reuse** (`--plan-file `): 기존 계획서를 재사용하는 유일한 경로입니다. 경로는 제어 루트 기준이며, 읽을 수 없거나 내용이 빈 파일이면 잡을 하나도 만들기 전에 종료합니다(exit 1). 로드된 계획서는 **최초 구현 프롬프트 1회**에만 실립니다 — 리뷰 이후의 수정 라운드에는 리뷰 피드백만 전달됩니다. `--plan` 과는 함께 쓸 수 없습니다. - **Targeted Peer-Review** (`--reviewer`): Runs custom-selected reviewer agents to verify code changes. - **Total Peer-Review** (`--all-reviewer`): Enforces a unanimous PASS verdict from all registered reviewer sessions. - **Rebuttal & Adjudication Protocol** (`--max-rebut N`): Allows Creator to reject invalid reviewer feedback using `[REBUT:]` tags and triggers Reviewer re-adjudication (`[ADJUDICATION:]`) or Planner arbitration (`[ARBITRATION:]`). - **Self-Review** (default): Creator verifies its code changes autonomously without peer reviews. - **Safety Limits** (`--max-loop N`): Aborts execution if reviews fail to PASS after N iterations. --- ## Liveness contract and remote sessions (Issue #18) Every delegate job the loop submits carries the liveness contract of `multi-agent-mux-delegate-job`: agents heartbeat automatically once they publish `started --heartbeat N`, a job with no event for K x N seconds is closed as `deadline_timeout`, and `started` must arrive within T seconds of the injection. Tune it for a whole loop with environment variables, which the runner passes through as `--heartbeat` / `--heartbeat-misses` / `--ack-timeout`: ```bash MAM_HEARTBEAT_SEC=30 MAM_HEARTBEAT_MISSES=4 MAM_ACK_TIMEOUT_S=180 \ bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh --creator creator-claude-01 --all-reviewer --task "..." ``` A session row in `.mam/agent-sessions.yaml` with `transport: remote` is delegated as `remote:` (the brief goes over the broker to a `remote.py run --session ` runner on another host; no herdr, pane or process probing happens for it). The row still needs `role` and `status: running` to be picked up by `--all-reviewer`. Remote rows need the default Python loop runner: the legacy shell runner (`MAM_LOOP_PY=0`) addresses every session as `herdr:` and does not support `transport: remote`. With `--worktree`/`--base` (review identity), remote reviewers are refused by default - they cannot reach the review tree on this host; `--remote-review diff-only` admits them with the snapshot diff as their only evidence, recorded as `evidence: diff-only`. ## Roles & Responsibilities 협업 시스템은 각 에이전트의 책임 영역을 명확히 격리하여 상호 교차 검증을 강제합니다. ``` ┌──────────────────────┐ │ User Prompt │ └──────────┬───────────┘ ▼ ┌──────────────────────┐ │ 1. Planner Agent │ ◄──────────────────┐ │ - Plan & Checklist │ │ └──────────┬───────────┘ │ ▼ │ ┌──────────────────────┐ │ │ 2. Creator Agent │ │ │ - Code & DoD Verify │ │ └──────────┬───────────┘ │ ▼ │ (NOT PASS Feedback) ┌──────────────────────┐ │ │ 3. Reviewer Agents │ │ │ - Dual Peer Review │ ───────────────────┘ └──────────┬───────────┘ ▼ (PASS) ┌──────────────────────┐ │ 4. Done & Standby │ └──────────────────────┘ ``` ### Planner (설계 및 통제) - **목적**: 요구사항을 명세화하고, 구현 단계의 설계 결함이나 모순(Contradiction)을 사전에 차단합니다. - **역할**: - 사용자 요구사항에 따른 구현 목표 및 범위 수립. - `implementation_plan.md` 및 `task.md` (체크리스트) 작성 및 버전 관리(Rev.1, Rev.2, ...). - 리뷰어 피드백 발생 시 설계 변경의 파급 범위를 계산하여 계획 갱신. - **핵심 원칙**: 직접 코드를 수정하지 않고 오직 설계와 체크리스트 자산만 관리합니다. ### Creator (구현 및 자가 검증) - **목적**: Planner가 제공한 체크리스트를 기반으로 실제 리포지토리 코드를 물리적으로 수정 및 구현합니다. - **역할**: - `task.md`를 순차적으로 완료 상태(`[x]`)로 업데이트하며 구현 수행. - 커밋 전 **Definition of Done (DoD)** 체크리스트를 자체 실행하여 금지된 코드 패턴, 메모리/구조적 사이드 이펙트 유무 자가 검토. - 수정 사항을 단일 원자적(Atomic) 커밋으로 마감하고 리뷰어에게 전달. ### Reviewer Agents (교차 피드백 및 검증) - **목적**: 구현된 결과물이 최초 설계서 및 제약 요건에 일치하는지 제3자의 관점에서 엄격하게 검토합니다. - **역할**: - 상위 논리적 정합성(설계 주장과 구현 간 모순 여부) 검증. - 전이 조건, 예외 처리, 타입 시그니처 등 하위 레벨 구현의 세부 사항 기계적 검증. - **판정 규칙**: 지정 또는 자동으로 수집된 모든 리뷰어 세션이 만장일치로 **PASS** 판정을 내릴 때까지 Creator는 마감할 수 없으며, 반려 시 **Planner**에게 피드백이 환류됩니다. --- ## Specification & Flow ```mermaid sequenceDiagram autonumber actor Loop as run_loop.sh participant Plan as Planner Agent participant Dev as Creator Agent participant Rev as Reviewer Agents Loop->>Loop: Parse args & validate session states alt --plan enabled Loop->>Plan: delegate plan design Plan-->>Loop: plan report generated loop for --plan-talk turns (default 1) Loop->>Dev: delegate plan review & challenge Dev->>Plan: send critiques (Discussion) Plan-->>Dev: update plan & reach consensus end else Creator Self-Plan (No --plan) alt Plan named with --plan-file Loop->>Dev: notify task execution using the named plan else No --plan-file Loop->>Dev: request Creator self-planning and code execution end end Loop->>Dev: delegate code implementation Dev-->>Loop: code modification complete loop up to --max-loop times (default 3) alt Reviewers specified (--reviewer / --all-reviewer) Loop->>Rev: delegate code validation Rev-->>Loop: Verdict report ([VERDICT: PASS] / [VERDICT: NOT PASS]) alt Unanimous PASS achieved Note over Loop,Rev: Break loop (Success) else NOT PASS detected Loop->>Dev: delegate code correction with reviewer feedback end else Self-Review (default) Loop->>Dev: notify self-evaluation Dev-->>Loop: verification complete end end alt --cleanup enabled Loop->>Loop: purge temporary job folders end ``` --- ## Feedback Loop Cadence 1. **Planning Phase**: - **Collaborative Planning (`--plan`)**: Planner가 프로젝트 구조를 파악하고 `implementation_plan.md`/`task.md`로 로드맵을 제공하며, Creator와의 피드백 루프를 통해 정제됩니다. - **Creator Self-Planning (No `--plan`)**: Planner의 개입 없이 Creator가 독자적으로 설계 및 태스크 단위를 구상한 후 구현에 착수합니다. `--plan-file ` 로 계획서를 명시한 경우에만 그 계획서를 기반으로 합니다. 2. **Execution Phase**: Creator가 배정된 태스크의 코드를 수정합니다. `--plan` 모드 진행 중 예상치 못한 설계 변경 필요성이 감지되면 작업을 멈추고 Planner에게 계획 수정을 먼저 위임합니다. (Creator 자율 계획 모드에서는 Creator가 직접 설계를 변경하며 진행합니다.) 구현 완료 후 DoD(타입 매핑, 공유 자원 사이드 이펙트 방지, 문서-코드 정합성)를 자체 검증한 뒤 단일 커밋을 작성합니다. 3. **Review Phase**: Creator가 리뷰어 세션에 작업 완료 사실과 변경 범위(`git diff`)를 전달합니다. 리뷰어는 검증 후 리포트 **마지막에 단독 행**으로 판정을 남깁니다: - **반려 (`[VERDICT: NOT PASS]`)** → 피드백 요약을 Planner에게 전송하여 상위 레벨 계획(Rev.n)을 개시합니다. - **통과 (`[VERDICT: PASS]`)** → 모든 검토 사항이 해결되었음을 명시합니다. 4. 지정되거나 자동 수집된 리뷰어 전원이 PASS를 발행해야 완결되며, `--max-loop N`회 내에 도달하지 못하면 안전을 위해 루프를 중단합니다. 5. 완결 후에도 에이전트 세션은 종료하지 않고, 다음 태스크 지시가 있을 때까지 프롬프트 대기 상태(Standby)로 유지됩니다. ### 계획서가 비어 있을 때 (Empty plan reports) 계획서를 읽는 네 지점(`--plan-file`, `--plan` 초기 계획서, 논의 턴 refine, 리뷰 에스컬레이션 refine)은 같은 판정을 씁니다: **읽을 수 있는 일반 파일이고 공백을 제외한 내용이 있어야** 계획서입니다. 리포트 파일이 존재하기만 하면 통과시키던 과거 동작에서는 빈 리포트가 계획서를 조용히 지웠고, 프롬프트가 자기계획 문구로 바뀐 채 루프가 정상 종료(rc 0)했습니다. - **`--plan-file` 이 비어 있으면**: 잡을 하나도 만들기 전에 `exit 1`. - **`--plan` 의 초기 계획서가 비어 있으면**: `exit 1`. 계획 단계를 지불하고 아무것도 받지 못한 실행이 자기계획으로 격하되지 않습니다. - **refine 결과가 비어 있으면**(논의 턴·리뷰 에스컬레이션 모두): 경고를 남기고 **이전 계획서를 유지**합니다. 덮어쓰지 않으므로, "갱신된 다음 계획서에 입각하여…" 로 시작하는 수정 프롬프트가 빈 계획서를 싣는 일이 없습니다. --- ## CLI Option ↔ Workflow Phase Mapping 워크플로우 단계별로 활용할 수 있는 `run_loop.sh` 옵션 규격은 다음과 같습니다: | 워크플로우 단계 | 해당 CLI 옵션 | 설명 | | :--- | :--- | :--- | | **Phase 1: Planning** | `--plan` | Planner 에이전트를 기동하여 최초 계획 작성을 강제합니다. (옵션을 지정하지 않을 경우 새 계획서 작성을 생략하고, Creator가 직접 계획 및 설계를 수립하여 즉시 구현에 착수합니다.) | | **Phase 1: Plan reuse** | `--plan-file ` | 기존 계획서를 재사용합니다. 제어 루트 기준 경로이며 **`--plan` 과 상호 배타**입니다. 지정하지 않으면 어떤 계획서도 로드되지 않습니다. | | **Phase 1: Planner session** | `--planner ` | 계획 단계를 수행할 세션을 명시합니다. **`--plan`과 함께만** 사용합니다. 생략 시 running planner를 자동 탐색합니다. | | **Phase 1: Debate** | `--plan-talk N` | Planner와 Creator가 상호 대화식 챌린지 루프를 `N`회 돌며 계획을 교차 정제합니다. | | **Phase 2: Execution** | `--creator ` | 코드를 구현할 Creator 세션에 코딩 태스크를 주입합니다. (필수) | | **Phase 3: Review** | `--reviewer "A,B"` | 지정된 리뷰어 세션 리스트(`A`, `B` 등)에 교차 Peer Review를 위임합니다. | | **Phase 3: Consensus** | `--all-reviewer` | 레지스트리에 등록된 모든 active 리뷰어 세션을 자동으로 수집하여 리뷰를 돌립니다. (`--reviewer` 옵션과는 상호 배타적이며, 지정/수집된 모든 리뷰어의 PASS 만장일치가 항상 필요합니다.) | | **Iterative Loop** | `--max-loop M` | NOT PASS 판정 시 최대 `M`회까지 Creator가 자체 수정합니다. `--plan` 모드에서 리뷰어가 리포트에 `[ESCALATE: PLANNER]` 태그를 남기면 설계 변경 수준으로 판단하여 Planner에게 계획 갱신을 위임합니다 (린트는 리뷰어가 검토 관점 중 하나로 확인할 뿐, 별도의 자동 게이트는 아닙니다). | | **Rebuttal** | `--max-rebut N` | 이터레이션당 Creator 반론 횟수 (기본 1, `0`이면 끔). | | **Job budget** | `--job-timeout ` | 위임 잡마다의 예산 (기본 `MAM_JOB_TIMEOUT_S` 또는 3600). 잡 대기 상한은 예산 + `MAM_WAIT_GRACE_S`(기본 300 s, 0 이상의 10진 정수; 잘못된 값은 경고 후 300) — 벽시계 뒤 래퍼의 종결·발행 꼬리와 1 s 레코드 폴링을 덮는 여유입니다. | | **Control** | `--verbose` / `--cleanup` | 상세 로그 / 성공 시 임시 job 디렉터리 삭제. | | **Source root** | `--worktree ` (env `MAM_LOOP_WORKTREE`, CLI 우선) | diff 수집·base·head·빈 변경분 판정만 이 git 워크트리 기준으로 합니다. wrapper·레지스트리·체크포인트·loop guard·리포트 승격·cleanup 은 루프를 띄운 본 체크아웃(제어 루트)에 남습니다. 모든 위임 프롬프트 앞에 `[워크트리 컨텍스트]` 블록(경로·브랜치·base·head·커밋 수·미커밋 변경)이 붙습니다. Python 루프 전용(Issue #21). | | **Diff base** | `--base ` (CLI 전용, env 없음) | 리뷰 diff 의 base 를 고정합니다. 소스 HEAD 의 조상이어야 하며 아니면 exit 1. 생략 시 Phase 2 시작 시점의 소스 HEAD 입니다. | | **Review only** | `--review-only` | Phase 2(구현 위임)를 건너뛰고 `..HEAD` 를 리뷰합니다. `--base` 필수, `--plan` 과 함께 쓸 수 없습니다. 수정·순응 잡은 여전히 creator 에게 갑니다. | | **Review isolation** | `--review-isolation worktree\|env` | `--worktree`/`--base` 에서만 의미. `worktree`(기본): 라운드마다 스냅샷의 detached 리뷰 워크트리(TMPDIR)에서 검증합니다. `env`: 소스 루트에서 `PYTHONDONTWRITEBYTECODE=1 … -p no:cacheprovider --basetemp=<밖>` 지침으로 검증합니다. 리뷰 워크트리를 열 수 없으면 조용히 낮추지 않고 exit 1. `env` 에서 리뷰어가 ignore 되지 않는 산출물을 소스 루트에 남기면 라운드가 stale 로 판정돼 재리뷰가 반복됩니다(fail-closed) — 산출물은 `--basetemp` 등으로 소스 밖에 둡니다. | | **Sub-jobs** | `--wait-open-jobs` | creator 잡의 하위 잡(아래 "하위 위임 잡") 외에, creator 작업 중 `--parent-job` 없이 등록된 열린 잡도 기다립니다. 기본 off: 같은 제어 평면의 무관한 잡이 루프를 붙잡을 수 있기 때문입니다. Python 루프 전용. | | **Remote reviewers** | `--remote-review refuse\|diff-only` | `--worktree`/`--base` 에서만 의미. 원격 리뷰어(`transport: remote`)는 이 호스트의 리뷰 트리에 닿을 수 없으므로 기본으로 **어떤 잡도 위임하기 전에** 거부(exit 1)합니다. `diff-only` 는 스냅샷 SHA 와 diff 만을 근거로 받아들이고 그렇게 기록합니다. | `--worktree` 또는 `--base` 가 있으면 매 리뷰 라운드(셀프 리뷰 포함) 전에 소스 루트의 변경분을 git 종료 코드로 판정합니다. 변경분이 비었거나 판정할 수 없으면 리뷰를 요청하지 않고 exit 1 로 끝납니다(fail-closed). 둘 다 없으면 기존 동작 그대로입니다. **리뷰 identity (Issue #21 항목 5).** `--worktree`/`--base` 가 있으면 매 리뷰 라운드를 `(loop_id, base, head, tree)` 에 묶습니다. 소스의 미커밋·untracked 상태까지 담은 스냅샷(ref 없는 커밋)을 만들고, 리뷰어가 받는 diff 도 그 스냅샷에서 만듭니다(`base..snapshot`). 라운드가 끝난 뒤 소스가 바뀌었으면 그 라운드의 PASS 는 버리고 수정 잡 없이 다시 리뷰합니다(마지막 반복이면 exit 1). 승격 직전에도 한 번 더 확인하며, 승격된 리포트 옆에 `report-.identity.json`(loop_id·base·head·tree·스냅샷 커밋·리뷰어·`transport`·`evidence`: `review-tree`/`source-tree`/`diff-only`)을 둡니다. 추적되지 않는 중첩 git 저장소는 스냅샷에 담을 수 없어 거부합니다. 서브모듈 안의 미커밋·untracked 내용도 스냅샷에는 gitlink 커밋만 남으므로 거부합니다(라운드 시작 시 exit 1, 리뷰 중에 생기면 그 라운드는 stale). `submodule.*.ignore` 설정으로 가려지지 않습니다. 리뷰어가 없으면 creator 셀프 리뷰가 같은 리뷰어 경로(스냅샷 diff·증거 검사·승격 직전 재확인·사이드카)를 거치고, NOT PASS 면 수정 잡 없이 다시 리뷰합니다. 리뷰 잡의 `[워크트리 컨텍스트]` 는 검증 대상을 `[리뷰 identity]` 의 검증 경로 하나로만 지시합니다. **하위 위임 잡 (Issue #34).** creator 가 작업 일부를 `delegate-job submit --parent-job <자기 job_id>` 로 맡기면, 루프는 creator 잡(실행·수정·순응)이 끝난 뒤 그 잡의 자손(자식·손자…, 폴링마다 다시 읽음)의 레코드가 모두 종결될 때까지 기다린 다음 리뷰로 넘어갑니다. 깊이 제한은 없고 상한은 둘입니다: `MAM_CHILD_WAIT_S`(기본 잡 예산 + `MAM_WAIT_GRACE_S`, creator 잡 종결부터; 0 이면 한 번만 확인; 각 하위 잡은 자기 등록 + `timeout_sec`(#33, 기본 `MAM_JOB_TIMEOUT_S`/3600 s)에 닫히므로 보통 그 전에 끝납니다)와 `MAM_JOB_TREE_MAX`(기본 50 개, 1 이상, 넘으면 기다리지 않음). 둘 다 10진 정수이고 잘못된 값은 경고 후 기본값을 씁니다. 그만큼 루프 벽시계가 늘어납니다. 루프를 잡으로 감싸 돌리면 바깥 잡의 3600 s 가 먼저 끝날 수 있습니다. 자식의 결과는 루프를 멈추지 않고 리뷰 근거가 됩니다: 하위 잡이나 귀속되지 않은 열린 잡이 있으면 모든 리뷰 프롬프트(셀프 리뷰 포함) 앞에 `[하위 위임 잡]` 표(상태·사유·깊이)와 `[귀속되지 않은 열린 잡]`(부모 미표기로 이 작업 중 등록된 열린 잡) 줄이 붙고(둘 다 없으면 프롬프트는 전과 같습니다), 리뷰어는 `OPEN`·`CLOSED-UNCONFIRMED`·실패(`error`/`cancelled`/`NOT-DISPATCHED`) 하위 잡이 있으면 creator 리포트가 대체 완료를 입증하지 않는 한 NOT PASS 를 냅니다. 표는 이 실행의 모든 creator 잡(앞 회차의 실행·수정·순응 잡 포함)의 자손을 매 회차 다시 읽어 만듭니다 — 수정 잡이 새로 생겼다고 앞 잡의 열린·실패 하위 잡이 사라지지 않습니다(대기는 새 creator 잡의 자손만 하므로 대기 상한이 회차마다 다시 쌓이지 않습니다). `CLOSED-UNCONFIRMED` 는 오케스트레이터가 마감(`deadline_timeout`/`wall_clock_timeout`/`agent_blocked`)으로 닫았거나 사유가 없는 `error` 입니다 — 레코드만 닫혔고 에이전트는 인터럽트되지 않으므로 계속 쓰고 있을 수 있습니다. creator 잡 자체의 실패는 전처럼 exit 1 입니다. **리뷰 중 소스 변경 = 승인 무효 (하위 잡이 있을 때, Issue #34).** `--worktree`/`--base` 가 없어도 이 실행에 하위 잡(또는 귀속되지 않은 열린 잡)이 있는 라운드마다 리뷰 요청 직전 소스(= 제어 루트)의 head 와 미커밋·untracked 를 포함한 tree 를 기록하고, 판정 수집 뒤와 승격 직전에 다시 계산합니다. 바뀌었으면 위 identity 모드와 같이 그 라운드의 PASS 를 버리고 수정 잡 없이 다시 리뷰합니다(마지막 반복이면 exit 1). 제어 평면(`.mam`, 잡·감사 로그 디렉터리)은 비교에서 뺍니다. 리뷰어가 ignore 되지 않는 산출물을 소스에 남기면 라운드가 stale 이 되니 산출물은 소스 밖에 둡니다. 하위 잡이 없는 루프는 이 검사를 하지 않습니다(전과 같음) — 소스에 잡마다 바뀌는 untracked 파일이 있을 수 있기 때문입니다. git 저장소가 아니거나 서브모듈이 dirty 해 지문을 만들 수 없으면 경고(`stale-review guard is off`) 후 기존 동작입니다. 루프가 끝난 **뒤**의 늦은 쓰기는 막을 수 없으며 다음 루프의 diff 에 미커밋 변경으로 드러납니다. 구현이 루프 밖(워크트리의 creator 에게 `delegate-job --type direct`)에서 끝났다면, **구현 위임 전에** base 를 기록해 두고 리뷰만 돌립니다: ```bash BASE=$(git -C "$WT" rev-parse HEAD) # 구현 위임 전에 기록 # ... creator 가 $WT 에서 구현·커밋 ... bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \ --worktree "$WT" --base "$BASE" --review-only \ --creator "" --reviewer "" --task "Issue #N review" ``` --- ## Workflow ```bash # 1. Creator Self-Planning & Development + Self-review (no plan is loaded; add --plan-file to reuse one) bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \ --creator "" \ --task "Fix typo in deploy/README.md" # 2. Collaborative planning + Targeted Reviewers + Safety limits # (실전 자율 루프 기동의 표준 패턴 — 리뷰어 2인 지정 + 최대 3회 반복) bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \ --creator "" \ --plan \ --planner "" \ --plan-talk 1 \ --reviewer "," \ --max-loop 3 \ --verbose \ --task "Refactor the session backup mechanism to handle NFS flock" # 3. Total validation (all reviewers must PASS) bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \ --creator "" \ --all-reviewer \ --max-loop 5 \ --cleanup \ --task "Close CI shellcheck coverage gaps" ``` ## Pitfalls - **Incorrect Verdict format (앵커링 파서 하드닝)**: 리뷰 리포트 파일 내에서 `[VERDICT: PASS]` 또는 `[VERDICT: NOT PASS]` 토큰은 반드시 리포트의 **마지막에 단독 행**으로 기재되어야 합니다. 코드 인용이나 변경 diff 내에 등장하는 토큰은 매칭 대상에서 완전 배제됩니다. - **Fail-closed on missing verdict**: 최종 Verdict 토큰이 누락되거나 리포트 픽업에 실패하면, 파서는 **경고 후 통과시키는 것이 아니라** 안전을 위해 즉시 `NOT PASS`로 판정(fail-closed)하고 교정 사이클을 수행합니다. 리뷰어에게는 반드시 리포트 끝에 단독 행으로 토큰을 찍도록 지시해야 합니다. - **Session Availability**: `run_loop.sh` 기동 전에 참조되는 Planner, Target Agent, Reviewer 세션들이 모두 herdr 세션으로 기동되어 (`status.sh` 기준 `alive` 및 `running`) 있어야 합니다. - **동시 루프 기동 금지 (NFS Lock Shadowing)**: 동일한 작업 트리 내에서 다수의 `run_loop.sh` 제어기를 동시에 기동하면 SQLite DB 갱신 경합 및 YAML 데이터 오염이 발생합니다. 하나의 루프가 끝날 때까지 다른 루프를 병렬로 기동하지 마십시오. (실제로는 loop lock 이 두 번째 루프를 exit 1 로 거부한다 — run_loop.sh 의 `mam_acquire_loop_lock` 분기) - **파이프라인의 종료 코드 (Issue #36)**: 위임이 실패하면 루프는 원인을 stderr 에 남기고 0 이 아닌 코드로 끝납니다. 루프를 `… | tee log` 처럼 파이프라인으로 돌리면 `$?` 는 `tee` 의 것이므로 `set -o pipefail` 또는 `${PIPESTATUS[0]}` 로 루프의 코드를 보십시오. stderr 도 함께 남기십시오(`2>&1`). - **원자적 아카이빙 (Promotion)**: 루프 성공 종료 시 최종 계획서와 검증 리포트들은 `.agents/reports//` 디렉토리로 원자적으로 덮어쓰기(`mv -f`)되어 보존됩니다. 해당 경로의 리포트들로 VCS 추적성을 확보해야 합니다.