# 📐 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)*<br>OR `--plan` *(auto-discover)* | If omitted: **Creator Self-Planning** (default).<br>If `--planner` passed: implicitly sets `PLAN_MODE=true`. |
| **Tier 2: Execution** | `--target-agent <session>` *(asymmetric)* | `--creator <session>` *(primary)*<br>OR `--target-agent <session>` *(legacy alias)* | Mandatory flag (fails fast if session is unregistered/dead). |
| **Tier 3: Verification** | `--reviewer "A,B"` *(explicit list)*<br>OR `--all-reviewer` *(boolean)* | `--reviewer "A,B"` *(explicit list)*<br>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`:

```bash
# ---------------------------------------------------------------------------
# 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**:
  ```bash
  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)**:
  ```bash
  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**:
  ```bash
  run_loop.sh --target-agent my-creator-agy-01 --task "Fix css margin"
  ```
* **After**:
  ```bash
  run_loop.sh --creator my-creator-agy-01 --task "Fix css margin"
  ```

### Example C: Auto-Discovered Planner with Unanimous Review
* **Before**:
  ```bash
  run_loop.sh --plan --target-agent my-creator-agy-01 --all-reviewer --task "Refactor auth"
  ```
* **After (Both supported)**:
  ```bash
  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](.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.