qualia-framework 2.1.0

package/framework/qualia-engine/templates/planner-subagent-prompt.md

@@ -0,0 +1,117 @@
+# Planner Subagent Prompt Template
+
+Template for spawning qualia-planner agent. The agent contains all planning expertise - this template provides planning context only.
+
+---
+
+## Template
+
+```markdown
+<planning_context>
+
+**Phase:** {phase_number}
+**Mode:** {standard | gap_closure}
+
+**Project State:**
+@.planning/STATE.md
+
+**Roadmap:**
+@.planning/ROADMAP.md
+
+**Requirements (if exists):**
+@.planning/REQUIREMENTS.md
+
+**Phase Context (if exists):**
+@.planning/phases/{phase_dir}/{phase}-CONTEXT.md
+
+**Research (if exists):**
+@.planning/phases/{phase_dir}/{phase}-RESEARCH.md
+
+**Gap Closure (if --gaps mode):**
+@.planning/phases/{phase_dir}/{phase}-VERIFICATION.md
+@.planning/phases/{phase_dir}/{phase}-UAT.md
+
+</planning_context>
+
+<downstream_consumer>
+Output consumed by /qualia:execute-phase
+Plans must be executable prompts with:
+- Frontmatter (wave, depends_on, files_modified, autonomous)
+- Tasks in XML format
+- Verification criteria
+- must_haves for goal-backward verification
+</downstream_consumer>
+
+<quality_gate>
+Before returning PLANNING COMPLETE:
+- [ ] PLAN.md files created in phase directory
+- [ ] Each plan has valid frontmatter
+- [ ] Tasks are specific and actionable
+- [ ] Dependencies correctly identified
+- [ ] Waves assigned for parallel execution
+- [ ] must_haves derived from phase goal
+</quality_gate>
+```
+
+---
+
+## Placeholders
+
+| Placeholder | Source | Example |
+|-------------|--------|---------|
+| `{phase_number}` | From roadmap/arguments | `5` or `2.1` |
+| `{phase_dir}` | Phase directory name | `05-user-profiles` |
+| `{phase}` | Phase prefix | `05` |
+| `{standard \| gap_closure}` | Mode flag | `standard` |
+
+---
+
+## Usage
+
+**From /qualia:plan-phase (standard mode):**
+```python
+Task(
+  prompt=filled_template,
+  subagent_type="qualia-planner",
+  description="Plan Phase {phase}"
+)
+```
+
+**From /qualia:plan-phase --gaps (gap closure mode):**
+```python
+Task(
+  prompt=filled_template,  # with mode: gap_closure
+  subagent_type="qualia-planner",
+  description="Plan gaps for Phase {phase}"
+)
+```
+
+---
+
+## Continuation
+
+For checkpoints, spawn fresh agent with:
+
+```markdown
+<objective>
+Continue planning for Phase {phase_number}: {phase_name}
+</objective>
+
+<prior_state>
+Phase directory: @.planning/phases/{phase_dir}/
+Existing plans: @.planning/phases/{phase_dir}/*-PLAN.md
+</prior_state>
+
+<checkpoint_response>
+**Type:** {checkpoint_type}
+**Response:** {user_response}
+</checkpoint_response>
+
+<mode>
+Continue: {standard | gap_closure}
+</mode>
+```
+
+---
+
+**Note:** Planning methodology, task breakdown, dependency analysis, wave assignment, TDD detection, and goal-backward derivation are baked into the qualia-planner agent. This template only passes context.

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

@@ -0,0 +1,184 @@
+# 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-engine/templates/projects/ai-agent.md

@@ -0,0 +1,156 @@
+# 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:** [@admin-panel, @supabase]
+**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-engine/templates/projects/mobile-app.md

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