# 🏛️ 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: 1. **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*. 2. **Fail-Fast Safety (No Magic, No Silent Drops)**: - Passing an identity without its corresponding phase switch (e.g., `--planner ` without `--plan`) immediately **fails fast with exit code 1**, providing an actionable error message and exact remediation syntax. 3. **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): ```bash 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 ` is provided, `PLANNER_SESSION` is assigned directly from the CLI argument, completely bypassing `resolve_planner_session`. - **Logic**: ```bash 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: ```bash 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: ```python 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 ```bash # =========================================================================== # 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 --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.