Blueprint Validator

Run comprehensive quality checks on your architecture blueprint to ensure it's complete, consistent, and ready for implementation.

Perfect for: Pre-implementation review, quality assurance, stakeholder review prep, team handoff

When to Use This Skill

Use this skill when you need to:

Validate blueprint before sharing with stakeholders
Check blueprint completeness before implementation
Ensure all 19 sections are present and properly structured
Verify consistency across sections (API → DB → Security)
Validate against best practices
Identify missing upgrade paths or assumptions
Check for potential security issues
Verify cost estimates are realistic

Input: Architecture blueprint (all 19 sections) Output: Validation report with errors, warnings, and suggestions

Validation Categories

1. Structural Completeness (Critical)

Check: All required sections present

Required sections (19 total):

Executive Summary
Product Type Detection
Tech Stack Decisions
Database Schema
Architecture Diagram
API Specification
Integrations
Security Architecture
Deployment & DevOps
Monitoring & Observability
Cost Estimate
Complexity Assessment
Service Level Objectives (SLOs)
Well-Architected Review
Sprint Backlog
Testing Strategy
Next Steps Guide
Required Accounts
Architecture Assumptions (NEW)

Errors:

❌ Section missing entirely
❌ Section header present but no content

Warnings:

⚠️ Section too short (< 3 paragraphs)
⚠️ Section lacks detail (< 500 characters)

2. Content Quality (High Priority)

Check: Each section has required subsections and details

Section 1: Executive Summary

✅ One-sentence product description
✅ Customer type (B2B/B2C)
✅ Problem statement
✅ Solution overview
✅ Key metrics (users, scale)
✅ Major assumptions called out

Section 3: Tech Stack Decisions

✅ Database choice with justification
✅ Hosting platform with cost
✅ Authentication provider
✅ All choices have confidence labels
✅ All choices have upgrade paths

Section 4: Database Schema

✅ At least 3 entities defined
✅ All entities have primary keys
✅ Foreign keys defined for relationships
✅ Indexes on foreign keys
✅ Multi-tenancy column if B2B
✅ Timestamps (created_at, updated_at)

Section 6: API Specification

✅ At least 5 endpoints documented
✅ All endpoints have HTTP methods
✅ Request/response examples provided
✅ Authentication requirements specified
✅ Error responses documented

Section 8: Security Architecture

✅ Authentication method specified
✅ Authorization strategy (RBAC, ABAC, etc.)
✅ Multi-tenancy isolation (if B2B)
✅ Secrets management approach
✅ OWASP Top 10 addressed

Section 11: Cost Estimate

✅ Infrastructure costs provided
✅ Cost ranges (not point estimates)
✅ At least 3 scenarios (MVP, Growth, Scale)
✅ Cost breakdown by service

Section 15: Sprint Backlog

✅ At least 5 sprints defined
✅ Each sprint has user stories
✅ User stories have acceptance criteria
✅ Story points provided
✅ Sprints are risk-prioritized

Section 19: Architecture Assumptions (NEW)

✅ All default choices documented
✅ Confidence labels used (Assumed/Recommended/Requires confirmation)
✅ Upgrade paths for each assumption
✅ Cost implications mentioned

3. Consistency Validation (High Priority)

Cross-section checks:

Database ↔ API Consistency

✅ All API endpoints reference valid database entities
✅ All database entities are exposed via API (or reason given)
❌ API returns fields not in database schema
❌ Database has orphaned entities (no API access)

Tech Stack ↔ Cost Estimate

✅ All tech stack choices appear in cost estimate
✅ Cost estimate matches chosen platforms
❌ Tech stack mentions Vercel, cost estimate shows AWS
❌ Database choice is PostgreSQL, cost shows MongoDB

Security ↔ Database

✅ If multi-tenant, database has tenant_id columns
✅ RLS policies mentioned if PostgreSQL + multi-tenant
❌ Multi-tenant product but no tenant isolation in schema

Sprint Backlog ↔ API/DB

✅ Sprint 0 includes database setup
✅ Sprints cover all major API endpoints
✅ Security features are prioritized early
❌ Sprint backlog missing critical infrastructure setup

Frontend ↔ Backend Connections

