qualia-framework 2.1.0

package/framework/qualia-engine/templates/projects/voice-agent.md

@@ -0,0 +1,134 @@
+# Project Template: Voice Agent
+
+> Voice AI agent with Supabase Edge Functions, VAPI/Retell AI, and ElevenLabs.
+
+**Stack:** Supabase Edge Functions (Deno), VAPI / Retell AI, ElevenLabs, TypeScript
+**Phases:** 6
+**Type:** voice-agent
+
+## Phases
+
+### Phase 1: Foundation
+**Goal:** Supabase project with schema, edge function boilerplate, and voice provider connection
+**Skills:** [@supabase, @voice-agent]
+**Tasks:**
+- Design Supabase schema: calls, call_events, contacts, tools, system_config
+- Create edge function scaffold (Deno, cors headers, error handling)
+- Configure voice provider (VAPI or Retell AI): API keys, assistant creation
+- Environment variables in Supabase (voice provider keys, webhook secret)
+- Basic webhook endpoint that receives and logs call events
+- RLS policies on all tables
+
+**Success Criteria:**
+1. Edge function deployed and responding to health check
+2. Voice provider can reach webhook endpoint
+3. Schema deployed with RLS enabled
+4. Call events logging to database
+
+---
+
+### Phase 2: Voice Flow Design
+**Goal:** Complete conversation state machine with branching paths and slot filling
+**Skills:** [@voice-agent]
+**Tasks:**
+- Design conversation flow (state machine: greeting → discovery → action → closing)
+- Create VAPI/Retell assistant configuration (system prompt, voice, language)
+- Define conversation states and transitions
+- Slot filling logic (extract key info from conversation)
+- Multi-language support (if applicable — e.g., Greek/English/Russian)
+- Interruption handling (user interrupts mid-sentence)
+- Silence detection and re-engagement prompts
+- Transfer-to-human escalation path
+
+**Success Criteria:**
+1. Assistant follows designed flow in test calls
+2. Slot filling correctly extracts required information
+3. Language switching works naturally (if multi-language)
+4. Escalation to human triggers correctly
+
+---
+
+### Phase 3: Webhook Handlers
+**Goal:** Robust webhook processing for all voice provider events
+**Skills:** [@supabase, @voice-agent]
+**Tasks:**
+- Webhook signature verification (prevent spoofing)
+- Call start handler: create call record, load contact context
+- Call end handler: save transcript, update call status, trigger follow-ups
+- Function call handler: route tool calls to appropriate handlers
+- Status update handler: track call progress in real-time
+- Error handler: graceful failure with logging
+- Idempotency: handle duplicate webhook deliveries
+
+**Success Criteria:**
+1. All webhook events processed and logged
+2. Signature verification blocks invalid requests
+3. Duplicate deliveries don't create duplicate records
+4. Failed handlers don't crash the entire endpoint
+
+---
+
+### Phase 4: Tool Functions
+**Goal:** Business logic tools the voice agent can call during conversations
+**Skills:** [@supabase]
+**Tasks:**
+- Tool definition schema (name, description, parameters)
+- Tool router: dispatch function calls to handlers
+- Business-specific tools (varies per project):
+  - Database lookups (order status, product search, appointment check)
+  - External API calls (CRM, inventory, booking system)
+  - Data mutations (create appointment, update record, send notification)
+- Tool response formatting (structured → natural language for voice)
+- Tool error handling (timeout, API failure → graceful voice response)
+- Tool call logging (for analytics and debugging)
+
+**Success Criteria:**
+1. Voice agent can call tools mid-conversation and use results
+2. Tool failures produce graceful voice responses (not errors)
+3. All tool calls logged with input/output
+4. Tool response latency < 2s (voice conversations are latency-sensitive)
+
+---
+
+### Phase 5: Testing & Tuning
+**Goal:** Reliable voice agent with optimized latency and conversation quality
+**Skills:** [@voice-agent]
+**Tasks:**
+- Test call suite: happy path, edge cases, error scenarios
+- Latency profiling: identify slow tool calls, optimize
+- Voice quality tuning: adjust voice provider settings (speed, pitch, stability)
+- Prompt engineering: refine system prompt based on test call results
+- Edge case handling: unknown inputs, off-topic queries, hostile callers
+- Load testing: concurrent calls (if applicable)
+- Transcript review: analyze test transcripts for quality issues
+- Cost analysis: per-call cost breakdown (voice + AI + telephony)
+
+**Success Criteria:**
+1. Happy path call completes successfully in < 3 minutes
+2. All tool calls respond within 2s
+3. Voice sounds natural (no robotic artifacts or awkward pauses)
+4. Edge cases handled gracefully (no hangups or infinite loops)
+
+---
+
+### Phase 6: Deploy & Verify
+**Goal:** Production edge functions deployed with voice provider configured
+**Skills:** [@deploy-verify, @voice-agent]
+**Team:** ship-team
+**Tasks:**
+- Final type check on edge functions
+- Deploy edge functions to Supabase production
+- Configure voice provider webhooks to production URLs
+- Verify webhook signature validation in production
+- Test call in production environment
+- Monitor first 10 production calls for issues
+- Set up alerting for webhook failures
+- Document: phone number, webhook URLs, provider dashboard links
+
+**Success Criteria:**
+1. Edge function responds 200 to health check
+2. Voice provider webhook configured and verified
+3. Test call completes full flow in production
+4. Tool calls work with production data
+5. No secrets exposed in edge function logs
+6. Webhook failures trigger alerts

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

@@ -0,0 +1,137 @@
+# 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-engine/templates/requirements.md

@@ -0,0 +1,231 @@
+# 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-engine/templates/research-project/ARCHITECTURE.md

@@ -0,0 +1,204 @@
+# 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>