SA Workflow — Claude Code Multi-Agent Orchestration

A production-style solution architect workflow built entirely with Claude Code subagents. Three phases, nine specialized AI agents, one human in the loop at every gate.

This repo contains the agent definitions, orchestration logic, and a complete end-to-end example run for a fictional company called AuroraStream — a streaming platform migrating to AWS.

---

What This Is

Manual SA workflows look like this:

Discovery meeting prep  →  Architecture design  →  Architecture review
(5 prompt templates)       (6 prompt templates)     (5 prompt templates)

This repo replaces each manual prompt with a specialized Claude Code subagent that runs autonomously, writes files to disk, and hands off to the next agent — with a human checkpoint at every phase boundary.

Phase 1: Discovery    →  Gate 1  →  Phase 2: Design    →  Gate 2  →  Phase 3: Validation
discovery-agent              design-agent                    security-validator
                             diagram-agent                   scalability-validator
                             iac-agent                       cost-validator
                             documentation-agent             red-team-cto

The SA never skips a gate. AI does the 70–80% draft. The human adds the 20–30% that matters.

---

The Agents

Agent	Phase	What It Does
discovery-agent	1	Company research, stakeholder mapping, discovery questions, post-meeting processing
design-agent	2	Three architecture options with trade-off analysis
diagram-agent	2	Architecture diagram using Python diagrams library
iac-agent	2	Modular Terraform — vpc, compute, data, security, observability
documentation-agent	2	ADRs, reference architectures, architecture summary
security-validator	3	PCI DSS / compliance gap analysis
scalability-validator	3	Performance bottleneck and scaling risk analysis
cost-validator	3	Monthly AWS cost estimate with optimization recommendations
red-team-cto	3	CTO-skeptic challenge questions with prepared answers

---

Customer Workspace

Each engagement lives in customers/<company-slug>/:

customers/
  aurorastream/                    ← example run (full output)
    project-context.md             ← living doc, updated at every gate
    00-discovery/
      company-brief.md
      stakeholder-map.md
      questions.md
      meeting-summary.md
      requirements.md
      gap-analysis.md
      follow-up.md
    01-design/
      architecture-options.md
      reference-architectures.md
      aurorastream-architecture.png
      ADR-001-migration-strategy.md
      ADR-002-compute-strategy.md
      ADR-003-database-choice.md
      ADR-004-media-pipeline.md
      ADR-005-cdn-apac-strategy.md
      ADR-006-data-residency-controls.md
      ADR-007-iac-tooling.md
      architecture-summary.md
      terraform/
    02-validation/
      security-report.md
      scalability-report.md
      cost-estimate.md
      cto-qa-prep.md
      validation-summary.md
  _template/                       ← blank workspace for new engagements

---

Requirements

• Claude Code (CLI or desktop app)
• Claude Max or API access with subagent support
• AWS CLI configured (for the pricing MCP server)
• Python diagrams library (pip install diagrams) for architecture diagrams
• Node.js for mcp-remote (AWS knowledge MCP)

MCP Servers (optional but recommended)

The .claude/settings.json includes MCP server configs for:

Server	Purpose
awslabs.core-mcp-server	Core AWS utilities
awslabs.aws-documentation-mcp-server	AWS docs lookup
awslabs.aws-pricing-mcp-server	Live pricing queries
awslabs.cdk-mcp-server	CDK construct docs
awslabs.aws-diagram-mcp-server	Diagram generation
awslabs.terraform-mcp-server	Terraform module docs
aws-knowledge-mcp-server	AWS knowledge base

Install with: pip install awslabs.core-mcp-server awslabs.aws-documentation-mcp-server awslabs.aws-pricing-mcp-server awslabs.cdk-mcp-server awslabs.aws-diagram-mcp-server awslabs.terraform-mcp-server (requires uvx)

---

Quickstart

1. Clone the repo and open it in Claude Code
2. Say: "new customer" or "start engagement"
3. The principal agent runs a 6-question intake to populate project-context.md
4. Confirm: "proceed with Phase 1"
5. Discovery agent runs — presents output at Gate 1A (company brief) and Gate 1B (questions)
6. After the meeting: paste your raw notes → Gate 1C
7. Confirm: "proceed with Phase 2"
8. Design, diagram, IaC, and documentation agents run in sequence
9. Gate 2 — review and revise the full package
10. Confirm: "proceed with Phase 3"
11. Four validation agents run in parallel
12. Gate 3 — final review, accept or revise

---

Example: AuroraStream

The customers/aurorastream/ folder is a complete end-to-end run for a fictional streaming platform:

• Company: AuroraStream — Series B, 8M subscribers, APAC expansion, GDPR/data residency constraints
• Stakeholders: CTO (cost mandate), VP Engineering (reliability), Head of Data (latency SLAs), CISO (PCI DSS)
• Architecture decision: Hybrid ECS Fargate + Aurora PostgreSQL + CloudFront CDK deployment

Key outputs:

• Architecture diagram
• 7 Architecture Decision Records
• Terraform modules
• Security, scalability, cost, and CTO validation reports

---

Decision Analysis Framework

Every architectural recommendation in this workflow is evaluated on six axes:

1. Cost — initial + ongoing operational
2. Timeline — implementation time, learning curve
3. Team Capability — current skills, training needs
4. Leadership Alignment — risk tolerance, strategic direction, politics
5. Technical Fit — scalability, reliability, security, maintainability
6. Vendor Lock-in — portability, exit strategy

---

Philosophy

AI gives speed and breadth. The human provides depth, context, and judgment.

This workflow produces 70–80% complete drafts — not perfect documents. The SA adds the customer relationship layer: the off-hand comment in the meeting, the political context the TAM shared, the gut feel about what the CISO will actually accept.

The gates are not optional. They are the workflow.

---

License

MIT — use it, adapt it, build on it.