✅ All frontend backend_connections reference defined services
✅ All services consumed by frontends have endpoints documented
✅ Frontend client_auth.token_storage is compatible with auth strategy (e.g., cookie for web, secure-store for mobile)
✅ Frontend realtime.protocol matches service type (e.g., websocket service exists if frontend uses websocket)
❌ Frontend references a service not defined in services[]
❌ Frontend has no backend_connections but communicates with services via communication[]
⚠️ Mobile frontend missing client_auth configuration
⚠️ Frontend using localStorage for token storage with sensitive data (prefer cookie or secure-store)

Mobile ↔ Platform Checks

✅ iOS frontend has bundle_id defined
✅ Android frontend has bundle_id defined
✅ Push notification providers match platform (FCM for Android, APNS for iOS)
✅ Permissions listed match app functionality (camera if video calls, microphone if audio)
❌ Mobile frontend missing push_providers but backend has notification service
⚠️ Mobile frontend missing deep_link_scheme (needed for push notification deep links)
⚠️ Mobile frontend missing ota_updates (recommended for Expo/React Native apps)

4. Best Practices (Medium Priority)

Architecture patterns:

✅ Monolith recommended for new projects (not microservices)
✅ Managed platforms recommended over raw AWS/GCP
✅ PostgreSQL recommended over MongoDB for relational data
⚠️ Microservices for <10 engineers (premature optimization)
⚠️ Multiple databases in initial design (complexity)

Security:

✅ JWT expiration < 24 hours
✅ Password minimum length ≥ 8 characters
✅ Rate limiting on auth endpoints
✅ HTTPS enforced in production
❌ Secrets hardcoded in examples
❌ No rate limiting mentioned

Database:

✅ All foreign keys indexed
✅ Composite unique constraints for multi-tenant
✅ Soft deletes for important data
✅ Timestamps on all tables
⚠️ No indexes on frequently queried columns
⚠️ Missing cascade delete rules

API Design:

✅ RESTful naming conventions
✅ Pagination on list endpoints
✅ Proper HTTP status codes (201 for create, 204 for delete)
✅ API versioning strategy
⚠️ Inconsistent naming (camelCase vs snake_case)
⚠️ No filtering/sorting on list endpoints

5. Assumption-First Model Compliance (NEW)

Check: Blueprint follows Assumption-First principles

✅ Only 3-5 gating questions asked (not 8-12)
✅ All defaults have confidence labels
✅ All defaults have upgrade paths
✅ Architecture Invariants section present
✅ Architecture Assumptions appendix present
❌ Missing confidence labels on some defaults
❌ Missing upgrade paths for tech choices
⚠️ Asked for budget/timeline (should assume)

6. Upgrade Paths (Medium Priority)

Check: All decisions have upgrade paths

Required for:

Database choice
Hosting platform
Architecture pattern (monolith → modular → microservices)
Authentication provider
Caching strategy
File storage

Format:

**Upgrade path**: Start with [X], upgrade to [Y] when [Z]

Examples:

✅ "Start with Vercel, upgrade to AWS when >100K users or SOC 2 required"
✅ "Start with monolith, upgrade to modular monolith when >10 engineers"
❌ "Use PostgreSQL" (no upgrade path)
❌ "Use Vercel for hosting" (no scale trigger)

7. Cost Validation (Medium Priority)

Realistic cost ranges:

Infrastructure (monthly):

MVP (< 1K users): $0-150
Growth (1K-10K users): $150-500
Scale (10K-100K users): $500-2000

Development (one-time):

AI tools: $20-60/month + time
Freelancer: $20K-60K
Agency: $60K-150K

Errors:

❌ MVP costs >$500/month (too high)
❌ Growth tier <$100/month (too low, unrealistic)
❌ No cost ranges (point estimates only)
❌ Missing cost breakdown

8. Security Checklist (High Priority)

Check: All OWASP Top 10 addressed

✅ Broken Access Control → Authorization strategy defined
✅ Cryptographic Failures → Secrets management, HTTPS
✅ Injection → ORM usage, parameterized queries
✅ Insecure Design → Well-Architected Review
✅ Security Misconfiguration → Environment variables, RLS
✅ Vulnerable Components → Dependency scanning mentioned
✅ Identification/Authentication → Auth provider specified
✅ Software/Data Integrity → Code signing, migrations
✅ Logging/Monitoring → Observability section
✅ SSRF → API security, input validation

