672bdacc8d
This update corrects misleading performance and cost claims in the documentation: CORRECTED CLAIMS: - Performance: Changed from "40-50% faster" to "20-30% faster" (honest observation) - Token Cost: Changed from "60-70% savings" to "1.9-2.0x more expensive" (actual cost) - Parallelism: Clarified "concurrent requests" vs "true parallel execution" - Architecture: Updated from "parallel" to "concurrent" throughout NEW DOCUMENTATION: - REALITY.md: Honest assessment and reality vs. marketing - ARCHITECTURE.md: Technical details on concurrent vs. parallel execution - TOKEN-USAGE.md: Detailed token cost breakdown and optimization strategies UPDATED FILES: - master-orchestrator.md: Accurate performance, cost, and when-to-use guidance - README.md: Updated architecture overview and trade-offs KEY INSIGHTS: - Concurrent agent architecture IS valuable but for different reasons: * Main thread context is clean (20-30% of single-agent size) * 4 independent expert perspectives (genuine value) * API rate limiting affects actual speed (20-30% typical) * Cost is 1.9-2.0x tokens vs. single agent analysis - Best for enterprise quality-critical work, NOT cost-efficient projects - Includes decision matrix and cost optimization strategies This update maintains technical accuracy while preserving the genuine benefits of multi-perspective analysis and context isolation that make the system valuable.
491 lines
17 KiB
Markdown
491 lines
17 KiB
Markdown
---
|
|
name: master-orchestrator
|
|
title: Master Workflow Orchestrator - Parallel Architecture
|
|
version: 2.0.0
|
|
author: Svrnty Development Team
|
|
category: code-review
|
|
keywords: [orchestrator, master-workflow, parallel, code-review, security, architecture]
|
|
description: High-performance orchestrator that launches specialized sub-agents in parallel for code review, security, architecture, and multi-perspective analysis. Keeps context clean by delegating to focused agents while maintaining overall workflow coordination.
|
|
icon: ✓
|
|
activation_phrases:
|
|
- "@master"
|
|
- "master workflow"
|
|
- "complete workflow"
|
|
- "finish session"
|
|
- "full pipeline"
|
|
- "wrap up and push"
|
|
min_claude_version: 3.5
|
|
requires_agents:
|
|
- code-review-agent
|
|
- architecture-audit-agent
|
|
- security-compliance-agent
|
|
- multi-perspective-agent
|
|
---
|
|
|
|
# Master Workflow Orchestrator - Concurrent Agent Architecture
|
|
|
|
**Multi-Perspective Code Quality Analysis 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.
|
|
|
|
## Architecture Overview
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ MASTER ORCHESTRATOR (Main Thread) │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
┌───────────────────┼───────────────────┐
|
|
│ Stage 1: Git Prep │ (Sequential) │
|
|
└───────────────────┼───────────────────┘
|
|
│
|
|
┌───────────────────▼───────────────────┐
|
|
│ CONCURRENT AGENT EXECUTION │
|
|
│ (Requests submitted simultaneously) │
|
|
└─────────────────────────────────────────┘
|
|
│ │ │ │
|
|
▼ ▼ ▼ ▼
|
|
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
|
│ Code Review │ │ Architecture │ │ Security & │ │ Multi-Perspective
|
|
│ Agent │ │ Audit Agent │ │ Compliance │ │ PR Review Agent
|
|
│ (Stage 2) │ │ (Stage 3) │ │ Agent │ │ (Stage 5)
|
|
│ │ │ │ │ (Stage 4) │ │
|
|
│ Analyzes: │ │ Analyzes: │ │ │ │ Reviews:
|
|
│ - Code style │ │ - Structure │ │ Checks: │ │ - Product value
|
|
│ - Readability│ │ - Design │ │ - OWASP Top10│ │ - Dev quality
|
|
│ - Duplicates │ │ - Patterns │ │ - Secrets │ │ - QA coverage
|
|
│ - Errors │ │ - Coupling │ │ - Vulns │ │ - Security risk
|
|
│ - Secrets │ │ - Debt │ │ - Compliance │ │ - DevOps readiness
|
|
│ - Tests │ │ - Metrics │ │ - Encryption │ │ - Design system
|
|
│ │ │ │ │ │ │
|
|
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
|
|
│ │ │ │
|
|
└──────────────┬──────────────┴──────────────┘
|
|
│
|
|
┌────────────────────▼────────────────────┐
|
|
│ Stage 6: Synthesis & Prioritization │
|
|
│ (Orchestrator waits for all results) │
|
|
│ - Consolidate findings │
|
|
│ - Identify critical blockers │
|
|
│ - Prioritize by severity │
|
|
│ - Create action plan │
|
|
└────────────────────┬────────────────────┘
|
|
│
|
|
┌────────────────────▼────────────────────┐
|
|
│ Stage 7-9: Sequential (Main Thread) │
|
|
│ - Interactive issue resolution │
|
|
│ - Final pre-push verification │
|
|
│ - Safe git operations & push │
|
|
└────────────────────────────────────────┘
|
|
```
|
|
|
|
## How It Works
|
|
|
|
### Sequential Phase 1: Git Preparation
|
|
**Runs in main thread (Stage 1)**
|
|
- Check git status
|
|
- Verify branch safety
|
|
- Identify changes
|
|
- Prepare context for sub-agents
|
|
|
|
### Concurrent Phase: Analysis
|
|
**All 4 agents are invoked concurrently (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:
|
|
|
|
1. **Code Review Agent** (Stage 2)
|
|
- Focuses on code quality issues
|
|
- Detects secrets, duplicates, errors
|
|
- Analyzes recent changes
|
|
- **Cleans up context after** (keeps main thread clean)
|
|
|
|
2. **Architecture Audit Agent** (Stage 3)
|
|
- Analyzes 6 dimensions independently
|
|
- Evaluates design patterns
|
|
- Assesses technical debt
|
|
- **Returns structured results** to orchestrator
|
|
|
|
3. **Security & Compliance Agent** (Stage 4)
|
|
- OWASP Top 10 validation
|
|
- Dependency scanning
|
|
- Secrets/key detection
|
|
- **Focused security analysis** only
|
|
|
|
4. **Multi-Perspective Agent** (Stage 5)
|
|
- Product perspective
|
|
- Dev perspective
|
|
- QA perspective
|
|
- Security perspective
|
|
- DevOps perspective
|
|
- Design perspective
|
|
- **Clean, focused feedback** without code details
|
|
|
|
### Synthesis Phase: Results Collection
|
|
**Runs in main thread (Stage 6)**
|
|
- Orchestrator **waits** for all 4 agents to complete
|
|
- Collects results from each agent
|
|
- **No context bloat** (each agent already summarized)
|
|
- Synthesizes into single action plan
|
|
- Prioritizes by severity
|
|
|
|
### Sequential Phase 2: Action & Push
|
|
**Runs in main thread (Stages 7-9)**
|
|
- Interactive issue resolution
|
|
- Pre-push verification
|
|
- Safe git push
|
|
|
|
---
|
|
|
|
## Context Architecture
|
|
|
|
### Main Thread Context (✅ Optimized)
|
|
```
|
|
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
|
|
```
|
|
|
|
### 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.**
|
|
|
|
---
|
|
|
|
## Execution Time Comparison
|
|
|
|
### 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**
|
|
|
|
### 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%)**
|
|
|
|
**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.
|
|
|
|
---
|
|
|
|
## Stage Details
|
|
|
|
### Stage 1: Git Preparation (Main Thread)
|
|
```
|
|
STAGE 1: GIT STATUS & PREPARATION
|
|
✓ Current branch: feature/my-feature
|
|
✓ Modified files: 12 files, 687 additions, 156 deletions
|
|
✓ Ready to launch parallel agents
|
|
```
|
|
|
|
**Then launches 4 sub-agents in parallel...**
|
|
|
|
### Stage 2: Code Review (Sub-Agent)
|
|
- Runs in: **code-review-agent**
|
|
- Output: Critical issues, warnings, suggestions
|
|
- Returns to main thread with: Structured findings
|
|
|
|
### Stage 3: Architecture Audit (Sub-Agent)
|
|
- Runs in: **architecture-audit-agent**
|
|
- Output: 6-dimension analysis with scores
|
|
- Returns to main thread with: Architecture findings
|
|
|
|
### Stage 4: Security & Compliance (Sub-Agent)
|
|
- Runs in: **security-compliance-agent**
|
|
- Output: OWASP assessment, vulnerabilities, compliance
|
|
- Returns to main thread with: Security findings
|
|
|
|
### Stage 5: Multi-Perspective Review (Sub-Agent)
|
|
- Runs in: **multi-perspective-agent**
|
|
- Output: 6 stakeholder perspectives
|
|
- Returns to main thread with: Consolidated feedback
|
|
|
|
### Stage 6: Synthesis & Prioritization (Main Thread)
|
|
```
|
|
STAGE 6: SYNTHESIS & PRIORITIZATION
|
|
Consolidating results from 4 parallel agents...
|
|
|
|
CRITICAL BLOCKERS (from all agents)
|
|
- SQL injection (Security Agent)
|
|
- Hardcoded key (Code Review + Security Agents)
|
|
- Missing tests (Code Review + QA Agent)
|
|
|
|
HIGH PRIORITY
|
|
- Code duplication (Code Review Agent)
|
|
- High coupling (Architecture Agent)
|
|
- [... consolidated list ...]
|
|
|
|
Estimated remediation: 45 minutes
|
|
```
|
|
|
|
### Stages 7-9: Sequential (Main Thread)
|
|
- Interactive issue resolution
|
|
- Final verification
|
|
- Safe git push
|
|
|
|
---
|
|
|
|
## Sub-Agent Communication
|
|
|
|
### How Agents Receive Input
|
|
|
|
Each sub-agent receives:
|
|
```
|
|
{
|
|
"git_diff": "Recent changes content",
|
|
"file_list": ["file1.py", "file2.js", ...],
|
|
"project_type": "detected type",
|
|
"language": "detected language",
|
|
"recent_changes": "summary of changes"
|
|
}
|
|
```
|
|
|
|
### How Agents Return Results
|
|
|
|
Each sub-agent returns:
|
|
```
|
|
{
|
|
"stage": 2, // or 3, 4, 5
|
|
"findings": [
|
|
{ "severity": "critical", "issue": "...", "location": "file:line" },
|
|
{ "severity": "warning", "issue": "...", "suggestion": "..." }
|
|
],
|
|
"summary": "X critical, Y warnings, Z suggestions",
|
|
"remediation_time": "minutes",
|
|
"quick_wins": ["item1", "item2"]
|
|
}
|
|
```
|
|
|
|
### Context Cleanup
|
|
|
|
Each sub-agent:
|
|
1. Receives task-specific data
|
|
2. Performs focused analysis
|
|
3. Returns structured results
|
|
4. **Exits and cleans up context** (important for efficiency)
|
|
5. Main thread collects lightweight results
|
|
|
|
This prevents context bloat from accumulating across all analyses.
|
|
|
|
---
|
|
|
|
## When to Use This (vs. Single Agent)
|
|
|
|
✅ **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)
|
|
|
|
❌ **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)
|
|
|
|
---
|
|
|
|
## Parallel Agent Requirements
|
|
|
|
This orchestrator requires these sub-agents to be installed:
|
|
|
|
1. **code-review-agent** - Code quality and review
|
|
2. **architecture-audit-agent** - Design and architecture
|
|
3. **security-compliance-agent** - Security validation
|
|
4. **multi-perspective-agent** - Stakeholder feedback
|
|
|
|
Each agent is available as a separate skill and can also be used independently.
|
|
|
|
---
|
|
|
|
## Usage
|
|
|
|
### Invoke the Orchestrator
|
|
|
|
```
|
|
@master
|
|
```
|
|
|
|
The orchestrator will:
|
|
1. Execute Stage 1 (git prep)
|
|
2. **Launch 4 agents in parallel** automatically
|
|
3. Wait for all to complete
|
|
4. Synthesize results
|
|
5. Continue with Stages 7-9
|
|
|
|
### Alternative Invocations
|
|
|
|
```
|
|
"complete workflow"
|
|
"finish session"
|
|
"full pipeline"
|
|
"wrap up and push"
|
|
```
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
1. **Install main orchestrator:**
|
|
```bash
|
|
cp master-orchestrator.md ~/.claude/skills/
|
|
```
|
|
|
|
2. **Install sub-agents:**
|
|
```bash
|
|
cp code-review-agent.md ~/.claude/skills/
|
|
cp architecture-audit-agent.md ~/.claude/skills/
|
|
cp security-compliance-agent.md ~/.claude/skills/
|
|
cp multi-perspective-agent.md ~/.claude/skills/
|
|
```
|
|
|
|
3. **Or copy all at once:**
|
|
```bash
|
|
cp *.md ~/.claude/skills/
|
|
```
|
|
|
|
---
|
|
|
|
## Honest Comparison: Single Agent vs. Concurrent Agents
|
|
|
|
| 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 |
|
|
|
|
---
|
|
|
|
## Technical Details
|
|
|
|
### Concurrent Execution Method
|
|
|
|
The orchestrator uses Claude's **Task tool** to launch sub-agents:
|
|
|
|
```
|
|
Task(subagent_type: "general-purpose", prompt: "Code Review Task...")
|
|
Task(subagent_type: "general-purpose", prompt: "Architecture Task...")
|
|
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.
|
|
|
|
### Result Collection
|
|
|
|
The orchestrator waits for all results using blocking collection:
|
|
```
|
|
results = [
|
|
await code_review_agent,
|
|
await architecture_agent,
|
|
await security_agent,
|
|
await multi_perspective_agent
|
|
]
|
|
```
|
|
|
|
Once all 4 agents complete, synthesis begins.
|
|
|
|
---
|
|
|
|
## What Each Agent Does (Quick Reference)
|
|
|
|
### Code Review Agent
|
|
- **Focuses on:** Code quality, readability, errors, secrets
|
|
- **Analyzes:** Recent git changes only
|
|
- **Detects:** Duplicates, missing error handling, exposed keys, test gaps
|
|
- **Time:** 5-10 minutes
|
|
- **Context:** Code diffs and recent changes
|
|
|
|
### Architecture Audit Agent
|
|
- **Focuses on:** Design, patterns, coupling, technical debt
|
|
- **Analyzes:** Full codebase structure
|
|
- **Evaluates:** 6 dimensions (architecture, quality, security, perf, testing, maintainability)
|
|
- **Time:** 10-15 minutes
|
|
- **Context:** File structure and module relationships
|
|
|
|
### Security & Compliance Agent
|
|
- **Focuses on:** Security vulnerabilities and compliance
|
|
- **Checks:** OWASP Top 10, dependency vulnerabilities, secrets
|
|
- **Analyzes:** Security-specific patterns only
|
|
- **Time:** 8-12 minutes
|
|
- **Context:** Code for security issues only
|
|
|
|
### Multi-Perspective Agent
|
|
- **Focuses on:** Stakeholder feedback
|
|
- **Provides:** 6 perspectives (Product, Dev, QA, Security, DevOps, Design)
|
|
- **Avoids:** Code details (uses findings from other agents)
|
|
- **Time:** 5-8 minutes
|
|
- **Context:** Feature description and requirements only
|
|
|
|
---
|
|
|
|
## 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 (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)
|
|
- 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.
|
|
|
|
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).
|