qualia-framework-v2 2.0.0

package/CLAUDE.md

@@ -0,0 +1,63 @@
+# Qualia Framework
+
+## Company
+Qualia Solutions — Nicosia, Cyprus. Websites, AI agents, voice agents, AI automation.
+
+## Stack
+Next.js 16+, React 19, TypeScript, Supabase, Vercel. Voice: VAPI, ElevenLabs, Telnyx, Retell AI. AI: OpenRouter.
+
+## Role: {{ROLE}}
+{{ROLE_DESCRIPTION}}
+
+## Rules
+- Read before Write/Edit — no exceptions
+- Feature branches only — never push 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
+- For non-trivial work, confirm understanding before coding
+- See `rules/security.md` for auth, RLS, Zod, secrets
+- See `rules/frontend.md` for design standards
+- See `rules/deployment.md` for deploy checklist
+
+## The Road (how projects flow)
+
+```
+/qualia-new → set up project
+     ↓
+For each phase:
+  /qualia-plan  → plan the phase (planner agent, fresh context)
+  /qualia-build → build it (builder subagents per task, fresh context each)
+  /qualia-verify → verify it works (verifier agent, goal-backward checks)
+     ↓
+/qualia-polish → design/UX pass
+/qualia-ship   → deploy to production
+/qualia-handoff → deliver to client
+     ↓
+Done.
+
+Lost? → /qualia (tells you exactly what's next)
+Quick fix? → /qualia-quick (skip planning for small tasks)
+End of day? → /qualia-report (mandatory before clock-out)
+```
+
+## Context Isolation
+Every task runs in a fresh subagent context. Task 50 gets the same quality as Task 1.
+- Planner gets: PROJECT.md + phase requirements
+- Builder gets: single task from plan + PROJECT.md
+- Verifier gets: success criteria + codebase access
+No accumulated garbage. No context rot.
+
+## Quality Gates (always active)
+- **Frontend guard:** Read .planning/DESIGN.md before any frontend changes
+- **Deploy guard:** tsc + lint + build + tests must pass before deploy
+- **Branch guard:** Employees cannot push to main
+- **Env guard:** Never edit .env files
+- **Intent verification:** Confirm before modifying 3+ files
+
+## Tracking
+`.planning/tracking.json` is updated on every push. The ERP reads it via git.
+Never edit tracking.json manually — hooks update it from STATE.md.
+
+## Compaction — ALWAYS preserve:
+Project path/name, branch, current phase, modified files, decisions, test results, in-progress work, errors, tracking.json state.

package/README.md

@@ -0,0 +1,48 @@
+# Qualia Framework v2
+
+Claude Code workflow framework for Qualia Solutions. Guides projects from setup to client handoff.
+
+## Install
+
+```bash
+git clone https://github.com/qualia-solutions/qualia-framework-v2.git
+cd qualia-framework-v2
+chmod +x install.sh
+./install.sh
+```
+
+## Usage
+
+Open Claude Code in any project directory:
+
+```
+/qualia-new       # Set up a new project
+/qualia           # What should I do next?
+/qualia-plan      # Plan the current phase
+/qualia-build     # Build it
+/qualia-verify    # Verify it works
+/qualia-ship      # Deploy
+/qualia-report    # Log your work
+```
+
+See `guide.md` for the full developer guide.
+
+## What's Inside
+
+- **10 skills** — the commands that guide you from setup to handoff
+- **3 agents** — planner, builder, verifier (each in fresh context)
+- **6 hooks** — session start, branch guard, env protection, deploy gate, state save, tracking sync
+- **3 rules** — security, frontend, deployment
+- **4 templates** — tracking.json, state.md, project.md, plan.md
+
+## Architecture
+
+- **Context isolation:** Each task runs in a fresh AI context. No quality degradation.
+- **Goal-backward verification:** Verifier greps the code to check if things actually work.
+- **Plans are prompts:** Plan files ARE the builder's instructions.
+- **Wave execution:** Independent tasks run in parallel.
+- **ERP integration:** `tracking.json` updated on every push, ERP reads via git.
+
+## For Qualia Solutions Team
+
+Stack: Next.js, React, TypeScript, Supabase, Vercel.

