qualia-framework-v2 2.0.0 → 2.1.0

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/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("");
+}

package/bin/install.js

@@ -1,248 +1,393 @@
 #!/usr/bin/env node
 
-const { execSync } = require("child_process");
+const { createInterface } = require("readline");
 const path = require("path");
 const fs = require("fs");
 
+// ─── Colors ──────────────────────────────────────────────
 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 YELLOW = "\x1b[38;2;234;179;8m";
+const RED = "\x1b[38;2;239;68;68m";
 const RESET = "\x1b[0m";
 
+// ─── Team codes ──────────────────────────────────────────
+const TEAM = {
+  "QS-FAWZI-01": {
+    name: "Fawzi Goussous",
+    role: "OWNER",
+    description: "Company owner. Full access. Can push to main, approve deploys, edit secrets.",
+  },
+  "QS-HASAN-02": {
+    name: "Hasan",
+    role: "EMPLOYEE",
+    description: "Developer. Feature branches only. Cannot push to main or edit .env files.",
+  },
+  "QS-MOAYAD-03": {
+    name: "Moayad",
+    role: "EMPLOYEE",
+    description: "Developer. Feature branches only. Cannot push to main or edit .env files.",
+  },
+};
+
 const CLAUDE_DIR = path.join(require("os").homedir(), ".claude");
 const FRAMEWORK_DIR = path.resolve(__dirname, "..");
 
+let installed = 0;
+let errors = 0;
+
 function log(msg) {
   console.log(`  ${msg}`);
 }
-
+function ok(label) {
+  installed++;
+  log(`${GREEN}✓${RESET} ${label}`);
+}
+function warn(label) {
+  errors++;
+  log(`${YELLOW}✗${RESET} ${label}`);
+}
 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);
-  }
+// ─── Prompt for code ─────────────────────────────────────
+function askCode() {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    console.log("");
+    console.log(`${TEAL}  ◆ Qualia Framework v2${RESET}`);
+    console.log(`${DIM}  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}`);
+    console.log("");
+    rl.question(`  ${WHITE}Enter install code:${RESET} `, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
 }
 
-// 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}`);
-}
+// ─── Main ────────────────────────────────────────────────
+async function main() {
+  const code = await askCode();
+  const member = TEAM[code];
 
-// 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}`);
-}
+  if (!member) {
+    console.log("");
+    log(`${RED}✗${RESET} Invalid code. Get your install code from Fawzi.`);
+    console.log("");
+    process.exit(1);
+  }
 
-// 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}`);
-}
+  console.log("");
+  log(`${GREEN}✓${RESET} ${WHITE}${member.name}${RESET} ${DIM}(${member.role})${RESET}`);
+  console.log("");
+  log(`Installing to ${WHITE}${CLAUDE_DIR}${RESET}`);
+  console.log("");
 
-// 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}`);
-}
+  // ─── Skills ──────────────────────────────────────────
+  const skillsDir = path.join(FRAMEWORK_DIR, "skills");
+  const skills = fs
+    .readdirSync(skillsDir)
+    .filter((d) => fs.statSync(path.join(skillsDir, d)).isDirectory());
 
-// 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}`);
-}
+  log(`${WHITE}Skills${RESET}`);
+  for (const skill of skills) {
+    try {
+      copy(
+        path.join(skillsDir, skill, "SKILL.md"),
+        path.join(CLAUDE_DIR, "skills", skill, "SKILL.md")
+      );
+      ok(skill);
+    } catch (e) {
+      warn(`${skill} — ${e.message}`);
+    }
+  }
 
-// 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`);
+  // ─── Agents ────────────────────────────────────────────
+  log(`${WHITE}Agents${RESET}`);
+  const agentsDir = path.join(FRAMEWORK_DIR, "agents");
+  for (const file of fs.readdirSync(agentsDir)) {
+    try {
+      copy(path.join(agentsDir, file), path.join(CLAUDE_DIR, "agents", file));
+      ok(file);
+    } catch (e) {
+      warn(`${file} — ${e.message}`);
+    }
+  }
 
