qualia-framework 2.6.0 → 3.2.0

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

@@ -1,184 +0,0 @@
-# PROJECT.md Template
-
-Template for `.planning/PROJECT.md` — the living project context document.
-
-<template>
-
-```markdown
-# [Project Name]
-
-## What This Is
-
-[Current accurate description — 2-3 sentences. What does this product do and who is it for?
-Use the user's language and framing. Update whenever reality drifts from this description.]
-
-## Core Value
-
-[The ONE thing that matters most. If everything else fails, this must work.
-One sentence that drives prioritization when tradeoffs arise.]
-
-## Requirements
-
-### Validated
-
-<!-- Shipped and confirmed valuable. -->
-
-(None yet — ship to validate)
-
-### Active
-
-<!-- Current scope. Building toward these. -->
-
-- [ ] [Requirement 1]
-- [ ] [Requirement 2]
-- [ ] [Requirement 3]
-
-### Out of Scope
-
-<!-- Explicit boundaries. Includes reasoning to prevent re-adding. -->
-
-- [Exclusion 1] — [why]
-- [Exclusion 2] — [why]
-
-## Context
-
-[Background information that informs implementation:
-- Technical environment or ecosystem
-- Relevant prior work or experience
-- User research or feedback themes
-- Known issues to address]
-
-## Constraints
-
-- **[Type]**: [What] — [Why]
-- **[Type]**: [What] — [Why]
-
-Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Performance, Security
-
-## Key Decisions
-
-<!-- Decisions that constrain future work. Add throughout project lifecycle. -->
-
-| Decision | Rationale | Outcome |
-|----------|-----------|---------|
-| [Choice] | [Why] | [✓ Good / ⚠️ Revisit / — Pending] |
-
----
-*Last updated: [date] after [trigger]*
-```
-
-</template>
-
-<guidelines>
-
-**What This Is:**
-- Current accurate description of the product
-- 2-3 sentences capturing what it does and who it's for
-- Use the user's words and framing
-- Update when the product evolves beyond this description
-
-**Core Value:**
-- The single most important thing
-- Everything else can fail; this cannot
-- Drives prioritization when tradeoffs arise
-- Rarely changes; if it does, it's a significant pivot
-
-**Requirements — Validated:**
-- Requirements that shipped and proved valuable
-- Format: `- ✓ [Requirement] — [version/phase]`
-- These are locked — changing them requires explicit discussion
-
-**Requirements — Active:**
-- Current scope being built toward
-- These are hypotheses until shipped and validated
-- Move to Validated when shipped, Out of Scope if invalidated
-
-**Requirements — Out of Scope:**
-- Explicit boundaries on what we're not building
-- Always include reasoning (prevents re-adding later)
-- Includes: considered and rejected, deferred to future, explicitly excluded
-
-**Context:**
-- Background that informs implementation decisions
-- Technical environment, prior work, user feedback
-- Known issues or technical debt to address
-- Update as new context emerges
-
-**Constraints:**
-- Hard limits on implementation choices
-- Tech stack, timeline, budget, compatibility, dependencies
-- Include the "why" — constraints without rationale get questioned
-
-**Key Decisions:**
-- Significant choices that affect future work
-- Add decisions as they're made throughout the project
-- Track outcome when known:
-  - ✓ Good — decision proved correct
-  - ⚠️ Revisit — decision may need reconsideration
-  - — Pending — too early to evaluate
-
-**Last Updated:**
-- Always note when and why the document was updated
-- Format: `after Phase 2` or `after v1.0 milestone`
-- Triggers review of whether content is still accurate
-
-</guidelines>
-
-<evolution>
-
-PROJECT.md evolves throughout the project lifecycle.
-
-**After each phase transition:**
-1. Requirements invalidated? → Move to Out of Scope with reason
-2. Requirements validated? → Move to Validated with phase reference
-3. New requirements emerged? → Add to Active
-4. Decisions to log? → Add to Key Decisions
-5. "What This Is" still accurate? → Update if drifted
-
-**After each milestone:**
-1. Full review of all sections
-2. Core Value check — still the right priority?
-3. Audit Out of Scope — reasons still valid?
-4. Update Context with current state (users, feedback, metrics)
-
-</evolution>
-
-<brownfield>
-
-For existing codebases:
-
-1. **Map codebase first** via `/qualia:map-codebase`
-
-2. **Infer Validated requirements** from existing code:
-   - What does the codebase actually do?
-   - What patterns are established?
-   - What's clearly working and relied upon?
-
-3. **Gather Active requirements** from user:
-   - Present inferred current state
-   - Ask what they want to build next
-
-4. **Initialize:**
-   - Validated = inferred from existing code
-   - Active = user's goals for this work
-   - Out of Scope = boundaries user specifies
-   - Context = includes current codebase state
-
-</brownfield>
-
-<state_reference>
-
-STATE.md references PROJECT.md:
-
-```markdown
-## Project Reference
-
-See: .planning/PROJECT.md (updated [date])
-
-**Core value:** [One-liner from Core Value section]
-**Current focus:** [Current phase name]
-```
-
-This ensures Claude reads current PROJECT.md context.
-
-</state_reference>

