qualia-framework 2.1.0

package/framework/skills/voice-agent/SKILL.md

@@ -0,0 +1,407 @@
+---
+name: voice-agent
+description: Build complete voice AI agents - design conversational flow, create VAPI assistant, integrate Supabase, deploy. Full voice agent development.
+tags: [voice, vapi, ai-agent, supabase, elevenlabs]
+---
+
+# Voice Agent Builder
+
+Build complete voice AI agents from design to deployment.
+
+## Pipeline
+
+```
+1. Design Conversation Flow
+       ↓
+2. Create VAPI Assistant
+       ↓
+3. Setup Supabase Backend
+       ↓
+4. Configure Webhooks
+       ↓
+5. Deploy & Test
+```
+
+## Quick Start
+
+Say: "build voice agent for [use case]"
+
+Example: "build voice agent for appointment scheduling"
+
+I will:
+1. Design the conversation flow
+2. Create VAPI assistant configuration
+3. Set up Supabase tables for state
+4. Configure webhooks
+5. Deploy and test
+
+## Stage 1: Design Conversation Flow
+
+### Flow Diagram
+```
+┌──────────────────┐
+│   Call Starts    │
+└────────┬─────────┘
+         ↓
+┌──────────────────┐
+│    Greeting      │
+│ "Hello, how can  │
+│  I help you?"    │
+└────────┬─────────┘
+         ↓
+┌──────────────────┐
+│  Intent Detection │
+│ - Book appointment│
+│ - Check status    │
+│ - Other inquiry   │
+└────────┬─────────┘
+         ↓
+   ┌─────┴─────┐
+   ↓           ↓
+┌──────┐   ┌──────┐
+│ Book │   │ Help │
+└──────┘   └──────┘
+```
+
+### State Machine
+```typescript
+const conversationStates = {
+  GREETING: {
+    next: ['INTENT_DETECTION'],
+    actions: ['playGreeting']
+  },
+  INTENT_DETECTION: {
+    next: ['BOOKING', 'STATUS_CHECK', 'TRANSFER'],
+    actions: ['detectIntent']
+  },
+  BOOKING: {
+    next: ['COLLECT_DATE', 'COLLECT_TIME', 'CONFIRM'],
+    actions: ['startBooking']
+  },
+  // ...
+};
+```
+
+## Stage 2: Create VAPI Assistant
+
+### Assistant Configuration
+```typescript
+const assistant = {
+  name: "Appointment Scheduler",
+  model: {
+    provider: "anthropic",
+    model: "claude-3-5-sonnet-20241022",
+    temperature: 0.7,
+    systemPrompt: `You are a friendly appointment scheduling assistant.
+Your job is to help callers book appointments.
+
+## Capabilities
+- Book new appointments
+- Check existing appointments
+- Reschedule appointments
+- Answer questions about services
+
+## Conversation Flow
+1. Greet the caller warmly
+2. Ask how you can help
+3. Collect necessary information
+4. Confirm the action
+5. End the call politely
+
+## Important Rules
+- Always confirm before booking
+- Validate dates and times
+- Collect caller's phone for confirmation
+- Be concise but friendly`
+  },
+  voice: {
+    provider: "11labs",
+    voiceId: "21m00Tcm4TlvDq8ikWAM", // Rachel
+    stability: 0.5,
+    similarityBoost: 0.75
+  },
+  firstMessage: "Hello! Thanks for calling. How can I help you today?",
+  endCallMessage: "Thank you for calling. Have a great day!",
+  transcriber: {
+    provider: "deepgram",
+    model: "nova-2",
+    language: "en"
+  },
+  serverUrl: "https://your-app.com/api/vapi-webhook"
+};
+```
+
+### Create via VAPI
+> Use VAPI MCP tools (available via settings.json) or direct VAPI API via curl/WebFetch.
+> Example: `curl -X POST https://api.vapi.ai/assistant -H "Authorization: Bearer $VAPI_API_KEY" -d '<config>'`
+
+## Stage 3: Setup Supabase Backend
+
+### Database Schema
+```sql
+-- Appointments table
+CREATE TABLE appointments (
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  customer_phone TEXT NOT NULL,
+  customer_name TEXT,
+  service_type TEXT NOT NULL,
+  appointment_date DATE NOT NULL,
+  appointment_time TIME NOT NULL,
+  status TEXT DEFAULT 'scheduled' CHECK (status IN ('scheduled', 'confirmed', 'cancelled', 'completed')),
+  notes TEXT,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Call logs
+CREATE TABLE call_logs (
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  call_id TEXT UNIQUE NOT NULL,
+  phone_number TEXT NOT NULL,
+  duration_seconds INTEGER,
+  transcript TEXT,
+  outcome TEXT,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Agent state (for context between calls)
+CREATE TABLE agent_state (
+  phone_number TEXT PRIMARY KEY,
+  last_call_id TEXT,
+  context JSONB DEFAULT '{}',
+  updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Enable RLS
+ALTER TABLE appointments ENABLE ROW LEVEL SECURITY;
+ALTER TABLE call_logs ENABLE ROW LEVEL SECURITY;
+ALTER TABLE agent_state ENABLE ROW LEVEL SECURITY;
+
+-- RLS Policies: service role only (called from edge functions)
+CREATE POLICY "Service role full access" ON appointments
+  FOR ALL USING (auth.role() = 'service_role');
+
+CREATE POLICY "Service role full access" ON call_logs
+  FOR ALL USING (auth.role() = 'service_role');
+
+CREATE POLICY "Service role full access" ON agent_state
+  FOR ALL USING (auth.role() = 'service_role');
+```
+
+### API Functions
+```typescript
+// supabase/functions/book-appointment/index.ts
+import { z } from "https://deno.land/x/zod/mod.ts"
+
+const BookingSchema = z.object({
+  phone: z.string().min(10),
+  date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+  time: z.string().regex(/^\d{2}:\d{2}$/),
+  service: z.string().min(1),
+})
+
+serve(async (req) => {
+  try {
+  const raw = await req.json();
+  const { phone, date, time, service } = BookingSchema.parse(raw);
+
+  const supabase = createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
+  );
+
+  // Check availability
+  const { data: existing } = await supabase
+    .from('appointments')
+    .select('id')
+    .eq('appointment_date', date)
+    .eq('appointment_time', time)
+    .single();
+
+  if (existing) {
+    return new Response(JSON.stringify({
+      success: false,
+      message: "That time slot is already booked."
+    }));
+  }
+
+  // Book appointment
+  const { data, error } = await supabase
+    .from('appointments')
+    .insert({
+      customer_phone: phone,
+      appointment_date: date,
+      appointment_time: time,
+      service_type: service
+    })
+    .select()
+    .single();
+
+  return new Response(JSON.stringify({
+    success: true,
+    appointment: data,
+    message: `Appointment booked for ${date} at ${time}`
+  }));
+  } catch (error) {
+    console.error("Booking error:", error);
+    return new Response(JSON.stringify({
+      success: false,
+      message: "Failed to process booking request"
+    }), { status: 500 });
+  }
+});
+```
+
+## Stage 4: Configure Webhooks
+
+### VAPI Webhook Handler
+```typescript
+// supabase/functions/vapi-webhook/index.ts
+serve(async (req) => {
+  try {
+  // Verify VAPI webhook signature
+  const signature = req.headers.get('x-vapi-signature');
+  const body = await req.text();
+
+  if (!verifyVapiSignature(body, signature, Deno.env.get('VAPI_WEBHOOK_SECRET')!)) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+
+  const event = JSON.parse(body);
+  const supabase = createClient(/* ... */);
+
+  switch (event.message.type) {
+    case 'function-call':
+      // Handle tool calls
+      const { name, parameters } = event.message.functionCall;
+
+      switch (name) {
+        case 'book_appointment':
+          const result = await bookAppointment(parameters);
+          return new Response(JSON.stringify({ result }));
+
+        case 'check_availability':
+          const slots = await checkAvailability(parameters);
+          return new Response(JSON.stringify({ result: slots }));
+
+        case 'get_customer_appointments':
+          const appointments = await getAppointments(parameters.phone);
+          return new Response(JSON.stringify({ result: appointments }));
+      }
+      break;
+
+    case 'end-of-call-report':
+      // Log call
+      await supabase.from('call_logs').insert({
+        call_id: event.call.id,
+        phone_number: event.call.customer.number,
+        duration_seconds: event.call.duration,
+        transcript: event.transcript,
+        outcome: event.call.endedReason
+      });
+      break;
+
+    case 'status-update':
+      console.log('Call status:', event.status);
+      break;
+  }
+
+  return new Response('OK');
+  } catch (error) {
+    console.error("Webhook error:", error);
+    return new Response(JSON.stringify({ error: "Internal server error" }), {
+      status: 500,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+});
+```
+
+### Tool Definitions
+```typescript
+const tools = [
+  {
+    type: "function",
+    function: {
+      name: "book_appointment",
+      description: "Book a new appointment for the caller",
+      parameters: {
+        type: "object",
+        properties: {
+          date: { type: "string", description: "Date in YYYY-MM-DD format" },
+          time: { type: "string", description: "Time in HH:MM format" },
+          service: { type: "string", description: "Type of service" }
+        },
+        required: ["date", "time", "service"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "check_availability",
+      description: "Check available appointment slots",
+      parameters: {
+        type: "object",
+        properties: {
+          date: { type: "string", description: "Date to check" }
+        },
+        required: ["date"]
+      }
+    }
+  }
+];
+```
+
+## Stage 5: Deploy & Test
+
+### Deploy Steps
+```bash
+# Deploy Supabase functions
+supabase functions deploy book-appointment
+supabase functions deploy vapi-webhook
+
+# Update VAPI assistant with webhook URL
+# Use VAPI dashboard or API
+
+# Test with a call
+vapi call --assistant-id your-assistant-id --to +1234567890
+```
+
+### Test Scenarios
+1. **Happy path**: Book appointment successfully
+2. **Conflict**: Time slot unavailable
+3. **Edge case**: Invalid date format
+4. **Error handling**: Database connection fails
+5. **Context persistence**: Caller calls back
+
+## Voice Selection (ElevenLabs)
+
+| Use Case | Voice | Why |
+|----------|-------|-----|
+| Professional | Rachel | Calm, clear, authoritative |
+| Friendly | Bella | Warm, approachable |
+| Energetic | Elli | Upbeat, engaging |
+| Corporate | Adam | Professional male |
+
+## Best Practices
+
+1. **Keep responses short** - 1-2 sentences max
+2. **Confirm important info** - Repeat back dates/times
+3. **Handle interruptions** - Allow user to interrupt
+4. **Provide escape routes** - "Say 'operator' for help"
+5. **Log everything** - For debugging and improvement
+6. **Test extensively** - Real phone calls, various accents
+
+## Integration with Other Skills
+
+- **voice-agent** - This skill (VAPI patterns, conversation flow, webhooks)
+- **supabase** - For database operations
+- **docs-lookup** - For VAPI/ElevenLabs/Deepgram API docs
+
+## Trigger Phrases
+
+- "build voice agent"
+- "create voice assistant"
+- "voice AI for"
+- "phone bot for"

