feat(skills): add multi-agent-mux-loop autonomous loop orchestrator

Implement a new autonomous planning-execution-review orchestration loop supporting: - Collaborative planning & creator-planner challenge discussions (--plan-talk) - Self-planning and self-review fallbacks - Custom reviewer target list and all-reviewer unanimous PASS verdicts - API-cost runaway safety limits via --max-loop Integrated inside deploy/install.sh checklist and deploy/gitea-ci.yml.
2026-07-16 08:12:24 +09:00
parent ff01984a69
commit bacf139447
4 changed files with 519 additions and 0 deletions
@@ -0,0 +1,99 @@
+# 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` and `--plan-talk` restrict API cost runaways.
+> **Single source of truth**: `./.mam/agent-sessions.yaml`.
+
+## 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.
+- **Self-Planning** (default): Creator designs and executes the code independently.
+- **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.
+- **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.
+
+---
+
+## Specification & Flow
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor Loop as run_loop.sh
+    participant Plan as Planner Claude
+    participant Dev as Creator Claude
+    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 Self-Planning
+        Loop->>Dev: notify direct task execution (Self-planned)
+    fi
+    
+    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
+        fi
+    end
+    
+    alt --cleanup enabled
+        Loop->>Loop: purge temporary job folders
+    end
+```
+
+---
+
+## Workflow
+
+```bash
+# 1. Self-planning + Self-review (direct task execution)
+bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \
+  --target-agent "canary-projects-multi-agent-mux-creator-claude" \
+  --task "Fix typo in deploy/README.md"
+
+# 2. Collaborative planning + Targeted Reviewers + Safety limits
+bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh \
+  --plan \
+  --plan-talk 1 \
+  --reviewer "canary-projects-multi-agent-mux-reviewer-cline,canary-projects-multi-agent-mux-reviewer-claude" \
+  --max-loop 3 \
+  --verbose \
+  --target-agent "canary-projects-multi-agent-mux-creator-claude" \
+  --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 \
+  --all-reviewer \
+  --max-loop 5 \
+  --cleanup \
+  --target-agent "canary-projects-multi-agent-mux-creator-claude" \
+  --task "Close CI shellcheck coverage gaps"
+```
+
+## Pitfalls
+
+- **Incorrect Verdict format**: Reviewers MUST output `[VERDICT: PASS]` or `[VERDICT: NOT PASS]` in their final reports for the loop parser to recognize results. If missing, the parser falls back to scanning for "PASS" or "not pass" but warns.
+- **Session Availability**: Ensure the referenced planner, creator, and reviewer sessions are running or alive before launching `run_loop.sh`.
+- **NFS Lock Shadowing**: Spawning simultaneous loop processes will serialize job database transactions. Let one loop finish before launching another.