qualia-framework 2.6.0 → 3.2.0

package/framework/skills/qualia-report/SKILL.md

@@ -1,166 +0,0 @@
----
-name: qualia-report
-description: "Generate a session work report as a branded DOCX — simple summary of what was done. Use this skill whenever the user says 'report', 'done for today', 'session report', 'log my work', 'what did I do', 'end of day', 'wrapping up', 'signing off', or finishes a working session. Also trigger when user mentions 'daily report', 'status update', 'work summary', or wants to document what they accomplished."
----
-
-# Qualia Report — Session DOCX Report
-
-Generate a clean, branded DOCX report of what was done in this session. Simple and clear — what happened, not every detail.
-
-## Usage
-
-`/qualia-report` — Generate DOCX report for current session
-`/qualia-report --week` — Aggregate weekly DOCX report
-
-## Process
-
-### 1. Gather Session Data
-
-Run a **single** bash command to collect everything:
-
-```bash
-echo "---GIT---"
-LAST_REPORT=$(ls -t .planning/reports/report-*.docx .planning/reports/report-*.md 2>/dev/null | head -1)
-if [ -n "$LAST_REPORT" ]; then
-  SINCE_DATE=$(stat -c %Y "$LAST_REPORT" 2>/dev/null)
-  SINCE=$(date -d "@$SINCE_DATE" '+%Y-%m-%d %H:%M' 2>/dev/null || echo "8 hours ago")
-else
-  SINCE="8 hours ago"
-fi
-echo "SINCE:$SINCE"
-echo "---COMMITS---"
-git log --oneline --since="$SINCE" 2>/dev/null | head -20
-echo "---STATS---"
-COMMIT_COUNT=$(git log --oneline --since="$SINCE" 2>/dev/null | wc -l)
-echo "COUNT:$COMMIT_COUNT"
-FIRST=$(git log --format="%ar" --since="$SINCE" 2>/dev/null | tail -1)
-LAST=$(git log --format="%ar" --since="$SINCE" 2>/dev/null | head -1)
-echo "FIRST:$FIRST"
-echo "LAST:$LAST"
-echo "---PROJECT---"
-echo "DIR:$(basename $(pwd))"
-echo "BRANCH:$(git branch --show-current 2>/dev/null)"
-echo "---STATE---"
-test -f .planning/STATE.md && head -20 .planning/STATE.md || echo "no-state"
-echo "---PHASE---"
-test -f .planning/ROADMAP.md && grep -A2 "^## Phase" .planning/ROADMAP.md | head -6 || echo "no-roadmap"
-```
-
-### 2. Synthesize — Keep It Simple
-
-From the gathered data, build a **concise** summary. The report should answer:
-
-1. **What was done?** — 3-6 bullet points summarizing accomplishments in plain language. Group related commits into single items. Don't list every file changed.
-2. **Any deviations?** — Only include if something was done differently from the plan. Skip this section entirely if everything went as planned.
-3. **Any blockers?** — Only include if something is actually blocked. Skip if none.
-4. **What's next?** — 1-3 clear next actions.
-
-**Tone:** Write for a busy founder reviewing work. Clear, factual, no filler. Each bullet should start with a verb: "Built...", "Fixed...", "Added...", "Refactored..."
-
-### 3. Generate DOCX
-
-Build a JSON object and pipe it to the generator:
-
-```bash
-mkdir -p .planning/reports
-
-cat <<'REPORT_JSON' | python3 ~/.claude/qualia-framework/bin/generate-report-docx.py ".planning/reports/report-$(date +%Y-%m-%d-%H%M).docx"
-{
-    "project": "<project-name>",
-    "user": "<git config user.name or 'Fawzi Goussous'>",
-    "date": "<YYYY-MM-DD>",
-    "time": "<HH:MM>",
-    "branch": "<current-branch>",
-    "duration": "<estimated from first to last commit, e.g. ~3 hours>",
-    "phase": "<Phase N of M — name, or omit if no .planning>",
-    "done": [
-        "<accomplishment 1>",
-        "<accomplishment 2>",
-        "<accomplishment 3>"
-    ],
-    "deviations": [],
-    "blockers": [],
-    "next": [
-        "<next action 1>",
-        "<next action 2>"
-    ],
-    "commits": [
-        "<hash> <message>",
-        "<hash> <message>"
-    ]
-}
-REPORT_JSON
-```
-
-**Important:** The JSON must be valid. Escape any quotes in commit messages. Omit `deviations` and `blockers` arrays if empty (the generator handles missing keys gracefully).
-
-### 4. Commit & Auto-Upload to ERP
-
-```bash
-# Commit the report
-git add .planning/reports/report-*.docx
-git commit -m "report: session report $(date +%Y-%m-%d) — $(basename $(pwd))"
-```
-
-Then **auto-upload** the report to the ERP so it's linked to the employee's active work session. This is mandatory and happens automatically — employees cannot skip or edit the report before it reaches the ERP.
-
-```bash
-# Auto-upload to ERP
-REPORT_FILE=$(ls -t .planning/reports/report-*.docx 2>/dev/null | head -1)
-EMPLOYEE_EMAIL=$(git config user.email)
-PROJECT_NAME=$(basename $(pwd))
-ERP_URL="https://portal.qualiasolutions.net/api/claude/report-upload"
-API_KEY=$(cat ~/.claude/.env 2>/dev/null | grep CLAUDE_API_KEY | cut -d= -f2 || echo "")
-
-if [ -z "$API_KEY" ]; then
-  # Try from project env
-  API_KEY=$(grep CLAUDE_API_KEY .env.local 2>/dev/null | cut -d= -f2 || echo "")
-fi
-
-if [ -n "$REPORT_FILE" ] && [ -n "$API_KEY" ]; then
-  UPLOAD_RESULT=$(curl -s -X POST "$ERP_URL" \
-    -H "x-api-key: $API_KEY" \
-    -F "file=@$REPORT_FILE" \
-    -F "employee_email=$EMPLOYEE_EMAIL" \
-    -F "project_name=$PROJECT_NAME")
-  echo "ERP upload: $UPLOAD_RESULT"
-else
-  echo "WARNING: Could not auto-upload report to ERP (missing API key or report file)"
-fi
-```
-
-Then tell the user:
-
-> Report saved to `.planning/reports/report-{date}.docx` and **auto-uploaded to ERP**.
->
-> Your report is now linked to your active work session. When you clock out, it will already be attached.
->
-> Want to save session context too? Run `/qualia-pause-work`
-
-### 5. Update STATE.md (if exists)
-
-Update `Last activity` and `Last worked by` fields.
-
-## Weekly Report (`--week`)
-
-When run with `--week`:
-
-1. Read all reports from the last 7 days (check `.planning/reports/`)
-2. Read git log for the full week
-3. Build an aggregate JSON with:
-   - `"project"` — project name
-   - `"date"` — current date with "Weekly" suffix
-   - `"duration"` — "Week of {date} to {date}"
-   - `"done"` — combined accomplishments from all sessions, deduplicated
-   - `"next"` — forward-looking items from the most recent report
-   - `"commits"` — full week's commits
-4. Pipe to the same generator, save as `weekly-{date}.docx`
-
-## Generator Location
-
-`~/.claude/qualia-framework/bin/generate-report-docx.py`
-
-Requires: `python-docx` (pre-installed). Uses Qualia logo from `~/.claude/qualia-framework/assets/qualia-logo.png`.
-
----
-> Stuck? Type `/qualia-idk` · Lost? Type `/qualia-help`