package/framework/skills/zoho-workflow/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: zoho-workflow
+description: Zoho Invoice and Mail operations - create invoices, send emails, manage contacts. Use when Fawzi mentions invoicing, email, or Zoho.
+tags: [zoho, invoice, email, billing, crm]
+---
+
+# Zoho Workflow
+
+
+## Zoho Invoice
+
+- Create, edit, send, and void invoices
+- List and search invoices by client, status, date
+- Manage items, taxes, contacts, and expenses
+- Mark invoices as sent/paid, send payment reminders
+- Generate invoice PDFs and email them to clients
+- Create recurring invoices and credit notes
+- When Fawzi says "invoice [client]" — create the full invoice, don't just explain how
+- Default sender org: Qualia Solutions
+
+## Zoho Mail
+
+- Read inbox, sent, drafts, and folder contents
+- Send emails and reply to threads
+- Move, label, and organize messages
+- Search emails by sender, subject, date
+- When Fawzi says "email [someone]" or "check inbox" — do it directly
+- Use Fawzi's primary Zoho Mail account
+
+## Email Formatting Rules (MANDATORY)
+
+- Always append Fawzi's signature at the bottom of every email
+- Read signature HTML from `~/.claude/knowledge/email-signature.html`
+- Never use dashes (---) or horizontal separators
+- Never use emojis
+- Professional, direct tone
+- Keep it concise and action-oriented
+
+## General Rules
+
+- Always act, don't just describe. Execute operations directly.
+- Fetch the organization ID first if needed (use the list/get org tools)
+- If a tool call fails, debug it — check params, retry with fixes
+
+## Trigger Phrases
+
+- "invoice [client]" → Create and send invoice
+- "email [someone]" → Compose and send email
+- "check inbox" → Read inbox
+- "send reminder" → Payment reminder
+- "create contact" → New Zoho contact