-// Guide
-copy(path.join(FRAMEWORK_DIR, "guide.md"), path.join(CLAUDE_DIR, "qualia-guide.md"));
-log(`  ${GREEN}✓${RESET} guide.md`);
+  // ─── Rules ─────────────────────────────────────────────
+  log(`${WHITE}Rules${RESET}`);
+  const rulesDir = path.join(FRAMEWORK_DIR, "rules");
+  for (const file of fs.readdirSync(rulesDir)) {
+    try {
+      copy(path.join(rulesDir, file), path.join(CLAUDE_DIR, "rules", file));
+      ok(file);
+    } catch (e) {
+      warn(`${file} — ${e.message}`);
+    }
+  }
 
-// Configure settings.json
-console.log("");
-log(`${WHITE}Configuring settings.json...${RESET}`);
+  // ─── Hooks ─────────────────────────────────────────────
+  log(`${WHITE}Hooks${RESET}`);
+  const hooksSource = 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(hooksSource)) {
+    try {
+      const dest = path.join(hooksDest, file);
+      copy(path.join(hooksSource, file), dest);
+      fs.chmodSync(dest, 0o755);
+      ok(file);
+    } catch (e) {
+      warn(`${file} — ${e.message}`);
+    }
+  }
 
-const settingsPath = path.join(CLAUDE_DIR, "settings.json");
-let settings = {};
-if (fs.existsSync(settingsPath)) {
+  // ─── Status line ───────────────────────────────────────
+  log(`${WHITE}Status line${RESET}`);
   try {
-    settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
-  } catch {}
-}
+    const slDest = path.join(CLAUDE_DIR, "statusline.sh");
+    copy(path.join(FRAMEWORK_DIR, "statusline.sh"), slDest);
+    fs.chmodSync(slDest, 0o755);
+    ok("statusline.sh");
+  } catch (e) {
+    warn(`statusline.sh — ${e.message}`);
+  }
 
-// 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",
-});
+  // ─── 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)) {
+    try {
+      copy(path.join(tmplDir, file), path.join(tmplDest, file));
+      ok(file);
+    } catch (e) {
+      warn(`${file} — ${e.message}`);
+    }
+  }
 
-// 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",
-  ],
-};
+  // ─── CLAUDE.md with role ───────────────────────────────
+  log(`${WHITE}CLAUDE.md${RESET}`);
+  try {
+    let claudeMd = fs.readFileSync(
+      path.join(FRAMEWORK_DIR, "CLAUDE.md"),
+      "utf8"
+    );
+    claudeMd = claudeMd.replace("{{ROLE}}", member.role);
+    claudeMd = claudeMd.replace("{{ROLE_DESCRIPTION}}", member.description);
+    const claudeDest = path.join(CLAUDE_DIR, "CLAUDE.md");
+    fs.writeFileSync(claudeDest, claudeMd, "utf8");
+    ok(`Configured as ${member.role}`);
+  } catch (e) {
+    warn(`CLAUDE.md — ${e.message}`);
+  }
 
-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",
-  ],
-};
+  // ─── Guide ─────────────────────────────────────────────
+  try {
+    copy(
+      path.join(FRAMEWORK_DIR, "guide.md"),
+      path.join(CLAUDE_DIR, "qualia-guide.md")
+    );
+    ok("guide.md");
+  } catch (e) {
+    warn(`guide.md — ${e.message}`);
+  }
 
-// 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"}\'',
-      }],
-    },
-  ],
-};
+  // ─── 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",
+    ],
+  };
 
