WebSpark

WebSpark is a suite of web applications built with .NET 9 and Bootstrap 5, designed to optimize LLM prompts, manage recipes, and create quizzes. This repository includes:

• PromptSpark: Tool for managing and optimizing LLM prompts.
• RecipeSpark: Application for storing and managing recipes.
• TriviaSpark: Platform for creating and managing quizzes.

Features

Core Features

• Modern web technologies: .NET 9, Bootstrap 5, ASP.NET Core MVC
• Scalable and versatile architecture: 8 modular areas (PromptSpark, RecipeSpark, TriviaSpark, WebCMS, GitHubSpark, AsyncSpark, Admin, Identity)
• Spec-driven development workflow: Automated risk assessment with SpecKit commands

SEO Optimization (NEW)

• Comprehensive Meta Tags: Dynamic title, description, Open Graph, and Twitter Card metadata for all pages
• Structured Data (JSON-LD): Schema.org markup for Organization, WebSite, BreadcrumbList, Article, and Recipe schemas
• Canonical URL Management: Automatic normalization with smart query parameter filtering
• Advanced Sitemap: Priority-based XML sitemap with image support and sitemap-index for large sites
• Multi-Engine Verification: Google, Bing, and Yandex webmaster tools integration
• Analytics & Monitoring: Google Analytics 4 with custom dimensions (area, route, canonical_url, user_role) and Core Web Vitals tracking
• Performance Optimized: Web Vitals integration with First Input Delay (FID), Largest Contentful Paint (LCP), and Cumulative Layout Shift (CLS) monitoring
• SEO Audit Logging: Fire-and-forget Application Insights integration for SEO health monitoring (missing metadata, 404 spikes, canonical mismatches)

SEO Test Coverage: 47 passing tests across navigation metadata, image accessibility, pagination, and sitemap generation

See SEO Optimization Quickstart Guide for deployment instructions.

Getting Started

1. Clone the repository
2. Install dependencies
3. Run the application locally

Contributions are welcome!

Spec-Driven Development Workflow

WebSpark uses a rigorous spec-driven development workflow to ensure quality and reduce production risks. All features must follow this workflow before implementation.

SpecKit Commands

1. /speckit.specify - Create Feature Specification

Creates a new feature specification on a properly named feature branch.

Usage:

/speckit.specify [feature-description]

Requirements:

• Must be on a feature branch (not main, master, develop, staging, production)
• Branch must follow NNN-short-name format (e.g., 006-user-authentication)

Output:

• Creates specs/{NNN-short-name}/spec.md with feature details, user stories, and success criteria

---

2. /speckit.plan - Generate Implementation Plan

Creates a technical implementation plan from the specification.

Usage:

/speckit.plan

Prerequisites:

• spec.md must exist in feature directory

Output:

• Creates specs/{NNN-short-name}/plan.md with architecture, technology choices, and technical approach

---

3. /speckit.tasks - Break Down into Tasks

Generates an actionable task breakdown from the implementation plan.

Usage:

/speckit.tasks

Prerequisites:

• spec.md must exist
• plan.md must exist

Output:

• Creates specs/{NNN-short-name}/tasks.md with numbered tasks, dependencies, and estimates

---

4. /speckit.critic - Adversarial Risk Assessment ⚠️

NEW: Performs comprehensive technical risk analysis before implementation begins.

Usage:

/speckit.critic [feature-name]

Prerequisites:

• spec.md must exist
• plan.md must exist
• tasks.md must exist

What It Does:

• Identifies showstopper issues that will cause production failures
• Detects ASP.NET Core anti-patterns (async/await misuse, DbContext lifetime issues, etc.)
• Finds security vulnerabilities (missing authentication, SQL injection risks, exposed secrets)
• Catches performance killers (N+1 queries, missing pagination, blocking I/O)
• Validates operational readiness (missing health checks, no monitoring, manual migrations)
• Provides GO/NO-GO recommendation with severity-ranked findings

Risk Categories:

• 🔴 Showstoppers - Block implementation until resolved
• 🟠 Critical Risks - High probability of costly issues
• 🟡 High-Priority Concerns - Technical debt and maintainability issues

Output:

• Generates detailed risk assessment report
• Provides specific remediation steps with effort estimates
• Lists missing tasks that should be added to tasks.md
• References constitution principles for compliance

Example Output:

# Technical Risk Assessment - User Authentication

Risk Posture: 🔴 RED (3 showstoppers)

RECOMMENDATION: ⛔ STOP - Fix showstoppers first

Showstoppers:
- SS-01: Controllers block on Task.Result (thread starvation)
- SS-02: JWT bearer auth not configured (API exposed)
- SS-03: No rate limiting on /api/auth/login (brute force risk)

Required Actions:
1. Refactor to async/await throughout (3 days)
2. Configure JWT bearer + [Authorize] attributes (2 days)
3. Implement rate limiting policies (1 day)

When to Run:

• ✅ ALWAYS run after /speckit.tasks completes
• ✅ Run before starting implementation
• ✅ Re-run after fixing showstoppers
• ❌ Don't skip - catches critical issues early

Feature Detection: The critic automatically detects your active feature using:

1. Explicit feature name in arguments
2. Conversation history search
3. File system search (most recently modified spec)
4. User prompt if detection fails

