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

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

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)
    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
        fi
    end
    
    alt --cleanup enabled
        Loop->>Loop: purge temporary job folders
    end

---

Workflow

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