claude-skills/master-orchestrator.md

name	title	version	author	category	keywords	description	icon	activation_phrases	min_claude_version	requires_agents
master-orchestrator	Master Workflow Orchestrator - Parallel Architecture	2.0.0	Svrnty Development Team	code-review	orchestrator master-workflow parallel code-review security architecture	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.	✓	@master master workflow complete workflow finish session full pipeline wrap up and push	3.5	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 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 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 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:

   cp master-orchestrator.md ~/.claude/skills/
   

2. Install sub-agents:

   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:

   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. For technical details, see ARCHITECTURE.md. For token costs, see TOKEN-USAGE.md.