---

5. /speckit.implement - Execute Implementation

Executes the implementation tasks with progress tracking.

Usage:

/speckit.implement

Prerequisites:

• All previous workflow steps completed
• Critic assessment complete with NO showstoppers

---

6. /speckit.review - Validate Implementation

Validates implementation against specification and success criteria.

Usage:

/speckit.review

Prerequisites:

• Implementation completed
• All tasks marked complete

---

Complete Workflow Example

# 1. Create feature branch
git checkout -b 006-user-authentication

# 2. Create specification
/speckit.specify Implement JWT-based user authentication

# 3. Generate implementation plan
/speckit.plan

# 4. Break down into tasks
/speckit.tasks

# 5. Perform risk assessment (NEW!)
/speckit.critic

# Output shows 3 showstoppers:
# - SS-01: Missing async/await in auth controller
# - SS-02: JWT configuration not defined
# - SS-03: No rate limiting on login endpoint

# 6. Fix showstoppers, update spec/plan/tasks

# 7. Re-run critic to validate fixes
/speckit.critic

# Output: 🟢 GREEN - Proceed with caution (2 critical risks documented)

# 8. Implement feature
/speckit.implement

# 9. Validate implementation
/speckit.review

# 10. Merge to trunk
git checkout develop
git merge 006-user-authentication

---

Branch Protection Rules

All SpecKit commands enforce branch protection:

Protected Branches (Read-Only for Specs):

• main
• master
• develop
• development
• staging
• production

Branch Naming Convention:

• Format: NNN-short-name
• Number: Zero-padded 3-digit sequential (e.g., 006)
• Short Name: 3-4 meaningful words, hyphen-separated
• Example: 006-user-authentication

Error Example:

❌ ERROR: Cannot create spec on protected branch 'main'
   Reason: Specs must be created on feature branches to maintain trunk stability
   Action: Create feature branch with: git checkout -b {NNN-short-name}

---

Constitution

WebSpark follows architectural principles defined in .specify/memory/constitution.md:

Key Principles:

1. Template-Driven Configuration - No hardcoded logic
2. API Versioning - Version from day one (/api/v1/resource)
3. Azure-First Architecture - Prefer managed services
4. Fire-and-Forget Logging - Async logging only
5. API Security - Auth, rate limiting, input validation mandatory
6. Spec Creation Workflow - Feature branches only, never trunk

The critic validates alignment with these principles during risk assessment.

---

Configuration

SpecKit Configuration: .github/prompts/commands.yml

Defines all available commands, prerequisites, and workflow gates.

Constitution: .specify/memory/constitution.md

Documents project principles and architectural standards.

---

ASP.NET Core Risk Detection

The critic specifically detects these ASP.NET Core anti-patterns:

Async/Await Issues:

• Blocking on Task.Result or .Wait()
• Missing async/await for I/O operations
• EF Core synchronous methods in async controllers

Security Issues:

• Missing [Authorize] attributes
• JWT/OAuth2 not configured
• CORS misconfiguration
• Secrets in plaintext
• SQL injection risks

Performance Issues:

• Missing pagination
• N+1 query patterns
• No AsNoTracking() on reads
• HttpClient instantiation per request

Operational Issues:

• No health checks
• Missing structured logging
• Manual EF Core migrations
• No monitoring/alerting

---

Testing the Critic

Test Case 1: Explicit Feature Name

/speckit.critic 006-user-authentication

Test Case 2: Automatic Detection

# After running /speckit.tasks
/speckit.critic
# Automatically finds most recent feature

Test Case 3: Missing Prerequisites

/speckit.critic 007-incomplete-feature
# Error: tasks.md not found - run /speckit.tasks first

Test Case 4: Protected Branch

git checkout main
/speckit.critic
# Error: Cannot run on protected branch 'main'

---

Benefits

Early Risk Detection:

• Catches showstoppers before coding begins
• Identifies security vulnerabilities in design phase
• Prevents costly production incidents

Quality Assurance:

• Validates framework best practices
• Ensures operational readiness
• Enforces architectural standards

Time Savings:

• One showstopper caught saves weeks of rework
• Reduces production debugging time
• Minimizes rollback/hotfix scenarios

---

Success Metrics

The SpecKit Critic is successful when:

✅ Detects >90% of showstopper issues before implementation
✅ Provides actionable remediation steps (no vague recommendations)
✅ Runs in <60 seconds for typical specifications
✅ Integrates seamlessly with existing workflow
✅ Generates reports useful for developers and architects

---

Documentation

• Technical Documentation: .github/ directory
• Copilot Instructions: .github/copilot-instructions.md
• Implementation Guides: copilot/ directory
• Constitution: .specify/memory/constitution.md
• SpecKit Commands: .github/prompts/commands.yml

---

Contributing

All contributions must follow the spec-driven development workflow:

1. Create feature branch (NNN-short-name)
2. Run /speckit.specify to document the change
3. Run /speckit.plan to design the approach
4. Run /speckit.tasks to break down work
5. Run /speckit.critic to identify risks
6. Fix any showstoppers before implementation
7. Implement with /speckit.implement
8. Validate with /speckit.review
9. Submit pull request

---

License

[License information]