🏛️ Definitive Architecture Consensus & Implementation Specification: `multi-agent-mux-loop` CLI Redesign

Author / Synthesist: creator-agy-01 (Worker / Creator Team Leader)
Contributors: planner-reviewer-claude-01, reviewer-cline-01, grok
Job ID: 9f2ae7bd
Version: Rev.3 (Final Consensus — Incorporating Grok's Critique & All Reviewer Findings)
Supersedes: Supersedes Section 4 & Edge Case 3.2 of cli_redesign_opinion.md and extends cli_redesign_debate_consensus.md.

1. Executive Summary & Core Paradigm

The Multi-Agent Mux team has converged on the Orthogonal with Fail-Safe Validation architecture for multi-agent-mux-loop (run_loop.sh).

Core Principles:

Separation of Phase Switch vs. Target Identity:
- Phase Switches (--plan, --all-reviewer) control which phases execute.
- Target Identities (--planner, --creator, --reviewer) control which sessions execute those phases.
Fail-Fast Safety (No Magic, No Silent Drops):
- Passing an identity without its corresponding phase switch (e.g., --planner <name> without --plan) immediately fails fast with exit code 1, providing an actionable error message and exact remediation syntax.
Role Lifecycle Alignment:
- Planner Tier: Optional phase (--plan to activate, --planner to bind, default: Creator self-planning).
- Creator Tier: Mandatory execution (--creator to bind, with --target-agent as 100% backward-compatible alias).
- Reviewer Tier: Optional peer verification (--reviewer for targeted list, --all-reviewer for all active reviewers, default: Creator self-review).

2. Exhaustive Resolution of Grok's Critique & Spec Gaps

2.1 Parser Variable Separation (Conflict Detection Fix)

Issue: Parsing --creator|--target-agent) into a single variable in the case loop overwrites the first flag, making conflicting input (--creator sess-A --target-agent sess-B) undetectable.
Fix: Parse into two distinct variables: CREATOR_OPT="" and TARGET_AGENT_OPT="".

Pre-Freeze Resolution: Check for conflicts immediately after the while loop using raw echo (before B-13 freeze snapshot re-exec):

if [ -n "$CREATOR_OPT" ] && [ -n "$TARGET_AGENT_OPT" ]; then
  if [ "$CREATOR_OPT" != "$TARGET_AGENT_OPT" ]; then
    echo "ERROR: Conflicting creator sessions specified via --creator ('$CREATOR_OPT') and --target-agent ('$TARGET_AGENT_OPT')."
    exit 1
  fi
fi
TARGET_AGENT="${CREATOR_OPT:-$TARGET_AGENT_OPT}"

2.2 Spec Gap (a): Explicit Bypass of Planner Auto-Discovery

Specification: When --planner <name> is provided, PLANNER_SESSION is assigned directly from the CLI argument, completely bypassing resolve_planner_session.

Logic:

if [ -n "$PLANNER_SESSION_OVERRIDE" ]; then
  PLANNER_SESSION="$PLANNER_SESSION_OVERRIDE"
else
  PLANNER_SESSION=$(resolve_planner_session)
fi

2.3 Spec Gap (b): 2-Branch Session Liveness & Registration Validation

Specification: Post-freeze validation for PLANNER_SESSION mirrors TARGET_AGENT validation with distinct error messages:

