docs(mux-loop): add multi-agent architecture consensus & review reports for CLI redesign
This commit is contained in:
@@ -0,0 +1,232 @@
|
||||
# 📐 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
Block a user