98 lines
6.6 KiB
Markdown
98 lines
6.6 KiB
Markdown
# ⚖️ 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.
|