package/framework/skills/qualia-research-phase/SKILL.md

@@ -1,88 +0,0 @@
----
-name: qualia-research-phase
-description: "Conduct standalone research for a project phase — ecosystem analysis, feasibility studies, implementation patterns, comparisons. Use this skill whenever the user says 'research', 'research phase', 'investigate options', 'tech research', or wants to explore technical options before planning a phase. Also trigger when user mentions 'feasibility study', 'compare frameworks', 'what stack should we use', or needs structured research output that feeds into phase planning."
----
-
-# Qualia Research Phase — Phase Research
-
-Conduct structured research for a project phase, producing a RESEARCH.md that feeds directly into phase planning.
-
-## Usage
-
-`/qualia-research-phase 3` — Research for phase 3 (default: ecosystem mode)
-`/qualia-research-phase 3 --mode=feasibility` — Feasibility study
-`/qualia-research-phase 3 --mode=implementation` — Implementation patterns
-`/qualia-research-phase 3 --mode=comparison` — Compare alternatives
-
-## Research Modes
-
-- **ecosystem** (default) — Survey the landscape: what libraries, APIs, patterns exist for this problem
-- **feasibility** — Can we do this? What are the blockers? What's the effort?
-- **implementation** — How should we build this? Concrete patterns and examples
-- **comparison** — Compare 2-3 approaches side by side with tradeoffs
-
-## Process
-
-### 1. Initialize
-
-Use `qualia-tools.js` for state management:
-```bash
-node ~/.claude/qualia-framework/bin/qualia-tools.js phase-op <phase>
-```
-
-Validate the phase exists in ROADMAP.md. Check if research already exists at `.planning/phases/{phase}-{slug}/{phase}-RESEARCH.md`.
-
-### 2. Gather Context
-
-Read project context:
-- `.planning/PROJECT.md` — tech stack, constraints
-- `.planning/ROADMAP.md` — phase description and dependencies
-- Phase CONTEXT.md if it exists (from discuss-phase)
-
-### 3. Spawn Researcher
-
-Spawn the `qualia-phase-researcher` agent with full context.
-
-Reference: `~/.claude/agents/qualia-phase-researcher.md`
-
-Model resolution:
-```bash
-node ~/.claude/qualia-framework/bin/qualia-tools.js resolve-model qualia-phase-researcher
-```
-
-### 4. Research Output
-
-The researcher produces `.planning/phases/{phase}-{slug}/{phase}-RESEARCH.md` with sections designed for downstream consumption by plan-phase:
-
-- **Standard Stack** — Recommended libraries and tools
-- **Architecture Patterns** — How to structure the implementation
-- **Don't Hand-Roll** — Things to use existing solutions for
-- **Common Pitfalls** — What to watch out for
-- **Code Examples** — Concrete snippets showing key patterns
-
-### 5. Handle Return
-
-The researcher returns one of:
-- **COMPLETE** — Research done, ready for planning
-- **CHECKPOINT** — Partial results, needs more investigation (spawn continuation)
-- **INCONCLUSIVE** — Couldn't determine best approach, present options to user
-
-### When to Use /deep-research Instead
-
-| Use `/qualia-research-phase` | Use `/deep-research` |
-|------------------------------|----------------------|
-| Phase-specific technical research | Whole-project architectural analysis |
-| Output feeds into `/qualia-plan-phase` | Output is a standalone report |
-| 1 researcher agent, fast | 6 parallel Opus agents, thorough |
-| "How should we build phase 3?" | "Is this codebase production-ready?" |
-
-Both can be combined: `/deep-research` for architectural context, then `/qualia-research-phase` for the specific phase.
-
-### 6. Next Step
-
-> "Research complete for phase {N}. Run `/qualia-plan-phase {N}` to create the execution plan."
-
-### Agents Used
-| Agent | File | Role |
-|-------|------|------|
-| `qualia-phase-researcher` | `~/.claude/agents/qualia-phase-researcher.md` | Conducts phase-specific research |

