qualia-framework 2.5.1 → 3.1.0

package/framework/qualia-framework/templates/projects/website.md

@@ -1,137 +0,0 @@
-# Project Template: Website
-
-> Opinionated Next.js + Supabase + Vercel template. Fawzi's exact stack.
-
-**Stack:** Next.js 16+, React 19, TypeScript, Tailwind v4, Supabase, Vercel
-**Phases:** 6
-**Type:** website
-
-## Phases
-
-### Phase 1: Foundation
-**Goal:** Working Next.js app with auth, Supabase connected, protected routes, base layout
-**Skills:** [@supabase]
-**Tasks:**
-- Initialize Next.js 16+ with App Router, TypeScript strict, Tailwind v4
-- Configure Supabase client (server.ts + client.ts pattern from `lib/supabase/`)
-- Implement auth: login, signup, password reset (Supabase Auth)
-- Create protected route middleware (redirect unauthenticated users)
-- Set up base layout: header, footer, navigation shell
-- Configure environment variables (.env.local)
-- Set up RLS on auth-related tables
-
-**Success Criteria:**
-1. User can create account, log in, and see protected dashboard
-2. Unauthenticated users redirected to login
-3. Server-side auth check works (not just client-side)
-4. `npx tsc --noEmit` passes
-
----
-
-### Phase 2: Landing & Marketing
-**Goal:** Polished public-facing pages that convert visitors
-**Skills:** [@frontend-master, @seo-master]
-**Team:** full-stack-team
-**Tasks:**
-- Hero section with distinctive typography and animations
-- Features section with staggered reveal animations
-- Testimonials/social proof section
-- Pricing section (if applicable)
-- CTA sections with micro-interactions
-- About/company page
-- Contact page with form (Supabase insert or email)
-- Footer with navigation, social links
-
-**Success Criteria:**
-1. Landing page loads in under 3s on mobile
-2. All sections have CSS transitions and staggered animations
-3. No generic card grids or blue-purple gradients (Fawzi's frontend rules)
-4. Distinctive fonts (not Inter/Arial)
-5. Mobile-responsive from the start
-
----
-
-### Phase 3: Dashboard / App
-**Goal:** Authenticated user area with full CRUD and real-time data
-**Skills:** [@admin-panel, @supabase]
-**Team:** full-stack-team
-**Tasks:**
-- Dashboard overview page with key metrics
-- Data listing pages with pagination, search, filters
-- Create/edit forms with Zod validation
-- Delete with confirmation dialog
-- Real-time updates (Supabase subscriptions)
-- User profile/settings page
-- Role-based access (if multi-user)
-
-**Success Criteria:**
-1. User can create, read, update, delete core resources
-2. Forms validate with Zod and show clear error messages
-3. Data persists correctly in Supabase with RLS
-4. Loading states and error boundaries on all data-fetching pages
-
----
-
-### Phase 4: SEO & Performance
-**Goal:** Production-grade SEO and Core Web Vitals passing scores
-**Skills:** [@seo-master]
-**Tasks:**
-- Dynamic metadata for all pages (title, description, OG image)
-- JSON-LD structured data (Organization, WebSite, BreadcrumbList)
-- Sitemap.xml generation (dynamic from routes)
-- robots.txt
-- Open Graph and Twitter card meta tags
-- Image optimization (next/image, WebP, lazy loading)
-- Font optimization (next/font, preload critical fonts)
-- Bundle analysis and code splitting review
-
-**Success Criteria:**
-1. Lighthouse SEO score ≥ 95
-2. Core Web Vitals: LCP < 2.5s, FID < 100ms, CLS < 0.1
-3. All pages have unique title and description
-4. JSON-LD renders correctly in Google Rich Results Test
-
----
-
-### Phase 5: Responsive & Polish
-**Goal:** Flawless experience across all screen sizes with refined animations
-**Skills:** [@responsive, @frontend-master]
-**Tasks:**
-- Mobile layout audit and fixes (320px–480px)
-- Tablet layout adjustments (768px–1024px)
-- Desktop optimization (1280px+)
-- Touch targets ≥ 44px on mobile
-- Loading skeletons for all async content
-- Error boundaries with recovery UI
-- Page transitions and route animations
-- Micro-interactions on buttons, links, form elements
-- Dark mode (if in scope)
-
-**Success Criteria:**
-1. Usable on 320px width without horizontal scroll
-2. Touch targets ≥ 44px on all interactive elements
-3. No layout shifts on route navigation
-4. Loading states visible for all data-fetching operations
-
----
-
-### Phase 6: Deploy & Verify
-**Goal:** Production deployment with full verification suite passing
-**Skills:** [@deploy-verify]
-**Team:** ship-team
-**Tasks:**
-- Final `npx tsc --noEmit` check
-- Final `next lint` check
-- Production build (`next build`)
-- Deploy to Vercel (`vercel --prod`)
-- Configure custom domain (if applicable)
-- Run 6-check post-deploy verification
-- Supabase production config review (RLS, service key not exposed)
-
-**Success Criteria:**
-1. HTTP 200 on homepage
-2. Auth flow works in production
-3. No console errors on key pages
-4. API latency < 500ms
-5. SSL certificate valid
-6. No source maps exposed

package/framework/qualia-framework/templates/requirements.md

@@ -1,231 +0,0 @@
-# Requirements Template
-
-Template for `.planning/REQUIREMENTS.md` — checkable requirements that define "done."
-
-<template>
-
-```markdown
-# Requirements: [Project Name]
-
-**Defined:** [date]
-**Core Value:** [from PROJECT.md]
-
-## v1 Requirements
-
-Requirements for initial release. Each maps to roadmap phases.
-
-### Authentication
-
-- [ ] **AUTH-01**: User can sign up with email and password
-- [ ] **AUTH-02**: User receives email verification after signup
-- [ ] **AUTH-03**: User can reset password via email link
-- [ ] **AUTH-04**: User session persists across browser refresh
-
-### [Category 2]
-
-- [ ] **[CAT]-01**: [Requirement description]
-- [ ] **[CAT]-02**: [Requirement description]
-- [ ] **[CAT]-03**: [Requirement description]
-
-### [Category 3]
-
-- [ ] **[CAT]-01**: [Requirement description]
-- [ ] **[CAT]-02**: [Requirement description]
-
-## v2 Requirements
-
-Deferred to future release. Tracked but not in current roadmap.
-
-### [Category]
-
-- **[CAT]-01**: [Requirement description]
-- **[CAT]-02**: [Requirement description]
-
-## Out of Scope
-
-Explicitly excluded. Documented to prevent scope creep.
-
-| Feature | Reason |
-|---------|--------|
-| [Feature] | [Why excluded] |
-| [Feature] | [Why excluded] |
-
-## Traceability
-
-Which phases cover which requirements. Updated during roadmap creation.
-
-| Requirement | Phase | Status |
-|-------------|-------|--------|
-| AUTH-01 | Phase 1 | Pending |
-| AUTH-02 | Phase 1 | Pending |
-| AUTH-03 | Phase 1 | Pending |
-| AUTH-04 | Phase 1 | Pending |
-| [REQ-ID] | Phase [N] | Pending |
-
-**Coverage:**
-- v1 requirements: [X] total
-- Mapped to phases: [Y]
-- Unmapped: [Z] ⚠️
-
----
-*Requirements defined: [date]*
-*Last updated: [date] after [trigger]*
-```
-
-</template>
-
-<guidelines>
-
-**Requirement Format:**
-- ID: `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02, SOCIAL-03)
-- Description: User-centric, testable, atomic
-- Checkbox: Only for v1 requirements (v2 are not yet actionable)
-
-**Categories:**
-- Derive from research FEATURES.md categories
-- Keep consistent with domain conventions
-- Typical: Authentication, Content, Social, Notifications, Moderation, Payments, Admin
-
-**v1 vs v2:**
-- v1: Committed scope, will be in roadmap phases
-- v2: Acknowledged but deferred, not in current roadmap
-- Moving v2 → v1 requires roadmap update
-
-**Out of Scope:**
-- Explicit exclusions with reasoning
-- Prevents "why didn't you include X?" later
-- Anti-features from research belong here with warnings
-
-**Traceability:**
-- Empty initially, populated during roadmap creation
-- Each requirement maps to exactly one phase
-- Unmapped requirements = roadmap gap
-
-**Status Values:**
-- Pending: Not started
-- In Progress: Phase is active
-- Complete: Requirement verified
-- Blocked: Waiting on external factor
-
-</guidelines>
-
-<evolution>
-
-**After each phase completes:**
-1. Mark covered requirements as Complete
-2. Update traceability status
-3. Note any requirements that changed scope
-
-**After roadmap updates:**
-1. Verify all v1 requirements still mapped
-2. Add new requirements if scope expanded
-3. Move requirements to v2/out of scope if descoped
-
-**Requirement completion criteria:**
-- Requirement is "Complete" when:
-  - Feature is implemented
-  - Feature is verified (tests pass, manual check done)
-  - Feature is committed
-
-</evolution>
-
-<example>
-
-```markdown
-# Requirements: CommunityApp
-
-**Defined:** 2025-01-14
-**Core Value:** Users can share and discuss content with people who share their interests
-
-## v1 Requirements
-
-### Authentication
-
-- [ ] **AUTH-01**: User can sign up with email and password
-- [ ] **AUTH-02**: User receives email verification after signup
-- [ ] **AUTH-03**: User can reset password via email link
-- [ ] **AUTH-04**: User session persists across browser refresh
-
-### Profiles
-
-- [ ] **PROF-01**: User can create profile with display name
-- [ ] **PROF-02**: User can upload avatar image
-- [ ] **PROF-03**: User can write bio (max 500 chars)
-- [ ] **PROF-04**: User can view other users' profiles
-
-### Content
-
-- [ ] **CONT-01**: User can create text post
-- [ ] **CONT-02**: User can upload image with post
-- [ ] **CONT-03**: User can edit own posts
-- [ ] **CONT-04**: User can delete own posts
-- [ ] **CONT-05**: User can view feed of posts
-
-### Social
-
-- [ ] **SOCL-01**: User can follow other users
-- [ ] **SOCL-02**: User can unfollow users
-- [ ] **SOCL-03**: User can like posts
-- [ ] **SOCL-04**: User can comment on posts
-- [ ] **SOCL-05**: User can view activity feed (followed users' posts)
-
-## v2 Requirements
-
-### Notifications
-
-- **NOTF-01**: User receives in-app notifications
-- **NOTF-02**: User receives email for new followers
-- **NOTF-03**: User receives email for comments on own posts
-- **NOTF-04**: User can configure notification preferences
-
-### Moderation
-
-- **MODR-01**: User can report content
-- **MODR-02**: User can block other users
-- **MODR-03**: Admin can view reported content
-- **MODR-04**: Admin can remove content
-- **MODR-05**: Admin can ban users
-
-## Out of Scope
-
-| Feature | Reason |
-|---------|--------|
-| Real-time chat | High complexity, not core to community value |
-| Video posts | Storage/bandwidth costs, defer to v2+ |
-| OAuth login | Email/password sufficient for v1 |
-| Mobile app | Web-first, mobile later |
-
-## Traceability
-
-| Requirement | Phase | Status |
-|-------------|-------|--------|
-| AUTH-01 | Phase 1 | Pending |
-| AUTH-02 | Phase 1 | Pending |
-| AUTH-03 | Phase 1 | Pending |
-| AUTH-04 | Phase 1 | Pending |
-| PROF-01 | Phase 2 | Pending |
-| PROF-02 | Phase 2 | Pending |
-| PROF-03 | Phase 2 | Pending |
-| PROF-04 | Phase 2 | Pending |
-| CONT-01 | Phase 3 | Pending |
-| CONT-02 | Phase 3 | Pending |
-| CONT-03 | Phase 3 | Pending |
-| CONT-04 | Phase 3 | Pending |
-| CONT-05 | Phase 3 | Pending |
-| SOCL-01 | Phase 4 | Pending |
-| SOCL-02 | Phase 4 | Pending |
-| SOCL-03 | Phase 4 | Pending |
-| SOCL-04 | Phase 4 | Pending |
-| SOCL-05 | Phase 4 | Pending |
-
-**Coverage:**
-- v1 requirements: 18 total
-- Mapped to phases: 18
-- Unmapped: 0 ✓
-
----
-*Requirements defined: 2025-01-14*
-*Last updated: 2025-01-14 after initial definition*
-```
-
-</example>

package/framework/qualia-framework/templates/research-project/ARCHITECTURE.md

@@ -1,204 +0,0 @@
-# Architecture Research Template
-
-Template for `.planning/research/ARCHITECTURE.md` — system structure patterns for the project domain.
-
-<template>
-
-```markdown
-# Architecture Research
-
-**Domain:** [domain type]
-**Researched:** [date]
-**Confidence:** [HIGH/MEDIUM/LOW]
-
-## Standard Architecture
-
-### System Overview
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        [Layer Name]                          │
-├─────────────────────────────────────────────────────────────┤
-│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
-│  │ [Comp]  │  │ [Comp]  │  │ [Comp]  │  │ [Comp]  │        │
-│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘        │
-│       │            │            │            │              │
-├───────┴────────────┴────────────┴────────────┴──────────────┤
-│                        [Layer Name]                          │
-├─────────────────────────────────────────────────────────────┤
-│  ┌─────────────────────────────────────────────────────┐    │
-│  │                    [Component]                       │    │
-│  └─────────────────────────────────────────────────────┘    │
-├─────────────────────────────────────────────────────────────┤
-│                        [Layer Name]                          │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐                   │
-│  │ [Store]  │  │ [Store]  │  │ [Store]  │                   │
-│  └──────────┘  └──────────┘  └──────────┘                   │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Component Responsibilities
-
-| Component | Responsibility | Typical Implementation |
-|-----------|----------------|------------------------|
-| [name] | [what it owns] | [how it's usually built] |
-| [name] | [what it owns] | [how it's usually built] |
-| [name] | [what it owns] | [how it's usually built] |
-
-## Recommended Project Structure
-
-```
-src/
-├── [folder]/           # [purpose]
-│   ├── [subfolder]/    # [purpose]
-│   └── [file].ts       # [purpose]
-├── [folder]/           # [purpose]
-│   ├── [subfolder]/    # [purpose]
-│   └── [file].ts       # [purpose]
-├── [folder]/           # [purpose]
-└── [folder]/           # [purpose]
-```
-
-### Structure Rationale
-
-- **[folder]/:** [why organized this way]
-- **[folder]/:** [why organized this way]
-
-## Architectural Patterns
-
-### Pattern 1: [Pattern Name]
-
-**What:** [description]
-**When to use:** [conditions]
-**Trade-offs:** [pros and cons]
-
-**Example:**
-```typescript
-// [Brief code example showing the pattern]
-```
-
-### Pattern 2: [Pattern Name]
-
-**What:** [description]
-**When to use:** [conditions]
-**Trade-offs:** [pros and cons]
-
-**Example:**
-```typescript
-// [Brief code example showing the pattern]
-```
-
-### Pattern 3: [Pattern Name]
-
-**What:** [description]
-**When to use:** [conditions]
-**Trade-offs:** [pros and cons]
-
-## Data Flow
-
-### Request Flow
-
-```
-[User Action]
-    ↓
-[Component] → [Handler] → [Service] → [Data Store]
-    ↓              ↓           ↓            ↓
-[Response] ← [Transform] ← [Query] ← [Database]
-```
-
-### State Management
-
-```
-[State Store]
-    ↓ (subscribe)
-[Components] ←→ [Actions] → [Reducers/Mutations] → [State Store]
-```
-
-### Key Data Flows
-
-1. **[Flow name]:** [description of how data moves]
-2. **[Flow name]:** [description of how data moves]
-
-## Scaling Considerations
-
-| Scale | Architecture Adjustments |
-|-------|--------------------------|
-| 0-1k users | [approach — usually monolith is fine] |
-| 1k-100k users | [approach — what to optimize first] |
-| 100k+ users | [approach — when to consider splitting] |
-
-### Scaling Priorities
-
-1. **First bottleneck:** [what breaks first, how to fix]
-2. **Second bottleneck:** [what breaks next, how to fix]
-
-## Anti-Patterns
-
-### Anti-Pattern 1: [Name]
-
-**What people do:** [the mistake]
-**Why it's wrong:** [the problem it causes]
-**Do this instead:** [the correct approach]
-
-### Anti-Pattern 2: [Name]
-
-**What people do:** [the mistake]
-**Why it's wrong:** [the problem it causes]
-**Do this instead:** [the correct approach]
-
-## Integration Points
-
-### External Services
-
-| Service | Integration Pattern | Notes |
-|---------|---------------------|-------|
-| [service] | [how to connect] | [gotchas] |
-| [service] | [how to connect] | [gotchas] |
-
-### Internal Boundaries
-
-| Boundary | Communication | Notes |
-|----------|---------------|-------|
-| [module A ↔ module B] | [API/events/direct] | [considerations] |
-
-## Sources
-
-- [Architecture references]
-- [Official documentation]
-- [Case studies]
-
----
-*Architecture research for: [domain]*
-*Researched: [date]*
-```
-
-</template>
-
-<guidelines>
-
-**System Overview:**
-- Use ASCII box-drawing diagrams for clarity (├── └── │ ─ for structure visualization only)
-- Show major components and their relationships
-- Don't over-detail — this is conceptual, not implementation
-
-**Project Structure:**
-- Be specific about folder organization
-- Explain the rationale for grouping
-- Match conventions of the chosen stack
-
-**Patterns:**
-- Include code examples where helpful
-- Explain trade-offs honestly
-- Note when patterns are overkill for small projects
-
-**Scaling Considerations:**
-- Be realistic — most projects don't need to scale to millions
-- Focus on "what breaks first" not theoretical limits
-- Avoid premature optimization recommendations
-
-**Anti-Patterns:**
-- Specific to this domain
-- Include what to do instead
-- Helps prevent common mistakes during implementation
-
-</guidelines>