Architecture Design

MANDATORY IMPORTANT MUST use TaskCreate to break ALL work into small tasks BEFORE starting. MANDATORY IMPORTANT MUST use AskUserQuestion at EVERY decision point — never assume user preferences. MANDATORY IMPORTANT MUST research top 3 options per architecture concern, compare with evidence, present report with recommendation + confidence %.

External Memory: For complex or lengthy work (research, analysis, scan, review), write intermediate findings and final results to a report file in plans/reports/ — prevents context loss and serves as deliverable.

Evidence Gate: MANDATORY IMPORTANT MUST — every claim, finding, and recommendation requires file:line proof or traced evidence with confidence percentage (>80% to act, <80% must verify first).

Quick Summary

Goal: Act as a solution architect — research, critically analyze, and recommend the complete technical architecture for a project or feature. Cover ALL architecture concerns: backend, frontend, design patterns, library ecosystem, testing strategy, CI/CD, deployment, monitoring, code quality, and dependency management. Produce a comprehensive comparison report with actionable recommendations.

Workflow (12 steps):

1. Load Context — Read domain model, tech stack, business evaluation, refined PBI
2. Derive Architecture Requirements — Map business/domain complexity to architecture constraints
3. Backend Architecture — Research top 3 backend architecture styles + design patterns
4. Frontend Architecture — Research top 3 frontend architecture styles + design patterns
5. Library Ecosystem Research — Best-practice libraries per concern (validation, caching, logging, utils, etc.)
6. Testing Architecture — Unit, integration, E2E, performance testing frameworks + strategy
7. CI/CD & Deployment — Pipeline design, containerization, orchestration, IaC
8. Observability & Monitoring — Logging, metrics, tracing, alerting stack
9. Code Quality & Clean Code — Linters, analyzers, formatters, enforcement tooling
10. Dependency Risk Assessment — Package health, obsolescence risk, maintenance cost
11. Generate Report — Full architecture decision report with all recommendations
12. User Validation — Present findings, ask 8-12 questions, confirm all decisions

Key Rules:

• MANDATORY IMPORTANT MUST research minimum 3 options per architecture concern with web evidence
• MANDATORY IMPORTANT MUST include confidence % with evidence for every recommendation
• MANDATORY IMPORTANT MUST run user validation interview at end (never skip)
• Delegate to solution-architect agent for complex architecture decisions
• All claims must cite sources (URL, benchmark, case study, or codebase evidence)
• Never recommend based on familiarity alone — evidence required

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

Step 1: Load Context

Read artifacts from prior workflow steps (search in plans/ and team-artifacts/):

• Domain model / ERD (complexity, bounded contexts, aggregate count)
• Tech stack decisions (confirmed languages, frameworks, databases)
• Business evaluation (scale, constraints, compliance)
• Refined PBI (scope, acceptance criteria)
• Discovery interview (team skills, experience level)

Extract and summarize:

Step 2: Derive Architecture Requirements

Map signals to architecture constraints:

MANDATORY IMPORTANT MUST validate derived requirements with user via AskUserQuestion before proceeding.

Step 3: Backend Architecture

3A: Architecture Styles

WebSearch top 3 backend architecture styles. Candidates:

3B: Backend Design Patterns

Evaluate applicability per layer:

For each recommended pattern, document: Apply to, Why, Example, Risk if skipped.

Step 4: Frontend Architecture

4A: Architecture Styles

WebSearch top 3 frontend architecture styles. Candidates:

4B: Frontend Design Patterns

Step 4B: UI System Architecture

Skip if: Backend-only project, no frontend component.

Research and recommend the project's design system architecture. Use AskUserQuestion for each decision.

4B-1: Styling Approach

WebSearch top 3 styling approaches for the confirmed frontend framework:

4B-2: Design Token Strategy

4B-3: Component Library Strategy

4B-4: Responsive Strategy

MANDATORY IMPORTANT MUST validate all UI system decisions with user via AskUserQuestion before proceeding to Step 5.

Step 5: Library Ecosystem Research

For EACH concern below, WebSearch top 3 library options for the confirmed tech stack. Evaluate: maturity, community, bundle size, maintenance activity, license, learning curve.

Library Concerns Checklist

Per-Library Evaluation Template

### {Concern}: Top 3 Options

