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

1. •Executive Summary
2. •Product Type Detection
3. •Tech Stack Decisions
4. •Database Schema
5. •Architecture Diagram
6. •API Specification
7. •Integrations
8. •Security Architecture
9. •Deployment & DevOps
10. •Monitoring & Observability
11. •Cost Estimate
12. •Complexity Assessment
13. •Service Level Objectives (SLOs)
14. •Well-Architected Review
15. •Sprint Backlog
16. •Testing Strategy
17. •Next Steps Guide
18. •Required Accounts
19. •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

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

1. •✅ Broken Access Control → Authorization strategy defined
2. •✅ Cryptographic Failures → Secrets management, HTTPS
3. •✅ Injection → ORM usage, parameterized queries
4. •✅ Insecure Design → Well-Architected Review
5. •✅ Security Misconfiguration → Environment variables, RLS
6. •✅ Vulnerable Components → Dependency scanning mentioned
7. •✅ Identification/Authentication → Auth provider specified
8. •✅ Software/Data Integrity → Code signing, migrations
9. •✅ Logging/Monitoring → Observability section
10. •✅ 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