-// 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.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 — full system
+  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...",
+          },
+          {
+            type: "command",
+            if: "Bash(git push*)",
+            command: `${hd}/pre-push.sh`,
+            timeout: 15,
+            statusMessage: "◆ Syncing tracking...",
+          },
+        ],
+      },
+      {
+        matcher: "Edit|Write",
+        hooks: [
+          {
+            type: "command",
+            if: "Edit(*.env*)|Write(*.env*)",
+            command: `${hd}/block-env-edit.sh`,
+            timeout: 5,
+            statusMessage: "◆ Checking file permissions...",
+          },
+          {
+            type: "command",
+            if: "Edit(*migration*)|Write(*migration*)|Edit(*.sql)|Write(*.sql)",
+            command: `${hd}/migration-guard.sh`,
+            timeout: 10,
+            statusMessage: "◆ Checking migration safety...",
+          },
+        ],
+      },
+    ],
+    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));
+
+  ok("Hooks: branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact");
+  ok("Status line + spinner configured");
+  ok("Environment variables + permissions");
+
+  // ─── Summary ───────────────────────────────────────────
+  console.log("");
+  console.log(`${TEAL}  ◆ Installed ✓${RESET}`);
+  console.log(`${DIM}  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}`);
+  console.log(`  ${WHITE}${member.name}${RESET} ${DIM}(${member.role})${RESET}`);
+  console.log(`  Skills:       ${WHITE}${skills.length}${RESET}`);
+  console.log(`  Agents:       ${WHITE}3${RESET} ${DIM}(planner, builder, verifier)${RESET}`);
+  console.log(`  Hooks:        ${WHITE}6${RESET} ${DIM}(branch-guard, pre-push, env-block, migration-guard, deploy-gate, pre-compact)${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}(${member.role})${RESET}`);
+
+  if (errors > 0) {
+    console.log("");
+    console.log(`  ${YELLOW}${errors} warning(s)${RESET} — check output above`);
+  }
+
+  console.log("");
+  console.log(`  Restart Claude Code, then type ${TEAL}/qualia${RESET} in any project.`);
+  console.log("");
 }
 
-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("");
+main().catch((e) => {
+  console.error(`${RED}  ✗ Installation failed: ${e.message}${RESET}`);
+  process.exit(1);
+});

package/hooks/block-env-edit.sh

@@ -1,8 +1,11 @@
 #!/bin/bash
 # Prevent Claude from editing .env files
+# Claude Code hooks receive JSON on stdin with tool_input.file_path
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.command // ""' 2>/dev/null)
 
-FILE="$1"
 if [[ "$FILE" == *.env* ]] || [[ "$FILE" == *".env.local"* ]] || [[ "$FILE" == *".env.production"* ]]; then
   echo "BLOCKED: Cannot edit environment files. Ask Fawzi to update secrets."
-  exit 1
+  exit 2
 fi

package/hooks/migration-guard.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# Catch dangerous SQL patterns in migration files
+# Runs as PreToolUse hook on Write/Edit of migration files
+
+INPUT=$(cat)
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null)
+CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // .tool_input.new_string // ""' 2>/dev/null)
+
+# Only check migration/SQL files
+case "$FILE" in
+  *migration*|*migrate*|*.sql) ;;
+  *) exit 0 ;;
+esac
+
+ERRORS=""
+
+# DROP TABLE without safeguards
+if echo "$CONTENT" | grep -qi "DROP TABLE" && ! echo "$CONTENT" | grep -qi "IF EXISTS"; then
+  ERRORS="${ERRORS}\n  ✗ DROP TABLE without IF EXISTS"
+fi
+
+# DELETE without WHERE
+if echo "$CONTENT" | grep -qi "DELETE FROM" && ! echo "$CONTENT" | grep -qi "WHERE"; then
+  ERRORS="${ERRORS}\n  ✗ DELETE FROM without WHERE clause"
+fi
+
+# TRUNCATE (almost always wrong in migrations)
+if echo "$CONTENT" | grep -qi "TRUNCATE"; then
+  ERRORS="${ERRORS}\n  ✗ TRUNCATE detected — are you sure?"
+fi
+
+# CREATE TABLE without RLS
+if echo "$CONTENT" | grep -qi "CREATE TABLE" && ! echo "$CONTENT" | grep -qi "ENABLE ROW LEVEL SECURITY"; then
+  ERRORS="${ERRORS}\n  ✗ CREATE TABLE without ENABLE ROW LEVEL SECURITY"
+fi
+
+if [ -n "$ERRORS" ]; then
+  echo "◆ Migration guard — dangerous patterns found:"
+  echo -e "$ERRORS"
+  echo ""
+  echo "Fix these before proceeding. If intentional, ask Fawzi to approve."
+  exit 2
+fi

package/hooks/pre-deploy-gate.sh

