multi-agent-mux/.agents/reports/cli_redesign_opinion.md

📐 Architecture & UX Review: CLI Option Redesign for multi-agent-mux-loop

• Author: creator-agy-01 (Worker / Creator Team Leader)
• Job ID: 13a8c27f
• Scope: Comprehensive Feasibility, Ergonomics, Compatibility & Edge Case Analysis
• Status: Analysis & Proposal (Non-Mutating)

---

1. Executive Summary & Verdict

🎯 Overall Verdict: STRONGLY ENDORSED (with Edge-Case Guards)

The proposal to introduce --creator <session> (with --target-agent retained as a 100% backward-compatible alias), introduce --planner <session> (with implicit --plan activation), and formalize a symmetric 3-tier role flag structure (--planner, --creator, --reviewer) is a major UX and architectural improvement.

Key Benefits:

1. Cognitive Symmetry: Replaces legacy asymmetric naming (--target-agent vs. --plan vs. --reviewer) with explicit, intuitive role-oriented flags directly matching the 3 Multi-Agent Mux (MAM) pillars (Planner, Creator, Reviewer).
2. Multi-Planner Disambiguation: Solves the limitation where multiple running planner sessions (e.g., domain-specific planners or specialized models) could not be explicitly selected without manual state alteration.
3. Ergonomic Shorthand: Specifying --planner <session> removes the redundant requirement to pass both --plan and session identifiers.
4. Zero-Breaking-Change Guarantee: Full backward compatibility for all existing scripts, tests, hooks, and subagent prompts using --target-agent and --plan.

---

2. Symmetry Matrix: Current vs. Proposed Design

Role Phase	Current (Legacy) Syntax	Proposed (Symmetric 3-Tier) Syntax	Auto-Discovery / Fallback Mechanism
Tier 1: Planning	--plan (boolean only; auto-selects first running planner)	--planner <session> (explicit session) OR --plan (auto-discover)	If omitted: Creator Self-Planning (default). If --planner passed: implicitly sets PLAN_MODE=true.
Tier 2: Execution	--target-agent <session> (asymmetric)	--creator <session> (primary) OR --target-agent <session> (legacy alias)	Mandatory flag (fails fast if session is unregistered/dead).
Tier 3: Verification	--reviewer "A,B" (explicit list) OR --all-reviewer (boolean)	--reviewer "A,B" (explicit list) OR --all-reviewer (all running)	If omitted: Creator Self-Review (default).

---

3. In-Depth Boundary & Edge Case Analysis

To ensure production stability, the redesign must account for the following edge cases in run_loop.sh:

3.1 Edge Case 1: Dual Specification of --creator and --target-agent

• Scenario: A user or automated caller passes both --creator sess-A and --target-agent sess-B (or sess-A).
• Behavior:
  • If sess-A == sess-B: Accept cleanly (idempotent).
  • If sess-A != sess-B: Fail fast with exit code 1 (ERROR: Conflicting creator sessions specified via --creator and --target-agent: 'sess-A' vs 'sess-B').
• Rationale: Silent precedence creates hidden bugs in automated workflows.

3.2 Edge Case 2: --planner <session> without --plan

• Scenario: Caller passes --planner my-planner --creator my-creator --task "...".
• Behavior: Automatically set PLAN_MODE=true and PLANNER_SESSION="my-planner".
• Rationale: Specifying a planner session is an unambiguous expression of intent to execute Phase 1 (Planning). Requiring --plan in addition is redundant friction.

3.3 Edge Case 3: --plan without --planner (Legacy Compatibility)

• Scenario: Caller passes --plan --creator my-creator --task "...".
• Behavior: Retain current resolve_planner_session behavior (dynamic scan of .mam/agent-sessions.yaml for running sessions with role: planner).
• Validation: If no running planner exists, fail fast with: ERROR: Planner mode enabled (--plan) but no running session with a 'planner' role was found.

3.4 Edge Case 4: --planner <session> validation & Role Sanity

• Scenario: Caller passes --planner bogus-sess or a session whose role in registry is reviewer.
• Behavior:
  • Verify session exists and is running.
  • Check if session role contains planner. If not, log an informational warning ([!] Session 'sess' has role 'reviewer' but was explicitly assigned as Planner) and proceed without hard failure (allowing ad-hoc role assignment).

3.5 Edge Case 5: Comma-Separated vs. Multi-Value Reviewers

• Scenario: --reviewer "rev1,rev2" vs --reviewer rev1 --reviewer rev2.
• Recommendation: Support both:
  • Standard comma-separated parsing: IFS=',' read -r -a REVIEWERS <<< "$CLEAN_REVS".
  • Appending multi-flag usage: If --reviewer appears multiple times, append tokens to REVIEWERS array.