package/framework/statusline-command.sh

@@ -0,0 +1,117 @@
+#!/bin/bash
+# Qualia statusline — teal-branded, compact, informative
+# Layout: ◆ dir  branch [status] │ phase │ model ━━━━ 23%
+
+input=$(cat)
+
+USED_PCT=$(echo "$input" | jq -r '.context_window.used_percentage // empty')
+MODEL=$(echo "$input" | jq -r '.model.display_name')
+CWD=$(echo "$input" | jq -r '.workspace.current_dir')
+
+[ -z "$USED_PCT" ] && exit 0
+
+USED_INT=$(printf '%.0f' "$USED_PCT")
+
+# Directory shortening (last 2 segments max)
+DIR="$CWD"
+DIR="${DIR/#$HOME/\~}"
+DEPTH=$(echo "$DIR" | tr -cd '/' | wc -c)
+if [ "$DEPTH" -gt 2 ]; then
+  DIR=$(echo "$DIR" | rev | cut -d'/' -f1-2 | rev)
+  DIR="…/$DIR"
+fi
+
+# ── Colors ──
+T='\033[38;2;0;188;175m'         # teal
+TB='\033[38;2;45;226;210m'       # teal bright
+TD='\033[38;2;0;120;112m'        # teal dim
+W='\033[38;2;220;225;230m'       # white
+G='\033[38;2;70;78;88m'          # gray
+GR='\033[38;2;52;211;153m'       # green
+Y='\033[38;2;234;179;8m'         # yellow
+R='\033[38;2;239;68;68m'         # red
+P='\033[38;2;189;147;249m'       # purple
+X='\033[0m'                      # reset
+
+# Context bar color
+if [ "$USED_INT" -ge 70 ]; then CB="$R"
+elif [ "$USED_INT" -ge 50 ]; then CB="$Y"
+else CB="$T"; fi
+
+# ── Project + phase detection ──
+PROJECT=""
+PHASE=""
+
+if [ -f "$CWD/.planning/STATE.md" ]; then
+  PROJECT=$(grep -m1 "^Project:" "$CWD/.planning/STATE.md" 2>/dev/null | sed 's/^Project: *//')
+  # Get phase number only (e.g. "3 of 6") — not the full description
+  PHASE_RAW=$(grep -m1 "^Phase:" "$CWD/.planning/STATE.md" 2>/dev/null | sed 's/^Phase: *//')
+  if [ -n "$PHASE_RAW" ]; then
+    # Extract "N of M" pattern or just take first 12 chars
+    PHASE_SHORT=$(echo "$PHASE_RAW" | grep -oP '^\d+ of \d+' 2>/dev/null)
+    [ -z "$PHASE_SHORT" ] && PHASE_SHORT=$(echo "$PHASE_RAW" | head -c 12)
+    PHASE="$PHASE_SHORT"
+  fi
+fi
+
+[ -z "$PROJECT" ] && [ -f "$CWD/package.json" ] && PROJECT=$(node -e "try{console.log(require('$CWD/package.json').name||'')}catch(e){}" 2>/dev/null)
+
+# Git branch
+BRANCH=$(git -C "$CWD" --no-optional-locks branch --show-current 2>/dev/null)
+GIT_STATUS=""
+if [ -n "$BRANCH" ]; then
+  GIT_RAW=$(git -C "$CWD" --no-optional-locks status --porcelain 2>/dev/null | head -20)
+  if [ -n "$GIT_RAW" ]; then
+    M=$(echo "$GIT_RAW" | grep -c '^ M\|^MM\|^AM')
+    S=$(echo "$GIT_RAW" | grep -c '^[MARCD] ')
+    U=$(echo "$GIT_RAW" | grep -c '^??')
+    [ "$M" -gt 0 ] && GIT_STATUS+="!${M}"
+    [ "$S" -gt 0 ] && GIT_STATUS+="+${S}"
+    [ "$U" -gt 0 ] && GIT_STATUS+="?${U}"
+  fi
+fi
+
+# ── Context bar ──
+BAR_W=10
+FILLED=$(( USED_INT * BAR_W / 100 ))
+[ "$FILLED" -gt "$BAR_W" ] && FILLED=$BAR_W
+EMPTY=$(( BAR_W - FILLED ))
+BAR=""; for ((i=0; i<FILLED; i++)); do BAR+="━"; done
+EBAR=""; for ((i=0; i<EMPTY; i++)); do EBAR+="─"; done
+
+# ── Build statusline ──
+OUT=""
+
+# ◆ brand mark
+OUT+="${TB}◆${X} "
+
+# Directory (teal)
+OUT+="${T}${DIR}${X}"
+
+# Git branch (purple, compact)
+if [ -n "$BRANCH" ]; then
+  OUT+=" ${P}${BRANCH}${X}"
+  [ -n "$GIT_STATUS" ] && OUT+="${Y}[${GIT_STATUS}]${X}"
+fi
+
+# Separator
+OUT+=" ${G}│${X} "
+
+# Qualia mode + phase (teal, the important bit)
+if [ -n "$PROJECT" ]; then
+  OUT+="${TB}${PROJECT}${X}"
+  [ -n "$PHASE" ] && OUT+=" ${TD}p${PHASE}${X}"
+elif [ -n "$PHASE" ]; then
+  OUT+="${T}p${PHASE}${X}"
+fi
+
+# If neither project nor phase, show "ad-hoc"
+[ -z "$PROJECT" ] && [ -z "$PHASE" ] && OUT+="${TD}ad-hoc${X}"
+
+# Separator + model (compact)
+OUT+=" ${G}│${X} ${G}${MODEL}${X}"
+
+# Context bar
+OUT+=" ${CB}${BAR}${G}${EBAR}${X} ${CB}${USED_INT}%%${X}"
+
+printf "$OUT"

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "qualia-framework",
+  "version": "2.1.0",
+  "description": "Qualia Solutions — Claude Code Framework",
+  "bin": {
+    "qualia-framework": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "framework/",
+    "profiles/",
+    "templates/"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Qualiasolutions/qualia-framework.git"
+  },
+  "keywords": ["claude-code", "qualia", "framework", "ai-dev"],
+  "author": "Qualia Solutions",
+  "license": "UNLICENSED"
+}

