Godopu
c3631e2aa1
- Resolve Herdr shim 5 routing & paste defects (ISSUE-1 ~ ISSUE-5):
* paste-buffer: use pane send-text without auto-enter, propagate rc=3 to send_keys_safe
* exact-match pane resolution: remove substring matching ('in tn') across all branches
* workspace scoping: introduce HERDR_WORKSPACE_ID and .mam/herdr_workspace_id persistence
* unified resolver: single _resolve_herdr_pane_id helper across shim commands
- Resolve dialog token false-positive on 'Yes, try it' tip and isolate fullscreen modal rejection
- Sync mock Herdr CLI contracts in tests/conftest.py
- Add contract tests H-15~H-23 and regression tests D-4~D-7 (412 tests, 100% PASS)
- Add multi-agent loop plans, review reports, and bug report
- Update framework and skill packages to v3.0.1
213 lines
15 KiB
Markdown
213 lines
15 KiB
Markdown
---
|
|
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: 3.0.1
|
|
author: godopu
|
|
license: MIT
|
|
platforms: [linux, macos]
|
|
environments: [terminal, herdr]
|
|
metadata:
|
|
hermes:
|
|
tags: [agent, herdr, multi-agent, loop, planning, review, orchestrator, grok]
|
|
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 <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.
|
|
|
|
---
|
|
|
|
## 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 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 디렉터리 삭제. |
|
|
|
|
---
|
|
|
|
## Workflow
|
|
|
|
```bash
|
|
# 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 데이터 오염이 발생합니다. 하나의 루프가 끝날 때까지 다른 루프를 병렬로 기동하지 마십시오.
|
|
- **원자적 아카이빙 (Promotion)**: 루프 성공 종료 시 최종 계획서와 검증 리포트들은 `.agents/reports/<session_name>/` 디렉토리로 원자적으로 덮어쓰기(`mv -f`)되어 보존됩니다. 해당 경로의 리포트들로 VCS 추적성을 확보해야 합니다.
|