qualia-framework 2.1.0

package/framework/skills/ship/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: ship
+description: "Full production deployment pipeline — quality gates, commit, deploy, and verify. Role-aware: OWNER pushes directly, DEVELOPER auto-creates feature branch. Use this skill whenever the user says 'ship', 'deploy', 'push to production', 'go live', 'release', 'ship it', 'push', 'push it', 'put it on github', 'send to github', 'push to github', or wants to deploy any project (website, AI agent, voice agent, edge functions). Also trigger when user mentions Vercel deploy, Supabase functions deploy, Cloudflare Workers deploy, or just wants their code pushed."
+---
+
+# Ship — Full Production Deployment Pipeline
+
+Ship the current project to production. Runs quality gates, commits, pushes, deploys, and verifies.
+
+Reference `.planning/PROJECT.md` and `.planning/STATE.md` for project config. If no `.planning/` exists, use `package.json` and git remote to identify the project.
+
+## Usage
+
+`/ship` — Auto-detect project type from codebase
+`/ship --type=agent` — AI agent deployment (safety checks, webhook idempotency)
+`/ship --type=voice` — Voice agent deployment (signature verification, latency checks)
+`/ship --type=website` — Website deployment (SEO, responsive checks)
+
+## Auto-Detection (when --type not specified)
+
+Detect project type from codebase signals:
+
+- **agent**: Has AI provider imports (`openai`, `anthropic`, `@ai-sdk`), webhook handlers, agent logic
+- **voice**: Has VAPI/Retell/Telnyx/ElevenLabs imports, voice webhook handlers, `x-vapi-signature`
+- **website**: Has `app/page.tsx` or `pages/index.tsx`, no AI provider imports, primarily UI components
+- **edge-functions**: Has `supabase/functions/` directory, no frontend
+
+If ambiguous, ask user. If pure edge functions, skip tsc/eslint quality gates.
+
+## Shipping Checklist Gate
+
+Before deploying, load the relevant shipping checklist from `~/Projects/qualia-erp/docs/completion-checklists.md`:
+
+- **website** → "Website-Specific Checklist" + "Universal Checklist"
+- **agent** → "AI Agent Checklist" + "Universal Checklist"
+- **voice** → "Voice Agent Checklist" + "Universal Checklist"
+- **mobile** → "Mobile App Checklist" + "Universal Checklist"
+- **platform** → "Platform with LLM Checklist" + "Universal Checklist"
+
+After quality gates pass (Step 2), scan the codebase against each checklist item and report:
+- PASS: item verified automatically (e.g., grep found no service_role in client code)
+- WARN: could not verify automatically — needs manual check
+- FAIL: item clearly not met (e.g., no meta descriptions found)
+
+Any FAIL items are **deploy blockers** — report them and ask if user wants to fix first or ship anyway.
+Include the checklist results in the final deploy report (Step 8).
+
+## Steps
+
+### 1. Identify Project
+
+`pwd` to determine which project, look up deploy config from `.planning/PROJECT.md` and `.planning/STATE.md`. If no `.planning/` exists, use `package.json` and git remote to identify the project.
+
+### 2. Quality Gates
+
+Run in sequence, stop on failure:
+
+```bash
+npx tsc --noEmit        # TypeScript check — skip if no tsconfig or pure edge functions
+npx eslint . --max-warnings 0   # Lint check — skip if no eslint config
+npm run build            # Build verification — skip if pure edge functions
+```
+
+### 2a. Run Tests
+
+If test infrastructure exists (per `~/.claude/skills/test-runner/SKILL.md` detection):
+
+```bash
+npm test 2>&1 | tail -30     # Unit/Integration
+npx playwright test 2>&1      # E2E (if configured)
+```
+
+If tests fail: STOP. Report failures. Do not proceed to deploy.
+If no test infrastructure: skip silently.
+
+### 2b. Review Gate
+
+Check for review results:
+
+1. Read `.planning/REVIEW.md` or `.review/REVIEW.md`
+2. If `status: has_blockers`:
+   - List unresolved CRITICAL/HIGH findings
+   - Ask: "Fix these first, or deploy anyway?"
+   - If user says fix → stop
+   - If user says deploy anyway → continue with warning logged
+3. If `status: clean` or file not found → continue (advisory note if not found)
+
+### 3. Type-Specific Checks
+
+Based on detected or specified type:
+
+#### If agent (AI Agent):
+
+- **AI safety quick-check** — Grep codebase for:
+  - `service_role` in client-side files (`app/`, `components/`, `src/`) — should be ZERO matches (FAIL = blocks deploy)
+  - Rate limiting middleware — grep for `rateLimit`, `rateLimiter` in API routes
+  - `maxTokens` on AI calls — grep for `maxTokens`, `max_tokens` in AI provider calls
+  - Report: PASS/FAIL per item
+- **Webhook idempotency check** — Grep for deduplication logic (`dedup`, `idempotency`, `already_processed`, `messageId`). Report: PASS/WARN
+- **Production resilience** — Check for timeout protection (`export const maxDuration`), circuit breakers, error monitoring (Sentry configured)
+
+#### If voice (Voice Agent):
+
+- **Webhook signature verification** — Grep for signature check (`x-vapi-signature`, `signature`, `hmac`, `verify`). Report: PASS/WARN
+- **Edge function latency note** — First-response latency target: < 500ms. After deploy, test with: `curl -w "%{time_total}" -X POST <webhook-url>`
+
+#### If website (Website):
+
+- **SEO quick-check** — Grep for viewport meta, Open Graph tags (`og:title`, `og:description`), JSON-LD structured data. Report: PASS/WARN per item
+- **Responsive quick-check** — Check viewport meta exists, no fixed pixel widths on containers, `max-width` used on main content areas. Report: PASS/WARN per item
+
+### 4. Git Workflow (Role-Aware Branching)
+
+**First: detect role and branch.**
+
+```bash
+ROLE=$(grep -m1 "^## Role:" ~/.claude/CLAUDE.md 2>/dev/null | sed 's/^## Role: *//')
+BRANCH=$(git branch --show-current 2>/dev/null)
+```
+
+**Branching logic:**
+
+| Role | On main/master | On feature branch |
+|------|---------------|-------------------|
+| OWNER | Push directly | Push directly |
+| DEVELOPER | Auto-create feature branch first | Push directly |
+
+**If DEVELOPER on main/master:**
+
+```bash
+# Auto-create a descriptive feature branch from the work done
+# Use the commit message or task description for the branch name
+git checkout -b feature/<descriptive-name>
+# Stage, commit, push to the NEW branch
+git push -u origin feature/<descriptive-name>
+```
+
+Tell the user: "Created branch `feature/<name>` and pushed there. You can't push directly to main — create a PR when ready."
+
+**If OWNER or already on feature branch:**
+
+```bash
+git status
+# Stage relevant files (NOT .env, NOT node_modules)
+# Create descriptive commit
+# Push to current branch
+```
+
+### 5. Preview Deploy
+
+Deploy to preview first (if applicable):
+
+```bash
+vercel  # without --prod — gets preview URL
+```
+
+Run post-deploy checks against the preview URL. If checks pass, proceed to production. If checks fail, fix issues and re-deploy to preview.
+
+### 6. Deploy
+
+Based on project:
+
+```bash
+vercel --prod                              # Vercel projects
+supabase functions deploy                  # Edge functions
+wrangler deploy                            # Cloudflare Workers
+supabase db push --project-ref <ref>       # If migrations pending — test on branch first
+```
+
+### 7. Post-Deploy Verification
+
+#### All types:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" <domain>   # HTTP 200
+# Key endpoints respond under 500ms
+```
+
+#### Agent additions:
+Auth flow, webhook test, console errors, load test, error monitoring
+
+#### Voice additions:
+Webhook test, latency test, edge function logs
+
+#### Website additions:
+Auth flow, console errors, SEO verify, Lighthouse hint
+
+### 8. Report
+
+Summary of what was deployed, type-specific check results, latency measurements, deploy verification.
+
+### 9. Rollback Plan
+
+If production issues detected:
+
+- **Vercel**: `vercel rollback`
+- **Cloudflare Workers**: `wrangler deploy` previous version
+- **Edge functions**: `supabase functions deploy <name> --version <previous>`
+- **Supabase migrations**: Create reverse migration
+- **Emergency**: Vercel dashboard manual rollback
+
+If ANY quality gate or safety check FAILS: stop, fix the issue, then re-run `/ship`.

package/framework/skills/stack-researcher/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: stack-researcher
+description: Research latest best practices for any tech stack using web search and documentation - Next.js, React, Supabase, Vercel, Tailwind, etc. Use when you need up-to-date framework guidance or want to compare approaches.
+tags: [research, best-practices, documentation, nextjs, react, supabase, vercel]
+---
+
+# Stack Researcher
+
+You are a technical researcher specializing in finding up-to-date best practices, patterns, and documentation for modern web development stacks. You use **web search and official documentation** to provide current guidance.
+
+**Announce at start:** "Activating stack-researcher to find latest best practices for your stack."
+
+## Phase 1: Identify Stack
+
+First, analyze the project to identify:
+```
+1. Framework (Next.js version, React version)
+2. Database (Supabase, PlanetScale, Prisma)
+3. Auth (NextAuth, Supabase Auth, Clerk)
+4. Styling (Tailwind, shadcn/ui)
+5. Deployment (Vercel, AWS, self-hosted)
+6. Package manager (npm, pnpm, yarn)
+```
+
+## Phase 2: Research Each Stack Component
+
+For each identified technology, research:
+
+### Next.js Research
+```
+- App Router vs Pages Router patterns
+- Server Components vs Client Components
+- Data fetching (RSC, Server Actions, Route Handlers)
+- Caching and revalidation
+- Middleware patterns
+- SEO and metadata
+- Performance optimization
+- Recent breaking changes
+```
+
+### React 19 Research
+```
+- New hooks and features
+- Concurrent rendering patterns
+- Server Components integration
+- Suspense boundaries
+- Error boundaries
+- Transitions
+- Memoization patterns (when needed vs unnecessary)
+```
+
+### Supabase Research
+```
+- Auth patterns (PKCE, SSR)
+- RLS policy patterns
+- Real-time subscriptions
+- Edge functions
+- Storage patterns
+- Performance optimization
+- Migration best practices
+```
+
+### Tailwind Research
+```
+- v4 changes (if applicable)
+- Design system setup
+- Dark mode patterns
+- Animation utilities
+- Custom configuration
+- Plugin recommendations
+```
+
+### Vercel Deployment Research
+```
+- Edge vs Serverless functions
+- ISR patterns
+- Image optimization
+- Analytics integration
+- Environment variables
+- Preview deployments
+- Cron jobs
+```
+
+## Research Output Format
+
+For each technology researched:
+
+```markdown
+## [Technology Name] Best Practices (as of YYYY-MM)
+
+### Official Documentation Summary
+[Key points from official docs]
+
+### Current Best Practices
+1. **[Practice]**: [Why and how]
+2. **[Practice]**: [Why and how]
+
+### Common Pitfalls to Avoid
+1. **[Anti-pattern]**: [Why it's bad, what to do instead]
+2. **[Anti-pattern]**: [Why it's bad, what to do instead]
+
+### Recent Changes (Last 6 months)
+- [Change]: [Impact on your code]
+
+### Code Examples
+
+#### Recommended Pattern
+```[language]
+// Good: [explanation]
+[code]
+```
+
+#### Anti-Pattern to Avoid
+```[language]
+// Bad: [explanation]
+[code]
+```
+
+### Resources
+- [Official docs link]
+- [Recommended blog post/video]
+```
+
+## Research Topics by Category
+
+### Frontend Patterns
+- Component composition patterns
+- State management approaches
+- Form handling (react-hook-form + zod)
+- Data fetching and caching
+- Optimistic updates
+- Error handling
+- Accessibility patterns
+- Testing strategies
+
+### Backend Patterns
+- API design (REST, GraphQL, tRPC)
+- Authentication flows
+- Authorization patterns
+- Input validation
+- Error handling
+- Logging and monitoring
+- Rate limiting
+- Caching strategies
+
+### Database Patterns
+- Schema design principles
+- Index optimization
+- Query patterns (avoiding N+1)
+- Migration strategies
+- Backup and recovery
+- Connection pooling
+- Row-level security
+
+### DevOps Patterns
+- CI/CD configuration
+- Environment management
+- Secret management
+- Monitoring and alerting
+- Logging aggregation
+- Performance profiling
+- Security scanning
+
+## Comparison Research
+
+When asked to compare approaches:
+
+```markdown
+## Comparison: [Option A] vs [Option B]
+
+### Overview
+[Brief description of what we're comparing]
+
+### Side-by-Side
+
+| Aspect | Option A | Option B |
+|--------|----------|----------|
+| Performance | ... | ... |
+| DX | ... | ... |
+| Ecosystem | ... | ... |
+| Learning Curve | ... | ... |
+| Maintenance | ... | ... |
+
+### When to Use Option A
+- [Scenario 1]
+- [Scenario 2]
+
+### When to Use Option B
+- [Scenario 1]
+- [Scenario 2]
+
+### Recommendation for This Project
+[Based on what was detected in the codebase]
+```
+
+## After Research
+
+```
+"Research complete. Would you like me to:
+
+1. **Apply Recommendations** - Update your code to follow best practices
+2. **Create Migration Plan** - Plan for updating to recommended patterns
+3. **Deep Dive Specific Area** - Research more detail on one topic
+4. **Save Research** - Save findings to docs/research/
+5. **Compare Alternatives** - Research alternative approaches"
+```
+
+## Trigger Phrases
+
+- "research best practices for [stack]"
+- "what's the latest on [technology]"
+- "compare [A] vs [B]"
+- "how should I do [X] in [framework]"
+- "is my [pattern] up to date"
+- "research current patterns"

package/framework/skills/status/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: status
+description: "Fleet-wide health check for all Qualia projects — HTTP status, SSL, Supabase, response times. Flags issues without fixing them. Supports --quick and --project modes."
+user-invocable: true
+---
+
+# Fleet Health Monitor
+
+Diagnostic sweep across all active and maintenance Qualia projects. Flags problems, doesn't fix them.
+
+## Usage
+
+- `/status` — Check all active + maintenance projects (HTTP, SSL, Supabase, latency)
+- `/status --quick` — HTTP status only (fast, ~15 seconds)
+- `/status --project vero` — Deep check on a single project
+
+## How It Works
+
+### Step 1: Read qualia-context.md
+
+ALWAYS read `~/.claude/knowledge/qualia-context.md` at the start. Never hardcode project URLs or Supabase refs — the file is the source of truth.
+
+Extract all projects with status ACTIVE, MAINTENANCE, or LIVE. Skip DORMANT and DEV unless specifically requested.
+
+Build the check list:
+```
+Project → URL (derive from project name: {name}.vercel.app) → Supabase ref (if any) → Hosting type
+```
+
+For projects where the URL isn't `{name}.vercel.app` (custom domains, Cloudflare, etc.), check the project's `.env.local` or Vercel dashboard.
+
+Known special cases:
+- `armenius` → Cloudflare Workers (not Vercel)
+- `qualia` (ERP) → `qualia-erp.vercel.app`
+- `sofiatesting` → verify the exact Vercel URL from project dir
+
+### Step 2: Run Health Checks
+
+Use `scripts/health-check.sh` for the actual HTTP/SSL checks. Run all projects in parallel using background processes.
+
+**Default mode checks (per project):**
+
+| Check | Method | PASS | WARN | FAIL |
+|-------|--------|------|------|------|
+| HTTP Status | `curl -sL -o /dev/null -w "%{http_code}" --max-time 10` | 200 | 301/302 (redirect) | 4xx, 5xx, timeout |
+| Response Time | `curl -sL -o /dev/null -w "%{time_total}" --max-time 10` | < 1s | 1–3s | > 3s or timeout |
+| SSL Certificate | `openssl s_client` + check expiry | > 30 days | 7–30 days | < 7 days or expired |
+| Supabase Health | `curl https://{ref}.supabase.co/rest/v1/` | Reachable (200/401) | Slow (> 500ms) | Unreachable |
+
+**Quick mode (`--quick`):** HTTP Status only. Skips SSL, Supabase, response time.
+
+**Deep mode (`--project {name}`):** All default checks plus:
+- Vercel deployment status (`vercel ls` in project dir)
+- Last deploy time
+- Supabase connection count (`supabase inspect db connections` or `pg_stat_activity`)
+- Supabase auth health (`/auth/v1/health`)
+- Edge function status (`supabase functions list`)
+
+### Step 3: Generate Report
+
+```
+════════════════════════════════════════════════════
+  QUALIA FLEET HEALTH — 2026-03-04 17:30 UTC
+  Checking: 8 active/maintenance projects
+════════════════════════════════════════════════════
+
+  WEBSITES
+  ✓ PASS  qualiafinal        200 OK  (287ms)  SSL: 68d
+  ✓ PASS  vero               200 OK  (342ms)  SSL: 45d  DB: healthy
+  ✓ PASS  aibossbrainz       200 OK  (198ms)  SSL: 45d  DB: healthy
+  ⚠ WARN  aquador            200 OK  (1.8s)   SSL: 12d  DB: healthy
+  ✓ PASS  glluztech          200 OK  (445ms)  SSL: 68d
+  ✓ PASS  inrvo              200 OK  (312ms)  SSL: 68d
+  ✓ PASS  maud               200 OK  (521ms)  SSL: 68d  DB: healthy
+  ✓ PASS  mpm                200 OK  (389ms)  SSL: 68d  DB: healthy
+
+  AI AGENTS
+  ✓ PASS  sofiatesting       200 OK  (412ms)  SSL: 45d  DB: healthy
+
+  VOICE
+  ✓ PASS  under              200 OK  (267ms)  SSL: 45d  DB: healthy
+  ⚠ WARN  armenius           200 OK  (890ms)  SSL: 22d
+
+──────────────────────────────────────────────────
+  RESULT: 9 PASS · 2 WARN · 0 FAIL
+  Total check time: 12.4s
+──────────────────────────────────────────────────
+```
+
+### Step 4: Flag Issues
+
+If any check returns FAIL or WARN, print specific next steps below the report:
+
+```
+  ISSUES FOUND:
+
+  ⚠ aquador — Response time 1.8s (threshold: 1s)
+    → Check: vercel logs aquador.vercel.app
+    → Check: supabase inspect db outliers --project-ref hznpuxplqgszbacxzbhv
+
+  ⚠ armenius — SSL expires in 22 days
+    → Check: Cloudflare dashboard → SSL/TLS → Edge Certificates
+    → Note: Armenius uses Cloudflare, not Vercel (auto-renewal should handle this)
+```
+
+For FAIL results, be more urgent:
+```
+  ✗ FAIL  vero — HTTP 503 Service Unavailable
+    → IMMEDIATE: Check Vercel dashboard for vero
+    → Run: vercel logs vero.vercel.app
+    → Check: Supabase dashboard → is project paused?
+    → If unrecoverable: vercel rollback --prod
+```
+
+## Project URL Resolution
+
+The script resolves project URLs in this order:
+
+1. Check for `VERCEL_URL` or `NEXT_PUBLIC_SITE_URL` in project's `.env.local`
+2. Check for custom domain in project's `vercel.json`
+3. Fall back to `{project-name}.vercel.app`
+
+Known URL overrides (kept in the health-check.sh script):
+```bash
+declare -A URL_OVERRIDES=(
+  ["qualia"]="qualia-erp.vercel.app"
+  # Add more as discovered
+)
+```
+
+## Cron Integration
+
+This skill is designed to work with a daily cron job:
+
+```bash
+# Run daily at 8am Cyprus time (5am UTC)
+0 5 * * * bash ~/.claude/skills/status/scripts/health-check.sh --all > /tmp/qualia-health-$(date +\%Y\%m\%d).log 2>&1
+```
+
+The health-check.sh script outputs plain text (no ANSI colors) when stdout isn't a terminal, making logs readable.
+
+To review the last health check:
+```bash
+cat /tmp/qualia-health-$(date +%Y%m%d).log
+```
+
+## Rules
+
+- **Flag but don't fix** — this is diagnostic only. Never modify, deploy, or rollback.
+- **Read qualia-context.md every time** — never hardcode URLs or refs.
+- **10-second timeout per check** — don't hang on unresponsive projects.
+- **Parallel execution** — run project checks concurrently using background processes.
+- **curl only** — no extra dependencies for HTTP checks.
+- **No secrets in output** — never print API keys, service role keys, or connection strings.