package/framework/qualia-framework/templates/projects/ai-agent.md

@@ -1,156 +0,0 @@
-# Project Template: AI Agent
-
-> AI chat agent with Next.js frontend, Supabase backend, and AI provider integration.
-
-**Stack:** Next.js 16+, React 19, TypeScript, Supabase, AI SDK / OpenRouter / Gemini, Vercel
-**Phases:** 7
-**Type:** ai-agent
-
-## Phases
-
-### Phase 1: Foundation
-**Goal:** Working Next.js app with Supabase schema, auth, and base project structure
-**Skills:** [@supabase]
-**Tasks:**
-- Initialize Next.js 16+ with App Router, TypeScript strict, Tailwind v4
-- Design Supabase schema: users, conversations, messages, system_prompts
-- Configure Supabase client (server.ts + client.ts pattern)
-- Implement auth: login, signup (Supabase Auth)
-- RLS policies on all tables (user can only access own conversations)
-- Environment variables for AI provider keys
-- Base layout with navigation shell
-
-**Success Criteria:**
-1. User can create account and log in
-2. Database schema deployed with RLS enabled
-3. Server-side auth working
-4. `npx tsc --noEmit` passes
-
----
-
-### Phase 2: AI Core
-**Goal:** Working AI conversation engine with streaming responses and conversation persistence
-**Skills:** [@supabase]
-**Tasks:**
-- AI provider integration (OpenRouter / Gemini / OpenAI — based on project needs)
-- System prompt management (stored in Supabase, editable)
-- Streaming response handler (SSE or WebSocket)
-- Conversation management: create, continue, branch
-- Message persistence: save user messages and AI responses
-- Context window management (truncation strategy for long conversations)
-- Token usage tracking per conversation
-- Error handling: rate limits, provider failures, timeout recovery
-
-**Success Criteria:**
-1. User can send message and receive streaming AI response
-2. Conversations persist across page reloads
-3. System prompt shapes AI behavior correctly
-4. Graceful handling of API errors (no crash, clear user message)
-
----
-
-### Phase 3: Chat UI
-**Goal:** Polished chat interface with real-time feel and markdown support
-**Skills:** [@frontend-master]
-**Tasks:**
-- Message bubbles with user/AI distinction
-- Streaming text animation (typewriter effect)
-- Markdown rendering in AI responses (code blocks, lists, links)
-- Typing indicator while AI generates
-- Conversation list sidebar with search
-- New conversation button
-- Auto-scroll to latest message
-- Message input with multiline support and send on Enter
-- Copy message button
-- Responsive layout (sidebar collapses on mobile)
-
-**Success Criteria:**
-1. Messages render with clear user/AI visual distinction
-2. Streaming responses appear character-by-character
-3. Code blocks syntax-highlighted and copyable
-4. UI works on mobile (sidebar toggles, input accessible)
-
----
-
-### Phase 4: Admin Panel
-**Goal:** Admin interface for managing the AI agent: prompts, users, analytics
-**Skills:** [@supabase, @frontend-master]
-**Tasks:**
-- Admin auth (role-based, separate from user auth)
-- System prompt editor (CRUD, version history)
-- User management: list, view conversations, ban/unban
-- Conversation analytics: message counts, popular topics, response times
-- Token usage dashboard per user and total
-- AI model configuration (switch providers, adjust temperature)
-- Export conversations (CSV/JSON)
-
-**Success Criteria:**
-1. Admin can edit system prompt and see changes reflected in new conversations
-2. Admin can view user conversations and usage stats
-3. Analytics dashboard shows meaningful metrics
-4. Non-admins cannot access admin routes
-
----
-
-### Phase 5: Channel Integration
-**Goal:** AI agent accessible via WhatsApp, Telegram, or web widget (based on project needs)
-**Skills:** [@supabase]
-**Tasks:**
-- Webhook endpoint for channel provider
-- Message format translation (channel format ↔ internal format)
-- User identity mapping (channel user → Supabase user)
-- Media handling (images, voice messages if applicable)
-- Rate limiting per channel user
-- Channel-specific formatting (WhatsApp markdown vs web markdown)
-- Health check endpoint for webhook verification
-
-**Success Criteria:**
-1. Messages from channel reach AI and response returns to channel
-2. Conversation history shared across channels for same user
-3. Rate limiting prevents abuse
-4. Webhook responds within provider timeout limits
-
----
-
-### Phase 6: Safety & Resilience
-**Goal:** Production-grade safety: prompt injection defense, rate limiting, failover
-**Skills:** []
-**Tasks:**
-- Prompt injection detection (input sanitization, pattern matching)
-- Output filtering (PII detection, harmful content blocking)
-- Rate limiting: per-user, per-IP, global
-- AI provider failover (primary → secondary provider)
-- Conversation length limits with graceful handling
-- Input validation (max length, content type)
-- Logging: all AI interactions logged for audit
-- Error recovery: conversation state preserved on failures
-
-**Success Criteria:**
-1. Known prompt injection patterns blocked
-2. Rate limits enforced and clear feedback to user
-3. Provider failover works (disable primary, secondary picks up)
-4. No PII leaked in AI responses (if configured)
-
----
-
-### Phase 7: Deploy & Verify
-**Goal:** Production deployment with AI-specific verification
-**Skills:** [@deploy-verify]
-**Team:** ship-team
-**Tasks:**
-- Final type check and lint
-- Production build
-- Deploy to Vercel
-- Verify AI provider keys work in production
-- Test full conversation flow in production
-- Load test: concurrent conversations (if applicable)
-- Run 6-check post-deploy verification
-- Supabase production review (RLS, no service key exposed)
-
-**Success Criteria:**
-1. HTTP 200, auth flow works, no console errors
-2. AI responds correctly in production
-3. Conversations persist across sessions
-4. API latency < 500ms for non-AI endpoints
-5. AI response time < 5s for first token
-6. No source maps or service keys exposed