package/profiles/fawzi.json

@@ -0,0 +1,16 @@
+{
+  "code": "QS-FAWZI-2024",
+  "name": "Fawzi",
+  "fullName": "Fawzi Goussous",
+  "role": "OWNER",
+  "since": "2024",
+  "location": "Nicosia, Cyprus",
+  "type": "founder",
+  "language": "ar-en",
+  "permissions": {
+    "canDeploy": true,
+    "canModifyFramework": true,
+    "canAccessAllProjects": true,
+    "canApproveWork": true
+  }
+}

package/profiles/hasan.json

@@ -0,0 +1,16 @@
+{
+  "code": "QS-HASAN-2026",
+  "name": "Hasan",
+  "fullName": "Hasan",
+  "role": "DEVELOPER",
+  "since": "March 2026",
+  "location": "Cyprus",
+  "type": "part-time",
+  "language": "en",
+  "permissions": {
+    "canDeploy": false,
+    "canModifyFramework": false,
+    "canAccessAllProjects": false,
+    "canApproveWork": false
+  }
+}

package/profiles/moayad.json

@@ -0,0 +1,16 @@
+{
+  "code": "QS-MOAYAD-2025",
+  "name": "Moayad",
+  "fullName": "Moayad",
+  "role": "DEVELOPER",
+  "since": "December 2025",
+  "location": "Jordan",
+  "type": "full-time",
+  "language": "ar-en",
+  "permissions": {
+    "canDeploy": true,
+    "canModifyFramework": false,
+    "canAccessAllProjects": true,
+    "canApproveWork": false
+  }
+}

