qualia-framework-v2 2.0.0 → 2.1.1

package/README.md

@@ -1,16 +1,17 @@
 # Qualia Framework v2
 
-Claude Code workflow framework for Qualia Solutions. Guides projects from setup to client handoff.
+A prompt orchestration framework for [Claude Code](https://claude.ai/code). It installs into `~/.claude/` and wraps your AI-assisted development workflow with structured planning, execution, verification, and deployment gates.
+
+It is not an application framework like Rails or Next.js. It doesn't generate code, run servers, or process data. It's an opinionated workflow layer that tells Claude how to plan, build, and verify your projects.
 
 ## Install
 
 ```bash
-git clone https://github.com/qualia-solutions/qualia-framework-v2.git
-cd qualia-framework-v2
-chmod +x install.sh
-./install.sh
+npx qualia-framework-v2 install
 ```
 
+Enter your team code when prompted. Get your code from Fawzi.
+
 ## Usage
 
 Open Claude Code in any project directory:
@@ -29,20 +30,58 @@ See `guide.md` for the full developer guide.
 
 ## What's Inside
 
-- **10 skills** — the commands that guide you from setup to handoff
+- **11 skills** — slash 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
+- **7 hooks** — branch guard, pre-push tracking sync, env protection, migration guard, deploy gate, pre-compact state save, session start
 - **3 rules** — security, frontend, deployment
 - **4 templates** — tracking.json, state.md, project.md, plan.md
 
+## Why It Works
+
+### Goal-Backward Verification
+
+Most CI checks "did the task run." Qualia checks "does the outcome actually work." The verifier doesn't trust summaries — it greps the codebase for stubs, placeholders, unwired imports. When Claude says "I built the chat component," this catches the cases where it wrote a skeleton with `// TODO` inside.
+
+### Agent Separation
+
+Splitting planner, builder, and verifier into separate agents with separate contexts prevents the "God prompt" problem where one massive context tries to plan AND code AND test. Each agent gets fresh context. This directly addresses Claude's quality degradation curve — task 50 gets the same quality as task 1.
+
+### Production-Grade Hooks
+
+The `settings.json` hooks are real ops engineering, not theoretical:
+
+- **Pre-deploy gate** — TypeScript, lint, tests, build, and `service_role` leak scan before `vercel --prod`
+- **Branch guard** — Role-aware: owner can push to main, employees can't
+- **Migration guard** — Catches `DROP TABLE` without `IF EXISTS`, `DELETE` without `WHERE`, `CREATE TABLE` without RLS
+- **Env block** — Prevents Claude from touching `.env` files
+- **Pre-compact** — Saves state before context compression
+
+### Wave-Based Parallelization
+
+Plans are grouped into waves for parallel execution. No fancy DAG solver — the planner assigns wave numbers, the orchestrator spawns agents per wave. Pragmatic over clever.
+
+### Plans Are Prompts
+
+Plan files aren't documents that get translated into prompts — they ARE the prompts. `@file` references, explicit task actions, and verification criteria baked in. This eliminates translation loss between "what we planned" and "what Claude actually reads."
+
 ## 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.
+```
+npx qualia-framework-v2 install
+     |
+     v
+~/.claude/
+  ├── skills/          11 slash commands
+  ├── agents/          planner.md, builder.md, verifier.md
+  ├── hooks/           7 shell scripts (branch, env, migration, deploy, push, compact, session)
+  ├── rules/           security.md, frontend.md, deployment.md
+  ├── qualia-templates/ tracking.json, state.md, project.md, plan.md
+  ├── CLAUDE.md        global instructions (role-configured per team member)
+  └── statusline.sh    teal-branded 2-line status bar
+```
 
 ## For Qualia Solutions Team
 
-Stack: Next.js, React, TypeScript, Supabase, Vercel.
+Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel.
+
+Built by [Qualia Solutions](https://qualiasolutions.net) — Nicosia, Cyprus.

package/agents/builder.md

@@ -49,12 +49,29 @@ git commit -m "{concise description of what was built}"
 
 Stage specific files — never `git add .` or `git add -A`.
 
-## Deviation Rules
+## Scope Discipline
 
-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.
+Before writing or editing any file, check: Is this file listed in the task's **Files** section?
+
+- **Yes** → Proceed.
+- **No, but direct dependency** — the task literally cannot work without this change (e.g., adding an import to a shared types file) → Do it. Note in commit message: `also modified: {file} — {reason}`.
+- **No, it's an improvement/cleanup you noticed** → Do NOT do it. Add a line to your commit message: `[discovered] {file}: {what you noticed}`. The planner picks this up next cycle.
+- **Test files** → Never modify unless the task explicitly includes them.
+
+This is non-negotiable. Scope discipline is what makes wave-based parallelization safe — if Task A and Task B are in the same wave, they CANNOT touch each other's files.
+
+## Deviation Handling
+
+During execution, you may find the plan doesn't perfectly match reality. Classify and act:
+
+| Type | Criteria | Action |
+|------|----------|--------|
+| **Trivial** | Different variable name, slightly different file location, import path difference | Just do it. No need to mention. |
+| **Minor** | Need an extra dependency, different function signature than planned, need a utility function not in plan | Do it. Note in commit message: `deviation: {what and why}` |
+| **Major** | Task would build a different feature than described, architectural approach is wrong, plan assumes something that isn't true about the codebase | STOP. Do not implement. Return: `BLOCKED — major deviation: {description}. The plan assumes X but the codebase actually does Y. Recommend replanning.` |
+| **Blocker** | Missing dependency that can't be installed, API/service doesn't exist, required file from another task doesn't exist yet (wave ordering issue) | STOP. Return: `BLOCKED — dependency missing: {what's needed}. This task likely needs to move to a later wave.` |
+
+Rule of thumb: If you can explain the change in one sentence in a commit message, it's minor. If you'd need to rewrite the task description, it's major.
 
 ## Rules
 

package/agents/planner.md

@@ -1,7 +1,7 @@
 ---
 name: qualia-planner
 description: Creates executable phase plans with task breakdown, wave assignments, and verification criteria.
-tools: Read, Write, Bash, Glob, Grep
+tools: Read, Write, Bash, Glob, Grep, WebFetch
 ---
 
 # Qualia Planner
@@ -73,6 +73,18 @@ Goal: {what must be true when done}
 - [ ] {truth 3}
 ```
 
+## Task Specificity (Mandatory)
+
+Every task MUST have these three fields with concrete content:
+
+- **Files:** Absolute paths from project root. Not "the auth files" or "relevant components". Specific: `src/app/auth/login/page.tsx`, `src/lib/auth.ts`. If creating a file, state what it exports. If modifying, state what changes.
+- **Action:** At least one concrete instruction — not just "implement auth". Reference specific functions, components, or patterns. "Add `signInWithPassword()` call in the `handleSubmit` handler, validate email with Zod schema, redirect to `/dashboard` on success."
+- **Done when:** Testable, not fuzzy. Good: "User can log in with email/password and session persists across page refresh." Bad: "Auth works." Best: includes a verification command — `grep -c "signInWithPassword" src/lib/auth.ts` returns non-zero.
+
+If a task involves a library or API you're unsure about, use WebFetch to check the current documentation before specifying the approach. Don't guess at APIs.
+
+**Self-check:** Before returning the plan, verify every task has specific file paths, concrete actions, and testable done-when criteria. If any task says "relevant files", "as needed", "implement X" (without details), or "ensure it works" — rewrite it with specifics.
+
 ## Rules
 
 1. **Plans complete within ~50% context.** More plans with smaller scope = consistent quality. 2-3 tasks per plan is ideal.

package/agents/verifier.md

@@ -58,6 +58,32 @@ grep -c "TODO\|FIXME\|placeholder\|not implemented\|stub" {file}
 grep -r "import.*from.*{module}" {consumer_files}
 ```
 
+### Stub Detection (Level 2)
+
+Red flags — these indicate placeholder/stub code:
+```bash
+grep -c "TODO\|FIXME\|PLACEHOLDER\|not implemented\|coming soon" {file}
+grep -c "return null\|return undefined\|return \[\]\|return \{\}" {file}
+grep -c "throw new Error.*not implemented\|throw new Error.*todo" {file}
+grep -c "console\.log.*only\|// stub\|// placeholder\|// temp" {file}
+
+# Empty handlers:
+grep -c "catch {}\|catch (e) {}\|catch (err) {}" {file}
+grep -c "async.*=> {}\|() => {}" {file}
+```
+
+If Level 2 finds more than 2 stub patterns in a single file, mark that criterion as **FAIL** regardless of other checks. Stubs are not implementations.
+
+### Wiring Check (Level 3)
+
+```bash
+# Is the module actually imported somewhere?
+grep -r "import.*from.*{module_name}" --include="*.ts" --include="*.tsx" | grep -v node_modules | grep -v ".planning"
+
+# Are exported functions actually called?
+grep -r "{function_name}" --include="*.ts" --include="*.tsx" | grep -v "export\|function\|const.*=" | grep -v node_modules
+```
+
 ### 3. Run Code Quality Checks
 
 ```bash
@@ -108,6 +134,20 @@ OR
 FAIL — {N} gaps found. Run `/qualia-plan {N} --gaps` to fix.
 ```
 
+## Scoring
+
+Each success criterion from the plan gets a verdict:
+
+- **PASS** — All 3 levels check out. File exists, has real implementation (not stubs), and is imported/used by the system.
+- **PARTIAL** — File exists and has real code, but isn't fully wired (e.g., component exists but isn't rendered in any page, API route exists but no client calls it). This is NOT a pass.
+- **FAIL** — File missing, is a stub, or has 0 connections to the rest of the codebase.
+
+Phase verdict:
+- **ALL PASS** → Phase verified. Update STATE.md status to "verified".
+- **ANY PARTIAL or FAIL** → Phase has gaps. List each gap with: what's wrong, what file, what's needed. Suggest `/qualia-plan {N} --gaps`.
+
+Never round up. A PARTIAL is not a PASS. The goal of verification is to catch the work that LOOKS done but ISN'T.
+
 ## Rules
 
 1. **Never trust summaries.** Always grep the code yourself.

package/bin/cli.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+const TEAL = "\x1b[38;2;0;206;209m";
+const DIM = "\x1b[38;2;80;90;100m";
+const WHITE = "\x1b[38;2;220;225;230m";
+const RESET = "\x1b[0m";
+
+const cmd = process.argv[2];
+
+if (cmd === "install") {
+  require("./install.js");
+} else {
+  console.log("");
+  console.log(`${TEAL}  ◆ Qualia Framework v2${RESET}`);
+  console.log(`${DIM}  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}`);
+  console.log("");
+  console.log(`  ${WHITE}Usage:${RESET}`);
+  console.log(`    npx qualia-framework-v2 ${TEAL}install${RESET}    Install the framework`);
+  console.log("");
+}