claude-skills/master-orchestrator.md

---
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 - Parallel Architecture

**The Ultimate High-Performance Code Quality Pipeline**

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

```
┌─────────────────────────────────────────────────────────────┐
│         MASTER ORCHESTRATOR (Main Thread)                   │
└─────────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │ Stage 1: Git Prep │ (Sequential)      │
        └───────────────────┼───────────────────┘
                            │
        ┌───────────────────▼───────────────────┐
        │  PARALLEL AGENT EXECUTION              │
        │  (All running 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

### Parallel Phase: Analysis
**All 4 agents run simultaneously (Stages 2-5)**

These agents work **completely independently**, each focusing on their specialty:

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 Efficiency

### 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)
- 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
```

**Result: 60-70% reduction in context usage across entire pipeline**

---

## Performance Improvement

### Execution Time

**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**

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

---

## 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

✅ **Perfect For:**
- Feature branches ready for merge
- Security-critical changes
- Complex architectural changes
- Release preparation
- Team code reviews
- Enterprise deployments
- Projects with complex codebases

✅ **Speed Benefits:**
- Large codebases (200+ files)
- Complex features (multiple modules)
- Security-sensitive work
- Quality-critical decisions

---

## 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/
   ```

---

## Benefits

| 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

### Parallel 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 launched in a single message block, executing in parallel.

### 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.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 1.0.0 (Sequential Architecture)
- Single agent implementation
- All stages in sequence
- Deprecated in favor of v2.0.0

---

**Status:** Production Ready
**Architecture:** Parallel with Sub-Agents
**Context Efficiency:** Optimized
**Performance:** High-speed execution
**Marketplace:** Yes

The future of code review: Fast, clean, parallel, focused.