---
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).