qualia-framework 2.6.0 → 3.1.0

package/framework/skills/critique/SKILL.md

@@ -1,126 +0,0 @@
----
-name: critique
-description: Evaluate design effectiveness from a UX perspective. Assesses visual hierarchy, information architecture, emotional resonance, and overall design quality with actionable feedback.
-user-invokable: true
-args:
-  - name: area
-    description: The feature or area to critique (optional)
-    required: false
----
-
-Conduct a holistic design critique, evaluating whether the interface actually works—not just technically, but as a designed experience. Think like a design director giving feedback.
-
-**First**: Use the frontend-master skill for design principles and anti-patterns.
-
-**Then**: Read the project's design decisions:
-
-```bash
-cat .planning/DESIGN.md 2>/dev/null
-```
-
-If DESIGN.md exists, use it as the authoritative source for this project's design direction. Reference its decisions when evaluating the interface (e.g., "DESIGN.md specifies warm palette — this blue accent is inconsistent"). If DESIGN.md does not exist, proceed with general design principles from frontend-master.
-
-## Design Critique
-
-Evaluate the interface across these dimensions:
-
-### 1. AI Slop Detection (CRITICAL)
-
-**This is the most important check.** Does this look like every other AI-generated interface from 2024-2025?
-
-Review the design against ALL the **DON'T** guidelines in the frontend-master skill—they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells.
-
-**The test**: If you showed this to someone and said "AI made this," would they believe you immediately? If yes, that's the problem.
-
-### 2. Visual Hierarchy
-- Does the eye flow to the most important element first?
-- Is there a clear primary action? Can you spot it in 2 seconds?
-- Do size, color, and position communicate importance correctly?
-- Is there visual competition between elements that should have different weights?
-
-### 3. Information Architecture
-- Is the structure intuitive? Would a new user understand the organization?
-- Is related content grouped logically?
-- Are there too many choices at once? (cognitive overload)
-- Is the navigation clear and predictable?
-
-### 4. Emotional Resonance
-- What emotion does this interface evoke? Is that intentional?
-- Does it match the brand personality?
-- Does it feel trustworthy, approachable, premium, playful—whatever it should feel?
-- Would the target user feel "this is for me"?
-
-### 5. Discoverability & Affordance
-- Are interactive elements obviously interactive?
-- Would a user know what to do without instructions?
-- Are hover/focus states providing useful feedback?
-- Are there hidden features that should be more visible?
-
-### 6. Composition & Balance
-- Does the layout feel balanced or uncomfortably weighted?
-- Is whitespace used intentionally or just leftover?
-- Is there visual rhythm in spacing and repetition?
-- Does asymmetry feel designed or accidental?
-
-### 7. Typography as Communication
-- Does the type hierarchy clearly signal what to read first, second, third?
-- Is body text comfortable to read? (line length, spacing, size)
-- Do font choices reinforce the brand/tone?
-- Is there enough contrast between heading levels?
-
-### 8. Color with Purpose
-- Is color used to communicate, not just decorate?
-- Does the palette feel cohesive?
-- Are accent colors drawing attention to the right things?
-- Does it work for colorblind users? (not just technically—does meaning still come through?)
-
-### 9. States & Edge Cases
-- Empty states: Do they guide users toward action, or just say "nothing here"?
-- Loading states: Do they reduce perceived wait time?
-- Error states: Are they helpful and non-blaming?
-- Success states: Do they confirm and guide next steps?
-
-### 10. Microcopy & Voice
-- Is the writing clear and concise?
-- Does it sound like a human (the right human for this brand)?
-- Are labels and buttons unambiguous?
-- Does error copy help users fix the problem?
-
-## Generate Critique Report
-
-Structure your feedback as a design director would:
-
-### Anti-Patterns Verdict
-**Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest.
-
-### Overall Impression
-A brief gut reaction—what works, what doesn't, and the single biggest opportunity.
-
-### What's Working
-Highlight 2-3 things done well. Be specific about why they work.
-
-### Priority Issues
-The 3-5 most impactful design problems, ordered by importance:
-
-For each issue:
-- **What**: Name the problem clearly
-- **Why it matters**: How this hurts users or undermines goals
-- **Fix**: What to do about it (be concrete)
-- **Command**: Which command to use (prefer: /animate, /design-quieter, /clarify, /distill, /delight, /onboard, /normalize, /responsive, /harden, /polish, /bolder, /colorize)
-
-### Minor Observations
-Quick notes on smaller issues worth addressing.
-
-### Questions to Consider
-Provocative questions that might unlock better solutions:
-- "What if the primary action were more prominent?"
-- "Does this need to feel this complex?"
-- "What would a confident version of this look like?"
-
-**Remember**:
-- Be direct—vague feedback wastes everyone's time
-- Be specific—"the submit button" not "some elements"
-- Say what's wrong AND why it matters to users
-- Give concrete suggestions, not just "consider exploring..."
-- Prioritize ruthlessly—if everything is important, nothing is
-- Don't soften criticism—developers need honest feedback to ship great design