---

4. Concrete Implementation Blueprint for run_loop.sh

Below is the exact parsing and normalization logic recommended for run_loop.sh:

# ---------------------------------------------------------------------------
# Default configuration parameters
# ---------------------------------------------------------------------------
PLAN_MODE=false
PLAN_TALK_TURNS=1
ALL_REVIEWERS=false
MAX_LOOP=3
MAX_REBUT=1
VERBOSE=false
CLEANUP=false
CREATOR_SESSION=""
TARGET_AGENT_LEGACY=""
PLANNER_SESSION_OVERRIDE=""
TASK=""
REVIEWER_LIST=""

# ---------------------------------------------------------------------------
# CLI Argument Parsing
# ---------------------------------------------------------------------------
while [[ "$#" -gt 0 ]]; do
  case "$1" in
    --plan)
      PLAN_MODE=true
      shift ;;
    --planner)
      PLAN_MODE=true
      PLANNER_SESSION_OVERRIDE="$2"
      shift 2 ;;
    --creator)
      CREATOR_SESSION="$2"
      shift 2 ;;
    --target-agent) # 100% Backward-compatible alias
      TARGET_AGENT_LEGACY="$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)
      PLAN_TALK_TURNS="$2"
      shift 2 ;;
    --max-loop)
      MAX_LOOP="$2"
      shift 2 ;;
    --max-rebut)
      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

# ---------------------------------------------------------------------------
# Creator Normalization & Conflict Resolution
# ---------------------------------------------------------------------------
if [ -n "$CREATOR_SESSION" ] && [ -n "$TARGET_AGENT_LEGACY" ]; then
  if [ "$CREATOR_SESSION" != "$TARGET_AGENT_LEGACY" ]; then
    log_error "Conflicting creator sessions specified via --creator ('$CREATOR_SESSION') and --target-agent ('$TARGET_AGENT_LEGACY')."
    exit 1
  fi
fi

TARGET_AGENT="${CREATOR_SESSION:-$TARGET_AGENT_LEGACY}"

if [ -z "$TARGET_AGENT" ] || [ -z "$TASK" ]; then
  log_error "Missing required arguments: --creator (or --target-agent) and --task must be provided."
  usage
fi

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

---

5. UX Walkthrough: Before vs. After

Example A: Full 3-Tier Collaboration (Planner + Creator + Targeted Reviewers)

• Before:

  run_loop.sh --plan --plan-talk 2 --target-agent my-creator-agy-01 \
    --reviewer "my-reviewer-claude-01,my-reviewer-hermes-01" \
    --task "Implement OAuth token refresh"
  

• After (Clear & Symmetric):

  run_loop.sh --planner my-planner-claude-01 --plan-talk 2 \
    --creator my-creator-agy-01 \
    --reviewer "my-reviewer-claude-01,my-reviewer-hermes-01" \
    --task "Implement OAuth token refresh"
  

Example B: Creator Self-Planning & Self-Review (Lightweight Fast Path)

• Before:

  run_loop.sh --target-agent my-creator-agy-01 --task "Fix css margin"
  

• After:

  run_loop.sh --creator my-creator-agy-01 --task "Fix css margin"
  

Example C: Auto-Discovered Planner with Unanimous Review

• Before:

  run_loop.sh --plan --target-agent my-creator-agy-01 --all-reviewer --task "Refactor auth"
  

• After (Both supported):

  run_loop.sh --plan --creator my-creator-agy-01 --all-reviewer --task "Refactor auth"
  

---

6. Migration Plan & Documentation Strategy

1. Phase 1: Zero-Risk Implementation:
   • Update run_loop.sh CLI parser and help text.
   • Update .agents/skills/multi-agent-mux-loop/SKILL.md examples highlighting --creator as primary and --target-agent as alias.
2. Phase 2: Comprehensive Test Additions:
   • Add unit tests in tests/test_tier1_unit.py testing:
     • --creator standalone invocation.
     • --target-agent backward-compatibility.
     • --creator + --target-agent identical vs conflicting arguments.
     • --planner <session> implicit plan activation.
     • --planner <session> precedence over auto-discovered planner.
3. Phase 3: Ecosystem Consistency:
   • Update .agents/MULTI_AGENT_RULES.md references to reflect the 3-tier flag convention.
   • Update /multi-agent-mux-loop prompt template hints in .gemini/ or custom skills.

---

7. Conclusion

The proposed redesign is clean, non-disruptive, highly ergonomic, and addresses real multi-agent team composition needs. It preserves 100% backward compatibility while elevating Multi-Agent Mux's CLI ergonomics to a first-class standard.