package/framework/qualia-framework/templates/projects/mobile-app.md

@@ -1,181 +0,0 @@
-# Project Template: Mobile App
-
-> React Native + Expo managed workflow + Supabase. Full pipeline from dev to App Store.
-
-**Stack:** React Native, Expo (managed workflow), TypeScript, expo-router, Supabase, EAS Build/Submit
-**Phases:** 8
-**Type:** mobile-app
-
-## Phases
-
-### Phase 1: Foundation
-**Goal:** Working Expo app with TypeScript, navigation, and Supabase connected
-**Skills:** [@supabase]
-**Tasks:**
-- Initialize Expo project with managed workflow and TypeScript strict
-- Configure expo-router (file-based routing)
-- Set up Supabase client (with @react-native-async-storage for token persistence)
-- Configure environment variables (expo-constants, app.config.ts)
-- Create tab navigation shell (bottom tabs)
-- Set up development build configuration
-- Configure ESLint + Prettier for React Native
-
-**Success Criteria:**
-1. App runs on iOS simulator and Android emulator
-2. Tab navigation works between screens
-3. Supabase client connects (test query succeeds)
-4. TypeScript strict mode passes
-
----
-
-### Phase 2: Auth
-**Goal:** Complete auth flow with secure token storage and deep linking
-**Skills:** [@supabase]
-**Tasks:**
-- Login screen (email/password)
-- Signup screen with email verification
-- Password reset flow
-- Auth state persistence (AsyncStorage + Supabase session)
-- Protected route wrapper (redirect unauthenticated to login)
-- Deep linking for email verification and password reset
-- Biometric authentication unlock (optional, Face ID / fingerprint)
-- Auth loading state (splash → check session → route)
-
-**Success Criteria:**
-1. User can sign up, verify email, and log in
-2. Session persists across app restarts
-3. Deep links from email open correct screen
-4. Unauthenticated users always see login screen
-
----
-
-### Phase 3: Core Screens
-**Goal:** Main app screens with data fetching, pull-to-refresh, and CRUD
-**Skills:** [@supabase]
-**Tasks:**
-- Home / dashboard screen with key data
-- List screen with FlatList (pagination, pull-to-refresh)
-- Detail screen with full resource view
-- Create form with validation
-- Edit form (pre-populated)
-- Delete with confirmation
-- Search / filter functionality
-- Empty states and error states for all screens
-- Loading skeletons
-
-**Success Criteria:**
-1. User can perform full CRUD on core resources
-2. Lists paginate correctly and pull-to-refresh works
-3. Forms validate input and show clear errors
-4. Empty states and loading states visible
-5. Back navigation works correctly on all flows
-
----
-
-### Phase 4: Native Features
-**Goal:** Platform-specific features: camera, push notifications, location, biometrics
-**Skills:** []
-**Tasks:**
-- Push notifications (expo-notifications + Supabase Edge Function for sending)
-- Camera integration (expo-camera or expo-image-picker)
-- Location services (expo-location — if applicable)
-- Biometric unlock (expo-local-authentication)
-- Share functionality (expo-sharing)
-- Haptic feedback on key interactions
-- Platform-specific UI adjustments (iOS vs Android)
-- Permission request flows with clear explanations
-
-**Success Criteria:**
-1. Push notifications deliver on both platforms
-2. Camera/image picker works and uploads to Supabase Storage
-3. Permission requests explain why access is needed
-4. Haptic feedback on primary actions
-
----
-
-### Phase 5: Offline & Performance
-**Goal:** Offline-first data with background sync and smooth 60fps UI
-**Skills:** []
-**Tasks:**
-- Local SQLite database (expo-sqlite) for offline cache
-- Sync engine: local changes → Supabase when online
-- Conflict resolution strategy (last-write-wins or merge)
-- Network status detection (NetInfo)
-- Optimistic updates (UI updates immediately, sync in background)
-- Image caching (expo-image)
-- List rendering optimization (FlashList or FlatList tuning)
-- Memory profiling and leak detection
-- Startup time optimization (reduce bundle, lazy imports)
-
-**Success Criteria:**
-1. App works offline for core read/write operations
-2. Data syncs when connectivity restored
-3. No dropped frames on list scrolling (60fps)
-4. App cold start < 2s
-5. Memory usage stable over extended use
-
----
-
-### Phase 6: App Store Prep
-**Goal:** App store assets, configuration, and metadata ready for submission
-**Skills:** []
-**Tasks:**
-- App icon (all required sizes for iOS + Android)
-- Splash screen (animated or static)
-- App Store screenshots (6.7", 6.5", 5.5" for iOS; phone + tablet for Android)
-- App Store description, keywords, category
-- Privacy policy URL
-- app.json / app.config.ts: version, bundle ID, permissions justification
-- EAS Build configuration (eas.json: development, preview, production profiles)
-- Code signing: Apple Developer certificates, Google Play keystore
-
-**Success Criteria:**
-1. App icon renders correctly on both platforms
-2. Splash screen displays during load
-3. Screenshots capture key features
-4. EAS Build config has all 3 profiles
-5. Code signing configured for both platforms
-
----
-
-### Phase 7: Build & Submit
-**Goal:** Production builds submitted to App Store Connect and Google Play Console
-**Skills:** []
-**Tasks:**
-- EAS Build: production profile for iOS
-- EAS Build: production profile for Android
-- Test production builds on physical devices
-- EAS Submit to App Store Connect (TestFlight)
-- EAS Submit to Google Play Console (internal testing track)
-- Fix any submission rejection issues
-- TestFlight beta testing round
-- Google Play internal testing round
-
-**Success Criteria:**
-1. iOS build uploads to App Store Connect without errors
-2. Android build uploads to Google Play Console without errors
-3. TestFlight build installs and runs on test devices
-4. Google Play internal test installs and runs
-5. No crash reports from beta testing
-
----
-
-### Phase 8: Post-Launch
-**Goal:** Production monitoring, OTA updates, and crash reporting configured
-**Skills:** []
-**Tasks:**
-- OTA updates: configure expo-updates for instant patches
-- Crash reporting (Sentry or expo-updates error tracking)
-- Analytics: screen views, key actions, funnel tracking
-- App Store listing live: submit for review (iOS), promote to production (Android)
-- Monitor first 48h: crash rates, ANR rates, user feedback
-- Hotfix process: OTA for JS changes, new build for native changes
-- Version bump and changelog for next release
-
-**Success Criteria:**
-1. OTA updates deliver to users within minutes
-2. Crash reports appear in dashboard with stack traces
-3. Analytics tracking key user flows
-4. App live on both stores
-5. No critical crashes in first 48h
-6. Hotfix pipeline tested and documented

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

@@ -1,134 +0,0 @@
-# Project Template: Voice Agent
-
-> Voice AI agent with Supabase Edge Functions, Retell AI, and ElevenLabs.
-
-**Stack:** Supabase Edge Functions (Deno), 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 Retell AI: API keys, agent creation, ElevenLabs voice selection
-- 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 Retell AI agent 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