START
  │
  ▼
┌─────────────────────────┐
│ Read docs/PRD.md        │ ◄── Load the PRD into context
└──────────┬──────────────┘
           │
           ▼
┌─────────────────────────┐
│ Analyze & Clarify       │ ◄── Ask questions if PRD has gaps
└──────────┬──────────────┘
           │
           ▼
┌─────────────────────────┐
│ Confirm with user       │ ◄── Summarize approach, get approval
└──────────┬──────────────┘
           │
           ▼
┌─────────────────────────┐
│ Generate Architecture   │ ◄── Write to docs/ARCHITECTURE.md
└─────────────────────────┘

Step 1: Read the PRD

Read docs/PRD.md to understand:

What the product does and who uses it
User scenarios and flows
Tech stack specified (or constraints)
Scope boundaries (MVP vs future)

If docs/PRD.md doesn't exist, ask the user to provide requirements or suggest using the product-design skill first.

Step 2: Analyze & Clarify

Identify gaps that would block architecture decisions:

Ambiguous scaling requirements?
Missing auth/authorization details?
Unclear data relationships?
Integration specifics missing?

Ask targeted questions. Don't over-ask—only what's needed to make architecture decisions.

Step 3: Confirm with User

Before generating, summarize:

The high-level approach (e.g., "monolith with clear module boundaries" vs "microservices")
Key technical choices and why
Any tradeoffs being made

Ask if they're ready to proceed or want to adjust the approach.

Step 4: Generate Architecture Document

Write to docs/ARCHITECTURE.md (create directory if needed) using the template below.

Architecture Document Template

# [Product Name] - Architecture

## Overview

[2-3 sentences: architectural style, key patterns, deployment model]

## High-Level Architecture

[ASCII diagram showing major components and relationships]

┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Client │────▶│ Server │────▶│ Database │ └─────────────┘ └─────────────┘ └─────────────┘


### Components
| Component | Responsibility | Technology |
|-----------|---------------|------------|
| [Name] | [What it does] | [Stack] |

## Tech Stack Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| Frontend | [e.g., Next.js] | [Why this fits the requirements] |
| Backend | [e.g., Node + Express] | [Why] |
| Database | [e.g., PostgreSQL] | [Why] |
| Auth | [e.g., Supabase Auth] | [Why] |
| Hosting | [e.g., Vercel + Railway] | [Why] |

## Directory Structure

project/ ├── src/ │ ├── app/ # [Purpose] │ ├── components/ # [Purpose] │ ├── lib/ # [Purpose] │ └── ... ├── public/ ├── tests/ └── ...


### Key Directories Explained
- `src/app/` - [What goes here and why]
- `src/lib/` - [What goes here and why]

## Key Abstractions

### [Abstraction 1 Name]
**Purpose:** [What problem it solves]
**Interface:** [Key methods/properties]
**Used by:** [Which parts of the system]

## Data Flow

[Describe data flow for key scenarios]

1. **[Scenario]**: [Step-by-step flow]

## What NOT to Over-Engineer

Keep these simple for MVP:

| Area | Keep Simple | Avoid |
|------|-------------|-------|
| Auth | Use built-in auth provider | Custom JWT infrastructure |
| State | React state/context | Redux unless proven necessary |
| API | Simple REST endpoints | GraphQL unless you need it |
| Database | Single database | Read replicas, sharding |
| Caching | None initially | Redis until you measure need |
| Validation | Validate at boundaries | Defensive checks everywhere |

## Future Considerations

[Things deliberately deferred that may influence future architecture]

- [Future need] → [How current architecture accommodates it]

Guidelines

Keep it buildable: Every section should reduce ambiguity. A developer reading this should know where to start.

Match complexity to scope: MVP architecture should be simple. Don't design for scale you don't have.

Be specific: "Use React" is less useful than "Next.js App Router with server components for data fetching."

Justify decisions: Every tech choice needs a reason tied to requirements, not preference.

Name anti-patterns: Explicitly calling out what NOT to build prevents scope creep.

architecture

Architecture

Workflow