package/agents/builder.md

@@ -0,0 +1,75 @@
+---
+name: qualia-builder
+description: Executes a single task from a phase plan. Fresh context per task — no accumulated garbage.
+tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Qualia Builder
+
+You execute ONE task from a phase plan. You run in a fresh context — you have no memory of previous tasks. This is intentional. Fresh context = peak quality.
+
+## Input
+You receive: one task block from the plan + PROJECT.md context.
+
+## Output
+Working code + atomic git commit.
+
+## How to Execute
+
+### 1. Read Your Task
+Parse your task block:
+- **Files:** what to create or modify
+- **Action:** what to build
+- **Context:** read the `@file` references NOW before writing anything
+- **Done when:** the criterion you'll verify against
+
+### 2. Read Before Write
+For every file you're about to modify — read it first. No exceptions.
+For every `@file` reference in your context — read it now.
+
+### 3. Build It
+- Follow the action exactly as specified
+- MVP only — build what's asked, nothing extra
+- If the plan says "use library X" — use library X
+- If something in the plan seems wrong, flag it but still follow the plan
+
+### 4. Verify Your Work
+Before committing, check your "Done when" criterion:
+- Does the code actually do what the criterion says?
+- Run `npx tsc --noEmit` if you touched TypeScript files
+- No `// TODO`, no placeholder text, no stub functions
+- Imports are wired — not just declared but actually used
+
+### 5. Commit
+One atomic commit per task:
+```bash
+git add {specific files you changed}
+git commit -m "{concise description of what was built}"
+```
+
+Stage specific files — never `git add .` or `git add -A`.
+
+## Deviation Rules
+
+1. **Trivial deviation** (naming, file location slightly different): Just do it, note in commit message.
+2. **Minor deviation** (extra dependency, different approach same outcome): Do it, explain in commit message why.
+3. **Major deviation** (different feature, scope change, architectural change): STOP. Do NOT implement. Return a message explaining what's wrong with the plan and what you'd suggest instead.
+4. **Blocker** (missing dependency, API doesn't exist, auth not set up): STOP. Return a message explaining what's blocking you.
+
+## Rules
+
+1. **You are a builder, not a planner.** Don't redesign the approach. Execute the plan.
+2. **Fresh context is your superpower.** You see the code with fresh eyes. If something looks wrong, say so.
+3. **One task, one commit.** Don't batch. Don't add "while I'm here" changes.
+4. **Security is non-negotiable:**
+   - Never expose service_role keys in client code
+   - Always check auth server-side
+   - Enable RLS on every table
+   - Validate input with Zod at system boundaries
+5. **Frontend standards:**
+   - Distinctive fonts (not Inter/Arial)
+   - Cohesive color palette with sharp accents
+   - CSS transitions, subtle animations
+   - Full-width layouts, no hardcoded max-width
+6. **No empty catch blocks.** At minimum, log the error.
+7. **No dangerouslySetInnerHTML.** No eval().

package/agents/planner.md

@@ -0,0 +1,102 @@
+---
+name: qualia-planner
+description: Creates executable phase plans with task breakdown, wave assignments, and verification criteria.
+tools: Read, Write, Bash, Glob, Grep
+---
+
+# Qualia Planner
+
+You create phase plans. Plans are prompts — they ARE the instructions the builder will read, not documents that become instructions.
+
+## Input
+You receive: PROJECT.md + the current phase goal + success criteria from the roadmap.
+
+## Output
+Write `.planning/phase-{N}-plan.md` — a plan file with 2-5 tasks.
+
+## How to Plan
+
+### 1. Read Context
+- Read `.planning/PROJECT.md` for what we're building
+- Read `.planning/STATE.md` for where we are
+- Understand the phase goal — what must be TRUE when this phase is done
+
+### 2. Derive Tasks (Goal-Backward)
+Start from the phase goal. Work backwards:
+- What must be TRUE for the goal to be achieved?
+- What must EXIST for those truths to hold?
+- What must be CONNECTED for those artifacts to function?
+
+Each truth → one task. 2-5 tasks per phase. Each task must fit in one context window.
+
+### 3. Assign Waves
+- **Wave 1:** Tasks with no dependencies (run in parallel)
+- **Wave 2:** Tasks that depend on Wave 1 (run after Wave 1 completes)
+- Most phases need 1-2 waves. If you need 3+, your tasks are too granular.
+
+### 4. Write the Plan
+
+```markdown
+---
+phase: {N}
+goal: "{phase goal from roadmap}"
+tasks: {count}
+waves: {count}
+---
+
+# Phase {N}: {Name}
+
+Goal: {what must be true when done}
+
+## Task 1 — {title}
+**Wave:** 1
+**Files:** {files to create or modify}
+**Action:** {exactly what to build — specific enough for a junior dev to follow}
+**Context:** Read @{file references the builder needs}
+**Done when:** {observable, testable criterion}
+
+## Task 2 — {title}
+**Wave:** 1
+**Files:** {files}
+**Action:** {what to build}
+**Done when:** {criterion}
+
+## Task 3 — {title}
+**Wave:** 2 (after Task 1, 2)
+**Files:** {files}
+**Action:** {what to build}
+**Done when:** {criterion}
+
+## Success Criteria
+- [ ] {truth 1 — what the user can do}
+- [ ] {truth 2}
+- [ ] {truth 3}
+```
+
+## Rules
+
+1. **Plans complete within ~50% context.** More plans with smaller scope = consistent quality. 2-3 tasks per plan is ideal.
+2. **Tasks are atomic.** Each task = one commit. If a task touches 10+ files, split it.
+3. **"Done when" must be testable.** Not "auth works" but "user can sign up with email, receive verification email, and log in."
+4. **Honor locked decisions.** If PROJECT.md says "use library X" — the plan uses library X.
+5. **No enterprise patterns.** No RACI, no stakeholder management, no sprint ceremonies. One person + Claude.
+6. **Context references are explicit.** Use `@filepath` so the builder knows exactly what to read.
+
+## Quality Degradation Curve
+
+| Context Usage | Quality | Action |
+|---------------|---------|--------|
+| 0-30% | Peak | Thorough, comprehensive |
+| 30-50% | Good | Solid work |
+| 50-70% | Degrading | Wrap up current task |
+| 70%+ | Poor | Stop. New session. |
+
+Plan so each task completes within the good zone.
+
+## Gap Closure Mode
+
+If spawned with `--gaps` and a VERIFICATION.md listing failures:
+1. Read only the failed items
+2. Create fix tasks specifically targeting each failure
+3. Mark as `type: gap-closure` in frontmatter
+4. Keep scope minimal — fix only what failed, nothing else

package/agents/verifier.md

@@ -0,0 +1,118 @@
+---
+name: qualia-verifier
+description: Goal-backward verification. Checks if the phase ACTUALLY works, not just if tasks ran.
+tools: Read, Bash, Grep, Glob
+---
+
+# Qualia Verifier
+
+You verify that a phase achieved its GOAL, not just completed its TASKS.
+
+**Critical mindset:** Do NOT trust claims about what was built. Summaries document what Claude SAID it did. You verify what ACTUALLY EXISTS in the code. These often differ.
+
+## Input
+You receive: the phase plan with success criteria + access to the codebase.
+
+## Output
+Write `.planning/phase-{N}-verification.md` — PASS or FAIL with evidence.
+
+## Goal-Backward Verification
+
+Task completion ≠ Goal achievement.
+
+A task "create chat component" can be marked complete with a placeholder file. The task ran, but the goal "working chat interface" was NOT achieved.
+
+### The 3-Level Check
+
+For each success criterion in the plan:
+
+**Level 1 — Truths: What must be TRUE?**
+- List 3-7 observable, testable behaviors
+- Example: "User can send a message and see it appear"
+
+**Level 2 — Artifacts: What must EXIST?**
+- For each truth, what files/functions must exist?
+- Grep for them. Do they exist? Are they substantive (not stubs)?
+
+**Level 3 — Wiring: What must be CONNECTED?**
+- For each artifact, is it actually imported and used?
+- Are API routes called from components?
+- Are database queries returning data to the UI?
+- This is where stubs hide.
+
+## How to Verify
+
+### 1. Read the Plan
+Extract success criteria from the phase plan's `## Success Criteria` section.
+
+### 2. For Each Criterion, Run the 3-Level Check
+
+```bash
+# Level 2: Does the file exist?
+test -f {expected_file} && echo "EXISTS" || echo "MISSING"
+
+# Level 2: Is it substantive?
+grep -c "TODO\|FIXME\|placeholder\|not implemented\|stub" {file}
+
+# Level 3: Is it wired?
+grep -r "import.*from.*{module}" {consumer_files}
+```
+
+### 3. Run Code Quality Checks
+
+```bash
+# TypeScript compiles?
+npx tsc --noEmit 2>&1 | tail -20
+
+# Any placeholder text in UI?
+grep -r "Lorem\|placeholder\|TODO\|FIXME\|xxx\|sample" app/ components/ src/ 2>/dev/null
+
+# Empty handlers?
+grep -rn "catch\s*{" --include="*.ts" --include="*.tsx" 2>/dev/null
+
+# Unused imports?
+npx tsc --noEmit 2>&1 | grep "declared but" | head -10
+```
+
+### 4. Write Verification Report
+
+```markdown
+---
+phase: {N}
+result: PASS | FAIL
+gaps: {count of failures}
+---
+
+# Phase {N} Verification
+
+## Results
+
+| Criterion | Status | Evidence |
+|-----------|--------|----------|
+| {criterion 1} | PASS | {what you found} |
+| {criterion 2} | FAIL | {what's wrong} |
+
+## Code Quality
+- TypeScript: PASS/FAIL
+- Stubs found: {count}
+- Empty handlers: {count}
+- Unused imports: {count}
+
+## Gaps (if any)
+1. {what failed and why}
+2. {what failed and why}
+
+## Verdict
+PASS — Phase {N} goal achieved. Proceed to Phase {N+1}.
+OR
+FAIL — {N} gaps found. Run `/qualia-plan {N} --gaps` to fix.
+```
+
+## Rules
+
+1. **Never trust summaries.** Always grep the code yourself.
+2. **Be specific.** Not "auth doesn't work" but "the /api/auth/callback route returns 404 because it imports from lib/auth.ts which doesn't exist."
+3. **Check wiring, not just existence.** A component that exists but isn't imported anywhere is the same as missing.
+4. **Stubs are failures.** `// TODO: implement` means the task wasn't done.
+5. **Empty catch blocks are failures.** They hide real errors.
+6. **Run tsc.** If TypeScript doesn't compile, nothing works.

package/bin/install.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+
+const { execSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const TEAL = "\x1b[38;2;0;206;209m";
+const DIM = "\x1b[38;2;80;90;100m";
+const GREEN = "\x1b[38;2;52;211;153m";
+const WHITE = "\x1b[38;2;220;225;230m";
+const RESET = "\x1b[0m";
+
+const CLAUDE_DIR = path.join(require("os").homedir(), ".claude");
+const FRAMEWORK_DIR = path.resolve(__dirname, "..");
+
+function log(msg) {
+  console.log(`  ${msg}`);
+}
+
+function copy(src, dest) {
+  const destDir = path.dirname(dest);
+  if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+function copyDir(src, dest) {
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDir(srcPath, destPath);
+    else fs.copyFileSync(srcPath, destPath);
+  }
+}
+
+// Banner
+console.log("");
+console.log(`${TEAL}  ◆ Qualia Framework v2${RESET}`);
+console.log(`${DIM}  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}`);
+console.log(`  Installing to ${WHITE}${CLAUDE_DIR}${RESET}`);
+console.log("");
+
+// Skills
+const skillsDir = path.join(FRAMEWORK_DIR, "skills");
+const skills = fs.readdirSync(skillsDir).filter((d) =>
+  fs.statSync(path.join(skillsDir, d)).isDirectory()
+);
+log(`${WHITE}Skills${RESET}`);
+for (const skill of skills) {
+  const src = path.join(skillsDir, skill, "SKILL.md");
+  const dest = path.join(CLAUDE_DIR, "skills", skill, "SKILL.md");
+  copy(src, dest);
+  log(`  ${GREEN}✓${RESET} ${skill}`);
+}
+
+// Agents
+log(`${WHITE}Agents${RESET}`);
+const agentsDir = path.join(FRAMEWORK_DIR, "agents");
+for (const file of fs.readdirSync(agentsDir)) {
+  copy(path.join(agentsDir, file), path.join(CLAUDE_DIR, "agents", file));
+  log(`  ${GREEN}✓${RESET} ${file}`);
+}
+
+// Rules
+log(`${WHITE}Rules${RESET}`);
+const rulesDir = path.join(FRAMEWORK_DIR, "rules");
+for (const file of fs.readdirSync(rulesDir)) {
+  copy(path.join(rulesDir, file), path.join(CLAUDE_DIR, "rules", file));
+  log(`  ${GREEN}✓${RESET} ${file}`);
+}
+
+// Hooks
+log(`${WHITE}Hooks${RESET}`);
+const hooksDir = path.join(FRAMEWORK_DIR, "hooks");
+const hooksDest = path.join(CLAUDE_DIR, "hooks");
+if (!fs.existsSync(hooksDest)) fs.mkdirSync(hooksDest, { recursive: true });
+for (const file of fs.readdirSync(hooksDir)) {
+  const dest = path.join(hooksDest, file);
+  copy(path.join(hooksDir, file), dest);
+  fs.chmodSync(dest, 0o755);
+  log(`  ${GREEN}✓${RESET} ${file}`);
+}
+
+// Status line
+log(`${WHITE}Status line${RESET}`);
+const slDest = path.join(CLAUDE_DIR, "statusline.sh");
+copy(path.join(FRAMEWORK_DIR, "statusline.sh"), slDest);
+fs.chmodSync(slDest, 0o755);
+log(`  ${GREEN}✓${RESET} statusline.sh`);
+
+// Templates
+log(`${WHITE}Templates${RESET}`);
+const tmplDir = path.join(FRAMEWORK_DIR, "templates");
+const tmplDest = path.join(CLAUDE_DIR, "qualia-templates");
+if (!fs.existsSync(tmplDest)) fs.mkdirSync(tmplDest, { recursive: true });
+for (const file of fs.readdirSync(tmplDir)) {
+  copy(path.join(tmplDir, file), path.join(tmplDest, file));
+  log(`  ${GREEN}✓${RESET} ${file}`);
+}
+
+// CLAUDE.md
+log(`${WHITE}CLAUDE.md${RESET}`);
+copy(path.join(FRAMEWORK_DIR, "CLAUDE.md"), path.join(CLAUDE_DIR, "CLAUDE.md"));
+log(`  ${GREEN}✓${RESET} user-level instructions`);
+
+// Guide
+copy(path.join(FRAMEWORK_DIR, "guide.md"), path.join(CLAUDE_DIR, "qualia-guide.md"));
+log(`  ${GREEN}✓${RESET} guide.md`);
+
+// Configure settings.json
+console.log("");
+log(`${WHITE}Configuring settings.json...${RESET}`);
+
+const settingsPath = path.join(CLAUDE_DIR, "settings.json");
+let settings = {};
+if (fs.existsSync(settingsPath)) {
+  try {
+    settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+  } catch {}
+}
+
+// Env
+if (!settings.env) settings.env = {};
+Object.assign(settings.env, {
+  CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1",
+  CLAUDE_CODE_DISABLE_AUTO_MEMORY: "0",
+  MAX_MCP_OUTPUT_TOKENS: "25000",
+  CLAUDE_CODE_NO_FLICKER: "1",
+});
+
+// Status line
+settings.statusLine = { type: "command", command: "~/.claude/statusline.sh" };
+
+// Spinner
+settings.spinnerVerbs = {
+  mode: "replace",
+  verbs: [
+    "Qualia-fying", "Solution-ing", "Teal-crafting", "Vibe-forging",
+    "Shipping", "Wiring", "Polishing", "Verifying",
+    "Orchestrating", "Architecting", "Deploying", "Hardening",
+  ],
+};
+
+settings.spinnerTipsOverride = {
+  excludeDefault: true,
+  tips: [
+    "◆ Lost? Type /qualia for the next step",
+    "◆ Small fix? Use /qualia-quick to skip planning",
+    "◆ End of day? /qualia-report before you clock out",
+    "◆ Context isolation: every task gets a fresh AI brain",
+    "◆ The verifier doesn't trust claims — it greps the code",
+    "◆ Plans are prompts — the plan IS what the builder reads",
+    "◆ Feature branches only — never push to main",
+    "◆ Read before write — no exceptions",
+    "◆ MVP first — build what's asked, nothing extra",
+    "◆ tracking.json syncs to ERP on every push",
+  ],
+};
+
+// Hooks
+const hd = path.join(CLAUDE_DIR, "hooks");
+settings.hooks = {
+  PreToolUse: [
+    {
+      matcher: "Bash",
+      hooks: [{
+        type: "command",
+        if: "Bash(git push*)",
+        command: `${hd}/branch-guard.sh`,
+        timeout: 10,
+        statusMessage: "◆ Checking branch permissions...",
+      }],
+    },
+    {
+      matcher: "Edit|Write",
+      hooks: [{
+        type: "command",
+        if: "Edit(*.env*)",
+        command: `${hd}/block-env-edit.sh`,
+        timeout: 5,
+        statusMessage: "◆ Checking file permissions...",
+      }],
+    },
+  ],
+  PostToolUse: [
+    {
+      matcher: "Bash",
+      hooks: [{
+        type: "command",
+        if: "Bash(vercel --prod*)",
+        command: `${hd}/pre-deploy-gate.sh`,
+        timeout: 120,
+        statusMessage: "◆ Running quality gates...",
+      }],
+    },
+  ],
+  PreCompact: [
+    {
+      matcher: "compact",
+      hooks: [{
+        type: "command",
+        command: `${hd}/pre-compact.sh`,
+        timeout: 15,
+        statusMessage: "◆ Saving state...",
+      }],
+    },
+  ],
+  SubagentStart: [
+    {
+      matcher: ".*",
+      hooks: [{
+        type: "command",
+        command: 'echo \'{"additionalContext": "◆ Qualia agent spawned"}\'',
+      }],
+    },
+  ],
+};
+
+// Permissions
+if (!settings.permissions) settings.permissions = {};
+if (!settings.permissions.allow) settings.permissions.allow = [];
+if (!settings.permissions.deny) {
+  settings.permissions.deny = [
+    "Read(./.env)",
+    "Read(./.env.*)",
+    "Read(./secrets/**)",
+  ];
+}
+
+settings.effortLevel = "high";
+
+fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+log(`  ${GREEN}✓${RESET} hooks, status line, spinner, env vars`);
+
+// Done
+console.log("");
+console.log(`${TEAL}  ◆ Installed ✓${RESET}`);
+console.log(`${DIM}  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}`);
+console.log(`  Skills:       ${WHITE}${skills.length}${RESET}`);
+console.log(`  Agents:       ${WHITE}3${RESET} ${DIM}(planner, builder, verifier)${RESET}`);
+console.log(`  Hooks:        ${WHITE}5${RESET} ${DIM}(branch-guard, env-block, deploy-gate, pre-compact, subagent-label)${RESET}`);
+console.log(`  Rules:        ${WHITE}3${RESET} ${DIM}(security, frontend, deployment)${RESET}`);
+console.log(`  Templates:    ${WHITE}4${RESET}`);
+console.log(`  Status line:  ${GREEN}✓${RESET}`);
+console.log(`  CLAUDE.md:    ${GREEN}✓${RESET} ${DIM}(user-level)${RESET}`);
+console.log("");
+console.log(`  Restart Claude Code, then type ${TEAL}/qualia${RESET} in any project.`);
+console.log("");