# 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.