architect

What this skill does

# Architecture Generator

Generate an architecture document from reverse-engineering documents (hereafter "RE docs") and user constraints.

**Estimated Time:** 10-20 minutes
**Prerequisites:** Gear 2 (Reverse Engineer) completed with RE docs present
**Output:** `architecture.md` — location determined by mode detection in Step 4

This skill assumes single-session execution. If interrupted, restart from Step 1.

---

## Process

### Step 1: Load Context

Read all available RE docs from `docs/reverse-engineering/`. Read all files in parallel for speed.

**Primary architecture sources (5 files):**
- `data-architecture.md` — Current data models, API contracts, domain boundaries
- `integration-points.md` — External services, data flows, auth patterns
- `operations-guide.md` — Current deployment, infrastructure, scalability
- `decision-rationale.md` — Why current choices were made, trade-offs
- `configuration-reference.md` — Configuration landscape

**Supporting context (4 files):**
- `functional-specification.md` — What the system needs to do
- `business-context.md` — Business constraints, scale expectations, compliance
- `technical-debt-analysis.md` — What needs to change
- `observability-requirements.md` — Monitoring and logging needs

**Error handling for Step 1:**
1. Use Glob to list all files in `docs/reverse-engineering/`.
2. Compare found files against the 9 listed above. Classify each as present or missing.
3. If any primary architecture source (the first 5) is missing: report the missing files to the user and ask whether to proceed with partial context or stop. Do not silently continue.
4. If only supporting context files (the last 4) are missing: proceed, but log which files are absent. Record these gaps for the assumptions section of the architecture document.
5. If `docs/reverse-engineering/` does not exist or is empty: stop and tell the user to run Gear 2 (Reverse Engineer) first.

Log after completing Step 1: "Step 1 complete: Loaded [N] of 9 RE docs. [List any missing files.]"

### Step 2: Ask Constraint Questions

Present these questions conversationally. Skip a question only if a single unambiguous answer is directly stated in the RE docs. When skipping a question, state the detected answer and ask the user to confirm or override. If multiple options are plausible or the RE docs are silent on a topic, ask the question.

**Question 1: Tech Stack Preference**
```
What tech stack do you want for the architecture?

A) Same as current (documented in decision-rationale.md)
   [Show detected stack: e.g., "TypeScript + Next.js + PostgreSQL"]

B) Let me specify
   Ask: "What languages, frameworks, and databases?"
   Examples: "Next.js 15 + TypeScript + Prisma + PostgreSQL"
             "Python + FastAPI + SQLAlchemy + PostgreSQL"
             "Go + Gin + GORM + PostgreSQL"

C) Recommend based on requirements
   Analyze functional-specification.md + business-context.md
   Recommend stack with rationale
```

**Question 2: Deployment Target**
```
Where will this run?

A) AWS (EC2, ECS, Lambda, RDS, etc.)
B) Google Cloud (GKE, Cloud Run, Cloud SQL, etc.)
C) Azure (AKS, App Service, Azure SQL, etc.)
D) Self-hosted / On-premise
E) Hybrid (specify)
F) Recommend based on requirements
```

**Question 3: Scale Expectations**
```
What scale should the architecture support?

A) Startup / MVP
   Single-region, simple deployment, cost-optimized
   100s of users, minimal redundancy

B) Growing Product
   Multi-AZ, auto-scaling, managed services
   1,000s - 10,000s of users

C) Enterprise / High-Scale
   Multi-region, microservices-ready, full redundancy
   100,000s+ users, strict SLAs

D) Specify custom requirements
   Ask for: expected users, requests/sec, data volume, SLA targets
```

**Question 4: Hard Constraints** (free text, optional)
```
Any hard constraints to keep in mind?

Examples:
- "Must be HIPAA compliant"
- "Budget under $500/month"
- "Team of 3 developers, keep it simple"
- "Must support offline mode"
- "No vendor lock-in"
- "Must use Kubernetes"

Enter constraints or press enter to skip.
```

**Question 5: Architecture Style**
If the architecture style is clear from the RE docs, skip this question: state the detected style and ask the user to confirm or override. Otherwise, ask:
```
What architecture style fits your needs?

A) Monolith (recommended for small teams / MVPs)
   Single deployable, simpler operations
   Can be modular monolith with clear boundaries

B) Microservices (recommended for larger teams / scale)
   Independent deployments, team autonomy
   Higher operational complexity

C) Serverless (recommended for event-driven / variable load)
   Pay-per-use, auto-scaling
   Cold start considerations

D) Hybrid (specify)

E) Recommend based on team size and requirements
```

**Error handling for Step 2:**
If the user provides contradictory constraints (e.g., "budget under $100/month" and "multi-region full redundancy"), identify the conflict explicitly, explain why the constraints conflict, and ask the user to resolve before proceeding.

For "Recommend" answers on any question, analyze functional-specification.md + business-context.md + observability-requirements.md to make an informed suggestion. Present the recommendation with rationale and ask the user to confirm.

Log after completing Step 2: "Step 2 complete: Collected constraints for [N] questions. Proceeding to generation."

### Step 3: Generate Architecture Document

Using the RE docs and user constraints, generate the architecture document. Follow the template at `operations/architecture-template.md` (relative to this skill).

**Generation approach:**
1. Start from the current architecture as described in the RE docs.
2. For each architecture decision, check user constraints and select the option that satisfies all hard constraints. Where constraints conflict, prefer the user's explicit choice over inferred preferences.
3. For each component in the current architecture, determine whether it maps to the target state unchanged, needs modification, or should be replaced. Generate recommendations that bridge current to target state.
4. Create ADRs justifying each major decision. Generate 3-10 ADRs focusing on consequential decisions. Source from decision-rationale.md where available; generate new ADRs for target-state decisions.
5. Draw Mermaid diagrams for visual clarity. Use Mermaid C4 notation for system context diagrams.
6. If the RE docs indicate a brownfield/evolution scenario (existing system being migrated or modernized), generate Section 10: Migration Path using the technical-debt-analysis.md Migration Priority Matrix. If the project is greenfield with no existing system to migrate from, omit Section 10.

**Progress signals:** Announce each major section as you generate it (e.g., "Generating Section 3: System Architecture..."). This ensures all sections are produced and prevents drift during the lengthy generation.

### Step 3.5: Verify Generated Content

Before writing the final document, verify:
1. All Mermaid diagrams use valid syntax (proper node definitions, valid arrow notation, balanced subgraphs).
2. ADR decisions are consistent with the stated user constraints. No ADR should contradict a hard constraint from Step 2.
3. Cost estimates align with the chosen cloud provider and scale tier. Flag all cost estimates as rough approximations.
4. If Section 10 (Migration Path) is included, confirm it references actual current-state findings from the RE docs.
5. The technology stack table is fully populated with rationale for each choice.

If any verification check fails, fix the issue before proceeding to Step 4.

### Step 4: Detect Mode and Write Output

**Mode detection:**
- If the directory `_bmad-output/` exists in the project root, operate in BMAD mode.
- Otherwise, operate in standalone mode.

**BMAD mode:** Write to `_bmad-output/planning-artifacts/architecture.md`. If running as part of BMAD Synthesize and RE docs have already been parsed in this session, reuse the