package/framework/skills/qualia-resume-work/SKILL.md

@@ -1,62 +0,0 @@
----
-name: qualia-resume-work
-description: "Restore context from a previous session and pick up where you left off. Use this skill whenever the user says 'resume', 'continue work', 'pick up where I left off', 'resume work', 'what was I doing', or starts a new session on an existing project. Also trigger when user mentions '.continue-here', 'last session', or needs to restore context from a previous handoff."
----
-
-# Qualia Resume Work — Session Context Restoration
-
-Restore context from a previous session and route to the right next action.
-
-## Usage
-
-`/qualia-resume-work` — Auto-detect and restore context
-
-## Process
-
-### 1. Load State
-
-Reference: `~/.claude/qualia-framework/workflows/resume-project.md`
-
-Check for context sources in priority order:
-
-1. **`.continue-here.md`** at project root — Full handoff from pause-work
-2. **`.planning/STATE.md`** — Project state file
-3. **Reconstruct from git** — `git log --oneline -10` and `git diff --stat`
-
-### 2. Context Restoration
-
-#### If `.continue-here.md` exists:
-Read it fully — it contains everything: what was done, what's in progress, next steps, decisions, blockers. This is the richest context source.
-
-#### If only STATE.md exists:
-Read STATE.md + ROADMAP.md to understand:
-- Current milestone and phase
-- Phase statuses
-- What was last worked on
-
-#### If neither exists:
-Reconstruct from git history and file structure. Present findings and ask user to confirm.
-
-### 3. Detect Incomplete Work
-
-Check for signs of interrupted work:
-- Phase has PLAN.md but no SUMMARY.md (execution started but not completed)
-- Uncommitted changes (`git status --short`)
-- Phase marked `in progress` in STATE.md
-
-### 4. Present Status
-
-Concise summary of:
-- Where the project stands
-- What was happening last session
-- Any incomplete work detected
-
-### 5. Route to Next Action
-
-Based on detected state, suggest the most logical next step:
-- Incomplete execution → "Continue with `/qualia-execute-phase {N}`"
-- Phase done but unverified → "Verify with `/qualia-verify-work {N}`"
-- Clean state → "Next up: `/qualia-plan-phase {N}`"
-- Has blockers from handoff → Surface them for user decision
-
-Clean up `.continue-here.md` after successful context restoration (or offer to keep it).

