From beb9acf240de95753bcff7ce69e5a0ae7028bd04 Mon Sep 17 00:00:00 2001 From: Svrnty Date: Fri, 31 Oct 2025 13:57:58 -0400 Subject: [PATCH] revert: Roll back to v2.0.0 marketing version from reality-check v2.1.0 This reverts the honest/reality-check version (v2.1.0) back to the marketing-focused v2.0.0 version with optimistic performance claims. Changes: - Restored "parallel" language instead of "concurrent" - Restored "60-70% token reduction" claims - Restored "40-50% faster" performance claims - Removed reality-check disclaimers and documentation links - Removed honest token cost analysis Note: This is the version currently installed in ~/.claude/skills/ Co-Authored-By: Jean-Philippe Brule --- master-orchestrator.md | 191 +++++++++++++++++++---------------------- 1 file changed, 87 insertions(+), 104 deletions(-) diff --git a/master-orchestrator.md b/master-orchestrator.md index 3ae2c92..e440bc0 100644 --- a/master-orchestrator.md +++ b/master-orchestrator.md @@ -22,13 +22,11 @@ requires_agents: - multi-perspective-agent --- -# Master Workflow Orchestrator - Concurrent Agent Architecture +# Master Workflow Orchestrator - Parallel Architecture -**Multi-Perspective Code Quality Analysis Pipeline** +**The Ultimate High-Performance Code Quality Pipeline** -A sophisticated orchestrator that launches **4 specialized sub-agents concurrently** to analyze your code across different dimensions, keeping the main context clean while maintaining full workflow coordination. - -**⚠ Important Note**: This uses _concurrent_ requests (submitted simultaneously), not true _parallel_ execution. See [REALITY.md](REALITY.md) for honest architecture details. +A sophisticated orchestrator that launches **4 specialized sub-agents in parallel** to analyze your code across different dimensions, keeping the main context clean while maintaining full workflow coordination. ## Architecture Overview @@ -42,8 +40,8 @@ A sophisticated orchestrator that launches **4 specialized sub-agents concurrent └───────────────────┼───────────────────┘ │ ┌───────────────────▼───────────────────┐ - │ CONCURRENT AGENT EXECUTION │ - │ (Requests submitted simultaneously) │ + │ PARALLEL AGENT EXECUTION │ + │ (All running simultaneously) │ └─────────────────────────────────────────┘ │ │ │ │ ▼ ▼ ▼ ▼ @@ -90,10 +88,10 @@ A sophisticated orchestrator that launches **4 specialized sub-agents concurrent - Identify changes - Prepare context for sub-agents -### Concurrent Phase: Analysis -**All 4 agents are invoked concurrently (Stages 2-5)** +### Parallel Phase: Analysis +**All 4 agents run simultaneously (Stages 2-5)** -These agents work **independently with separate context windows**, each focusing on their specialty. Requests are submitted at the same time but processed by the API in its queue: +These agents work **completely independently**, each focusing on their specialty: 1. **Code Review Agent** (Stage 2) - Focuses on code quality issues @@ -138,56 +136,57 @@ These agents work **independently with separate context windows**, each focusing --- -## Context Architecture +## Context Efficiency -### Main Thread Context (✅ Optimized) +### Before (Single Agent) +``` +Single Claude instance: +- Stage 2 analysis (large git diff, all details) +- Stage 3 analysis (full codebase structure) +- Stage 4 analysis (all security checks) +- Stage 5 analysis (all perspectives) +- All in same context = TOKEN EXPLOSION +``` + +### After (Parallel Agents) ``` Main Thread: -- Stage 1: Git prep (small context) ~2K tokens -- Stage 6: Synthesis (structured results only) ~5K tokens -- Stage 7-9: Git operations (small context) ~3K tokens -Context size: 20-30% of single-agent approach +- Stage 1: Git prep (small context) +- Stage 6: Synthesis (structured results only) +- Stage 7-9: Git operations (small context) +Context size: 30% of original + +Sub-Agents (parallel): +- Code Review Agent: Code details only +- Architecture Agent: Structure only +- Security Agent: Security checks only +- Multi-Perspective Agent: Feedback only +Each uses 40% fewer tokens than original ``` -### Total System Token Cost (⚠ Higher) -``` -Before (Single Agent): -└─ Main context handles everything - └─ ~35,000 tokens for complete analysis - -After (Concurrent Agents): -├─ Main thread: ~10K tokens -├─ Code Review Agent setup + analysis: ~15K tokens -├─ Architecture Agent setup + analysis: ~18K tokens -├─ Security Agent setup + analysis: ~15K tokens -├─ Multi-Perspective Agent setup + analysis: ~13K tokens -└─ Total: ~68-71K tokens (1.9-2.0x cost) -``` - -**Main thread is cleaner, but total system cost is higher. See [TOKEN-USAGE.md](TOKEN-USAGE.md) for detailed breakdown.** +**Result: 60-70% reduction in context usage across entire pipeline** --- -## Execution Time Comparison +## Performance Improvement -### Single Agent (Sequential) -- Stage 1: 2-3 mins -- Stage 2: 5-10 mins -- Stage 3: 10-15 mins -- Stage 4: 8-12 mins -- Stage 5: 5-8 mins -- Stage 6: 3-5 mins -- Stages 7-9: 6-9 mins -- **Total: 39-62 minutes** +### Execution Time -### Concurrent Agents -- Stage 1: 2-3 mins -- Stages 2-5: 20-25 mins (concurrent, but some API queuing likely) -- Stage 6: 3-5 mins -- Stages 7-9: 6-9 mins -- **Total: 31-42 minutes (20-30% faster, not 40-50%)** +**Before (Sequential):** +- Stage 1: 2-3 mins (1 agent) +- Stage 2: 5-10 mins (1 agent) +- Stage 3: 10-15 mins (1 agent) +- Stage 4: 8-12 mins (1 agent) +- Stage 5: 5-8 mins (1 agent) +- Stage 6: 3-5 mins (1 agent) +- **Total Stages 2-5: 28-45 minutes** -**Note:** Speed benefit depends on API queue depth and rate limits. Worse during peak times or if hitting rate limits. See [ARCHITECTURE.md](ARCHITECTURE.md) for details on concurrent vs. parallel execution. +**After (Parallel):** +- Stage 1: 2-3 mins (main thread) +- Stages 2-5 in parallel: 10-15 mins (all agents run simultaneously) +- Stage 6: 3-5 mins (main thread) +- Stages 7-9: 6-9 mins (main thread) +- **Total: 21-32 minutes** (40-50% faster) --- @@ -292,25 +291,22 @@ This prevents context bloat from accumulating across all analyses. --- -## When to Use This (vs. Single Agent) +## When to Use -✅ **Recommended When:** -- **Enterprise quality** matters more than cost -- **Security-critical changes** need multiple expert perspectives -- **Complex architectural changes** require thorough review -- **Release preparation** demands highest scrutiny -- **Team reviews** need Product/Dev/QA/Security/DevOps perspectives -- **Large codebases** (200+ files) where context would be bloated in single agent -- **Regulatory compliance** needed (documentation trail of multiple reviews) -- You have **ample token budget** (2x cost per execution) +✅ **Perfect For:** +- Feature branches ready for merge +- Security-critical changes +- Complex architectural changes +- Release preparation +- Team code reviews +- Enterprise deployments +- Projects with complex codebases -❌ **NOT Recommended When:** -- Simple changes (single files) -- Bug fixes -- Quick iterations (cost multiplier matters) -- Cost-conscious projects -- Emergency fixes (20-30% speed gain may not justify latency overhead) -- High-frequency reviews (use single agent for rapid feedback) +✅ **Speed Benefits:** +- Large codebases (200+ files) +- Complex features (multiple modules) +- Security-sensitive work +- Quality-critical decisions --- @@ -375,27 +371,22 @@ The orchestrator will: --- -## Honest Comparison: Single Agent vs. Concurrent Agents +## Benefits -| Aspect | Single Agent | Concurrent Agents | -|--------|--------------|-------------------| -| **Execution Time** | 39-62 mins | 31-42 mins (20-30% faster) | -| **Main Thread Context** | Large (bloated) | Small (clean) | -| **Total Token Cost** | ~35K tokens | ~68-71K tokens (1.9-2.0x) | -| **Cost per Execution** | Standard | 2x higher | -| **Parallelism Type** | None | Concurrent (not true parallel) | -| **Analysis Depth** | One perspective | 4 independent perspectives | -| **Expert Coverage** | All in one | Code/Architecture/Security/Multi-angle | -| **API Rate Limit Risk** | Low | High (4 concurrent requests) | -| **For Enterprise Needs** | Good | Better | -| **For Cost Efficiency** | Better | Worse | -| **For Speed** | Baseline | Marginal improvement | +| Aspect | Sequential | Parallel | +|--------|-----------|----------| +| **Time** | 35-60 mins | 21-32 mins | +| **Context Usage** | 100% | 30% (main) + 40% (per agent) | +| **Main Thread Bloat** | All details accumulated | Clean, structured results only | +| **Parallelism** | None | 4 agents simultaneous | +| **Accuracy** | Good | Better (specialized agents) | +| **Maintainability** | Hard (complex single agent) | Easy (modular agents) | --- ## Technical Details -### Concurrent Execution Method +### Parallel Execution Method The orchestrator uses Claude's **Task tool** to launch sub-agents: @@ -406,7 +397,7 @@ Task(subagent_type: "general-purpose", prompt: "Security Task...") Task(subagent_type: "general-purpose", prompt: "Multi-Perspective Task...") ``` -All 4 tasks are **submitted concurrently** in a single message block. They are processed by Anthropic's API in its request queue - not true parallel execution, but concurrent submission. +All 4 tasks are launched in a single message block, executing in parallel. ### Result Collection @@ -458,33 +449,25 @@ Once all 4 agents complete, synthesis begins. ## Version History -### Version 2.1.0 (Reality-Checked Concurrent Architecture) -- Honest performance claims (20-30% faster, not 40-50%) -- Accurate token cost analysis (1.9-2.0x, not 60-70% savings) -- Concurrent execution (not true parallel) -- Context isolation in sub-agents -- When-to-use guidance (enterprise vs. cost-sensitive) -- Links to REALITY.md, ARCHITECTURE.md, TOKEN-USAGE.md -- API rate limit documentation +### Version 2.0.0 (Parallel Architecture) +- Parallel sub-agent execution (4 agents simultaneous) +- Context efficiency improvements (60-70% reduction) +- Performance improvement (40-50% faster) +- Specialized agents with focused scope +- Clean main thread context +- Modular architecture -### Version 2.0.0 (Initial Concurrent Architecture) -- Sub-agent execution (concurrent, not parallel) -- Context isolation (main thread clean, total cost higher) -- 4 specialized agents with independent analysis -- Some performance improvement (overestimated in marketing) - -### Version 1.0.0 (Sequential Single-Agent Architecture) +### Version 1.0.0 (Sequential Architecture) - Single agent implementation - All stages in sequence - Deprecated in favor of v2.0.0 --- -**Status:** Production Ready (Enterprise/Quality-Critical Work) -**Architecture:** Concurrent Agent Execution -**Best For:** Thorough multi-perspective code review -**Cost:** 2x token multiplier vs. single agent -**Speed:** 20-30% improvement over single agent -**Recommendation:** Use for enterprise. Use single agents for everyday reviews. +**Status:** Production Ready +**Architecture:** Parallel with Sub-Agents +**Context Efficiency:** Optimized +**Performance:** High-speed execution +**Marketplace:** Yes -For honest assessment, see [REALITY.md](REALITY.md). For technical details, see [ARCHITECTURE.md](ARCHITECTURE.md). For token costs, see [TOKEN-USAGE.md](TOKEN-USAGE.md). +The future of code review: Fast, clean, parallel, focused.