feat(mux-loop): redesign role CLI flags with --creator and --planner, drop --target-agent

- Replace '--target-agent' with mandatory '--creator <session>' flag
- Add explicit rejection error for legacy '--target-agent'
- Add '--planner <session>' flag with fail-fast check when '--plan' is missing
- Implement 2-branch session validation ('is not registered' vs 'is not running')
- Update in-repo references in hooks, SKILL.md, INSTALL.md, and tests
- Add tests/test_loop_cli.py with 9 unit/contract tests
This commit is contained in:
2026-08-26 14:03:20 +09:00
parent d56f60bbc6
commit 87b4501bbf
8 changed files with 210 additions and 19 deletions
+9 -5
View File
@@ -26,7 +26,7 @@ metadata:
## 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` and `--plan-talk N`): Planner designs the solution, Creator challenges the plan for N turns to resolve edge cases, then implementation starts.
- **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.
@@ -163,11 +163,14 @@ sequenceDiagram
| 워크플로우 단계 | 해당 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** | (기본값) | `--target-agent`로 명시한 주 작업 세션에 코딩 태스크를 주입합니다. |
| **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 디렉터리 삭제. |
---
@@ -176,26 +179,27 @@ sequenceDiagram
```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 \
--target-agent "<creator-session-name>" \
--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 \
--target-agent "<creator-session-name>" \
--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 \
--target-agent "<creator-session-name>" \
--task "Close CI shellcheck coverage gaps"
```