# ⚖️ Architecture Debate & Consensus Report: Orthogonal vs. Coupled CLI Design for `multi-agent-mux-loop`

- **Author**: `creator-agy-01` (Worker / Creator Team Leader)
- **Reviewers / Contributors**: `planner-reviewer-claude-01`, `reviewer-cline-01`, `grok`
- **Job ID**: `53ff6303`
- **Topic**: Phase Switch (`--plan`) vs. Target Identity (`--planner <name>`) Orthogonality vs. Coupling
- **Status**: Consensus Recommendation (ANALYSIS ONLY)

---

## 1. Executive Summary & Debate Context

In the redesign of `multi-agent-mux-loop` (`run_loop.sh`) to establish symmetric 3-tier role flags (`--planner`, `--creator`, `--reviewer`), an architectural debate arose regarding the relationship between `--plan` and `--planner <name>`:

1. **Initial Coupled Proposal (Claude / AGY initial view)**:
   - Passing `--planner <name>` automatically and implicitly activates Phase 1 (`PLAN_MODE=true`).
   - *Driver*: Ergonomics, brevity, DWIM (Do What I Mean).

2. **Grok's Orthogonal Proposal (`grok`)**:
   - Make `--plan` (Phase Switch: Enable planning phase) and `--planner <name>` (Target Identity: Which session to use) **strictly orthogonal**.
   - Invocation: `bash run_loop.sh --creator <name> --plan --planner <name> --reviewer <name> --task "..."`
   - *Driver*: Unix design philosophy (separation of mechanism vs. policy), predictable state machines, zero "magic" side-effects, composability for automated multi-agent pipeline scripts.

---

## 2. In-Depth Trade-Off Analysis

| Dimension | Coupled / Implicit Design (`--planner` auto-enables `--plan`) | Strictly Orthogonal Design (`--plan` separate from `--planner`) |
| :--- | :--- | :--- |
| **Ergonomics & Brevity** | **Superior for Interactive CLI**: Eliminates redundant flags (`--planner foo` instead of `--plan --planner foo`). | **Slightly More Verbose**: Requires passing both `--plan` and `--planner foo`. |
| **Predictability & State Machine** | **Risk of Ambiguity**: If flags are assembled dynamically by scripts, setting `--planner "$VAR"` might unexpectedly activate planning when `$VAR` is present but planning was not intended. | **Superior Predictability**: Phase activation is 100% controlled by `--plan`; session binding is 100% controlled by `--planner`. |
| **Error Modes** | If caller passes `--planner foo --no-plan` (contradiction), complex precedence resolution is needed. | If caller passes `--planner foo` without `--plan`, system can fail-fast with a clear, actionable validation error. |
| **Symmetry across Roles** | Asymmetric with Reviewer tier (where `--all-reviewer` is a phase/aggregation switch and `--reviewer` is session identity). | Highly symmetric: Phase switches (`--plan`, `--all-reviewer`) operate independently of Identity specifications (`--planner`, `--creator`, `--reviewer`). |

---

## 3. Team Perspectives & Reviewer Synthesis

### 3.1 Grok's Perspective
- **Core Argument**: In automated agent orchestration, hidden side-effects are a common source of subtle pipeline bugs. Having a flag change both *identity* and *execution flow* breaks the single-responsibility principle of CLI options.
- **Key Recommendation**: Explicit is better than implicit.

### 3.2 Claude's Perspective (`10a3201c`)
- **Core Argument**: Endorsed role symmetry. Acknowledged that user intent is rarely to specify a planner session and *not* execute planning, but emphasized that conflicting states must be prevented.

### 3.3 Cline's Perspective (`75c06a1e`)
- **Core Argument**: Detailed critical implementation realities in `run_loop.sh`:
  - Input validation (`--plan-talk`, `--max-loop`, `--max-rebut`) must be preserved.
  - B-13 freeze snapshot ordering means pre-freeze error emission must use raw `echo`, while post-freeze uses `log_*`.
  - Session existence and liveness validation for `--planner <name>` must be explicitly performed post-freeze.

---

## 4. The Consensus Recommendation: "Orthogonal with Fail-Safe Validation"

To synthesize Grok's rigor with high CLI usability, the team recommends the **Orthogonal with Fail-Safe Validation** model:

### 4.1 Specification Rules
1. **Explicit Roles & Switches**:
   - `--plan`: Enables Phase 1 (Planning). If passed without `--planner`, it auto-discovers the running planner via `load_state_json` (`resolve_planner_session`).
   - `--planner <session>`: Explicitly identifies the target session for Phase 1.
   - `--creator <session>` (or legacy alias `--target-agent <session>`): Mandatory target session for Phase 2 (Implementation).
   - `--reviewer <list>` / `--all-reviewer`: Target identity and aggregation for Phase 3 (Verification).
2. **Deterministic Orthogonal Enforcement**:
   - Standard invocation with explicit planner:
     ```bash
     bash run_loop.sh --creator <name> --plan --planner <name> --task "..."
     ```
3. **Fail-Fast Error on Omission (Zero Magic, Zero Silent Dropping)**:
   - If `--planner <name>` is passed **without** `--plan`:
     - **Do NOT silently ignore `--planner`** (which would surprise the user by skipping planning).
     - **Fail-fast with exit code 1**:
       ```text
       ERROR: --planner was specified without --plan.
       To enable planning with this planner, please include the --plan flag:
         run_loop.sh --creator <creator> --plan --planner <planner> --task "..."
       ```
   - *Why this is the optimal consensus*: It prevents magic side-effects (satisfying Grok's orthogonality requirement) while preventing accidental omission bugs (satisfying AGY/Claude/Cline's UX safety requirement).

---

## 5. Summary Matrix of CLI Invocations

| Use Case | Invocation Syntax | Behavior |
| :--- | :--- | :--- |
| **Creator Self-Planning (Default)** | `run_loop.sh --creator c1 --task "..."` | No Phase 1. Creator plans and implements. Self-review. |
| **Auto-Discovered Planner** | `run_loop.sh --creator c1 --plan --task "..."` | Phase 1 runs using auto-discovered planner session. |
| **Explicit Targeted Planner** | `run_loop.sh --creator c1 --plan --planner p1 --task "..."` | Phase 1 runs targeting `p1`. |
| **Misconfiguration Guard** | `run_loop.sh --creator c1 --planner p1 --task "..."` | **Fails fast with clear error**: Prompting user to add `--plan`. |
| **Targeted Peer Review** | `run_loop.sh --creator c1 --reviewer "r1,r2" --task "..."` | Phase 2 -> Phase 3 with reviewers `r1` and `r2`. |
| **Full Team (All Tiers)** | `run_loop.sh --creator c1 --plan --planner p1 --all-reviewer --task "..."` | Full 3-tier orchestration with unanimous review. |

---

## 6. Conclusion

The debate brought valuable architectural precision to Multi-Agent Mux. By adopting **Orthogonal CLI flags with fail-fast validation**, we maintain clean Unix separation of concerns, robust pipeline automation, and clear, foolproof ergonomics.