| Criteria         | Option A          | Option B | Option C |
| ---------------- | ----------------- | -------- | -------- |
| GitHub Stars     | ...               | ...      | ...      |
| Last Release     | ...               | ...      | ...      |
| Bundle Size      | ...               | ...      | ...      |
| Weekly Downloads | ...               | ...      | ...      |
| License          | ...               | ...      | ...      |
| Maintenance      | Active/Slow/Stale | ...      | ...      |
| Learning Curve   | Low/Med/High      | ...      | ...      |

**Recommendation:** {Option} — Confidence: {X}%

Step 6: Testing Architecture

Research best testing tools and strategy for the confirmed tech stack:

Test Strategy Template

### Test Pyramid

- **Unit (70%):** {framework} — {what to test}
- **Integration (20%):** {framework} — {what to test}
- **E2E (10%):** {framework} — {what to test}

### Coverage Targets

- Unit: {X}% | Integration: {X}% | E2E: critical paths only
- Enforcement: {tool} in CI pipeline, fail build below threshold

Step 7: CI/CD & Deployment

Research deployment architecture and CI/CD tooling:

Deployment Strategy Comparison

Step 8: Observability & Monitoring

Observability Decision: 3 Pillars

### Recommended Observability Stack

| Pillar   | Tool   | Why         |
| -------- | ------ | ----------- |
| Logs     | {tool} | {rationale} |
| Metrics  | {tool} | {rationale} |
| Traces   | {tool} | {rationale} |
| Alerting | {tool} | {rationale} |

Step 9: Code Quality & Clean Code Enforcement

Research and recommend tooling for automated code quality:

Enforcement Strategy

### Code Quality Gates

| Gate        | Tool   | Trigger        | Fail Criteria         |
| ----------- | ------ | -------------- | --------------------- |
| Pre-commit  | {tool} | git commit     | Lint errors, format   |
| PR Check    | {tool} | Pull request   | Coverage < X%, issues |
| CI Pipeline | {tool} | Push to branch | Build fail, test fail |
| Scheduled   | {tool} | Weekly/nightly | Security vulns, debt  |

Scaffold Handoff (MANDATORY — consumed by /scaffold)

Ref: .claude/skills/shared/scaffold-production-readiness-protocol.md

After completing code quality research, produce this handoff table in the architecture report. The /scaffold skill reads this table to generate actual config files — without it, scaffold cannot auto-configure quality tooling.

### Scaffold Handoff — Tool Choices

| Concern        | Chosen Tool       | Config File | Rationale |
| -------------- | ----------------- | ----------- | --------- |
| Linter (FE)    | {tool}            | {filename}  | {why}     |
| Linter (BE)    | {tool}            | {filename}  | {why}     |
| Formatter      | {tool}            | {filename}  | {why}     |
| Pre-commit     | {tool}            | {filename}  | {why}     |
| Error handling | {pattern}         | {files}     | {why}     |
| Loading state  | {pattern}         | {files}     | {why}     |
| Docker         | {compose pattern} | {files}     | {why}     |

Also include: Error handling strategy (4-layer pattern), loading state approach (global vs per-component), and Docker profile structure. See protocol for framework-specific options.

Step 10: Dependency Risk Assessment

For EVERY recommended library/package, evaluate maintenance and obsolescence risk:

Package Health Scorecard

Risk Categories

Dependency Maintenance Strategy

### Recommended Practices

1. **Automated scanning:** {tool} (Dependabot/Renovate/Snyk) — weekly PR for updates
2. **Lock file strategy:** Commit lock files, pin major versions, allow patch auto-update
3. **Audit schedule:** Monthly `npm audit` / `dotnet list package --vulnerable`
4. **Vendor policy:** Max {N} dependencies per concern, prefer well-maintained alternatives
5. **Exit strategy:** For each High-risk dependency, document migration path to alternative

Step 11: Generate Report

Write report to {plan-dir}/research/architecture-design.md with sections:

