multi-agent-mux/.agents/skills/multi-agent-mux-loop/SKILL.md

name, description, version, author, license, platforms, environments, metadata

name	description	version	author	license	platforms	environments	metadata
multi-agent-mux-loop	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.	4.5.0	godopu	MIT	linux macos	terminal herdr	hermes tags related_skills prereq_skills agent herdr multi-agent loop planning review orchestrator grok opencode codex multi-agent-mux-create multi-agent-mux-resume multi-agent-mux-stop multi-agent-mux-delegate-job 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. 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 <session>, 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)가 스스로 구현 계획 및 설계 수립을 포함한 개발 전 과정을 직접 진행합니다.
• 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:

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:<name> (the brief goes over the broker to a remote.py run --session <name> 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:<name> and does not support transport: remote.

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

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 Use Existing Plan or Creator Self-Plan (No --plan)
        alt Existing Plan Found
            Loop->>Dev: notify task execution using existing plan
        else No Plan Found
            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가 독자적으로 설계 및 태스크 단위를 구상한 후 구현에 착수합니다.
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)로 유지됩니다.

---

CLI Option ↔ Workflow Phase Mapping

워크플로우 단계별로 활용할 수 있는 run_loop.sh 옵션 규격은 다음과 같습니다:

워크플로우 단계	해당 CLI 옵션	설명
Phase 1: Planning	--plan	Planner 에이전트를 기동하여 최초 계획 작성을 강제합니다. (옵션을 지정하지 않을 경우 새 계획서 작성을 생략하며, 기존 계획서가 있는 경우 이를 로드하고, 없는 경우 Creator가 직접 계획 및 설계를 수립하여 즉시 구현에 착수합니다.)
Phase 1: Planner session	--planner <name>	계획 단계를 수행할 세션을 명시합니다. --plan과 함께만 사용합니다. 생략 시 running planner를 자동 탐색합니다.
Phase 1: Debate	--plan-talk N	Planner와 Creator가 상호 대화식 챌린지 루프를 N회 돌며 계획을 교차 정제합니다.
Phase 2: Execution	--creator <name>	코드를 구현할 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이면 끔).
Control	--verbose / --cleanup	상세 로그 / 성공 시 임시 job 디렉터리 삭제.
Source root	--worktree <path> (env MAM_LOOP_WORKTREE, CLI 우선)	diff 수집·base·head·빈 변경분 판정만 이 git 워크트리 기준으로 합니다. wrapper·레지스트리·체크포인트·loop guard·리포트 승격·cleanup 은 루프를 띄운 본 체크아웃(제어 루트)에 남습니다. 모든 위임 프롬프트 앞에 [워크트리 컨텍스트] 블록(경로·브랜치·base·head·커밋 수·미커밋 변경)이 붙습니다. Python 루프 전용(Issue #21).
Diff base	--base <ref> (CLI 전용, env 없음)	리뷰 diff 의 base 를 고정합니다. 소스 HEAD 의 조상이어야 하며 아니면 exit 1. 생략 시 Phase 2 시작 시점의 소스 HEAD 입니다.
Review only	--review-only	Phase 2(구현 위임)를 건너뛰고 <base>..HEAD 를 리뷰합니다. --base 필수, --plan 과 함께 쓸 수 없습니다. 수정·순응 잡은 여전히 creator 에게 갑니다.

--worktree 또는 --base 가 있으면 매 리뷰 라운드(셀프 리뷰 포함) 전에 소스 루트의 변경분을 git 종료 코드로 판정합니다. 변경분이 비었거나 판정할 수 없으면 리뷰를 요청하지 않고 exit 1 로 끝납니다(fail-closed). 둘 다 없으면 기존 동작 그대로입니다.

구현이 루프 밖(워크트리의 creator 에게 delegate-job --type direct)에서 끝났다면, 구현 위임 전에 base 를 기록해 두고 리뷰만 돌립니다:

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 "<worktree-creator>" --reviewer "<reviewer>" --task "Issue #N review"

---

Workflow

# 1. Creator Self-Planning & Development + Self-review (direct task execution using existing promoted plan or Creator's own self-plan)
bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \
  --creator "<creator-session-name>" \
  --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 "<creator-session-name>" \
  --plan \
  --planner "<planner-session-name>" \
  --plan-talk 1 \
  --reviewer "<reviewer-session-name-1>,<reviewer-session-name-2>" \
  --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 "<creator-session-name>" \
  --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 분기)
• 원자적 아카이빙 (Promotion): 루프 성공 종료 시 최종 계획서와 검증 리포트들은 .agents/reports/<session_name>/ 디렉토리로 원자적으로 덮어쓰기(mv -f)되어 보존됩니다. 해당 경로의 리포트들로 VCS 추적성을 확보해야 합니다.