package/templates/CLAUDE-owner.md

@@ -0,0 +1,52 @@
+# CLAUDE.md — Qualia Solutions
+
+## Identity
+**Fawzi Goussous** — Founder, Qualia Solutions. Nicosia, Cyprus.
+
+- Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel, VAPI, ElevenLabs, Telnyx, Retell AI, OpenRouter
+- Partner: Jay | Team: Moayad (full-time, Jordan), Ahasan (part-time, Cyprus)
+
+## Role: OWNER
+
+Full authority over all projects, deployments, architecture, and client decisions.
+- Deploy directly to production
+- Make architectural decisions unilaterally
+- Access all Supabase projects and service role keys
+- Modify the Qualia framework (CLAUDE.md, skills, hooks)
+
+## Rules
+- Read before Write/Edit — no exceptions
+- Feature branches only — never commit to main/master
+- MVP first. Build only what's asked. No over-engineering.
+- Root cause on failures — no band-aids
+- `npx tsc --noEmit` after multi-file TS changes
+- Glob/Grep directly — no Task(Explore) unless 5+ rounds needed
+- For non-trivial work (multi-file changes, architectural decisions, unfamiliar codebases), confirm understanding before coding — quick tasks are exempt
+- See `rules/security.md` for auth, RLS, Zod, secrets rules
+- See `rules/frontend.md` for design standards
+- See `rules/deployment.md` for deploy checklist
+
+## Collaboration
+Collaborator, not executor. Speak up about bugs, simpler approaches, bad architecture.
+Be honest. Default to action. Never speculate on unread code. Say when blocked.
+- Direct, action-oriented, no fluff. Code > theory.
+- Arabic or English — match whatever language is used
+
+## Workflow
+- **MANDATORY FIRST ACTION**: On every session start, invoke the `qualia-start` skill before doing anything else. This is non-negotiable — do not wait for user input, do not skip it, do not just acknowledge the hook message. Actually invoke the skill using the Skill tool.
+- Subagents (Sonnet) for research. Opus for complex reasoning.
+- `/compact` at 60%. `/clear` between tasks. `/learn` after mistakes.
+
+## Qualia Mode (always active)
+These behaviors apply to ALL interactions:
+- **Frontend guard:** Read .planning/DESIGN.md before any frontend file changes
+- **Deploy guard:** Check .planning/REVIEW.md freshness before any deploy command (run /qualia-review to generate)
+- **Intent verification:** Confirm before modifying 3+ files in one response
+- **Task-type detection:** Auto-load relevant skill patterns based on what's being done
+- **Quality defaults:** Security rules, tsc checks, RLS consideration — always enforced
+
+## Compaction — ALWAYS preserve:
+Project path/name/ref, branch, modified files, decisions, test results, in-progress work, errors, Qualia phase/milestone state, Qualia mode active/inactive state, session digest context.
+
+## Learned Patterns & Gotchas
+See ~/.claude/knowledge/learned-patterns.md for full rules and project gotchas.