1. Executive summary (recommended architecture in 8-10 lines)
2. Architecture requirements table (from Step 2)
3. Backend architecture — style comparison + recommended patterns (Steps 3)
4. Frontend architecture — style comparison + recommended patterns (Step 4)
5. Library ecosystem — per-concern recommendations with alternatives (Step 5)
6. Testing architecture — pyramid, tools, coverage targets (Step 6)
7. CI/CD & deployment — pipeline design, deployment strategy (Step 7)
8. Observability stack — 3 pillars + alerting (Step 8)
9. Code quality — enforcement gates, tooling (Step 9)
10. Dependency risk matrix — high-risk packages, mitigation (Step 10)
11. Architecture diagram (Mermaid — showing all layers and data flow)
12. Risk assessment for overall architecture
13. Unresolved questions

Architecture Diagram Template

```mermaid
graph TB
    subgraph "Frontend"
        UI[SPA / Micro Frontend]
        STORE[State Management]
    end
    subgraph "API Gateway"
        GW[Gateway / BFF]
    end
    subgraph "Backend Services"
        CMD[Commands / Handlers]
        QRY[Queries / Read Models]
        SVC[Domain Services]
        ENT[Entities / Aggregates]
    end
    subgraph "Infrastructure"
        DB[(Database)]
        CACHE[(Cache)]
        MSG[Message Bus]
        SEARCH[(Search Index)]
    end
    subgraph "Observability"
        LOG[Logging]
        METRIC[Metrics]
        TRACE[Tracing]
    end
    subgraph "CI/CD"
        PIPE[Pipeline]
        REG[Container Registry]
        K8S[Orchestration]
    end
    UI --> GW --> CMD & QRY
    CMD --> SVC --> ENT --> DB
    QRY --> CACHE & SEARCH
    ENT -.-> MSG
    CMD & QRY -.-> LOG & METRIC & TRACE
    PIPE --> REG --> K8S
```

Step 12: User Validation Interview

MANDATORY IMPORTANT MUST present findings and ask 8-12 questions via AskUserQuestion:

Required Questions

1. Backend architecture — "I recommend {style}. Agree?"
2. Frontend architecture — "I recommend {style} with {state management}. Agree?"
3. Design patterns — "Recommended backend patterns: {list}. Frontend patterns: {list}. Any to add/remove?"
4. Key libraries — "For {concern}, I recommend {lib} over {alternatives}. Agree?"
5. Testing strategy — "Test pyramid: {unit}%/{integration}%/{E2E}% using {frameworks}. Appropriate?"
6. CI/CD — "Pipeline: {tool} with {deployment strategy}. Fits your infra?"
7. Observability — "Monitoring stack: {logs}/{metrics}/{traces}. Sufficient?"
8. Code quality — "Enforcement: {linter + formatter + pre-commit hooks}. Team ready?"
9. Dependency risk — "Found {N} high-risk dependencies. Accept or find alternatives?"
10. Complexity check — "This architecture has {N} concerns addressed. Appropriate for team size?"

Optional Deep-Dive Questions (pick 2-3)

• "Should we use event sourcing or traditional state-based persistence?"
• "Monolith-first or start with service boundaries?"
• "Micro frontends or monolith SPA?"
• "How important is framework independence for this project?"
• "Self-hosted observability or managed SaaS?"
• "Strict lint rules from day 1 or gradual adoption?"

After user confirms, update report with final decisions and mark as status: confirmed.

Best Practices Audit (applied across all steps)

Validate architecture against these principles — flag violations in report:

Output

{plan-dir}/research/architecture-design.md     # Full architecture analysis report
{plan-dir}/phase-02b-architecture.md           # Confirmed architecture decisions

MANDATORY IMPORTANT MUST break work into small todo tasks using TaskCreate BEFORE starting. MANDATORY IMPORTANT MUST validate EVERY architecture recommendation with user via AskUserQuestion — never auto-decide. MANDATORY IMPORTANT MUST include confidence % and evidence citations for all claims. MANDATORY IMPORTANT MUST add a final review todo task to verify work quality.

Next Steps

MANDATORY IMPORTANT MUST after completing this skill, use AskUserQuestion to recommend:

• "/plan (Recommended)" — Create implementation plan from architecture design
• "/refine" — If need to create PBIs first
• "Skip, continue manually" — user decides

Closing Reminders

MANDATORY IMPORTANT MUST break work into small todo tasks using TaskCreate BEFORE starting. MANDATORY IMPORTANT MUST validate decisions with user via AskUserQuestion — never auto-decide. MANDATORY IMPORTANT MUST add a final review todo task to verify work quality.