architecture-design

TaskCreate

AskUserQuestion

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).

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

• 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

plans/

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)

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

AskUserQuestion

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

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

---

Ref:

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

/scaffold

undefined

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

---

{plan-dir}/research/architecture-design.md

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

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?"

• "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?"

status: confirmed

AskUserQuestion

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