Warnings:

⚠️ No mention of XSS prevention
⚠️ No CSRF protection strategy
⚠️ No SQL injection mitigation (if raw SQL used)

Output Format

When invoked, generate:

🔍 Validating architecture blueprint...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STRUCTURAL COMPLETENESS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ All 19 required sections present
✅ All sections have content (>500 characters)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CONTENT QUALITY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Executive Summary: Complete (product, customer, problem, solution)
✅ Tech Stack Decisions: 5 decisions with confidence labels
✅ Database Schema: 7 entities, all with PKs and indexes
✅ API Specification: 18 endpoints documented
⚠️  Security Architecture: Missing XSS prevention strategy
    → Add: "Sanitize all user input, use CSP headers"
✅ Cost Estimate: 3 scenarios ($50-150/month MVP to $500-1500/month Scale)
✅ Sprint Backlog: 8 sprints, 56 user stories, 134 story points
✅ Architecture Assumptions: All defaults with upgrade paths

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CONSISTENCY VALIDATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Database ↔ API: All entities exposed, all endpoints valid
✅ Tech Stack ↔ Cost: All platforms in cost estimate
✅ Security ↔ Database: tenant_id columns present, RLS mentioned
❌ Sprint Backlog ↔ API: GET /analytics endpoint not in any sprint
    → Fix: Add analytics implementation to Sprint 5 or 6

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
BEST PRACTICES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Architecture: Monolith recommended (appropriate for scale)
✅ Hosting: Managed platforms (Vercel + Supabase)
✅ Database: PostgreSQL with indexes and RLS
✅ Security: JWT expiration 15 minutes, rate limiting on auth
⚠️  Database: Missing index on tickets.created_at (used for sorting)
    → Add: CREATE INDEX tickets_created_at_idx ON tickets(created_at DESC)
⚠️  API: No pagination limit enforcement (should max at 100)
    → Add: Validate limit parameter: min=1, max=100

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ASSUMPTION-FIRST COMPLIANCE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Only 3 gating questions asked (customer type, scale, compliance)
✅ All tech defaults have confidence labels
✅ All defaults have upgrade paths
✅ Architecture Invariants section present
✅ Architecture Assumptions appendix complete
⚠️  File storage choice missing confidence label
    → Add: "Cloudflare R2 **(Recommended)** - Zero egress fees"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
UPGRADE PATHS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Database: "PostgreSQL (Supabase) → Dedicated PostgreSQL when >100K users"
✅ Hosting: "Vercel + Railway → AWS when SOC 2 or >100K users"
✅ Architecture: "Monolith → Modular monolith when >10 engineers"
✅ Auth: "Clerk → Auth0 when enterprise SSO required"
❌ Caching: No upgrade path defined
    → Add: "Start with in-memory cache, upgrade to Redis when >10K users"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COST VALIDATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ MVP costs: $50-150/month (realistic)
✅ Growth costs: $150-500/month (realistic)
✅ Scale costs: $500-1500/month (realistic)
✅ Cost ranges provided (not point estimates)
✅ Cost breakdown by service
⚠️  No bandwidth costs mentioned (can be significant at scale)
    → Add: Bandwidth estimate for file downloads (R2 egress is free)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SECURITY CHECKLIST (OWASP Top 10)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ 1. Broken Access Control: RLS policies + RBAC
✅ 2. Cryptographic Failures: Secrets in env vars, HTTPS enforced
✅ 3. Injection: Prisma ORM (parameterized queries)
✅ 4. Insecure Design: Well-Architected Review included
✅ 5. Security Misconfiguration: Environment-based config
⚠️  6. Vulnerable Components: No dependency scanning mentioned
    → Add: "Use Dependabot or Snyk for dependency scanning"
✅ 7. Identification/Authentication: Clerk with JWT
✅ 8. Software/Data Integrity: Prisma migrations, code review
✅ 9. Logging/Monitoring: Sentry + structured logging
⚠️  10. SSRF: No mention of URL validation for integrations
    → Add: "Validate all external URLs before fetching"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
VALIDATION SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Score: 87/100 (Good - Ready with minor fixes)

✅ Passed: 42 checks
⚠️  Warnings: 8 (fixable, non-blocking)
❌ Errors: 2 (should fix before implementation)

