Architecture

Design the technical architecture for a set of requirements: components, data flow, dependency graph, tech stack decisions, integration points, and risks.

When to Use

A PRD exists and the technical approach needs to be designed
Before task breakdown — architecture defines WHAT components exist; breakdown defines the ORDER to build them
When architectural decisions need to be documented (data model, API design, component structure)
When integration with existing systems requires explicit mapping

When NOT to use: The technical approach is already documented in an architecture.md, or the change is trivial (single file, no architectural decisions).

Input

prd.md from the artifact folder (required)
context-map.md from the artifact folder (required — for tech stack and existing patterns)
brainstorming.md from the artifact folder (recommended — for chosen direction rationale)

Output

architecture.md saved to the artifact folder (see references/formats.md for template)

The Process

Step 1: Load Upstream Artifacts

Read prd.md, context-map.md, and optionally brainstorming.md from the artifact folder. If prd.md or context-map.md is missing, tell the user which skill to run first.

Extract:

User stories and functional requirements (from PRD)
Tech stack, patterns, and conventions (from context map)
Chosen direction and trade-offs accepted (from brainstorming)

Step 2: Identify Components

From the PRD requirements, identify the distinct components needed:

Data layer: schemas, models, migrations
Backend logic: services, business rules, validation
API layer: endpoints, routes, middleware
Frontend components: views, forms, widgets
Shared utilities: helpers, types, constants

For each component, define:

Responsibility — what it does (single responsibility)
Location — where it lives in the project (follow existing conventions from context map)
Interface — key functions, endpoints, or props it exposes
Dependencies — what other components it needs

Follow existing codebase patterns. If the project uses a service layer pattern, use it. If components are colocated with tests, follow that. Do not invent new patterns when existing ones work.

Step 3: Map Data Flow

Describe how data moves through the system for the key user stories:

[User Action]
  → [Frontend Component] (handles UI state)
    → [API Call] (request to backend)
      → [Route Handler] (validation, auth)
        → [Service] (business logic)
          → [Database] (persistence)
        ← [Response]
      ← [API Response]
    ← [UI Update] (re-render with new data)

Cover the primary happy path and the most important error path.

Step 4: Build Dependency Graph

Map what must be built before what. This directly feeds the task breakdown:

[Database Schema / Migrations]
    ├── [Types / Interfaces]
    │       ├── [Service Layer]
    │       │       ├── [API Endpoints]
    │       │       │       └── [Frontend API Client]
    │       │       │               └── [UI Components]
    │       │       └── [Validation Logic]
    │       └── [Test Utilities]
    └── [Seed Data]

Implementation order follows the graph bottom-up: foundations first.

Step 5: Document Tech Decisions

For every non-trivial technical choice, record:

Decision	Choice	Rationale
State management	[e.g. URL params + React state]	[Why — aligns with existing pattern, simpler than Redux for this scope]
Data fetching	[e.g. SWR with optimistic updates]	[Why — already in the stack, handles caching]
Validation	[e.g. Zod schemas shared client/server]	[Why — single source of truth, TypeScript inference]

Do not introduce new dependencies without justification. Check the existing stack first (context map).

Step 6: Map Integration Points

How does this feature connect to what already exists?

Which existing files will be modified?
Which existing APIs will be consumed?
Which existing components will be extended or composed?
Are there database schema changes that affect other features?

Step 7: Define Boundaries

State what is and isn't allowed during implementation:

Always: [e.g. follow existing naming conventions, write tests for new logic, use existing error handling patterns]
Ask first: [e.g. adding new dependencies, changing shared types, modifying database schema]
Never: [e.g. bypass validation, commit secrets, modify unrelated code]

Step 8: Identify Risks

Risk	Impact	Mitigation
[e.g. Schema migration breaks existing queries]	High	[Run migration in staging first, write rollback]
[e.g. New endpoint conflicts with existing route]	Medium	[Check route registry before adding]

Flag high-risk items — these should be tackled early in the task breakdown (fail fast).

Step 9: Write and Save Architecture Document

Write architecture.md to the artifact folder using the template from references/formats.md.

Present the architecture to the user for review. Walk through:

Component overview
Data flow for the primary user story
Key tech decisions and their rationale
Any risks or open questions

Apply requested changes, then save.

Announce the saved path:

"Architecture saved to [path]/architecture.md."

Common Rationalizations

Rationalization	Reality
"I'll figure out the architecture while coding"	Architecture decisions made under implementation pressure are worse. 15 minutes of design saves hours of refactoring.
"This is too small for an architecture document"	If it touches 3+ files or makes a tech decision, write it down. A short document is fine.
"The PRD already describes the technical approach"	PRD describes WHAT. Architecture describes HOW — components, data flow, dependencies. Different concerns.
"I know the codebase, I don't need to document integration points"	The task breakdown skill and any agent doing implementation will need this documented. Write it for them.
"We can refactor later if the architecture is wrong"	Wrong architecture is the most expensive kind of rework. Get it right in a document before committing to code.

Red Flags

No dependency graph — implementation order will be wrong
Components that don't follow existing codebase patterns
New dependencies added without checking what's already in the stack
No integration points mapped — feature will break existing functionality
Empty risks section — every architecture has risks
Writing code during the architecture phase

Verification

Before handing off, confirm:

"Architecture complete. Next recommended skill: breakdown — slice this into ordered, interlinked development tasks."