@@ -12,6 +12,24 @@ if [ -f "tsconfig.json" ]; then
   echo "  ✓ TypeScript"
 fi
 
+# Lint check
+if [ -f "package.json" ] && grep -q '"lint"' package.json; then
+  if ! npm run lint 2>/dev/null; then
+    echo "BLOCKED: Lint errors. Fix before deploying."
+    exit 1
+  fi
+  echo "  ✓ Lint"
+fi
+
+# Test check
+if [ -f "package.json" ] && grep -q '"test"' package.json; then
+  if ! npm test 2>/dev/null; then
+    echo "BLOCKED: Tests failed. Fix before deploying."
+    exit 1
+  fi
+  echo "  ✓ Tests"
+fi
+
 # Build check
 if [ -f "package.json" ] && grep -q '"build"' package.json; then
   if ! npm run build 2>/dev/null; then

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "qualia-framework-v2",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
-    "qualia-framework-v2": "./bin/install.js"
+    "qualia-framework-v2": "./bin/cli.js"
   },
   "keywords": [
     "claude-code",
@@ -31,8 +31,7 @@
     "templates/",
     "CLAUDE.md",
     "guide.md",
-    "statusline.sh",
-    "install.sh"
+    "statusline.sh"
   ],
   "engines": {
     "node": ">=18"

package/skills/qualia-build/SKILL.md

@@ -49,7 +49,7 @@ YOUR TASK:
 {paste the single task block from the plan — title, files, action, context refs, done-when}
 
 Execute this task. Read all @file references before writing. Commit when done.
-", subagent_type="general-purpose", description="Task {N}: {title}")
+", subagent_type="qualia-builder", description="Task {N}: {title}")
 ```
 
 **After each task completes:**

package/skills/qualia-plan/SKILL.md

@@ -48,7 +48,7 @@ Phase {N} success criteria: {criteria from STATE.md}
 {If --gaps: Also read @.planning/phase-{N}-verification.md for failures to fix}
 
 Create the plan file at .planning/phase-{N}-plan.md
-", subagent_type="general-purpose", description="Plan phase {N}")
+", subagent_type="qualia-planner", description="Plan phase {N}")
 ```
 
 ### 3. Review Plan

package/skills/qualia-task/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: qualia-task
+description: "Build a single task — more structured than /qualia-quick, lighter than /qualia-build. Spawns a fresh builder agent for one focused task."
+---
+
+# /qualia-task — Single Task Builder
+
+Build one thing properly. Fresh builder context, atomic commit, but no phase plan needed.
+
+## Usage
+`/qualia-task` — describe what to build interactively
+`/qualia-task {description}` — build it directly
+
+## When to Use
+- Too big for a quick fix, too small for a full phase
+- Adding a single feature, component, API route, or integration
+- Refactoring one module
+- Building something specific someone asked for
+
+## Process
+
+### 1. Clarify
+
+If no description provided, ask: **"What do you want to build?"**
+
+Then use AskUserQuestion:
+
+```
+question: "How complex is this task?"
+header: "Scope"
+options:
+  - label: "Small (30min-1hr)"
+    description: "Single file or component, straightforward implementation"
+  - label: "Medium (1-3hrs)"
+    description: "Multiple files, some integration work, needs testing"
+  - label: "Large (3hrs+)"
+    description: "Significant feature, multiple components, consider /qualia-plan instead"
+```
+
+If "Large" — suggest `/qualia-plan` instead. Ask if they want to proceed anyway.
+
+### 2. Task Spec
+
+Write a quick task spec (don't save to file, just confirm with user):
+
+```
+◆ QUALIA ► TASK
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  What:    {what to build}
+  Files:   {files to create/modify}
+  Done:    {what "done" looks like}
+```
+
+Ask: **"Good to build?"**
+
+### 3. Build
+
+Spawn a builder agent with the task:
+
+```
+Agent(subagent_type: "qualia-builder")
+
+Task: {task description}
+Files: {files to create/modify}
+Done when: {completion criteria}
+
+Context: Read PROJECT.md if it exists. Follow all rules (security, frontend, deployment).
+```
+
+The builder runs in fresh context — reads before writing, follows rules, commits atomically.
+
+### 4. Verify
+
+After the builder finishes:
+- Run `npx tsc --noEmit` if TypeScript
+- Quick smoke test if applicable
+- Review what was built
+
+### 5. Report
+
+```
+◆ QUALIA ► TASK COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Task      {description}
+  Files     {files changed}
+  Commit    {commit hash}
+  Status    ✓ Done
+```
+
+Update `.planning/tracking.json` notes field if it exists.

package/skills/qualia-verify/SKILL.md

@@ -41,7 +41,7 @@ Phase plan with success criteria:
 {@.planning/phase-{N}-verification.md}
 
 Verify this phase. Write report to .planning/phase-{N}-verification.md
-", subagent_type="general-purpose", description="Verify phase {N}")
+", subagent_type="qualia-verifier", description="Verify phase {N}")
 ```
 
 ### 3. Present Results

package/install.sh

@@ -1,223 +0,0 @@
-#!/bin/bash
-# Qualia Framework v2 — Installer
-# Installs skills, agents, rules, hooks, templates, status line, and configures settings.json
-
-set -e
-
-FRAMEWORK_DIR="$(cd "$(dirname "$0")" && pwd)"
-CLAUDE_DIR="$HOME/.claude"
-
-echo "◆ Qualia Framework v2"
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-echo "  Installing to $CLAUDE_DIR"
-echo ""
-
-# Skills
-echo "  Installing skills..."
-for skill_dir in "$FRAMEWORK_DIR"/skills/*/; do
-  skill_name=$(basename "$skill_dir")
-  mkdir -p "$CLAUDE_DIR/skills/$skill_name"
-  cp "$skill_dir/SKILL.md" "$CLAUDE_DIR/skills/$skill_name/SKILL.md"
-  echo "    ✓ $skill_name"
-done
-
-# Agents
-echo "  Installing agents..."
-mkdir -p "$CLAUDE_DIR/agents"
-for agent in "$FRAMEWORK_DIR"/agents/*.md; do
-  cp "$agent" "$CLAUDE_DIR/agents/"
-  echo "    ✓ $(basename "$agent")"
-done
-
-# Rules
-echo "  Installing rules..."
-mkdir -p "$CLAUDE_DIR/rules"
-for rule in "$FRAMEWORK_DIR"/rules/*.md; do
-  cp "$rule" "$CLAUDE_DIR/rules/"
-  echo "    ✓ $(basename "$rule")"
-done
-
-# Hook scripts
-echo "  Installing hook scripts..."
-mkdir -p "$CLAUDE_DIR/hooks"
-for hook in "$FRAMEWORK_DIR"/hooks/*.sh; do
-  cp "$hook" "$CLAUDE_DIR/hooks/"
-  chmod +x "$CLAUDE_DIR/hooks/$(basename "$hook")"
-  echo "    ✓ $(basename "$hook")"
-done
-
-# Status line
-echo "  Installing status line..."
-cp "$FRAMEWORK_DIR/statusline.sh" "$CLAUDE_DIR/statusline.sh"
-chmod +x "$CLAUDE_DIR/statusline.sh"
-echo "    ✓ statusline.sh"
-
-# Templates
-echo "  Installing templates..."
-mkdir -p "$CLAUDE_DIR/qualia-templates"
-for tmpl in "$FRAMEWORK_DIR"/templates/*; do
-  cp "$tmpl" "$CLAUDE_DIR/qualia-templates/"
-  echo "    ✓ $(basename "$tmpl")"
-done
-
-# CLAUDE.md (user-level — applies to all projects)
-echo "  Installing CLAUDE.md..."
-cp "$FRAMEWORK_DIR/CLAUDE.md" "$CLAUDE_DIR/CLAUDE.md"
-echo "    ✓ CLAUDE.md"
-
-# Guide
-cp "$FRAMEWORK_DIR/guide.md" "$CLAUDE_DIR/qualia-guide.md"
-echo "    ✓ guide.md"
-
-# Configure settings.json with hooks, status line, and env
-echo ""
-echo "  Configuring settings.json..."
-
-python3 << 'PYEOF'
-import json, os
-
-settings_path = os.path.expanduser("~/.claude/settings.json")
-
-# Load existing settings or start fresh
-if os.path.exists(settings_path):
-    with open(settings_path) as f:
-        settings = json.load(f)
-else:
-    settings = {}
-
-# Env vars
-settings.setdefault("env", {})
-settings["env"].update({
-    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
-    "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "0",
-    "MAX_MCP_OUTPUT_TOKENS": "25000",
-    "CLAUDE_CODE_NO_FLICKER": "1"
-})
-
-# Status line — teal branded, 2-line
-settings["statusLine"] = {
-    "type": "command",
-    "command": "~/.claude/statusline.sh"
-}
-
-# Spinner verbs — Qualia branded
-settings["spinnerVerbs"] = {
-    "mode": "replace",
-    "verbs": [
-        "Qualia-fying", "Solution-ing", "Teal-crafting", "Vibe-forging",
-        "Shipping", "Wiring", "Polishing", "Verifying",
-        "Orchestrating", "Architecting", "Deploying", "Hardening"
-    ]
-}
-
-# Spinner tips — Qualia tips
-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
-hooks_dir = os.path.expanduser("~/.claude/hooks")
-settings["hooks"] = {
-    "PreToolUse": [
-        {
-            "matcher": "Bash",
-            "hooks": [{
-                "type": "command",
-                "if": "Bash(git push*)",
-                "command": f"{hooks_dir}/branch-guard.sh",
-                "timeout": 10,
-                "statusMessage": "◆ Checking branch permissions..."
-            }]
-        },
-        {
-            "matcher": "Edit|Write",
-            "hooks": [{
-                "type": "command",
-                "if": "Edit(*.env*)",
-                "command": f"{hooks_dir}/block-env-edit.sh",
-                "timeout": 5,
-                "statusMessage": "◆ Checking file permissions..."
-            }]
-        }
-    ],
-    "PostToolUse": [
-        {
-            "matcher": "Bash",
-            "hooks": [{
-                "type": "command",
-                "if": "Bash(vercel --prod*)",
-                "command": f"{hooks_dir}/pre-deploy-gate.sh",
-                "timeout": 120,
-                "statusMessage": "◆ Running quality gates..."
-            }]
-        }
-    ],
-    "PreCompact": [
-        {
-            "matcher": "compact",
-            "hooks": [{
-                "type": "command",
-                "command": f"{hooks_dir}/pre-compact.sh",
-                "timeout": 15,
-                "statusMessage": "◆ Saving state..."
-            }]
-        }
-    ],
-    "SubagentStart": [
-        {
-            "matcher": ".*",
-            "hooks": [{
-                "type": "command",
-                "command": "echo '{\"additionalContext\": \"◆ Qualia agent spawned\"}'"
-            }]
-        }
-    ]
-}
-
-# Permissions
-settings.setdefault("permissions", {})
-settings["permissions"].setdefault("allow", [])
-settings["permissions"].setdefault("deny", [
-    "Read(./.env)",
-    "Read(./.env.*)",
-    "Read(./secrets/**)"
-])
-
-# Effort level
-settings["effortLevel"] = "high"
-
-with open(settings_path, "w") as f:
-    json.dump(settings, f, indent=2)
-
-print("    ✓ Hooks registered (branch-guard, env-block, deploy-gate, pre-compact, subagent-label)")
-print("    ✓ Status line configured (2-line teal branded)")
-print("    ✓ Spinner verbs: Qualia branded")
-print("    ✓ Spinner tips: Qualia tips")
-print("    ✓ Environment variables set")
-PYEOF
-
-echo ""
-echo "◆ Installed ✓"
-echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-echo "  Skills:       10"
-echo "  Agents:       3 (planner, builder, verifier)"
-echo "  Hooks:        4 (branch-guard, env-block, deploy-gate, pre-compact)"
-echo "  Rules:        3 (security, frontend, deployment)"
-echo "  Templates:    4"
-echo "  Status line:  ✓"
-echo "  CLAUDE.md:    ✓ (user-level)"
-echo ""
-echo "  Restart Claude Code, then type /qualia in any project."
-echo ""