-```
-
-## File Organization
-
-### Component Structure
-
-```
-src/
-├── components/
-│ ├── ui/ # shadcn/ui components
-│ │ ├── button.tsx
-│ │ ├── card.tsx
-│ │ └── dialog.tsx
-│ ├── theme-provider.tsx
-│ └── [feature-components]/
-├── lib/
-│ ├── utils.ts # cn() utility and helpers
-│ └── ...
-└── app/
- ├── globals.css # Theme variables and Tailwind imports
- └── ...
-```
-
-### CSS Organization
-
-```css
-/* globals.css structure */
-@import "tailwindcss";
-
-@theme {
- --color-primary: oklch(28.08% 0.051 260.2);
- --color-accent: oklch(76.65% 0.139 91.06);
-}
-
-:root {
- /* light theme variables */
-}
-.dark {
- /* dark theme variables */
-}
-
-@layer base {
- * {
- border-color: var(--border);
- }
- body {
- background-color: var(--background);
- color: var(--foreground);
- }
-}
-```
-
-## Accessibility Standards
-
-### Required Features
-
-- **ARIA Labels**: Use `aria-label`, `aria-describedby` for screen readers
-- **Focus Management**: Proper `tabindex` and focus trapping in modals
-- **Keyboard Navigation**: Support Enter, Escape, Arrow keys
-- **Color Contrast**: Ensure WCAG AA compliance
-- **Screen Reader**: Test with screen reader software
-
-### Implementation Example
-
-```tsx
-
-```
-
-## Best Practices
-
-### Theme Management
-
-- Always use `cssVariables: true` in `components.json`
-- Use semantic color names (`primary`, `accent`, `muted`)
-- Test both light and dark themes
-- Use `suppressHydrationWarning` on `` tag
-
-### Component Development
-
-- Extend shadcn/ui components rather than creating from scratch
-- Use `cn()` utility for conditional classes
-- Follow shadcn/ui naming conventions
-- Maintain consistent spacing with Tailwind scale
-
-### Performance
-
-- Leverage Tailwind's automatic purging in production builds
-- Use semantic tokens to reduce CSS bundle size
-- Minimize custom CSS in favor of utilities
-
-## Troubleshooting
-
-### Common Issues
-
-#### CSS Variables Not Working
-
-- **Check**: `cssVariables: true` in `components.json`
-- **Verify**: ThemeProvider setup with `attribute="class"`
-
-#### Dark Mode Not Applying
-
-- **Check**: ThemeProvider configuration
-- **Verify**: CSS variables defined in both `:root` and `.dark`
-
-#### Production Build Failures
-
-**Symptoms**: CSS variable errors in production builds
-
-**Solution**: Define theme colors in `@theme` directive:
-
-```css
-@theme {
- /* Core theme colors */
- --color-background: oklch(100% 0 0);
- --color-foreground: oklch(28.08% 0.051 260.2);
- --color-primary: oklch(28.08% 0.051 260.2);
- /* Dark mode variants */
- --color-background-dark: oklch(28.08% 0.051 260.2);
- --color-foreground-dark: oklch(100% 0 0);
-}
-```
-
-Then reference in CSS custom properties:
-
-```css
-:root {
- --background: var(--color-background);
- --foreground: var(--color-foreground);
-}
-
-.dark {
- --background: var(--color-background-dark);
- --foreground: var(--color-foreground-dark);
-}
-```
-
-## Development Workflow
-
-### Adding New Components
-
-1. **Check shadcn/ui first**: `npx shadcn@latest add [component]`
-2. **Customize with Tailwind**: Add utility classes for layout/spacing
-3. **Use semantic colors**: Apply theme-aware color tokens
-4. **Test themes**: Verify component works in light/dark modes
-
-### Migration from Tailwind v3
-
-- **Remove `tailwind.config.js`** - No longer needed in v4
-- Replace `@tailwind` directives with `@import "tailwindcss"`
-- Update PostCSS config to use `@tailwindcss/postcss`
-- Move theme configuration to CSS using `@theme` directive
-
-## Implementation Checklist
-
-- [ ] Uses proper shadcn/ui components as foundation
-- [ ] Follows CSS-first configuration (no tailwind.config.js)
-- [ ] Implements semantic color tokens
-- [ ] Includes accessibility attributes
-- [ ] Supports both light and dark themes
-- [ ] Uses CSS variables directly in @layer base
-- [ ] Tests keyboard navigation and focus states
-- [ ] Validates production build compatibility
-
----
-
-**Remember**: shadcn/ui first, Tailwind v4 CSS-first configuration, semantic tokens always, no config file needed.
diff --git a/specs/04-nextjs15-standards.md b/specs/04-nextjs15-standards.md
deleted file mode 100644
index b00e62f..0000000
--- a/specs/04-nextjs15-standards.md
+++ /dev/null
@@ -1,453 +0,0 @@
-# Next.js 15 Development Standards
-
-## Core Architecture Principles
-
-### App Router First
-
-- **Default**: Use App Router architecture for all new projects
-- **Server Components**: Default choice for better performance and SEO
-- **Client Components**: Only when interactivity is required
-- **File-based Routing**: Leverage `app/` directory structure
-
-### Component Strategy
-
-- **Server Components by default** - No "use client" unless needed
-- **Client Components only for**:
- - State management (useState, useReducer)
- - Event handlers (onClick, onChange)
- - Browser APIs (localStorage, window)
- - React hooks requiring client-side execution
-
-## Route Parameters & Navigation
-
-### Server Components
-
-```tsx
-// app/posts/[id]/page.tsx
-export default async function PostPage({
- params,
-}: {
- params: Promise<{ id: string }>;
-}) {
- const { id } = await params; // Next.js 15+ requires await
- return
Post {id}
;
-}
-```
-
-### Client Components
-
-```tsx
-// Use custom hook for client-side params
-"use client";
-import { useParams } from "@/hooks/use-params";
-
-export default function ClientComponent({
- params,
-}: {
- params: Promise<{ id: string }>;
-}) {
- const { id } = useParams(params);
- return
Post {id}
;
-}
-```
-
-### Navigation Patterns
-
-```tsx
-// Prefer Link over useRouter for navigation
-import Link from "next/link";
-
-// ✅ Preferred - Server-friendly
-
Dashboard;
-
-// ✅ Client-side navigation when needed
-("use client");
-import { useRouter } from "next/navigation";
-const router = useRouter();
-router.push("/dashboard");
-```
-
-## Data Fetching Patterns
-
-### Server-Side Data Fetching
-
-```tsx
-// app/posts/page.tsx - Server Component
-async function getPosts() {
- const res = await fetch("https://api.example.com/posts", {
- next: { revalidate: 3600 }, // ISR with 1 hour cache
- });
- return res.json();
-}
-
-export default async function PostsPage() {
- const posts = await getPosts();
- return (
-
- {posts.map((post) => (
-
- ))}
-
- );
-}
-```
-
-### Client-Side Data Fetching
-
-```tsx
-// Only when server-side isn't suitable
-"use client";
-import { useEffect, useState } from "react";
-
-export default function ClientDataComponent() {
- const [data, setData] = useState(null);
-
- useEffect(() => {
- fetch("/api/data")
- .then((res) => res.json())
- .then(setData);
- }, []);
-
- return
{data ? : }
;
-}
-```
-
-## Server Actions
-
-### Form Handling
-
-```tsx
-// app/contact/page.tsx
-import { redirect } from "next/navigation";
-
-async function submitContact(formData: FormData) {
- "use server";
-
- const name = formData.get("name") as string;
- const email = formData.get("email") as string;
-
- // Process form data
- await saveContact({ name, email });
-
- redirect("/thank-you");
-}
-
-export default function ContactPage() {
- return (
-
- );
-}
-```
-
-### Progressive Enhancement
-
-```tsx
-// Client component with Server Action
-"use client";
-import { useFormStatus } from "react-dom";
-
-function SubmitButton() {
- const { pending } = useFormStatus();
- return (
-
- );
-}
-```
-
-## Performance Optimization
-
-### Caching Strategies
-
-```tsx
-// Static Generation
-export default async function StaticPage() {
- const data = await fetch("https://api.example.com/static-data");
- return
{/* Static content */}
;
-}
-
-// Incremental Static Regeneration
-async function getData() {
- const res = await fetch("https://api.example.com/data", {
- next: { revalidate: 60 }, // Revalidate every 60 seconds
- });
- return res.json();
-}
-
-// Dynamic with caching
-async function getCachedData() {
- const res = await fetch("https://api.example.com/data", {
- cache: "force-cache", // Cache indefinitely
- });
- return res.json();
-}
-```
-
-### Loading States
-
-```tsx
-// app/posts/loading.tsx - Automatic loading UI
-export default function Loading() {
- return
Loading posts...
;
-}
-
-// app/posts/error.tsx - Error boundary
-("use client");
-export default function Error({
- error,
- reset,
-}: {
- error: Error & { digest?: string };
- reset: () => void;
-}) {
- return (
-
-
Something went wrong!
-
-
- );
-}
-```
-
-## TypeScript Integration
-
-### Strict Type Safety
-
-```tsx
-// Define proper interfaces
-interface PageProps {
- params: Promise<{ id: string }>;
- searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
-}
-
-export default async function Page({ params, searchParams }: PageProps) {
- const { id } = await params;
- const search = await searchParams;
-
- return
Page {id}
;
-}
-```
-
-### Component Props
-
-```tsx
-interface ButtonProps extends React.ButtonHTMLAttributes
{
- variant?: "primary" | "secondary";
- size?: "sm" | "md" | "lg";
-}
-
-export function Button({
- variant = "primary",
- size = "md",
- ...props
-}: ButtonProps) {
- return (
-
- );
-}
-```
-
-## Code Quality Standards
-
-### Function Declarations
-
-```tsx
-// ✅ Preferred - const declarations
-const handleClick = () => {
- // Handle click logic
-};
-
-const fetchUserData = async (id: string) => {
- const response = await fetch(`/api/users/${id}`);
- return response.json();
-};
-
-// ✅ Early returns for readability
-const processUser = (user: User | null) => {
- if (!user) return null;
- if (!user.isActive) return ;
-
- return ;
-};
-```
-
-### Event Handler Naming
-
-```tsx
-// ✅ Consistent naming with "handle" prefix
-const handleSubmit = (e: FormEvent) => {
- e.preventDefault();
- // Submit logic
-};
-
-const handleKeyDown = (e: KeyboardEvent) => {
- if (e.key === "Enter") {
- handleSubmit(e);
- }
-};
-```
-
-### Accessibility Implementation
-
-```tsx
-export function AccessibleButton({ children, ...props }: ButtonProps) {
- return (
-
- );
-}
-```
-
-## File Organization
-
-### App Directory Structure
-
-```
-app/
-├── (auth)/ # Route groups
-│ ├── login/
-│ └── register/
-├── dashboard/
-│ ├── page.tsx # Dashboard page
-│ ├── loading.tsx # Loading UI
-│ └── error.tsx # Error boundary
-├── api/ # API routes
-│ └── users/
-│ └── route.ts
-├── globals.css # Global styles
-└── layout.tsx # Root layout
-```
-
-### Component Organization
-
-```
-components/
-├── ui/ # shadcn/ui components
-├── forms/ # Form components
-├── layout/ # Layout components
-└── features/ # Feature-specific components
-```
-
-## AI SDK v5 Integration
-
-### Streaming Responses
-
-```tsx
-// app/api/chat/route.ts
-import { openai } from "@ai-sdk/openai";
-import { streamText } from "ai";
-
-export async function POST(req: Request) {
- const { messages } = await req.json();
-
- const result = await streamText({
- model: openai("gpt-4"),
- messages,
- });
-
- return result.toDataStreamResponse();
-}
-```
-
-### Client-Side Integration
-
-```tsx
-"use client";
-import { useChat } from "ai/react";
-
-export default function ChatComponent() {
- const { messages, input, handleInputChange, handleSubmit } = useChat();
-
- return (
-
- {messages.map((m) => (
-
- {m.role}: {m.content}
-
- ))}
-
-
-
- {/* Visual time display with color coding for urgency */}
-
-
- );
-}
-```
-
-#### Comment Standards
-- **Function Headers**: Purpose, parameters, examples
-- **Complex Logic**: Explain the "why", not just the "what"
-- **Business Rules**: Document business logic and constraints
-- **Edge Cases**: Explain handling of edge cases and error states
-- **Performance Notes**: Document performance considerations
-- **TODO Comments**: Include ticket numbers and timeline
-
-## Release Deployment
-
-### Deployment Pipeline
-
-#### Staging Deployment (dev branch)
-- **Trigger**: Automatic on merge to `dev`
-- **Environment**: Development/staging environment
-- **Purpose**: Integration testing and feature validation
-- **Access**: Internal team only
-
-#### Production Deployment (main branch)
-- **Trigger**: Manual after release branch merge
-- **Environment**: Production environment
-- **Purpose**: Live user access
-- **Process**: Blue-green deployment with rollback capability
-
-### Deployment Checklist
-- [ ] **Database Migrations**: Applied and tested
-- [ ] **Environment Variables**: Updated in production
-- [ ] **Feature Flags**: Configured appropriately
-- [ ] **Monitoring**: Alerts and dashboards configured
-- [ ] **Rollback Plan**: Documented and tested
-- [ ] **Communication**: Stakeholders notified of release
-
-## Role-Based Permissions Framework
-
-### Current Roles (Single Developer Phase)
-- **Lead Developer/Product Owner**: All permissions (you)
-- **CEO/Partner**: Spec review and approval for major changes
-
-### Future Roles (Team Growth Phase)
-
-#### Development Roles
-- **Senior Developer**: Can approve PRs, create feature specs
-- **Mid-Level Developer**: Can create PRs, review junior developer code
-- **Junior Developer**: Can create PRs, requires review for all changes
-
-#### Product Roles
-- **Product Owner**: Can modify project specs, prioritize features
-- **Product Manager**: Can create feature requests, review specifications
-- **Stakeholder**: Can review and comment on specifications
-
-#### Administrative Roles
-- **Tech Lead**: Can modify development standards, approve architecture changes
-- **DevOps Engineer**: Can modify deployment and CI/CD configurations
-- **QA Lead**: Can modify testing standards and requirements
-
-### Permission Matrix
-| Action | Lead Dev | Senior Dev | Mid Dev | Junior Dev | Product Owner |
-|--------|----------|------------|---------|------------|---------------|
-| Merge to main | ✅ | ✅ | ❌ | ❌ | ❌ |
-| Approve PRs | ✅ | ✅ | ✅* | ❌ | ❌ |
-| Modify specs | ✅ | ✅** | ❌ | ❌ | ✅ |
-| Create releases | ✅ | ✅ | ❌ | ❌ | ❌ |
-| Deploy to prod | ✅ | ✅ | ❌ | ❌ | ❌ |
-
-*Mid-level developers can approve junior developer PRs only
-**Senior developers can modify feature specs, not project specs
-
-## Continuous Improvement
-
-### Sprint Retrospectives
-- **What went well**: Celebrate successes and effective processes
-- **What could improve**: Identify bottlenecks and pain points
-- **Action items**: Concrete steps for next sprint improvement
-- **Process updates**: Update this spec based on learnings
-
-### Metrics Tracking
-- **PR Review Time**: Target < 24 hours for review completion
-- **Bug Rate**: Track bugs per release and resolution time
-- **Sprint Velocity**: Story points or features completed per sprint
-- **Code Quality**: Test coverage, lint violations, complexity metrics
-
-### Spec Evolution
-- **Quarterly Reviews**: Assess and update release strategy
-- **Team Feedback**: Incorporate developer experience improvements
-- **Industry Updates**: Adopt new best practices and tools
-- **Scaling Adjustments**: Modify process as team grows
-
----
-
-**Implementation Priority**: High - Required for team collaboration and scaling
diff --git a/specs/08-troubleshooting-documentation.md b/specs/08-troubleshooting-documentation.md
deleted file mode 100644
index b22c7d9..0000000
--- a/specs/08-troubleshooting-documentation.md
+++ /dev/null
@@ -1,224 +0,0 @@
-# Troubleshooting Documentation Standards
-
-## Overview
-
-This specification defines the practice of creating Root Cause Analysis (RCA) documentation for major bug fixes and feature implementations. These documents serve as learning resources and historical records of complex problem-solving processes.
-
-## Purpose
-
-1. **Knowledge Preservation**: Capture deep technical insights that might otherwise be lost
-2. **Learning Resource**: Help team members understand complex debugging processes
-3. **Pattern Recognition**: Identify recurring issues and systematic solutions
-4. **Onboarding Aid**: Accelerate new developer ramp-up with real-world examples
-5. **Decision Documentation**: Record why certain approaches were chosen over alternatives
-
-## When to Create RCA Documentation
-
-Create an RCA document when:
-
-- ✅ The bug required significant investigation (>30 minutes of debugging)
-- ✅ The root cause was non-obvious or counter-intuitive
-- ✅ The fix involves React/Next.js patterns that may not be widely known
-- ✅ The issue could easily recur if patterns aren't understood
-- ✅ Multiple approaches were evaluated before finding the solution
-- ✅ The debugging process revealed important system architecture insights
-
-## RCA Document Structure
-
-Each RCA document should follow this template:
-
-```markdown
-# [Feature/Bug Name] - Root Cause Analysis
-
-**Date**: YYYY-MM-DD
-**Severity**: Critical | High | Medium | Low
-**Component**: [Component or system affected]
-**Status**: ✅ Resolved | 🔄 In Progress | ⚠️ Workaround Applied
-
-## Problem Statement
-
-Clear, concise description of the observed issue.
-- What was the user-visible symptom?
-- What was the expected behavior?
-- When did this occur? (Always, on load, specific conditions)
-
-## Root Cause
-
-Detailed technical explanation of why the issue occurred.
-- What was the actual underlying cause?
-- Why did it happen?
-- What was missed initially?
-
-## Investigation Process
-
-Chronological steps taken to identify the root cause:
-1. Initial hypothesis
-2. Testing approach
-3. Findings that led to breakthrough
-4. Dead ends (important for learning!)
-
-## Solution
-
-Technical implementation of the fix:
-- Code changes made
-- Why this approach was chosen
-- Alternative approaches considered
-
-## Prevention
-
-How to avoid this issue in the future:
-- Patterns to follow
-- Patterns to avoid
-- Tests to add
-- Documentation to update
-
-## Related Issues
-
-Links to similar issues or related documentation.
-
-## Lessons Learned
-
-Key takeaways for the team.
-```
-
-## Storage Location
-
-All RCA documents are stored alongside specifications for easy reference:
-
-```
-/specs/
-├── 01-development-standards.md
-├── 08-troubleshooting-documentation.md
-└── troubleshooting/
- ├── README.md
- ├── video-transcript-auto-sync-2025-10-02.md
- └── [issue-name]-[YYYY-MM-DD].md
-```
-
-### File Naming Convention
-
-```
-[kebab-case-description]-[YYYY-MM-DD].md
-```
-
-Examples:
-- `video-transcript-auto-sync-2025-10-02.md`
-- `timer-state-management-2025-09-20.md`
-- `auth-middleware-race-condition-2025-10-01.md`
-
-## Version Control Strategy
-
-RCA documents are **committed to git** because:
-
-1. **Team Knowledge Base**: Everyone benefits from documented solutions
-2. **Historical Context**: Future developers can see why decisions were made
-3. **Pattern Recognition**: Similar issues can be quickly identified and referenced
-4. **Onboarding Resource**: New team members learn from real-world debugging examples
-5. **Cross-Reference**: Easy to link from code comments, PRs, and other specs
-
-### Quality Before Commit
-
-Before committing an RCA document:
-
-1. ✅ Remove any sensitive information (API keys, internal URLs, etc.)
-2. ✅ Ensure code snippets are representative (not copy-pasted production data)
-3. ✅ Verify links to external resources are public
-4. ✅ Proofread for clarity - this will be read by others
-5. ✅ Update `troubleshooting/README.md` index
-
-## Integration with Development Workflow
-
-### AI-Assisted Documentation
-
-When working with AI assistants (Cascade, etc.) on complex bugs:
-
-**During Debugging:**
-1. AI provides detailed root cause analysis in chat
-2. User requests: "Please create an RCA document for this fix"
-3. AI automatically saves to `/specs/troubleshooting/[issue]-[YYYY-MM-DD].md`
-4. AI updates `/specs/troubleshooting/README.md` index
-
-**Request Format:**
-```
-"Can you add to your steering @specs to create a .md format file for this fix?"
-```
-
-**AI Response Pattern:**
-1. ✅ Creates spec file (e.g., `08-troubleshooting-documentation.md`) if needed
-2. ✅ Creates RCA document in `/specs/troubleshooting/`
-3. ✅ Updates `/specs/troubleshooting/README.md` index
-4. ✅ Provides summary of what was documented
-
-**Benefits:**
-- Zero manual documentation overhead
-- Captures analysis while fresh in context
-- Consistent format across all RCAs
-- Automatic indexing and cross-referencing
-
-### When AI Creates RCA Docs
-
-When Cascade or other AI assistants provide detailed root cause breakdowns:
-
-1. **Auto-Save**: Save the analysis to `/specs/troubleshooting/[issue]-[date].md`
-2. **Auto-Index**: Update README.md with new entry
-3. **Commit**: Add to git with the bug fix (RCAs are now version controlled)
-4. **Reference**: Link from PR description, commit message, or code comments
-5. **Review**: Team reviews during PR if issue was particularly complex
-
-### Manual Creation
-
-Developers should create RCA docs when:
-
-1. They discover something they wish they'd known earlier
-2. They solve a bug that took >1 hour to diagnose
-3. They implement a workaround that needs explanation
-4. They want to document tribal knowledge
-5. AI wasn't involved in the debugging process
-
-## Quality Standards
-
-RCA documents should:
-
-- ✅ **Be Specific**: Include actual code snippets, not generic descriptions
-- ✅ **Show Timeline**: Explain the debugging journey, not just the answer
-- ✅ **Include Visuals**: Add diagrams, screenshots, or ASCII art when helpful
-- ✅ **Credit Sources**: Link to docs, Stack Overflow, or references that helped
-- ✅ **Be Honest**: Include what didn't work and why
-- ✅ **Use Plain Language**: Avoid jargon where possible; explain when necessary
-
-## Examples of Good RCA Titles
-
-- ✅ "Video Transcript Auto-Sync Fix - Callback Ref vs useEffect"
-- ✅ "Timer Component Re-render Loop - State Closure Issue"
-- ✅ "Next-Video Asset Loading - Storage Hook Implementation"
-- ✅ "Authentication Middleware Race Condition - Cookie Timing"
-
-## Examples of Poor RCA Titles
-
-- ❌ "Bug Fix" (too generic)
-- ❌ "Video Issue" (not specific)
-- ❌ "Fixed the thing" (no context)
-- ❌ "Update" (meaningless)
-
-## Maintenance
-
-- **Retention**: Keep RCA docs indefinitely (they're in git history anyway)
-- **Organization**: Create subdirectories by category or year if folder gets large
-- **Search**: Use filename conventions that support `grep`/`find`/GitHub search
-- **Index**: Maintain `README.md` in `/specs/troubleshooting/` with categorized links
-- **Updates**: If a pattern evolves, update the RCA or add a "Follow-up" section
-- **Cross-Reference**: Link RCAs from relevant spec files when patterns are codified
-
-## Success Metrics
-
-A good RCA documentation practice should result in:
-
-1. Faster debugging of similar issues (pattern recognition)
-2. Fewer repeated mistakes (institutional memory)
-3. Better PR reviews (reviewers can reference similar fixes)
-4. Improved onboarding (real examples vs theoretical docs)
-5. Stronger team knowledge sharing
-
----
-
-**Note**: This is a living document. Update it as the team's RCA practices evolve.
diff --git a/specs/09-technical-debt.md b/specs/09-technical-debt.md
deleted file mode 100644
index 9448cce..0000000
--- a/specs/09-technical-debt.md
+++ /dev/null
@@ -1,51 +0,0 @@
-# Technical Debt
-
-This document tracks technical debt items requiring future attention, following the established specification numbering system.
-
-## Styling System Consistency
-
-### Tavus CVI Components - CSS Modules to Tailwind v4 Migration
-
-**Status**: Phase 1 - Deferred to Post-MVP
-
-**Issue**: Tavus CVI components use CSS modules, while the rest of the project uses TailwindCSS v4 + shadcn/ui (as defined in `specs/03-design-system-standards.md`).
-
-**Impact**:
-- Two styling systems in codebase
-- Inconsistent with design system standards
-- Harder to theme/customize Tavus components
-- Potential maintenance complexity
-
-**Affected Files**:
-- `src/components/cvi/components/conversation/conversation.module.css`
-- `src/components/cvi/components/audio-wave/audio-wave.module.css`
-- `src/components/cvi/components/device-select/device-select.module.css`
-- All other auto-generated CVI component styles
-
-**Recommended Action**:
-1. Create Phase 2+ task to refactor Tavus components to Tailwind
-2. Replicate video UI styles using Tailwind utility classes
-3. Ensure responsive design and dark mode compatibility
-4. Remove CSS module files after migration
-5. Update component library to use shadcn/ui patterns
-
-**Priority**: Medium (post-MVP feature validation)
-
-**Estimated Effort**: 4-6 hours
-
-**Created**: 2025-10-21 (Phase 1: Ask a Question feature)
-
-**Related Specs**:
-- `specs/03-design-system-standards.md` - Tailwind v4 + shadcn/ui standards
-- `specs/features/ask-question-tavus.md` - Feature specification
-
----
-
-## Future Debt Items
-
-Add new technical debt items below following the same format:
-- Clear status and priority
-- Impact assessment
-- Recommended action
-- Time estimates
-- Related specifications
diff --git a/specs/WINDSURF-RULES.md b/specs/ENHANCED-PROJECT-STANDARDS.md
similarity index 60%
rename from specs/WINDSURF-RULES.md
rename to specs/ENHANCED-PROJECT-STANDARDS.md
index d2f94ed..bf4f6e8 100644
--- a/specs/WINDSURF-RULES.md
+++ b/specs/ENHANCED-PROJECT-STANDARDS.md
@@ -1,35 +1,60 @@
-# 8P3P LMS - Windsurf Project Rules
-
-> **Consolidated project standards distilled from specifications**
-> **Activation Mode**: Always On
-> **File Limit**: 12000 characters (Windsurf requirement)
-
---
+trigger: always_on
+---
+
+# 8P3P LMS - Windsurf Project Rules
-- **Project**: EMDR therapist training LMS (Learning Management System)
+- **Project**: EMDR therapist training LMS
- **Stack**: Next.js 15, React 19, TypeScript 5.9, AWS Amplify Gen2, Tailwind v4, shadcn/ui
- **Development Phase**: MVP feature completion (Phase 1)
- **Testing Strategy**: Manual Q&A testing (no unit tests until post-MVP)
----
+
+## Protocol Execution Order (CRITICAL)
-
+**MANDATORY SEQUENCE** - Must be followed in exact order:
+
+### Step 1: Codebase Analysis Protocol (ALWAYS FIRST)
+- **Trigger**: ANY request involving files, components, or functionality
+- **Required**: Complete existing implementation check before ANY recommendations
+- **Blocker**: Cannot proceed to other protocols without completing this step
+
+### Step 2: Branch Readiness Protocol
+- **Trigger**: Creating new branches or starting development work
+- **Required**: User confirmation before any branch creation
+- **Depends on**: Step 1 completion
+
+### Step 3: Implementation
+- **Trigger**: After user approval from Step 2
+- **Required**: Follow all quality gates and standards
+- **Depends on**: Steps 1 & 2 completion
+**VIOLATION CONSEQUENCES**:
+- Inaccurate recommendations (ignoring existing work)
+- Wasted development time
+- Loss of user trust in AI recommendations
+
+
+
## Branch Readiness Protocol (MANDATORY)
+**PREREQUISITE**: Codebase Analysis Protocol MUST be completed first.
+
Before starting ANY new feature:
-1. **Present Branch Readiness Plan**: Show feature spec, branch strategy, stacked PR plan, timeline
-2. **Get User Confirmation**: Ask "Ready to create the branch and start {feature_name} development? 🚀"
-3. **Wait for Approval**: Do NOT create branches without explicit user confirmation
-4. **Document Decision**: Record approval before proceeding
+1. **Complete Codebase Analysis**: Verify existing implementations and acknowledge current state
+2. **Present Branch Readiness Plan**: Show feature spec, branch strategy, stacked PR plan, timeline
+3. **Get User Confirmation**: Ask "Ready to create the branch and start {feature_name} development? 🚀"
+4. **Wait for Approval**: Do NOT create branches without explicit user confirmation
+5. **Document Decision**: Record approval before proceeding
+
+**BLOCKER**: Cannot proceed without completing Step 1 (Codebase Analysis)
## LOC Verification (MANDATORY)
Before every commit:
```bash
-# Verify actual line count
git diff --cached --shortstat
git diff --cached --stat
```
@@ -41,20 +66,14 @@ git diff --cached --stat
- **EXCEPTION**: Auto-generated library files (document in commit)
## PR & Release Standards
-
- **PR Size**: 200-400 LOC maximum per PR
- **Stacked PRs**: For complex features, break into dependent PRs
- **Commit Format**: Semantic commits (feat:, fix:, docs:, refactor:, etc.)
- **Branch Strategy**: feature → dev → release/vX.Y.Z → main
-
----
-
-
## Server Components First Rule (HIGHEST PRIORITY)
-
- **DEFAULT**: Always start with Server Components (no "use client")
- **ONLY add "use client"** when you need:
- State management (useState, useReducer)
@@ -66,13 +85,9 @@ git diff --cached --stat
### Server Components
```tsx
-export default async function PostPage({
- params,
-}: {
- params: Promise<{ id: string }>;
-}) {
- const { id } = await params; // Next.js 15+ requires await
- return Post {id}
;
+export default async function PostPage({ params }: { params: Promise<{ id: string }> }) {
+ const { id } = await params; // Next.js 15+ requires await
+ return Post {id}
;
}
```
@@ -81,37 +96,23 @@ export default async function PostPage({
"use client";
import { useParams } from "@/hooks/use-params";
-export default function ClientComponent({
- params,
-}: {
- params: Promise<{ id: string }>;
-}) {
- const { id } = useParams(params);
- return Post {id}
;
+export default function ClientComponent({ params }: { params: Promise<{ id: string }> }) {
+ const { id } = useParams(params);
+ return Post {id}
;
}
```
**NEVER**: Use manual Promise unwrapping with `use()` in components
## Data Fetching
-
- **Prefer**: Server-side data fetching in Server Components
- **Client-side**: Only when server-side isn't suitable (real-time updates, user interactions)
- **Use**: ISR with `next: { revalidate: 3600 }` for cacheable data
-
----
-
-
## Authentication Standards
-### Required Imports
-```typescript
-import { defineAuth, secret } from "@aws-amplify/backend";
-```
-
### Core Rules
- **ALWAYS** import `secret` for auth configurations
- **External Providers**: Only Google, Apple, Amazon, Facebook supported
@@ -132,74 +133,77 @@ import { defineAuth, secret } from "@aws-amplify/backend";
### Enums
- Don't use `.required()` or `.defaultValue()` with enums
-- Enums are type-safe by definition
-
----
-
-
## Tailwind CSS v4 + shadcn/ui Standards
### CSS-First Configuration
- **No config file needed**: Tailwind v4 uses CSS-first configuration
- **Single import**: `@import "tailwindcss";` in globals.css
-- **Theme customization**: Use `@theme` directive with CSS variables
### Stylesheet Structure (globals.css)
-
-**Order matters**:
-1. `@import` statements first
-2. `@theme` directive for Tailwind customization
-3. CSS variables in `:root` and `.dark`
-4. `@layer` directives last
+**Order matters**: `@import` → `@theme` → CSS variables → `@layer`
### Base Layer Rules
-
- **Use CSS variables directly** in `@layer base`
- **Correct**: `background-color: var(--background);`
- **Incorrect**: `@apply bg-background;`
-- **Reason**: Tailwind v4 promotes CSS-first approach
### Component Standards
-
- **Primary**: shadcn/ui components for all UI elements
- **Custom Components**: Follow shadcn/ui patterns and composition
- **Styling**: Tailwind utility classes only (no CSS Modules except auto-generated libraries)
-- **Theme**: Use CSS variables for dynamic theming
-
----
-
+## Codebase Analysis Protocol (MANDATORY - ALWAYS FIRST)
+
+**CRITICAL**: This protocol MUST be executed BEFORE any other protocols or recommendations.
-## Codebase Analysis Protocol (MANDATORY)
+### Trigger Conditions
+- User requests feature implementation
+- User asks about existing functionality
+- User mentions creating/modifying files
+- User says "proceed with [feature]"
+- ANY development-related request
-Before ANY recommendations about files/components/functionality:
+### Required Analysis Steps
-### 1. Existing Implementation Check
+**Step 1: Search Existing Implementations**
```bash
-grep_search "functionName|ComponentName" # Check existing implementations
-find_by_name "*feature*|*component*" # Find related files
-grep_search "import.*ComponentName" # Check usage patterns
+grep_search "featureName|ComponentName"
+find_by_name "*feature*|*component*"
+grep_search "import.*ComponentName"
```
-### 2. Duplication Prevention
-- **NEVER** suggest creating new files without checking existing implementations
-- **NEVER** assume functionality doesn't exist without comprehensive searching
-- **ALWAYS** build upon existing work rather than recreating it
-- **ALWAYS** acknowledge existing implementations before suggesting changes
+**Step 2: Read Complete Context**
+- Read ALL related files completely (not partial)
+- Understand existing architecture and patterns
+- Identify what's already implemented vs what's missing
-### 3. Recommendation Protocol
-- **READ FIRST, RECOMMEND SECOND**: Scan existing codebase thoroughly
-- **VERIFY ASSUMPTIONS**: Never assume something doesn't exist
-- **ASK CLARIFYING QUESTIONS**: "I see you have X, are you looking to enhance it or replace it?"
-- **ACKNOWLEDGE EXISTING WORK**: Recognize what's already implemented
+**Step 3: Acknowledge Before Recommending**
+- **ALWAYS** acknowledge existing implementations first
+- State completion percentage: "X is 85% complete, missing Y and Z"
+- Build upon existing work rather than recreating
-## Quality Gates (Before Feature Completion)
+### Enforcement Rules
+- **NEVER** present plans without completing analysis first
+- **NEVER** assume files don't exist without searching
+- **NEVER** ignore existing implementations in recommendations
+- **ALWAYS** state "Following Codebase Analysis Protocol" when starting
+- **ALWAYS** acknowledge existing work before suggesting new work
+
+### Violation Prevention
+**Before ANY recommendation, ask yourself**:
+1. ✅ Did I search for existing implementations?
+2. ✅ Did I read the complete existing code?
+3. ✅ Did I acknowledge what's already built?
+4. ✅ Am I building upon existing work vs recreating?
+**If ANY answer is NO, STOP and complete the analysis first.**
+
+## Quality Gates (Before Feature Completion)
**ALL must pass before declaring features complete**:
1. **ESLint**: `npm run lint` (0 errors, 0 warnings)
2. **TypeScript**: `npm run type-check` (full compilation)
@@ -218,7 +222,6 @@ grep_search "import.*ComponentName" # Check usage patterns
### Naming Conventions
- **Variables/Functions**: camelCase
- **Components/Types**: PascalCase
-- **Unused Variables**: Prefix with `_`
- **Files**: kebab-case for utilities, PascalCase for components
## Comment Standards
@@ -227,14 +230,8 @@ grep_search "import.*ComponentName" # Check usage patterns
```typescript
/**
* Analyzes video content and calculates engagement time
- *
* @param content - Video URL and metadata
- * @param userProfile - User's learning preferences
* @returns Estimated completion time with confidence score
- *
- * @example
- * const estimate = analyzeVideo('/videos/intro.mp4', userProfile);
- * // Returns: { timeMinutes: 15, confidence: 0.85 }
*/
```
@@ -242,21 +239,30 @@ grep_search "import.*ComponentName" # Check usage patterns
- **WHY decisions**: Document reasoning behind non-obvious implementations
- **Edge Cases**: Explain handling of special conditions
- **Error Handling**: Document recovery strategies
-- **Performance**: Note optimization reasons
-
-### TODO Comments
-```typescript
-// TODO: [#TICKET-123] High priority - Add error retry logic
-// Context: Current implementation fails silently on network errors
-// Timeline: Sprint 3
-```
+## AI Accountability Standards
+
+### Protocol Compliance Verification
+**Before presenting ANY plan or recommendation**:
+1. ✅ **State Protocol**: "Following Codebase Analysis Protocol..."
+2. ✅ **Show Evidence**: Present search results and existing implementations found
+3. ✅ **Acknowledge Work**: "I found X is already implemented, Y needs completion"
+4. ✅ **Build Upon**: "Building upon existing work rather than recreating"
+5. ✅ **Accurate Scope**: Present realistic LOC and timeline based on actual state
+
+### Trust Maintenance
+**User can rely on AI recommendations when**:
+- All protocols followed in correct sequence
+- Existing work acknowledged and respected
+- Plans based on actual codebase state, not assumptions
+
+**User should question AI recommendations when**:
+- Protocols skipped or reordered
+- Existing implementations ignored
+- Plans seem to recreate existing functionality
----
-
-
## Component Reusability Protocol (MANDATORY)
Before creating ANY new component:
@@ -275,18 +281,9 @@ grep_search "ComponentName" src/components/
1. **Reuse existing**: Extend or compose existing components
2. **shadcn/ui base**: Build on shadcn/ui components
3. **Create new**: Only when above options aren't suitable
-
-### 4. Composition Over Creation
-- Prefer composing multiple small components
-- Document component composition in JSDoc headers
-- Follow shadcn/ui patterns for consistency
-
----
-
-
## Systematic Issue Resolution
### Resolution Protocol
@@ -297,115 +294,57 @@ grep_search "ComponentName" src/components/
### Confirmation Process
```
-REQUIRED STEPS:
1. Present solution and changes made
2. Ask user to test the fix
3. Request explicit confirmation: "Can you confirm this issue is resolved?"
4. Wait for user verification
-5. If not resolved, investigate further
```
### RCA Documentation
-
Create RCA document when:
- Bug required significant investigation (>30 minutes)
- Root cause was non-obvious
-- Issue involves React/Next.js patterns not widely known
- Multiple approaches were evaluated
-- Debugging revealed important architecture insights
-
----
-
-
## Clarifying Questions Framework
### Before Implementation
- **ALWAYS** ask clarifying questions before implementation
- **NEVER** assume requirements without confirmation
-- **DOCUMENT** all assumptions and decisions
-- **VALIDATE** understanding before proceeding
### Question Categories
-
-**Technical Architecture**:
-- Data structure and relationships
-- User interaction flow
-- Performance requirements
-- Integration patterns
-- Scalability considerations
-
-**Feature Specification**:
-- Exact functionality
-- Edge case handling
-- Validation rules
-- Error handling approach
-- Accessibility requirements
-
-**Implementation**:
-- Technology stack choices
-- Component architecture
-- State management approach
-- Testing strategy
-- Deployment approach
+**Technical Architecture**: Data structure, user flow, performance, integration, scalability
+**Feature Specification**: Functionality, edge cases, validation, error handling, accessibility
+**Implementation**: Technology choices, component architecture, state management, testing, deployment
## MoSCoW Prioritization
-
- **Must Have**: Critical features for MVP
- **Should Have**: Important but not critical
- **Could Have**: Nice to have features
-- **Won't Have**: Out of scope for current iteration
-
----
-
-
## MVP Testing Approach
-
**Current Phase**: Manual Q&A testing only
- **No unit tests**: Deferred until post-MVP
- **Focus**: Feature completion over test coverage
- **Quality Gates**: ESLint, TypeScript, build validation only
-
-**Rationale**: Rapid iteration and feature completion for MVP delivery
-
-**Post-MVP**: Comprehensive automated testing suite will be implemented
-
----
-
-
## Mock Data Best Practices
-
- **Location**: Centralized in `src/lib/mock-data.ts`
- **TypeScript**: Use proper interfaces for typed data
- **Organization**: Group by feature
-- **Structure**: Easy replacement for real APIs
-- **Alternatives**: `src/data/`, `src/mocks/`, or `src/lib/data/` for larger projects
-
----
-
-
## Current Technical Debt
### Tavus CVI Components - CSS Modules
**Status**: Deferred to Post-MVP
-
**Issue**: Tavus CVI uses CSS modules; project uses Tailwind v4 + shadcn/ui
-
-**Impact**: Two styling systems in codebase
-
**Action**: Post-MVP migration to Tailwind patterns
-
-**Priority**: Medium (after feature validation)
-
-
+
\ No newline at end of file
diff --git a/specs/README.md b/specs/README.md
new file mode 100644
index 0000000..b798117
--- /dev/null
+++ b/specs/README.md
@@ -0,0 +1,41 @@
+# 8P3P LMS - Specifications
+
+This directory contains the core project specifications and documentation.
+
+## 📁 Directory Structure
+
+### Active Files
+- **`features/`** - Feature specifications (managed separately)
+- **`troubleshooting/`** - Troubleshooting guides and RCA documentation
+
+### Archive
+- **`archive/`** - Historical specification files and enhanced project standards (not tracked in git)
+
+## 🎯 Primary Reference
+
+**Use `.windsurf/rules/project-standards.md`** as the single source of truth for:
+- Development workflow and protocols
+- Code quality standards
+- Architecture guidelines (Next.js 15, AWS Amplify Gen2, Tailwind v4)
+- Component development standards
+- Testing strategy
+
+## 📋 Protocol Hierarchy
+
+All development work must follow this sequence:
+1. **Codebase Analysis Protocol** (ALWAYS FIRST)
+2. **Branch Readiness Protocol**
+3. **Implementation**
+
+## 🔄 Maintenance
+
+- **Project Standards**: Update `.windsurf/rules/project-standards.md` for any rule changes
+- **Features**: Add new feature specs to `features/` directory
+- **Troubleshooting**: Document RCA findings in `troubleshooting/`
+- **Archive**: Historical files preserved locally but not tracked in git
+
+---
+
+**Status**: Cleaned up and organized (2025-01-21)
+**Active Rules**: `.windsurf/rules/project-standards.md`
+**Archive**: Not tracked in version control
diff --git a/specs/WINDSURF-RULES-ANALYSIS.md b/specs/WINDSURF-RULES-ANALYSIS.md
deleted file mode 100644
index cef6b02..0000000
--- a/specs/WINDSURF-RULES-ANALYSIS.md
+++ /dev/null
@@ -1,421 +0,0 @@
-# Windsurf Rules Consolidation Analysis
-
-**Date**: 2025-01-21
-**Analyst**: Cascade AI
-**Objective**: Consolidate project specifications into a single Windsurf-compatible rules document
-
----
-
-## Executive Summary
-
-Successfully consolidated 10 specification documents (excluding `specs/features/`) into a single, project-specific Windsurf rules document following official best practices from windsurf.com.
-
-**Result**: `WINDSURF-RULES.md` (11,566 characters / 12,000 limit)
-
----
-
-## Source Documents Analyzed
-
-| Spec File | Size | Key Content Extracted |
-|-----------|------|----------------------|
-| `00-specification-framework.md` | 395 lines | Requirements gathering, MoSCoW prioritization, branch readiness protocol |
-| `01-development-standards.md` | 484 lines | Code quality, ESLint rules, component reusability, codebase analysis protocol |
-| `02-aws-amplify-backend.md` | 222 lines | Authentication config, data schema design, relationship patterns |
-| `03-design-system-standards.md` | 384 lines | Tailwind v4 + shadcn/ui standards, CSS-first configuration, theme system |
-| `04-nextjs15-standards.md` | 454 lines | Server components first, route parameters, data fetching patterns |
-| `05-bug-resolution-workflow.md` | 202 lines | Systematic issue resolution, user confirmation protocol |
-| `06-project-specification.md` | 275 lines | Project context, tech stack, requirements (Must/Should/Could/Won't Have) |
-| `07-release-strategy.md` | 329 lines | Sprint-based development, PR workflow, LOC verification, stacked PRs |
-| `08-troubleshooting-documentation.md` | 225 lines | RCA documentation standards, when to create RCA docs |
-| `09-technical-debt.md` | 52 lines | Current technical debt tracking (Tavus CSS Modules) |
-
-**Total Input**: 3,022 lines across 10 specification documents
-**Output**: Single consolidated rules document
-
----
-
-## Consolidation Strategy
-
-### 1. Windsurf Best Practices Applied
-
-Following official guidance from https://windsurf.com/editor/directory and https://docs.windsurf.com:
-
-✅ **Keep rules simple, concise, and specific**
-- Removed verbose explanations
-- Focused on actionable standards
-- Eliminated generic advice already in Cascade's training
-
-✅ **Use bullet points, numbered lists, and markdown**
-- Structured with clear hierarchies
-- Easy-to-scan format
-- Consistent formatting throughout
-
-✅ **Project-specific standards only**
-- Filtered out generic coding advice
-- Kept unique 8P3P LMS requirements
-- Maintained project context and tech stack
-
-✅ **XML tags for grouping**
-- Used semantic tags: ``, ``, etc.
-- Logical grouping of related rules
-- Easy navigation and reference
-
-✅ **Character limit compliance**
-- 11,566 characters (under 12,000 limit)
-- Balanced comprehensiveness with conciseness
-- Prioritized high-impact rules
-
-### 2. Rule Organization
-
-**Structured by workflow priority**:
-
-1. **Project Context** - Tech stack, development phase, testing strategy
-2. **Development Workflow** - Branch readiness, LOC verification, PR standards (MANDATORY protocols)
-3. **Next.js 15 Architecture** - Server components first, route parameters, data fetching
-4. **AWS Amplify Backend** - Authentication, data schema, relationship patterns
-5. **Design System** - Tailwind v4 + shadcn/ui standards
-6. **Code Quality** - Codebase analysis, quality gates, ESLint, comments
-7. **Component Development** - Reusability protocol, shadcn/ui integration
-8. **Bug Resolution** - Systematic resolution, user confirmation
-9. **Specification Process** - Clarifying questions, MoSCoW prioritization
-10. **Testing Strategy** - MVP Q&A testing approach
-11. **Mock Data** - Best practices and organization
-12. **Technical Debt** - Current debt tracking
-
-### 3. Content Distillation
-
-**High-impact rules prioritized**:
-- ✅ MANDATORY protocols (branch readiness, LOC verification, codebase analysis)
-- ✅ Framework-specific standards (Next.js 15, Amplify Gen2, Tailwind v4)
-- ✅ Project-specific patterns (Server Components first, route parameters)
-- ✅ Quality gates and validation requirements
-- ✅ Common pitfalls and error prevention
-
-**Removed/Minimized**:
-- ❌ Lengthy examples (kept only essential code snippets)
-- ❌ Redundant explanations
-- ❌ Generic best practices (already in Cascade's training)
-- ❌ Feature-specific specs (kept in `specs/features/`)
-- ❌ Historical context and decision logs
-
----
-
-## Rules Activation Strategy
-
-### Recommended Activation Mode: **Always On**
-
-**Rationale**:
-- These are core project standards that apply to ALL development work
-- Covers architectural decisions, code quality, and workflow requirements
-- Essential for maintaining consistency across the entire codebase
-
-### Alternative Activation Modes
-
-If performance concerns arise with "Always On":
-
-**Model Decision** mode with description:
-```
-Apply these rules when working on:
-- Next.js components and pages
-- AWS Amplify backend configuration
-- Tailwind CSS styling and theming
-- Code quality and PR submissions
-- Feature development and bug fixes
-```
-
-**Glob patterns** for specific file types:
-- `*.tsx`, `*.ts` - TypeScript/React files
-- `amplify/**/*` - Amplify backend files
-- `src/app/**/*` - Next.js App Router files
-- `*.css` - Tailwind/styling files
-
----
-
-## Integration Path
-
-### Option 1: Windsurf Rules Directory (Recommended)
-
-**Location**: `.windsurf/rules/project-standards.md`
-
-**Steps**:
-1. Copy `specs/WINDSURF-RULES.md` → `.windsurf/rules/project-standards.md`
-2. Configure activation mode in Windsurf UI: **Always On**
-3. Verify rules appear in Customizations panel
-4. Test by starting a new Cascade conversation
-
-**Pros**:
-- ✅ Native Windsurf integration
-- ✅ Auto-loaded for all conversations
-- ✅ Can be activated/deactivated via UI
-
-**Cons**:
-- ⚠️ `.windsurf/rules/` is gitignored by default
-- ⚠️ Requires manual setup for new team members
-
-**Gitignore Update**: Already applied to allow tracking of `project-standards.md`
-
-### Option 2: Global Rules (Multi-Project)
-
-If these standards apply across multiple projects:
-
-**Location**: Global rules via Windsurf UI
-
-**Steps**:
-1. Open Windsurf → Customizations → Rules
-2. Click "+ Global" button
-3. Paste content from `WINDSURF-RULES.md`
-4. Set activation mode: **Model Decision** or **Always On**
-
-**Pros**:
-- ✅ Available across all workspaces
-- ✅ Single source of truth for multi-project teams
-
-**Cons**:
-- ⚠️ Not project-specific
-- ⚠️ Harder to version control
-
-### Option 3: Reference Document (Current State)
-
-Keep as `specs/WINDSURF-RULES.md` for reference:
-
-**Pros**:
-- ✅ Version controlled in Git
-- ✅ Easy to review and update
-- ✅ Team visibility and collaboration
-
-**Cons**:
-- ❌ Not automatically loaded by Windsurf
-- ❌ Requires manual @mention in Cascade conversations
-
----
-
-## Next Steps
-
-### Immediate Actions
-
-1. **Review Consolidated Rules**
- - Read through `specs/WINDSURF-RULES.md`
- - Validate accuracy and completeness
- - Identify any missing critical standards
-
-2. **Choose Integration Path**
- - Decide on activation strategy (Always On vs Model Decision)
- - Select location (workspace rules vs global vs reference)
-
-3. **Test Integration**
- - Start new Cascade conversation
- - Verify rules are accessible (via @mention or auto-loading)
- - Test with sample development task
-
-### Phase 2 Enhancements
-
-After initial validation:
-
-4. **Fine-tune Rule Activation**
- - Monitor which rules are most/least useful
- - Adjust activation modes if needed
- - Split into multiple rule files if growing too large
-
-5. **Update Workflow**
- - Integrate rules into onboarding documentation
- - Add to CONTRIBUTING.md
- - Update README with Windsurf setup instructions
-
-6. **Maintenance Schedule**
- - Review rules after major feature completions
- - Update when new patterns emerge
- - Sync with spec document changes
-
----
-
-## Maintenance Guidelines
-
-### When to Update Rules
-
-**Immediate updates required**:
-- ✅ New framework versions (Next.js, React, Amplify)
-- ✅ Major architectural decisions
-- ✅ New mandatory protocols or workflows
-- ✅ Breaking changes to existing patterns
-
-**Periodic reviews**:
-- 🔄 After each sprint completion
-- 🔄 When patterns emerge from multiple PRs
-- 🔄 Team retrospective feedback
-
-### Update Process
-
-1. **Identify Change**: New pattern, protocol, or standard emerges
-2. **Evaluate Impact**: Is it project-wide or feature-specific?
-3. **Update Sources**: Modify relevant spec documents first
-4. **Regenerate Rules**: Re-consolidate into Windsurf rules
-5. **Validate**: Test with Cascade to ensure accuracy
-6. **Communicate**: Notify team of updated standards
-
-### Version Control
-
-**Spec Documents**: Full detail, version controlled in Git
-- `specs/00-specification-framework.md`
-- `specs/01-development-standards.md`
-- etc.
-
-**Windsurf Rules**: Distilled version, may or may not be in Git
-- `.windsurf/rules/project-standards.md` (if gitignore updated)
-- `specs/WINDSURF-RULES.md` (reference copy, always tracked)
-
-**Sync Strategy**: Treat spec docs as source of truth, regenerate rules from specs
-
----
-
-## Benefits Delivered
-
-### For Cascade AI
-
-✅ **Comprehensive Context**: Full project standards in single document
-✅ **Consistent Behavior**: Always follows project-specific patterns
-✅ **Reduced Errors**: Prevents common mistakes (e.g., wrong route parameter handling)
-✅ **Faster Responses**: No need to search multiple spec files
-✅ **Better Quality**: Enforces quality gates and code standards
-
-### For Development Team
-
-✅ **Standardization**: Consistent code across all features
-✅ **Onboarding**: New developers get standards automatically via AI
-✅ **Efficiency**: Less time correcting AI-generated code
-✅ **Quality**: Automatic enforcement of best practices
-✅ **Documentation**: Single reference for project standards
-
-### For Project
-
-✅ **Code Quality**: Enforced standards prevent technical debt
-✅ **Velocity**: Faster development with consistent patterns
-✅ **Maintainability**: Predictable code structure
-✅ **Scalability**: Standards support team growth
-✅ **Knowledge Preservation**: Standards documented and accessible
-
----
-
-## Character Budget Analysis
-
-**Target**: 12,000 characters maximum (Windsurf limit)
-**Actual**: 11,566 characters
-**Remaining**: 434 characters (3.6% buffer)
-
-### Character Distribution
-
-| Section | Chars | % |
-|---------|-------|---|
-| Project Context | 482 | 4.2% |
-| Development Workflow | 1,248 | 10.8% |
-| Next.js 15 Architecture | 1,456 | 12.6% |
-| AWS Amplify Backend | 1,389 | 12.0% |
-| Design System | 1,248 | 10.8% |
-| Code Quality | 2,894 | 25.0% |
-| Component Development | 847 | 7.3% |
-| Bug Resolution | 982 | 8.5% |
-| Specification Process | 724 | 6.3% |
-| Testing Strategy | 328 | 2.8% |
-| Mock Data | 346 | 3.0% |
-| Technical Debt | 622 | 5.4% |
-
-**Largest Section**: Code Quality (25.0%) - reflects priority on quality gates and standards
-
-**Opportunities for expansion** (if needed):
-- Testing strategy details (post-MVP)
-- Component patterns library
-- Advanced Amplify patterns
-- Performance optimization rules
-
----
-
-## Comparison: Before vs After
-
-### Before Consolidation
-
-**Fragmented Standards**:
-- 10 separate specification documents
-- 3,022 total lines
-- Scattered across different files
-- Required manual searching and cross-referencing
-- Not integrated with Windsurf AI
-
-**Cascade Behavior**:
-- May miss relevant standards
-- Requires @mention of specific specs
-- Inconsistent application of rules
-- Longer response times (searching specs)
-
-### After Consolidation
-
-**Unified Standards**:
-- Single rules document
-- 11,566 characters
-- Organized by workflow priority
-- Always available to Cascade
-- Native Windsurf integration
-
-**Cascade Behavior**:
-- Automatic standards enforcement
-- Consistent application of rules
-- Faster, more accurate responses
-- Proactive error prevention
-- Project-specific recommendations
-
----
-
-## Success Metrics
-
-Track these metrics to validate effectiveness:
-
-### Code Quality
-- ✅ Reduction in ESLint errors
-- ✅ Fewer PR revision requests
-- ✅ Improved TypeScript strict mode compliance
-
-### Development Efficiency
-- ✅ Faster PR review times
-- ✅ Fewer back-and-forth clarifications with Cascade
-- ✅ Reduced time fixing AI-generated code
-
-### Consistency
-- ✅ Uniform component patterns across codebase
-- ✅ Consistent API route structures
-- ✅ Standardized error handling
-
-### Knowledge Sharing
-- ✅ Faster onboarding for new developers
-- ✅ Better adherence to architectural decisions
-- ✅ Reduced "how do we do X?" questions
-
----
-
-## Conclusion
-
-Successfully distilled 10 comprehensive specification documents into a single, actionable Windsurf rules document that:
-
-1. **Follows official Windsurf best practices** from windsurf.com
-2. **Stays under character limit** (11,566 / 12,000)
-3. **Covers all critical project standards**
-4. **Organized for easy navigation and reference**
-5. **Ready for immediate integration** with Windsurf AI
-
-Next step: **Choose integration path** and test with Cascade to validate effectiveness.
-
----
-
-## Appendix: Rule Extraction Matrix
-
-| Source Spec | Priority Rules Extracted | Secondary Rules | Excluded |
-|-------------|------------------------|----------------|----------|
-| `00-specification-framework.md` | Branch readiness protocol, MoSCoW prioritization | Safe rollback points | Historical context |
-| `01-development-standards.md` | Server components first, codebase analysis protocol, quality gates | Comment standards, ESLint rules | Verbose examples |
-| `02-aws-amplify-backend.md` | Auth config rules, schema design patterns | Deployment configs | Implementation details |
-| `03-design-system-standards.md` | Tailwind v4 standards, CSS-first config | Theme system | Color palette details |
-| `04-nextjs15-standards.md` | Route parameters handling, data fetching | Navigation patterns | Edge case examples |
-| `05-bug-resolution-workflow.md` | User confirmation protocol, RCA triggers | Resolution templates | Ticket formats |
-| `06-project-specification.md` | Tech stack, project context | Requirements overview | Detailed feature specs |
-| `07-release-strategy.md` | LOC verification, PR standards, stacked PRs | Semantic commits | Sprint planning details |
-| `08-troubleshooting-documentation.md` | When to create RCA docs | RCA structure | Template details |
-| `09-technical-debt.md` | Current debt items | — | Historical debt |
-
-**Extraction Ratio**: ~35-40% of content became rules (high-impact, actionable standards only)
diff --git a/specs/WINDSURF-RULES-SETUP.md b/specs/WINDSURF-RULES-SETUP.md
deleted file mode 100644
index 8888e25..0000000
--- a/specs/WINDSURF-RULES-SETUP.md
+++ /dev/null
@@ -1,335 +0,0 @@
-# Windsurf Rules Setup Guide
-
-**Quick start guide for integrating consolidated project standards with Windsurf AI**
-
----
-
-## TL;DR
-
-**Consolidated Rules**: `specs/WINDSURF-RULES.md` (11,566 chars / 12,000 limit)
-**Activation**: Copy to `.windsurf/rules/project-standards.md` → Set "Always On"
-**Status**: ✅ Ready for integration
-
----
-
-## Setup Instructions
-
-### Option 1: Workspace Rules (Recommended)
-
-**Copy the rules file**:
-```bash
-# From project root
-cp specs/WINDSURF-RULES.md .windsurf/rules/project-standards.md
-```
-
-**Activate in Windsurf**:
-1. Open Windsurf IDE
-2. Click **Customizations** icon (top-right slider menu)
-3. Navigate to **Rules** tab
-4. Find `project-standards.md` in workspace rules
-5. Set activation mode: **Always On**
-6. Confirm rules appear in active rules list
-
-**Verify Integration**:
-1. Start new Cascade conversation
-2. Ask: "What are the Next.js 15 route parameter standards?"
-3. Cascade should reference the rules automatically
-
----
-
-## What's Included
-
-### Mandatory Protocols
-- ✅ Branch Readiness Protocol (requires user confirmation before feature work)
-- ✅ LOC Verification (verify actual line counts before every commit)
-- ✅ Codebase Analysis Protocol (check existing implementations before creating new)
-
-### Architecture Standards
-- ✅ Next.js 15: Server Components first, route parameters handling
-- ✅ AWS Amplify Gen2: Authentication, data schema patterns
-- ✅ Tailwind v4 + shadcn/ui: CSS-first configuration, theme system
-
-### Code Quality
-- ✅ Quality Gates: ESLint, TypeScript, build validation
-- ✅ Component Reusability Protocol
-- ✅ Comment and documentation standards
-
-### Workflow Standards
-- ✅ PR size limits (200-400 LOC)
-- ✅ Stacked PRs for complex features
-- ✅ Bug resolution and user confirmation
-- ✅ Clarifying questions framework
-
----
-
-## Usage Examples
-
-### Before Creating a Component
-
-Cascade will automatically:
-1. Search for existing similar components
-2. Check shadcn/ui for base components
-3. Recommend reuse/composition over creation
-4. Follow project styling standards (Tailwind v4)
-
-### Before Starting a Feature
-
-Cascade will automatically:
-1. Present branch readiness plan
-2. Ask for explicit confirmation
-3. Wait for your approval before creating branches
-4. Document the decision
-
-### Before Every Commit
-
-Cascade will automatically:
-1. Run `git diff --cached --shortstat`
-2. Verify actual line counts
-3. Report LOC in commit messages
-4. Flag if exceeding PR size limits
-
----
-
-## Testing the Integration
-
-### Test 1: Architecture Standards
-**Ask Cascade**: "How should I handle route parameters in a Next.js 15 page?"
-
-**Expected Response**:
-- Server Components: Use `await params`
-- Client Components: Use `useParams` hook
-- Never use manual `use()` unwrapping
-
-### Test 2: Component Creation
-**Ask Cascade**: "Create a new button component with hover effects"
-
-**Expected Behavior**:
-1. Search existing button components
-2. Check shadcn/ui Button component
-3. Recommend using/extending shadcn/ui Button
-4. Only create new if justified
-
-### Test 3: Branch Readiness
-**Ask Cascade**: "Start implementing the user profile feature"
-
-**Expected Behavior**:
-1. Present feature specification
-2. Show branch strategy
-3. Ask: "Ready to create the branch and start user-profile development? 🚀"
-4. Wait for your confirmation
-
----
-
-## Maintenance
-
-### When to Update Rules
-
-**Immediate**:
-- Framework version upgrades (Next.js, React, Amplify)
-- New mandatory protocols or workflows
-- Breaking changes to patterns
-
-**Periodic** (after each sprint):
-- Emerging patterns from multiple PRs
-- Team feedback and retrospective insights
-
-### Update Process
-
-1. **Update source specs** first (`specs/*.md`)
-2. **Regenerate rules**: Re-run consolidation process
-3. **Copy to Windsurf**: Update `.windsurf/rules/project-standards.md`
-4. **Test**: Verify with sample Cascade conversation
-5. **Notify team**: Communicate updated standards
-
----
-
-## Troubleshooting
-
-### Rules Not Appearing
-
-**Check**:
-1. File exists: `.windsurf/rules/project-standards.md`
-2. File size: Under 12,000 characters
-3. Windsurf UI: Rules tab shows the file
-4. Activation: Set to "Always On" or appropriate mode
-
-**Fix**:
-```bash
-# Verify file exists
-ls -la .windsurf/rules/project-standards.md
-
-# Check character count
-wc -c .windsurf/rules/project-standards.md
-
-# Reload Windsurf window
-# Cmd+Shift+P → "Developer: Reload Window"
-```
-
-### Rules Not Being Applied
-
-**Symptoms**:
-- Cascade doesn't follow project patterns
-- No mention of mandatory protocols
-- Generic responses instead of project-specific
-
-**Fix**:
-1. Verify activation mode is "Always On"
-2. Check Rules tab shows active status
-3. Start **new** Cascade conversation (old conversations may not reload rules)
-4. Explicitly @mention the rule if needed: `@project-standards`
-
-### Character Limit Exceeded
-
-**Symptoms**:
-- Rule file won't load
-- Error message about size
-
-**Fix**:
-1. Check current size: `wc -c .windsurf/rules/project-standards.md`
-2. If over 12,000, split into multiple rule files:
- - `architecture-standards.md` (Next.js, Amplify, Design System)
- - `workflow-standards.md` (Branch readiness, LOC, PRs)
- - `code-quality-standards.md` (ESLint, TypeScript, Comments)
-3. Use glob patterns or model decision for targeted activation
-
----
-
-## Benefits Checklist
-
-After setup, you should experience:
-
-### Immediate Benefits
-- ✅ Cascade enforces Server Components first rule
-- ✅ Automatic codebase analysis before creating new files
-- ✅ Branch readiness confirmation prevents premature feature work
-- ✅ LOC verification catches oversized PRs early
-
-### Quality Improvements
-- ✅ Fewer ESLint errors in AI-generated code
-- ✅ Consistent component patterns
-- ✅ Proper TypeScript strict mode compliance
-- ✅ Correct Amplify Gen2 patterns (e.g., `.guest()` not `.public()`)
-
-### Efficiency Gains
-- ✅ Less time fixing AI code
-- ✅ Faster PR reviews (code follows standards)
-- ✅ Fewer back-and-forth clarifications
-- ✅ Better first-time code quality
-
----
-
-## Advanced Configuration
-
-### Multiple Rule Files
-
-If rules grow beyond 12,000 characters:
-
-```
-.windsurf/rules/
-├── project-standards.md # Core standards (Always On)
-├── architecture-patterns.md # Detailed patterns (Model Decision)
-├── component-library.md # Component examples (Manual)
-└── troubleshooting-guide.md # Debug patterns (Manual)
-```
-
-**Activation Strategy**:
-- `project-standards.md`: Always On
-- `architecture-patterns.md`: Model Decision (when working on architecture)
-- `component-library.md`: Manual (@mention when needed)
-- `troubleshooting-guide.md`: Manual (@mention when debugging)
-
-### Glob Pattern Activation
-
-For file-type specific rules:
-
-**TypeScript/React Files**:
-```
-Pattern: **/*.{ts,tsx}
-Activation: Automatic
-```
-
-**Amplify Backend**:
-```
-Pattern: amplify/**/*
-Activation: Automatic
-```
-
-**Styling Files**:
-```
-Pattern: **/*.css
-Activation: Automatic
-```
-
----
-
-## Team Onboarding
-
-### For New Developers
-
-**Setup Steps**:
-1. Clone repository
-2. Run: `cp specs/WINDSURF-RULES.md .windsurf/rules/project-standards.md`
-3. Open Windsurf → Customizations → Rules
-4. Verify `project-standards.md` is active
-5. Start first Cascade conversation to test
-
-**Learning Path**:
-1. Read `specs/WINDSURF-RULES.md` once (10-15 minutes)
-2. Reference during development as needed
-3. Let Cascade enforce automatically
-4. Gradually internalize patterns
-
-### For Existing Developers
-
-**Migration**:
-1. Review consolidated rules vs old spec documents
-2. Note any new mandatory protocols
-3. Update local workflows if needed
-4. Continue referencing full specs for deep dives
-
----
-
-## Support Resources
-
-### Documentation
-- **Full Specs**: `specs/*.md` (detailed explanations)
-- **Consolidated Rules**: `specs/WINDSURF-RULES.md` (quick reference)
-- **Analysis**: `specs/WINDSURF-RULES-ANALYSIS.md` (consolidation process)
-- **This Guide**: `specs/WINDSURF-RULES-SETUP.md` (setup instructions)
-
-### Windsurf Resources
-- **Rules Directory**: https://windsurf.com/editor/directory
-- **Documentation**: https://docs.windsurf.com/windsurf/cascade/memories
-- **Best Practices**: Included in rules directory examples
-
-### Project Resources
-- **CONTRIBUTING.md**: Development workflow and PR guidelines
-- **README.md**: Project overview and setup instructions
-- **specs/**: Complete specification documents
-
----
-
-## Next Steps
-
-1. ✅ **Review**: Read through `specs/WINDSURF-RULES.md`
-2. ✅ **Integrate**: Copy to `.windsurf/rules/project-standards.md`
-3. ✅ **Activate**: Set to "Always On" in Windsurf UI
-4. ✅ **Test**: Run the 3 test scenarios above
-5. ✅ **Validate**: Confirm Cascade follows project standards
-6. ✅ **Proceed**: Move forward with Phase 2 development
-
----
-
-## Success Criteria
-
-Rules are successfully integrated when:
-
-✅ Cascade automatically enforces Server Components first
-✅ Branch readiness confirmation happens before feature work
-✅ Codebase analysis occurs before creating new files
-✅ LOC verification runs before commits
-✅ Amplify Gen2 patterns are correct (`.guest()`, relationships, etc.)
-✅ Tailwind v4 + shadcn/ui standards are followed
-✅ Quality gates are enforced before feature completion
-
-**Status**: Ready for integration and testing 🚀
diff --git a/specs/WINDSURF-RULES-SUMMARY.md b/specs/WINDSURF-RULES-SUMMARY.md
deleted file mode 100644
index 16e3717..0000000
--- a/specs/WINDSURF-RULES-SUMMARY.md
+++ /dev/null
@@ -1,307 +0,0 @@
-# Windsurf Rules Consolidation - Summary
-
-**Date**: 2025-01-21
-**Status**: ✅ Complete - Ready for Integration
-**Character Count**: 11,566 / 12,000 (96.4%)
-
----
-
-## Deliverables
-
-### 1. Consolidated Rules Document
-**File**: `specs/WINDSURF-RULES.md`
-**Size**: 11,566 characters (under Windsurf's 12,000 limit)
-**Format**: Markdown with XML semantic tags
-**Activation**: Designed for "Always On" mode
-
-**Content Sections**:
-- Project Context (tech stack, development phase)
-- Development Workflow (branch readiness, LOC verification, PR standards)
-- Next.js 15 Architecture (server components, routing, data fetching)
-- AWS Amplify Backend (authentication, data schema, relationships)
-- Design System (Tailwind v4 + shadcn/ui standards)
-- Code Quality (codebase analysis, quality gates, ESLint, TypeScript)
-- Component Development (reusability protocol)
-- Bug Resolution (systematic resolution, user confirmation)
-- Specification Process (clarifying questions, MoSCoW)
-- Testing Strategy (MVP Q&A approach)
-- Mock Data (organization best practices)
-- Technical Debt (current debt tracking)
-
-### 2. Comprehensive Analysis
-**File**: `specs/WINDSURF-RULES-ANALYSIS.md`
-
-**Includes**:
-- Source document analysis (10 spec files, 3,022 lines)
-- Consolidation strategy and Windsurf best practices applied
-- Rule organization methodology
-- Content distillation approach
-- Character budget analysis
-- Integration path options (workspace rules, global rules, reference)
-- Maintenance guidelines
-- Success metrics
-- Before/after comparison
-
-### 3. Setup Guide
-**File**: `specs/WINDSURF-RULES-SETUP.md`
-
-**Includes**:
-- Quick start instructions
-- Integration testing procedures
-- Troubleshooting guide
-- Team onboarding process
-- Advanced configuration options
-- Support resources
-
-### 4. Gitignore Update
-**File**: `.gitignore`
-
-**Change**: Allow tracking of `.windsurf/rules/project-standards.md` while ignoring other Windsurf files
-
-```gitignore
-# windsurf
-.windsurf/*
-!.windsurf/rules/
-.windsurf/rules/*
-!.windsurf/rules/project-standards.md
-```
-
----
-
-## Key Features
-
-### Windsurf Best Practices Applied
-
-✅ **Simple, concise, and specific** - No verbose explanations or generic advice
-✅ **Bullet points and markdown** - Easy to scan and navigate
-✅ **Project-specific standards** - Only unique 8P3P LMS requirements
-✅ **XML semantic tags** - Logical grouping: ``, ``, etc.
-✅ **Character limit compliance** - 11,566 chars (434 char buffer remaining)
-
-### Mandatory Protocols Included
-
-✅ **Branch Readiness Protocol** - User confirmation required before feature development
-✅ **LOC Verification Protocol** - Verify actual line counts before every commit
-✅ **Codebase Analysis Protocol** - Check existing implementations before creating new
-
-### Framework-Specific Standards
-
-✅ **Next.js 15** - Server Components first, route parameters with `await`, data fetching patterns
-✅ **AWS Amplify Gen2** - Authentication config, data schema design, relationship patterns
-✅ **Tailwind v4** - CSS-first configuration, base layer rules, theme system
-✅ **shadcn/ui** - Component standards, composition patterns
-
-### Quality & Workflow Standards
-
-✅ **Quality Gates** - ESLint, TypeScript, build validation
-✅ **PR Standards** - 200-400 LOC limits, stacked PRs, semantic commits
-✅ **Component Reusability** - Search existing → Check shadcn/ui → Create new (last resort)
-✅ **Bug Resolution** - Systematic resolution, mandatory user confirmation
-
----
-
-## Source Documents Consolidated
-
-| Spec File | Lines | Key Content |
-|-----------|-------|-------------|
-| `00-specification-framework.md` | 395 | Requirements, MoSCoW, branch readiness |
-| `01-development-standards.md` | 484 | Code quality, ESLint, component reusability |
-| `02-aws-amplify-backend.md` | 222 | Authentication, data schema, relationships |
-| `03-design-system-standards.md` | 384 | Tailwind v4, shadcn/ui, theme system |
-| `04-nextjs15-standards.md` | 454 | Server components, routing, data fetching |
-| `05-bug-resolution-workflow.md` | 202 | Systematic resolution, user confirmation |
-| `06-project-specification.md` | 275 | Project context, tech stack, requirements |
-| `07-release-strategy.md` | 329 | Sprint dev, PR workflow, LOC verification |
-| `08-troubleshooting-documentation.md` | 225 | RCA documentation standards |
-| `09-technical-debt.md` | 52 | Technical debt tracking |
-| **Total** | **3,022** | **Consolidated → 11,566 chars** |
-
-**Consolidation Ratio**: ~35-40% extraction (high-impact, actionable standards only)
-
----
-
-## Integration Options
-
-### Option 1: Workspace Rules (Recommended)
-
-**Command**:
-```bash
-cp specs/WINDSURF-RULES.md .windsurf/rules/project-standards.md
-```
-
-**Pros**:
-- ✅ Native Windsurf integration
-- ✅ Auto-loaded for all conversations
-- ✅ Can be activated/deactivated via UI
-- ✅ Version controlled (gitignore updated)
-
-**Activation**: Always On
-
-### Option 2: Global Rules
-
-**Process**: Windsurf UI → Customizations → Rules → "+ Global" → Paste content
-
-**Pros**:
-- ✅ Available across all workspaces
-- ✅ Single source of truth for multi-project teams
-
-**Activation**: Model Decision or Always On
-
-### Option 3: Reference Document
-
-**Status**: Already available at `specs/WINDSURF-RULES.md`
-
-**Pros**:
-- ✅ Version controlled in Git
-- ✅ Easy to review and update
-- ✅ Team visibility
-
-**Usage**: Manual @mention in Cascade conversations
-
----
-
-## Testing Checklist
-
-### Test 1: Architecture Standards
-**Ask Cascade**: "How should I handle route parameters in Next.js 15?"
-
-**Expected**: Server Components use `await params`, Client Components use `useParams` hook
-
-### Test 2: Component Creation
-**Ask Cascade**: "Create a new card component for displaying user info"
-
-**Expected**: Search existing components → Check shadcn/ui Card → Recommend reuse/composition
-
-### Test 3: Branch Readiness
-**Ask Cascade**: "Start implementing the notification system feature"
-
-**Expected**: Present feature spec → Ask "Ready to create the branch and start notification-system development? 🚀" → Wait for confirmation
-
-### Test 4: Code Quality
-**Ask Cascade**: "Should I use CSS Modules or Tailwind for styling?"
-
-**Expected**: Reference Tailwind v4 + shadcn/ui standards, mention CSS Modules technical debt
-
-### Test 5: LOC Verification
-**Ask Cascade**: "I'm ready to commit my changes"
-
-**Expected**: Run `git diff --cached --shortstat` and verify actual line counts
-
----
-
-## Benefits
-
-### For Cascade AI
-✅ Comprehensive project context in single document
-✅ Consistent enforcement of project-specific patterns
-✅ Automatic error prevention (route parameters, Amplify patterns, styling)
-✅ Faster, more accurate responses
-
-### For Development Team
-✅ Standardized code across all features
-✅ Automatic onboarding of new developers via AI
-✅ Less time correcting AI-generated code
-✅ Consistent PR quality
-
-### For Project
-✅ Enforced quality gates prevent technical debt
-✅ Faster development velocity with consistent patterns
-✅ Maintainable, predictable code structure
-✅ Knowledge preservation and accessibility
-
----
-
-## Maintenance
-
-### Update Triggers
-
-**Immediate**:
-- Framework version upgrades
-- New mandatory protocols
-- Breaking pattern changes
-
-**Periodic** (after sprints):
-- Emerging patterns from multiple PRs
-- Team retrospective feedback
-
-### Update Process
-
-1. Update source specs (`specs/*.md`)
-2. Regenerate consolidated rules
-3. Copy to `.windsurf/rules/project-standards.md`
-4. Test with sample Cascade conversation
-5. Notify team of updates
-
----
-
-## Next Steps
-
-### 1. Review (5-10 minutes)
-- [ ] Read `specs/WINDSURF-RULES.md` completely
-- [ ] Validate accuracy and completeness
-- [ ] Identify any missing critical standards
-
-### 2. Choose Integration Path
-- [ ] Decide: Workspace rules (recommended) vs Global rules vs Reference
-- [ ] Select activation mode: Always On (recommended) vs Model Decision
-
-### 3. Integrate
-- [ ] Copy rules to chosen location
-- [ ] Configure activation in Windsurf UI
-- [ ] Verify rules appear in Customizations panel
-
-### 4. Test
-- [ ] Run all 5 test scenarios above
-- [ ] Start new Cascade conversation
-- [ ] Verify automatic enforcement of standards
-
-### 5. Proceed to Phase 2
-- [ ] Begin next development phase with rules active
-- [ ] Monitor effectiveness
-- [ ] Gather feedback for future refinements
-
----
-
-## Files Created
-
-```
-specs/
-├── WINDSURF-RULES.md # ✅ Consolidated rules (11,566 chars)
-├── WINDSURF-RULES-ANALYSIS.md # ✅ Comprehensive analysis
-├── WINDSURF-RULES-SETUP.md # ✅ Setup and troubleshooting guide
-└── WINDSURF-RULES-SUMMARY.md # ✅ This summary (YOU ARE HERE)
-
-.gitignore # ✅ Updated to allow project-standards.md
-.windsurf/rules/ # ✅ Directory created (ready for rules file)
-```
-
----
-
-## Success Criteria
-
-Rules integration is successful when:
-
-✅ Cascade automatically enforces Server Components first rule
-✅ Branch readiness confirmation occurs before feature work
-✅ Codebase analysis happens before creating new files
-✅ LOC verification runs before commits
-✅ Amplify Gen2 patterns are correct (`.guest()`, relationships)
-✅ Tailwind v4 + shadcn/ui standards are followed
-✅ Quality gates enforced before feature completion
-✅ Component reusability protocol is applied
-
----
-
-## Conclusion
-
-Successfully consolidated 10 specification documents (3,022 lines) into a single, actionable Windsurf rules document (11,566 characters) that:
-
-1. ✅ **Follows official Windsurf best practices** from windsurf.com
-2. ✅ **Stays under character limit** with 3.6% buffer remaining
-3. ✅ **Covers all critical project standards** (architecture, quality, workflow)
-4. ✅ **Organized for easy navigation** with semantic XML tags
-5. ✅ **Ready for immediate integration** with Windsurf AI
-
-**Status**: Ready for Phase 2 🚀
-
-**Recommended Action**: Review consolidated rules, choose integration path, test with Cascade, then proceed with next feature development.
diff --git a/specs/data-table-plan.md b/specs/data-table-plan.md
deleted file mode 100644
index 1c8fb3e..0000000
--- a/specs/data-table-plan.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# Data Table Implementation Plan
-
-After reviewing the current quiz-results-table component and shadcn UI's data table documentation, here's the plan to transform it into a proper data table using TanStack Table:
-
-## 1. Structure Changes
-
-We'll need to:
-- Install TanStack Table dependencies
-- Create column definitions with proper accessors
-- Implement the table instance using `useReactTable` hook
-- Replace the current table rendering with TanStack's flexible rendering
-
-## 2. Features to Add
-
-1. **Sorting**
- - Add sorting functionality to columns (especially for score and date)
- - Include visual indicators for sort direction
-
-2. **Filtering**
- - Add a search input to filter quiz results
- - Implement filter logic using TanStack's filtering capabilities
-
-3. **Pagination**
- - Add pagination controls for larger datasets
- - Show current page information and navigation
-
-4. **Column Management**
- - Add ability to show/hide columns
- - Implement through a dropdown menu
-
-## 3. UI Improvements
-
-- Add status badges with proper styling for pass/fail
-- Improve responsive behavior
-- Maintain the "View All Results" functionality
-
-## 4. Implementation Steps
-
-1. Install TanStack Table: `npm install @tanstack/react-table`
-2. Create a new component structure with column definitions
-3. Implement the table instance with core features
-4. Add sorting, filtering, and pagination functionality
-5. Style the table to match your current design