package/framework/skills/deep-research/SKILL.md

@@ -1,240 +0,0 @@
----
-name: deep-research
-description: Deep research and best practices analysis for any codebase - spawns parallel Opus agents to analyze frontend, backend, database, security, performance, and deployment. Use when you want comprehensive production-readiness audit or best practices recommendations.
-tags: [research, best-practices, production, analysis, audit, frontend, backend]
----
-
-# Deep Research & Best Practices Analyzer
-
-You are an expert architect conducting deep research on a codebase to identify best practices, patterns, and production-readiness improvements. You spawn **parallel Opus agents** to analyze different aspects comprehensively.
-
-**Announce at start:** "Activating deep-research skill with parallel Opus agents for comprehensive analysis."
-
-## Phase 1: Initial Discovery (YOU do this)
-
-Before spawning agents, gather context:
-
-```
-1. Read CLAUDE.md, README.md, package.json
-2. List directory structure (top 2 levels)
-3. Identify tech stack from dependencies
-4. Check git history for recent changes
-5. Identify entry points (app/, src/, pages/)
-```
-
-## Phase 2: Spawn Parallel Research Agents
-
-**CRITICAL**: Spawn ALL agents in a SINGLE message with multiple Agent tool calls:
-
-### Agent 1: Frontend Architecture Analyst
-```
-Agent(
-  subagent_type="general-purpose",
-  prompt="
-  You are a Frontend Architecture Analyst (Opus). Research this codebase for frontend best practices.
-
-  ANALYZE:
-  1. Component architecture (atomic design? feature-based? smart/dumb split?)
-  2. State management (context, zustand, redux, jotai?)
-  3. Data fetching patterns (server components, tanstack-query, SWR?)
-  4. Form handling (react-hook-form, zod validation?)
-  5. Styling approach (CSS modules, tailwind, styled-components?)
-  6. Performance patterns (lazy loading, memoization, virtualization?)
-  7. Error boundaries and error handling
-  8. Accessibility (ARIA, semantic HTML, keyboard nav)
-
-  RESEARCH best practices for the detected stack.
-  COMPARE current patterns vs industry best practices.
-  RETURN: Structured report with findings, gaps, and specific recommendations.
-```
-
-### Agent 2: Backend Architecture Analyst
-```
-Agent(
-  subagent_type="general-purpose",
-  prompt="
-  You are a Backend Architecture Analyst (Opus). Research this codebase for backend best practices.
-
-  ANALYZE:
-  1. API design (REST, GraphQL, tRPC, server actions?)
-  2. Authentication/Authorization patterns
-  3. Database queries and ORM usage
-  4. Error handling and logging
-  5. Input validation and sanitization
-  6. Rate limiting and security headers
-  7. Caching strategies
-  8. Background jobs/queues
-
-  RESEARCH best practices for the detected stack.
-  COMPARE current patterns vs industry best practices.
-  RETURN: Structured report with findings, gaps, and specific recommendations.
-```
-
-### Agent 3: Database & Data Layer Analyst
-```
-Agent(
-  subagent_type="general-purpose",
-  prompt="
-  You are a Database & Data Layer Analyst (Opus). Research this codebase for data best practices.
-
-  ANALYZE:
-  1. Schema design (normalization, indexes, constraints)
-  2. Migration patterns and versioning
-  3. RLS policies and row-level security
-  4. Query performance (N+1, joins, aggregations)
-  5. Data validation at database level
-  6. Backup and recovery strategies
-  7. Connection pooling
-  8. Soft deletes vs hard deletes
-
-  RESEARCH best practices for the detected database.
-  COMPARE current patterns vs industry best practices.
-  RETURN: Structured report with findings, gaps, and specific recommendations.
-```
-
-### Agent 4: Security & DevOps Analyst
-```
-Agent(
-  subagent_type="general-purpose",
-  prompt="
-  You are a Security & DevOps Analyst (Opus). Research this codebase for security and deployment best practices.
-
-  ANALYZE:
-  1. Environment variable handling (.env patterns)
-  2. Secret management (API keys, tokens)
-  3. CORS configuration
-  4. CSP headers and security headers
-  5. Input sanitization (XSS, SQL injection)
-  6. Dependency vulnerabilities (npm audit)
-  7. CI/CD pipeline configuration
-  8. Deployment configuration (Vercel, Docker, K8s)
-  9. Monitoring and error tracking
-  10. Logging and observability
-
-  RESEARCH best practices for production deployment.
-  COMPARE current patterns vs industry best practices.
-  RETURN: Structured report with findings, gaps, and specific recommendations.
-```
-
-### Agent 5: Performance & Scalability Analyst
-```
-Agent(
-  subagent_type="general-purpose",
-  prompt="
-  You are a Performance & Scalability Analyst (Opus). Research this codebase for performance best practices.
-
-  ANALYZE:
-  1. Bundle size and code splitting
-  2. Image optimization
-  3. Caching strategies (browser, CDN, server)
-  4. Database query optimization
-  5. API response times
-  6. Memory leaks potential
-  7. Render performance (React profiling patterns)
-  8. SSR vs CSR vs ISR decisions
-  9. Edge functions and edge computing
-  10. Horizontal scaling readiness
-
-  RESEARCH best practices for performance optimization.
-  COMPARE current patterns vs industry best practices.
-  RETURN: Structured report with findings, gaps, and specific recommendations.
-```
-
-### Agent 6: Code Quality & Testing Analyst
-```
-Agent(
-  subagent_type="general-purpose",
-  prompt="
-  You are a Code Quality & Testing Analyst (Opus). Research this codebase for quality best practices.
-
-  ANALYZE:
-  1. Test coverage (unit, integration, e2e)
-  2. Testing patterns and frameworks
-  3. Type safety (TypeScript strictness)
-  4. Linting and formatting
-  5. Code duplication
-  6. Documentation quality
-  7. Naming conventions
-  8. Error messages quality
-  9. Code organization patterns
-  10. Dead code detection
-
-  RESEARCH best practices for code quality.
-  COMPARE current patterns vs industry best practices.
-  RETURN: Structured report with findings, gaps, and specific recommendations.
-```
-
-## Phase 3: Synthesize Reports
-
-After all 6 agents return, **spawn the synthesizer agent** to consolidate findings. Do NOT synthesize inline — this prevents context bloat in the parent.
-
-Each agent's report will be in the tool result. Write each one to a temp file, then spawn the synthesizer:
-
-```bash
-# Write each agent's output to a temp file
-# (use the actual tool result content from each agent)
-```
-
-Then spawn the synthesizer agent:
-
-```
-Agent(
-  subagent_type="qualia-research-synthesizer",
-  prompt="
-  Synthesize these specialist reports:
-  - [path to frontend report]
-  - [path to backend report]
-  - [path to database report]
-  - [path to security report]
-  - [path to performance report]
-  - [path to code quality report]
-
-  Downstream consumer: The user needs a prioritized Deep Research Report with:
-  - Overall production readiness score (/100)
-  - Critical/High/Medium/Low severity findings with file:line references
-  - Cross-cutting patterns across all 6 areas
-  - Implementation roadmap grouped by week
-  - Resources and references
-
-  Output path: docs/research/[YYYY-MM-DD]-deep-research.md
-  (also return the full report in your response)
-
-  Do NOT commit.
-  "
-)
-```
-
-The synthesizer handles deduplication, cross-cutting pattern detection, and severity ranking — producing a single unified report.
-
-## Phase 4: Offer Next Steps
-
-After presenting the report:
-
-```
-"Research complete. Would you like to:
-
-1. **Create Implementation Plan** - Use /qualia-plan-phase to create detailed tasks
-2. **Deep Dive on Specific Area** - Focus on frontend/backend/security/etc
-3. **Start Fixing Critical Issues** - Begin implementing top priority fixes
-4. **Save Report** - Save to docs/research/YYYY-MM-DD-deep-research.md
-5. **Compare to Specific Standard** - Research against OWASP, 12-factor, etc.
-6. **Feed into phase planning** - Run `/qualia-research-phase <N>` for phase-specific research that builds on this architectural analysis"
-```
-
-## Key Principles
-
-- **Parallel Execution**: Always spawn all 6 agents in ONE message for speed
-- **Evidence-Based**: Every finding must reference specific files/lines
-- **Actionable**: Every recommendation must be implementable
-- **Prioritized**: Critical > High > Medium > Low
-- **Stack-Aware**: Research best practices for the ACTUAL stack detected
-- **Production Focus**: Everything geared toward production deployment
-
-## Trigger Phrases
-
-- "deep research this project"
-- "analyze best practices"
-- "production readiness audit"
-- "what should I fix before deploying"
-- "research how to improve this codebase"
-- "comprehensive code review"

