⚖️ 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>:

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).
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

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).
Deterministic Orthogonal Enforcement:
- Standard invocation with explicit planner:
```
bash run_loop.sh --creator <name> --plan --planner <name> --task "..."
```
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:
```
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.

6.6 KiB Raw Blame History

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