/solution-architect

name: solution-architect
description: >
  [production-grade internal] Designs system architecture when you need to
  decide tech stack, API contracts, data models, or infrastructure shape.
  Routed via the production-grade orchestrator.

Solution Architect

Protocols

!`cat Claude-Production-Grade-Suite/.protocols/ux-protocol.md 2>/dev/null || true` !`cat Claude-Production-Grade-Suite/.protocols/input-validation.md 2>/dev/null || true` !`cat Claude-Production-Grade-Suite/.protocols/tool-efficiency.md 2>/dev/null || true` !`cat Claude-Production-Grade-Suite/.protocols/visual-identity.md 2>/dev/null || true` !`cat Claude-Production-Grade-Suite/.protocols/freshness-protocol.md 2>/dev/null || true` !`cat Claude-Production-Grade-Suite/.protocols/receipt-protocol.md 2>/dev/null || true` !`cat Claude-Production-Grade-Suite/.protocols/boundary-safety.md 2>/dev/null || true` !`cat Claude-Production-Grade-Suite/.protocols/loop-protocol.md 2>/dev/null || true` !`cat Claude-Production-Grade-Suite/.protocols/conflict-resolution.md 2>/dev/null || true` !`cat Claude-Production-Grade-Suite/.protocols/platform-adaptation.md 2>/dev/null || true`

**Portability:** the `` !` `` lines above are preamble commands; if your host did not auto-execute them, run them yourself. If any tool this skill names is missing in your environment, apply `platform-adaptation.md` (workspace `.protocols/` copy, or `skills/_shared/` in this plugin's repo) — same guarantees, host-native mechanisms.

!`cat .production-grade.yaml 2>/dev/null || echo "No config — using defaults"` !`cat Claude-Production-Grade-Suite/.orchestrator/codebase-context.md 2>/dev/null || true`

**Fallback (if protocols not loaded):** Use AskUserQuestion with options (never open-ended), "Chat about this" last, recommended first. Work continuously. Print progress constantly. Validate inputs before starting — classify missing as Critical (stop), Degraded (warn, continue partial), or Optional (skip silently). Use parallel tool calls for independent reads. Use Glob before Read to map file structure. No oracle, no loop — never iterate without an executable exit check; never edit or weaken tests you must pass (tests/ is QA-owned).

Brownfield Awareness

If `Claude-Production-Grade-Suite/.orchestrator/codebase-context.md` exists and mode is `brownfield`:

• **READ existing architecture first** — understand current patterns, tech stack, API structure
• **Design around existing code** — new architecture extends the system, doesn't replace it
• **Document existing patterns in ADRs** — capture what's already decided
• **API contracts must be backward-compatible** — new endpoints, not breaking changes
• **Don't redesign what works** — focus architecture on the NEW features/requirements

Engagement Mode

!`cat Claude-Production-Grade-Suite/.orchestrator/settings.md 2>/dev/null || echo "No settings — using Standard"`

Read `Claude-Production-Grade-Suite/.orchestrator/settings.md` at startup. Adapt discovery depth:

| Mode | Discovery Approach | |------|-------------------| | **Express** | Auto-derive from BRD. Ask only if critical info missing. Conservative defaults. | | **Standard** | 5-7 questions across 2 rounds. Scale sizing + constraints. Fitness-derived architecture. | | **Thorough** | 12-15 questions across 4 structured rounds. Full capacity planning. Trade-off analysis. Architecture alternatives. | | **Meticulous** | Everything in Thorough + individual ADR approval, tech stack walkthrough, capacity modeling with cost estimates. |

Progress Output

Follow `Claude-Production-Grade-Suite/.protocols/visual-identity.md`. Print structured progress throughout execution.

**Skill header** (print on start):

━━━ Solution Architect ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**Phase progress** (print during execution):

  [1/5] Constraint Discovery
    ✓ Scale: {users}, {CCU}, {constraints}
    ⧖ analyzing compliance requirements...
    ○ fitness function

  [2/5] Architecture Design
    ✓ Pattern: {pattern}, {N} ADRs
    ⧖ generating system diagrams...
    ○ user review

  [3/5] API Contracts
    ✓ {N} OpenAPI specs, {M} endpoints
    ⧖ defining error schemas...
    ○ versioning strategy

  [4/5] Data Model
    ✓ ERD: {N} entities, {M} migrations
    ⧖ writing migration files...
    ○ audit trail schema

  [5/5] Scaffold
    ✓ Project structure generated
    ⧖ writing Dockerfiles...
    ○ docker-compose

**Completion summary** (print on finish — MUST include concrete numbers):

✓ Solution Architect    {pattern}, {N} ADRs, {M} endpoints, scaffold generated    ⏱ Xm Ys

Overview

Full architecture pipeline: from business requirements to a scaffolded, production-ready codebase. The architecture is DERIVED from project constraints (scale, team, budget, compliance) — not picked from a template. There is no one-size-fits-all architecture.

Generates architecture deliverables at the project root (`api/`, `schemas/`, `docs/architecture/`, project scaffold) with workspace artifacts in `Claude-Production-Grade-Suite/solution-architect/`.

Config Paths

Read `.production-grade.yaml` at startup. Use these overrides if defined:

• `paths.api_contracts` — default: `api/`
• `paths.adrs` — default: `docs/architecture/architecture-decision-records/`
• `paths.architecture_docs` — default: `docs/architecture/`
• `paths.erd` — default: `schemas/erd.md`
• `paths.migrations` — default: `schemas/migrations/`
• `paths.tech_stack` — default: `docs/architecture/tech-stack.md`

Deliverables go to the **project root** (`api/`, `schemas/`, `docs/architecture/`). Workspace artifacts go to `Claude-Production-Grade-Suite/solution-architect/`.

When to Use

• Designing a new SaaS product or platform
• Planning microservices or service-oriented architecture
• Selecting tech stacks for production systems
• Creating API contracts and data models
• Scaffolding multi-cloud, production-grade projects
• Architecture review or modernization of existing systems

Proce