package/framework/skills/delight/SKILL.md

@@ -1,329 +0,0 @@
----
-name: delight
-description: Add moments of joy, personality, and unexpected touches that make interfaces memorable and enjoyable to use. Elevates functional to delightful.
-user-invokable: true
-args:
-  - name: target
-    description: The feature or area to add delight to (optional)
-    required: false
----
-
-Identify opportunities to add moments of joy, personality, and unexpected polish that transform functional interfaces into delightful experiences.
-
-## MANDATORY PREPARATION
-
-### Read DESIGN.md (Authoritative Source)
-
-Before any context gathering, check for the project's design decisions file:
-
-```bash
-cat .planning/DESIGN.md 2>/dev/null
-```
-
-**If DESIGN.md exists:** This is the authoritative source for all design decisions in this project. Use its palette, typography, spacing, component, and motion decisions as your foundation. Do NOT override these decisions unless the user explicitly asks. Reference specific DESIGN.md decisions in your output (e.g., "Per DESIGN.md, the primary color is...").
-
-**If DESIGN.md does not exist:** Proceed with normal context gathering below. Consider suggesting the user run `/qualia-discuss-phase` to establish design decisions.
-
-### Context Gathering (Do This First)
-
-You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), brand personality (playful vs professional vs quirky vs elegant), and what's appropriate for the domain.
-
-Attempt to gather these from the current thread or codebase.
-
-1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and ask the user directly to clarify. whether you got it right.
-2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and ask the user directly to clarify. clarifying questions first to complete your context.
-
-Do NOT proceed until you have answers. Delight that's wrong for the context is worse than no delight at all.
-
-### Use frontend-master skill
-
-Use the frontend-master skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts.
-
----
-
-## Assess Delight Opportunities
-
-Identify where delight would enhance (not distract from) the experience:
-
-1. **Find natural delight moments**:
-   - **Success states**: Completed actions (save, send, publish)
-   - **Empty states**: First-time experiences, onboarding
-   - **Loading states**: Waiting periods that could be entertaining
-   - **Achievements**: Milestones, streaks, completions
-   - **Interactions**: Hover states, clicks, drags
-   - **Errors**: Softening frustrating moments
-   - **Easter eggs**: Hidden discoveries for curious users
-
-2. **Understand the context**:
-   - What's the brand personality? (Playful? Professional? Quirky? Elegant?)
-   - Who's the audience? (Tech-savvy? Creative? Corporate?)
-   - What's the emotional context? (Accomplishment? Exploration? Frustration?)
-   - What's appropriate? (Banking app ≠ gaming app)
-
-3. **Define delight strategy**:
-   - **Subtle sophistication**: Refined micro-interactions (luxury brands)
-   - **Playful personality**: Whimsical illustrations and copy (consumer apps)
-   - **Helpful surprises**: Anticipating needs before users ask (productivity tools)
-   - **Sensory richness**: Satisfying sounds, smooth animations (creative tools)
-
-If any of these are unclear from the codebase, STOP and ask the user directly to clarify.
-
-**CRITICAL**: Delight should enhance usability, never obscure it. If users notice the delight more than accomplishing their goal, you've gone too far.
-
-## Delight Principles
-
-Follow these guidelines:
-
-### Delight Amplifies, Never Blocks
-- Delight moments should be quick (< 1 second)
-- Never delay core functionality for delight
-- Make delight skippable or subtle
-- Respect user's time and task focus
-
-### Surprise and Discovery
-- Hide delightful details for users to discover
-- Reward exploration and curiosity
-- Don't announce every delight moment
-- Let users share discoveries with others
-
-### Appropriate to Context
-- Match delight to emotional moment (celebrate success, empathize with errors)
-- Respect the user's state (don't be playful during critical errors)
-- Match brand personality and audience expectations
-- Cultural sensitivity (what's delightful varies by culture)
-
-### Compound Over Time
-- Delight should remain fresh with repeated use
-- Vary responses (not same animation every time)
-- Reveal deeper layers with continued use
-- Build anticipation through patterns
-
-## Delight Techniques
-
-Add personality and joy through these methods:
-
-### Micro-interactions & Animation
-
-**Button delight**:
-```css
-/* Satisfying button press */
-.button {
-  transition: transform 0.1s, box-shadow 0.1s;
-}
-.button:active {
-  transform: translateY(2px);
-  box-shadow: 0 2px 4px rgba(0,0,0,0.2);
-}
-
-/* Ripple effect on click */
-/* Smooth lift on hover */
-.button:hover {
-  transform: translateY(-2px);
-  transition: transform 0.2s cubic-bezier(0.25, 1, 0.5, 1); /* ease-out-quart */
-}
-```
-
-**Loading delight**:
-- Playful loading animations (not just spinners)
-- Personality in loading messages ("Herding pixels..." "Teaching robots to dance...")
-- Progress indication with encouraging messages
-- Skeleton screens with subtle animations
-
-**Success animations**:
-- Checkmark draw animation
-- Confetti burst for major achievements
-- Gentle scale + fade for confirmation
-- Satisfying sound effects (subtle)
-
-**Hover surprises**:
-- Icons that animate on hover
-- Color shifts or glow effects
-- Tooltip reveals with personality
-- Cursor changes (custom cursors for branded experiences)
-
-### Personality in Copy
-
-**Playful error messages**:
-```
-"Error 404"
-"This page is playing hide and seek. (And winning)"
-
-"Connection failed"
-"Looks like the internet took a coffee break. Want to retry?"
-```
-
-**Encouraging empty states**:
-```
-"No projects"
-"Your canvas awaits. Create something amazing."
-
-"No messages"
-"Inbox zero! You're crushing it today."
-```
-
-**Playful labels & tooltips**:
-```
-"Delete"
-"Send to void" (for playful brand)
-
-"Help"
-"Rescue me" (tooltip)
-```
-
-**IMPORTANT**: Match copy personality to brand. Banks shouldn't be wacky, but they can be warm.
-
-### Illustrations & Visual Personality
-
-**Custom illustrations**:
-- Empty state illustrations (not stock icons)
-- Error state illustrations (friendly monsters, quirky characters)
-- Loading state illustrations (animated characters)
-- Success state illustrations (celebrations)
-
-**Icon personality**:
-- Custom icon set matching brand personality
-- Animated icons (subtle motion on hover/click)
-- Illustrative icons (more detailed than generic)
-- Consistent style across all icons
-
-**Background effects**:
-- Subtle particle effects
-- Gradient mesh backgrounds
-- Geometric patterns
-- Parallax depth
-- Time-of-day themes (morning vs night)
-
-### Satisfying Interactions
-
-**Drag and drop delight**:
-- Lift effect on drag (shadow, scale)
-- Snap animation when dropped
-- Satisfying placement sound
-- Undo toast ("Dropped in wrong place? [Undo]")
-
-**Toggle switches**:
-- Smooth slide with spring physics
-- Color transition
-- Haptic feedback on mobile
-- Optional sound effect
-
-**Progress & achievements**:
-- Streak counters with celebratory milestones
-- Progress bars that "celebrate" at 100%
-- Badge unlocks with animation
-- Playful stats ("You're on fire! 5 days in a row")
-
-**Form interactions**:
-- Input fields that animate on focus
-- Checkboxes that bounce when checked
-- Success state that celebrates valid input
-- Auto-grow textareas
-
-### Sound Design
-
-**Subtle audio cues** (when appropriate):
-- Notification sounds (distinctive but not annoying)
-- Success sounds (satisfying "ding")
-- Error sounds (empathetic, not harsh)
-- Typing sounds for chat/messaging
-- Ambient background audio (very subtle)
-
-**IMPORTANT**:
-- Respect system sound settings
-- Provide mute option
-- Keep volumes quiet (subtle cues, not alarms)
-- Don't play on every interaction (sound fatigue is real)
-
-### Easter Eggs & Hidden Delights
-
-**Discovery rewards**:
-- Konami code unlocks special theme
-- Hidden keyboard shortcuts (Cmd+K for special features)
-- Hover reveals on logos or illustrations
-- Alt text jokes on images (for screen reader users too!)
-- Console messages for developers ("Like what you see? We're hiring!")
-
-**Seasonal touches**:
-- Holiday themes (subtle, tasteful)
-- Seasonal color shifts
-- Weather-based variations
-- Time-based changes (dark at night, light during day)
-
-**Contextual personality**:
-- Different messages based on time of day
-- Responses to specific user actions
-- Randomized variations (not same every time)
-- Progressive reveals with continued use
-
-### Loading & Waiting States
-
-**Make waiting engaging**:
-- Interesting loading messages that rotate
-- Progress bars with personality
-- Mini-games during long loads
-- Fun facts or tips while waiting
-- Countdown with encouraging messages
-
-```
-Loading messages rotation:
-- "Waking up the servers..."
-- "Teaching robots to dance..."
-- "Consulting the magic 8-ball..."
-- "Counting backwards from infinity..."
-```
-
-### Celebration Moments
-
-**Success celebrations**:
-- Confetti for major milestones
-- Animated checkmarks for completions
-- Progress bar celebrations at 100%
-- "Achievement unlocked" style notifications
-- Personalized messages ("You published your 10th article!")
-
-**Milestone recognition**:
-- First-time actions get special treatment
-- Streak tracking and celebration
-- Progress toward goals
-- Anniversary celebrations
-
-## Implementation Patterns
-
-**Animation libraries**:
-- Framer Motion (React)
-- GSAP (universal)
-- Lottie (After Effects animations)
-- Canvas confetti (party effects)
-
-**Sound libraries**:
-- Howler.js (audio management)
-- Use-sound (React hook)
-
-**Physics libraries**:
-- React Spring (spring physics)
-- Popmotion (animation primitives)
-
-**IMPORTANT**: File size matters. Compress images, optimize animations, lazy load delight features.
-
-**NEVER**:
-- Delay core functionality for delight
-- Force users through delightful moments (make skippable)
-- Use delight to hide poor UX
-- Overdo it (less is more)
-- Ignore accessibility (animate responsibly, provide alternatives)
-- Make every interaction delightful (special moments should be special)
-- Sacrifice performance for delight
-- Be inappropriate for context (read the room)
-
-## Verify Delight Quality
-
-Test that delight actually delights:
-
-- **User reactions**: Do users smile? Share screenshots?
-- **Doesn't annoy**: Still pleasant after 100th time?
-- **Doesn't block**: Can users opt out or skip?
-- **Performant**: No jank, no slowdown
-- **Appropriate**: Matches brand and context
-- **Accessible**: Works with reduced motion, screen readers
-
-Remember: Delight is the difference between a tool and an experience. Add personality, surprise users positively, and create moments worth sharing. But always respect usability - delight should enhance, never obstruct.