if [ "$PLAN_MODE" = true ]; then
  if [ -z "$PLANNER_SESSION" ]; then
    log_error "Planner mode enabled (--plan) but no running session with a 'planner' role was found."
    exit 1
  fi

  PLANNER_STATUS=$(MAM_STATE_JSON="$(load_state_json)" PLANNER="$PLANNER_SESSION" python3 -c "
import os, json
d = json.loads(os.environ.get('MAM_STATE_JSON', '{}'))
target = os.environ.get('PLANNER')
status = ''
for s in d.get('herdr_sessions', []):
    if s.get('name') == target:
        status = s.get('status')
        break
print(status)
")

  if [ -z "$PLANNER_STATUS" ]; then
    log_error "Planner agent session '$PLANNER_SESSION' is not registered in the session registry."
    exit 1
  elif [ "$PLANNER_STATUS" != "running" ]; then
    log_error "Planner agent session '$PLANNER_SESSION' is not running (current status: '$PLANNER_STATUS'). Please start it first."
    exit 1
  fi

2.4 Spec Gap (c): Substring Matching for Composite Roles

Specification: Role verification must support composite roles (e.g. planner,reviewer or creator,planner) using lowercase substring checks:
```
if 'planner' in (s.get('role') or '').lower():
    # Valid planner role match
```
If a session with a non-planner role (e.g. strictly role: creator) is explicitly targeted via --planner, emit an advisory warning (log_warn "Session '$PLANNER_SESSION' has role '$PLANNER_ROLE' but was assigned as Planner") and proceed.

2.5 Spec Gap (d): Test Suite Division (Pre-Freeze vs. Sandbox)

Tier 1 Unit Tests (tests/test_tier1_unit.py):
- Direct shell CLI parser tests (verifying exit codes 0 vs 1 for --creator + --target-agent conflict, --planner without --plan, invalid integer inputs).
Tier 2 Component Tests (tests/test_tier2_component.py):
- Isolated multi-agent state tests using mam_sandbox (mocking load_state_json, planner/creator/reviewer job registration, 3-tier feedback loops).

2.6 Spec Gap (e): Documentation & Formatting Scope

Include deploy/INSTALL.md in the rollout update list alongside all SKILL.md documents, MULTI_AGENT_RULES.md, and slash command help.
Clean all quotation escaping in documentation examples.

3. Production-Ready `run_loop.sh` Reference Implementation

# ===========================================================================
# 1. Configuration Defaults
# ===========================================================================
PLAN_MODE=false
PLAN_TALK_TURNS=1
ALL_REVIEWERS=false
MAX_LOOP=3
MAX_REBUT=1
VERBOSE=false
CLEANUP=false
CREATOR_OPT=""
TARGET_AGENT_OPT=""
PLANNER_SESSION_OVERRIDE=""
TASK=""
REVIEWER_LIST=""

# ===========================================================================
# 2. CLI Option Parser (Pre-Freeze Safe)
# ===========================================================================
while [[ "$#" -gt 0 ]]; do
  case "$1" in
    --plan)
      PLAN_MODE=true
      shift ;;
    --planner)
      PLANNER_SESSION_OVERRIDE="$2"
      shift 2 ;;
    --creator)
      CREATOR_OPT="$2"
      shift 2 ;;
    --target-agent) # Backward-compatible alias
      TARGET_AGENT_OPT="$2"
      shift 2 ;;
    --reviewer)
      if [ -n "$REVIEWER_LIST" ]; then
        REVIEWER_LIST="${REVIEWER_LIST},$2"
      else
        REVIEWER_LIST="$2"
      fi
      shift 2 ;;
    --all-reviewer)
      ALL_REVIEWERS=true
      shift ;;
    --plan-talk)
      if [[ ! "$2" =~ ^[0-9]+$ ]]; then
        echo "ERROR: --plan-talk requires a positive integer."
        exit 1
      fi
      PLAN_TALK_TURNS="$2"
      shift 2 ;;
    --max-loop)
      if [[ ! "$2" =~ ^[0-9]+$ ]] || [ "$2" -le 0 ]; then
        echo "ERROR: --max-loop requires a positive non-zero integer."
        exit 1
      fi
      MAX_LOOP="$2"
      shift 2 ;;
    --max-rebut)
      if [[ ! "$2" =~ ^[0-9]+$ ]]; then
        echo "ERROR: --max-rebut requires a non-negative integer."
        exit 1
      fi
      MAX_REBUT="$2"
      shift 2 ;;
    --verbose)
      VERBOSE=true
      shift ;;
    --cleanup)
      CLEANUP=true
      shift ;;
    --task)
      TASK="$2"
      shift 2 ;;
    -h|--help)
      usage ;;
    *)
      echo "Unknown option: $1"
      usage ;;
  esac
done

# ===========================================================================
# 3. Pre-Freeze Validation & Resolution (Uses raw echo)
# ===========================================================================
# Fail-fast on --planner without --plan
if [ -n "$PLANNER_SESSION_OVERRIDE" ] && [ "$PLAN_MODE" = false ]; then
  echo "ERROR: --planner was specified without --plan."
  echo "To enable the planning phase with this planner, please include the --plan flag:"
  echo "  run_loop.sh --creator <creator> --plan --planner $PLANNER_SESSION_OVERRIDE --task \"$TASK\""
  exit 1
fi

# Resolve Creator & detect conflicts
if [ -n "$CREATOR_OPT" ] && [ -n "$TARGET_AGENT_OPT" ]; then
  if [ "$CREATOR_OPT" != "$TARGET_AGENT_OPT" ]; then
    echo "ERROR: Conflicting creator sessions specified via --creator ('$CREATOR_OPT') and --target-agent ('$TARGET_AGENT_OPT')."
    exit 1
  fi
fi

TARGET_AGENT="${CREATOR_OPT:-$TARGET_AGENT_OPT}"

if [ -z "$TARGET_AGENT" ] || [ -z "$TASK" ]; then
  echo "ERROR: --creator (or --target-agent) and --task are mandatory fields."
  usage
fi

4. Summary Matrix of Supported Invocations

Scenario	Command Line	Execution Behavior
Creator Self-Planning (Default)	`run_loop.sh --creator c1 --task "..."`	No Phase 1. Creator plans & implements. Self-review.
Auto-Discovered Planner	`run_loop.sh --creator c1 --plan --task "..."`	Phase 1 runs with auto-discovered planner.
Targeted Planner	`run_loop.sh --creator c1 --plan --planner p1 --task "..."`	Phase 1 runs with `p1` explicitly.
Fail-Fast Misconfiguration	`run_loop.sh --creator c1 --planner p1 --task "..."`	Exits 1 immediately: prompts user to add `--plan`.
Targeted Reviewers	`run_loop.sh --creator c1 --reviewer "r1,r2" --task "..."`	Phase 2 -> Phase 3 with reviewers `r1`, `r2`.
Repeated Reviewer Flags	`run_loop.sh --creator c1 --reviewer r1 --reviewer r2 --task "..."`	Appends `r1,r2` -> runs review with both.
Full 3-Tier Suite	`run_loop.sh --creator c1 --plan --planner p1 --all-reviewer --task "..."`	Full 3-tier orchestration with unanimous review.
Legacy Invocations	`run_loop.sh --target-agent c1 --plan --task "..."`	100% backward-compatible execution.

5. Verdict & Status

The team is in complete consensus (100% Unanimous PASS) on this architecture. All 5 spec gaps and the parser conflict detection bug identified by Grok are fully resolved.

9.7 KiB Raw Blame History

🏛️ Definitive Architecture Consensus & Implementation Specification: multi-agent-mux-loop CLI Redesign