🎯 Recommendation: PROCEED WITH FIXES

Priority fixes:
1. ❌ Add analytics endpoint to sprint backlog (5 min fix)
2. ❌ Define caching upgrade path (2 min fix)
3. ⚠️  Add database index on tickets.created_at (1 line)
4. ⚠️  Add API pagination limit validation (2 lines)
5. ⚠️  Add dependency scanning to DevOps section (1 paragraph)

Blueprint is 87% complete and ready for implementation after addressing 2 critical issues and 8 warnings.

Next steps:
1. Fix 2 errors (analytics sprint, caching upgrade)
2. Review 8 warnings and decide which to address
3. Re-run validation to confirm 100% pass
4. Share with stakeholders using /architect:stakeholder-doc

Validation Levels

1. Strict (Default)

All errors must be fixed, warnings recommended.

Use when: Production blueprint, stakeholder review, team handoff

2. Relaxed

Warnings allowed, only errors block.

Use when: Early draft, rapid iteration, experimental designs

3. Pedantic

All warnings treated as errors.

Use when: Enterprise projects, compliance-heavy, security-critical

Examples:

# Default strict validation
/architect:validate

# Relaxed (ignore warnings)
/architect:validate --level=relaxed

# Pedantic (all warnings = errors)
/architect:validate --level=pedantic

Custom Validation Rules

Add project-specific rules:

Example:

/architect:validate --rules=custom-rules.yaml

custom-rules.yaml:

rules:
  - name: must_use_typescript
    severity: error
    check: tech_stack.language == "TypeScript"
    message: "All projects must use TypeScript (company policy)"

  - name: max_cost_mvp
    severity: error
    check: cost_estimate.mvp.max <= 200
    message: "MVP infrastructure costs must be <$200/month"

  - name: require_sentry
    severity: warning
    check: monitoring.includes("Sentry")
    message: "Sentry recommended for error tracking"

  - name: postgres_only
    severity: error
    check: database.type == "PostgreSQL"
    message: "Only PostgreSQL allowed (team expertise)"

Auto-Fix Suggestions

For common issues, suggest fixes:

Missing index:

⚠️  Missing index on tickets.created_at

Auto-fix available:
  prisma/schema.prisma:42
  Add: @@index([createdAt])

Apply fix? [y/N]

Missing upgrade path:

❌ Caching choice has no upgrade path

Auto-fix suggestion:
  Section 3, line 127
  Add: "**Upgrade path**: Start with in-memory cache (Node.js Map),
        upgrade to Redis when >10K concurrent users or when session
        sharing needed across instances."

Apply fix? [y/N]

Error Handling

If blueprint file not found:

Action: Error with guidance
Example: "❌ blueprint.md not found. Run /architect:blueprint first."

If blueprint is incomplete (< 10 sections):

Action: Error with list of missing sections
Example: "❌ Blueprint incomplete. Missing: Database Schema, API Spec, Security Architecture..."

If blueprint is malformed (invalid markdown):

Action: Warning, attempt to parse anyway
Example: "⚠️ Malformed markdown detected. Attempting to parse..."

Success Criteria

A passing validation should:

✅ All 19 sections present with content
✅ No critical errors (score ≥ 90/100)
✅ Warnings addressed or acknowledged
✅ Cross-section consistency validated
✅ Best practices followed
✅ Assumption-First model compliance
✅ All upgrade paths defined
✅ Cost estimates realistic
✅ Security checklist complete
✅ Ready for implementation or stakeholder review

Examples

Example 1: Basic Validation

/architect:validate

# Output:
# 📊 Score: 87/100
# ✅ 42 checks passed
# ⚠️  8 warnings
# ❌ 2 errors

Example 2: Relaxed Mode

/architect:validate --level=relaxed

# Output:
# 📊 Score: 95/100 (warnings ignored)
# ✅ 42 checks passed
# ❌ 2 errors

Example 3: With Auto-Fix

/architect:validate --auto-fix

# Interactive prompts to apply suggested fixes

Example 4: Custom Rules

/architect:validate --rules=company-standards.yaml

# Validates against company-specific requirements

Example 5: CI/CD Integration

# In GitHub Actions
- name: Validate Blueprint
  run: /architect:validate --format=json --exit-code

# Exits with code 1 if validation fails
# Output: validation-report.json

validate