package/framework/skills/qualia-review/SKILL.md

@@ -1,263 +0,0 @@
----
-name: qualia-review
-description: "Production audit and code review. Use --web for web app audit (security, performance, reliability), --ai for AI/voice agent audit (prompt injection, safety, RAG, voice), or no flag for general code review. Trigger on 'review', 'audit', 'code review', 'security check', 'qualia-review'."
-tags: [review, audit, security, production, ai, voice]
----
-
-# Review & Audit
-
-> **Deep parallel-agent analysis with full severity-scored report.** For a quick checklist scan without agents, run the shipping checklist manually.
-
-Unified review skill. Detects project type, spawns parallel agents, scores everything.
-
-## Usage
-
-- `/review` — General code review: quality, security, architecture, performance, tests
-- `/review --web` — Web app production audit: security hardening, performance, reliability, observability
-- `/review --ai` — AI/voice agent audit: prompt injection, safety rails, RAG quality, voice latency, conversation flow
-
----
-
-## General Code Review (default)
-
-Spawn parallel review agents for:
-
-### 1. Code Quality
-- Clean code principles, SOLID, DRY, naming
-- Code smells, readability, maintainability
-- TypeScript strictness, type safety
-
-### 2. Security
-- OWASP top 10 (injection, XSS, CSRF)
-- Auth/authorization checks server-side
-- Secrets scan, env var handling
-- RLS policies on Supabase tables
-
-### 3. Architecture
-- Component boundaries, coupling/cohesion
-- API contract stability
-- Design pattern consistency
-
-### 4. Performance
-- Database query efficiency (N+1, missing indexes)
-- Bundle size, lazy loading, render performance
-- Caching strategy
-
-### 5. Test Coverage
-- Unit/integration test gaps
-- Edge cases not covered
-- Test quality (not just coverage numbers)
-
-### Output
-Consolidated report with severity levels:
-- **CRITICAL** — Must fix before deploy (security, data loss)
-- **HIGH** — Should fix soon (performance, reliability)
-- **MEDIUM** — Recommended (code quality, maintainability)
-- **LOW** — Nice to have (style, documentation)
-
----
-
-## --web (Web App Production Audit)
-
-Full production-readiness audit for Next.js + Supabase + Vercel web apps.
-
-### Pre-Audit Discovery
-Detect: deployment target, database, auth provider, CI/CD setup.
-
-### Security Audit
-```
-CRITICAL:
-[ ] No secrets in code
-[ ] HTTPS enforced
-[ ] Auth tokens have expiry/refresh
-[ ] CORS properly restricted
-[ ] CSP headers configured
-[ ] SQL injection prevention
-[ ] XSS prevention
-[ ] Rate limiting on auth endpoints
-
-HIGH:
-[ ] npm audit clean
-[ ] Security headers (X-Frame-Options, HSTS)
-[ ] Admin routes protected
-[ ] File upload validation
-```
-
-### Performance Audit
-```
-[ ] Core Web Vitals (LCP < 2.5s, FID < 100ms, CLS < 0.1)
-[ ] Image optimization (next/image, WebP)
-[ ] Bundle analysis (no oversized chunks)
-[ ] Database query performance
-[ ] API response times
-[ ] Caching strategy
-```
-
-### Reliability Audit
-```
-[ ] Error boundaries on all pages
-[ ] API error handling (timeouts, retries)
-[ ] Database connection pooling
-[ ] Graceful degradation
-[ ] Health check endpoint
-```
-
-### Observability Audit
-```
-[ ] Error tracking (Sentry or similar)
-[ ] Structured logging
-[ ] Uptime monitoring
-[ ] Analytics configured
-```
-
-### Deployment Config
-```
-[ ] Environment variables set per environment
-[ ] Build succeeds locally
-[ ] Rollback procedure documented
-[ ] Database backups configured
-```
-
----
-
-## --ai (AI/Voice Agent Production Audit)
-
-Purpose-built for voice agents, chatbots, and multi-channel AI apps.
-
-### Phase 0: Auto-Detection
-Scan package.json for:
-- **Voice**: VAPI, ElevenLabs, Retell, Telnyx
-- **Chat**: AI SDK, OpenAI, Anthropic, Gemini
-- **Channels**: WhatsApp, Telegram, Slack, Twilio
-- **RAG**: pgvector, Pinecone, ChromaDB, LangChain
-
-Skip irrelevant agents based on detection.
-
-### Prompt Safety Audit
-```
-CRITICAL:
-[ ] System prompts not exposed to users
-[ ] Prompt injection defenses (input sanitization)
-[ ] No eval() or dynamic code execution from AI output
-[ ] Output validation before rendering
-[ ] Token limits enforced
-
-HIGH:
-[ ] Prompt template versioning
-[ ] Fallback responses for edge cases
-[ ] Content filtering on AI output
-[ ] User input length limits
-```
-
-### Auth & Data Security
-```
-[ ] User context isolated per session
-[ ] API keys server-side only
-[ ] Conversation data encrypted at rest
-[ ] PII handling compliant
-[ ] Rate limiting per user
-```
-
-### Conversation Flow
-```
-[ ] Graceful handling of off-topic inputs
-[ ] Context window management (not exceeding limits)
-[ ] Conversation history pruning strategy
-[ ] Error recovery mid-conversation
-[ ] Handoff to human when needed
-```
-
-### Voice-Specific (when voice detected)
-```
-[ ] Latency < 500ms first response
-[ ] Interruption handling
-[ ] Silence detection and timeout
-[ ] Audio quality / codec settings
-[ ] VAPI webhook security (signature verification)
-[ ] Fallback TTS if primary fails
-```
-
-### RAG Quality (when embeddings detected)
-```
-[ ] Embedding consistency (same model for index/query)
-[ ] Chunk size appropriate for use case
-[ ] Metadata filtering working
-[ ] Retrieval relevance scoring
-[ ] Index refresh strategy
-```
-
-### Tool/Function Calling
-```
-[ ] Tool descriptions clear and unambiguous
-[ ] Input validation on tool parameters
-[ ] Error handling for tool failures
-[ ] Tool execution timeout
-[ ] Dangerous tools gated behind confirmation
-```
-
-### AI Resilience
-```
-[ ] Provider failover (primary → fallback model)
-[ ] Timeout handling (don't hang on slow API)
-[ ] Cost monitoring and alerts
-[ ] Token budget per request
-[ ] Streaming error recovery
-```
-
-### Output
-Severity-scored findings with exact `file:line` references and fix recommendations.
-
----
-
-## Shipping Checklist Scan
-
-After running all review agents, cross-reference findings against the relevant shipping checklist from `~/.claude/qualia-framework/references/completion-checklists.md`.
-
-Detect project type and load the matching checklist:
-- **website** → "Website-Specific Checklist" + "Universal Checklist"
-- **agent/ai** → "AI Agent Checklist" + "Universal Checklist"
-- **voice** → "Voice Agent Checklist" + "Universal Checklist"
-- **mobile** → "Mobile App Checklist" + "Universal Checklist"
-- **platform** → "Platform with LLM Checklist" + "Universal Checklist"
-
-For each checklist item, run automated verification where possible (grep, file checks, build checks). Include a "Shipping Checklist" section in the review report with PASS/WARN/FAIL per item. FAIL items should be scored as HIGH severity findings.
-
-## Persist Results
-
-After generating the review report, write findings to a persistent file:
-
-**Location:** `.planning/REVIEW.md` if `.planning/` exists, otherwise `.review/REVIEW.md` at project root.
-
-**Format:**
-```markdown
----
-date: YYYY-MM-DD HH:MM
-mode: general|web|ai
-critical_count: N
-high_count: N
-medium_count: N
-low_count: N
-status: clean|has_blockers
----
-
-# Review — YYYY-MM-DD
-
-## Blockers (CRITICAL + HIGH)
-- [file:line] description (CRITICAL)
-- [file:line] description (HIGH)
-
-## Recommendations (MEDIUM + LOW)
-- [file:line] description (MEDIUM)
-```
-
-**Rules:**
-- `status: has_blockers` when critical_count > 0 OR high_count > 0
-- `status: clean` when critical_count == 0 AND high_count == 0
-- If file exists, prepend new review (keep last 3 reviews, delete older)
-- Confirm: "Review saved to {path}. `/ship` will check this before deploying."
-
-## Deploy Gate
-
-Any CRITICAL or HIGH finding from `/review` is a **deploy blocker**. The `/deploy-verify` skill checks for unresolved review findings before running its 8-point verification. If you haven't run `/review` before deploying, `/deploy-verify` will flag it as a warning.
-
-Workflow: `/review` → fix findings → `/ship` (which triggers `/deploy-verify` automatically)