tmpl/multi-agent-mux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5ed9ec79d76dfe6588951ce5b2ac943222f009ad
multi-agent-mux/.agents/reports/cli_redesign_opinion.md
T

233 lines
9.7 KiB
Markdown
Raw Blame History

# 📐 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.
Reference in New Issue View Git Blame Copy Permalink