qualia-framework-v2 2.3.0 → 2.4.0

package/README.md

@@ -12,6 +12,12 @@ npx qualia-framework-v2 install
 
 Enter your team code when prompted. Get your code from Fawzi.
 
+**Other commands:**
+```bash
+npx qualia-framework-v2 version    # Check installed version + updates
+npx qualia-framework-v2 update     # Update to latest (remembers your code)
+```
+
 ## Usage
 
 Open Claude Code in any project directory:
@@ -33,6 +39,7 @@ Open Claude Code in any project directory:
 /qualia-handoff   # Deliver to client
 /qualia-pause     # Save session, continue later
 /qualia-resume    # Pick up where you left off
+/qualia-learn     # Save a pattern, fix, or client pref
 /qualia-report    # Log your work (mandatory)
 ```
 
@@ -40,7 +47,7 @@ See `guide.md` for the full developer guide.
 
 ## What's Inside
 
-- **17 skills** — slash commands from setup to handoff, plus debugging, design, review, and session management
+- **18 skills** — slash commands from setup to handoff, plus debugging, design, review, knowledge, and session management
 - **3 agents** — planner, builder, verifier (each in fresh context)
 - **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
@@ -85,10 +92,11 @@ npx qualia-framework-v2 install
      |
      v
 ~/.claude/
-  ├── skills/          17 slash commands
+  ├── skills/          18 slash commands
   ├── agents/          planner.md, builder.md, verifier.md
   ├── hooks/           7 shell scripts (branch, env, migration, deploy, push, compact, session)
   ├── bin/             state.js (state machine with precondition enforcement)
+  ├── knowledge/       learned-patterns.md, common-fixes.md, client-prefs.md
   ├── 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)

package/bin/cli.js

@@ -1,20 +1,148 @@
 #!/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 TG = "\x1b[38;2;0;170;175m";
 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";
+const BOLD = "\x1b[1m";
 
-const cmd = process.argv[2];
+const CLAUDE_DIR = path.join(require("os").homedir(), ".claude");
+const PKG = require("../package.json");
+const CONFIG_FILE = path.join(CLAUDE_DIR, ".qualia-config.json");
+
+function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function writeConfig(cfg) {
+  if (!fs.existsSync(CLAUDE_DIR)) fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2) + "\n");
+}
+
+function banner() {
+  console.log("");
+  console.log(`  ${TEAL}${BOLD}◆${RESET} ${WHITE}${BOLD}Qualia Framework${RESET} ${DIM}v${PKG.version}${RESET}`);
+  console.log(`  ${DIM}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}`);
+}
 
-if (cmd === "install") {
+// ─── Commands ────────────────────────────────────────────
+
+function cmdInstall() {
   require("./install.js");
-} else {
+}
+
+function cmdVersion() {
+  banner();
+  const cfg = readConfig();
+
+  console.log(`  ${DIM}Installed:${RESET}  ${WHITE}${PKG.version}${RESET}`);
+  if (cfg.installed_by) {
+    console.log(`  ${DIM}User:${RESET}       ${WHITE}${cfg.installed_by}${RESET} ${DIM}(${cfg.role})${RESET}`);
+  }
+  if (cfg.installed_at) {
+    console.log(`  ${DIM}Date:${RESET}       ${WHITE}${cfg.installed_at}${RESET}`);
+  }
+
+  // Check for updates
+  try {
+    const latest = execSync("npm view qualia-framework-v2 version 2>/dev/null", {
+      encoding: "utf8",
+      timeout: 5000,
+    }).trim();
+    const semverGt = (a, b) => {
+      const pa = a.split(".").map(Number), pb = b.split(".").map(Number);
+      for (let i = 0; i < 3; i++) { if (pa[i] > pb[i]) return true; if (pa[i] < pb[i]) return false; }
+      return false;
+    };
+    if (latest && semverGt(latest, PKG.version)) {
+      console.log("");
+      console.log(`  ${YELLOW}Update available:${RESET} ${WHITE}${latest}${RESET}`);
+      console.log(`  ${DIM}Run:${RESET} npx qualia-framework-v2 update`);
+    } else if (latest) {
+      console.log(`  ${DIM}Latest:${RESET}     ${GREEN}${latest} ✓${RESET} ${DIM}(up to date)${RESET}`);
+    }
+  } catch {
+    console.log(`  ${DIM}Latest:${RESET}     ${DIM}(offline — couldn't check)${RESET}`);
+  }
   console.log("");
-  console.log(`${TEAL}  ◆ Qualia Framework v2${RESET}`);
-  console.log(`${DIM}  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}`);
+}
+
+function cmdUpdate() {
+  banner();
+  const cfg = readConfig();
+
+  if (!cfg.code) {
+    console.log(`  ${RED}✗${RESET} No install code saved. Run ${TEAL}install${RESET} first.`);
+    console.log("");
+    process.exit(1);
+  }
+
+  console.log(`  ${DIM}Current:${RESET}  ${WHITE}${PKG.version}${RESET}`);
+  console.log(`  ${DIM}Updating...${RESET}`);
   console.log("");
-  console.log(`  ${WHITE}Usage:${RESET}`);
-  console.log(`    npx qualia-framework-v2 ${TEAL}install${RESET}    Install the framework`);
+
+  try {
+    // Pull latest and reinstall with saved code
+    execSync(
+      `npx qualia-framework-v2@latest install <<< "${cfg.code}"`,
+      { stdio: "inherit", shell: true, timeout: 60000 }
+    );
+  } catch (e) {
+    console.log(`  ${RED}✗${RESET} Update failed. Run manually: npx qualia-framework-v2@latest install`);
+    process.exit(1);
+  }
+}
+
+function cmdHelp() {
+  banner();
   console.log("");
+  console.log(`  ${WHITE}Commands:${RESET}`);
+  console.log(`    npx qualia-framework-v2 ${TEAL}install${RESET}     Install or reinstall the framework`);
+  console.log(`    npx qualia-framework-v2 ${TEAL}update${RESET}      Update to the latest version`);
+  console.log(`    npx qualia-framework-v2 ${TEAL}version${RESET}     Show installed version + check for updates`);
+  console.log("");
+  console.log(`  ${WHITE}After install:${RESET}`);
+  console.log(`    ${TG}/qualia${RESET}          What should I do next?`);
+  console.log(`    ${TG}/qualia-new${RESET}      Set up a new project`);
+  console.log(`    ${TG}/qualia-plan${RESET}     Plan a phase`);
+  console.log(`    ${TG}/qualia-build${RESET}    Build it (parallel tasks)`);
+  console.log(`    ${TG}/qualia-verify${RESET}   Verify it works`);
+  console.log(`    ${TG}/qualia-design${RESET}   One-shot design fix`);
+  console.log(`    ${TG}/qualia-debug${RESET}    Structured debugging`);
+  console.log(`    ${TG}/qualia-review${RESET}   Production audit`);
+  console.log(`    ${TG}/qualia-ship${RESET}     Deploy to production`);
+  console.log(`    ${TG}/qualia-report${RESET}   Log your work`);
+  console.log("");
+}
+
+// ─── Main ────────────────────────────────────────────────
+const cmd = process.argv[2];
+
+switch (cmd) {
+  case "install":
+    cmdInstall();
+    break;
+  case "version":
+  case "-v":
+  case "--version":
+    cmdVersion();
+    break;
+  case "update":
+  case "upgrade":
+    cmdUpdate();
+    break;
+  default:
+    cmdHelp();
 }

package/bin/install.js

@@ -223,6 +223,36 @@ async function main() {
     warn(`guide.md — ${e.message}`);
   }
 
+  // ─── Knowledge directory ─────────────────────────────────
+  log(`${WHITE}Knowledge${RESET}`);
+  const knowledgeDir = path.join(CLAUDE_DIR, "knowledge");
+  if (!fs.existsSync(knowledgeDir)) fs.mkdirSync(knowledgeDir, { recursive: true });
+  const knowledgeFiles = {
+    "learned-patterns.md": "# Learned Patterns\n\nPatterns discovered across projects. Updated by `/qualia-evolve` and manual notes.\n",
+    "common-fixes.md": "# Common Fixes\n\nRecurring issues and their solutions.\n",
+    "client-prefs.md": "# Client Preferences\n\nClient-specific preferences, design choices, and requirements.\n",
+  };
+  for (const [name, defaultContent] of Object.entries(knowledgeFiles)) {
+    const dest = path.join(knowledgeDir, name);
+    if (!fs.existsSync(dest)) {
+      fs.writeFileSync(dest, defaultContent);
+      ok(`${name} (created)`);
+    } else {
+      ok(`${name} (exists)`);
+    }
+  }
+
+  // ─── Save config (for update command) ──────────────────
+  const configFile = path.join(CLAUDE_DIR, ".qualia-config.json");
+  const config = {
+    code,
+    installed_by: member.name,
+    role: member.role,
+    version: require("../package.json").version,
+    installed_at: new Date().toISOString().split("T")[0],
+  };
+  fs.writeFileSync(configFile, JSON.stringify(config, null, 2) + "\n");
+
   // ─── Configure settings.json ───────────────────────────
   console.log("");
   log(`${WHITE}Configuring settings.json...${RESET}`);
@@ -397,7 +427,8 @@ async function main() {
   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(`  Scripts:      ${WHITE}1${RESET} ${DIM}(state.js)${RESET}`);
+  console.log(`  Scripts:      ${WHITE}1${RESET} ${DIM}(state.js — state machine)${RESET}`);
+  console.log(`  Knowledge:    ${WHITE}3${RESET} ${DIM}(patterns, fixes, client prefs)${RESET}`);
   console.log(`  Templates:    ${WHITE}4${RESET}`);
   console.log(`  Status line:  ${GREEN}✓${RESET}`);
   console.log(`  CLAUDE.md:    ${GREEN}✓${RESET} ${DIM}(${member.role})${RESET}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework-v2",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework-v2": "./bin/cli.js"

package/skills/qualia-learn/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: qualia-learn
+description: "Save a learning, pattern, fix, or client preference to the knowledge base. Persists across projects and sessions. Trigger on 'remember this', 'save this pattern', 'learned something', 'note for future', 'client prefers', 'qualia-learn'."
+---
+
+# /qualia-learn — Save Knowledge
+
+Persist learnings across projects and sessions. Saved to `~/.claude/knowledge/`.
+
+## Usage
+
+- `/qualia-learn` — Interactively save a learning
+- `/qualia-learn {description}` — Save directly
+
+## Knowledge Types
+
+### Patterns (`learned-patterns.md`)
+Recurring approaches that work (or don't). Architecture decisions, library choices, prompt patterns.
+
+**Example:** "Supabase RLS policies need to be added in the same migration as the table — adding them later causes a window where data is unprotected."
+
+### Fixes (`common-fixes.md`)
+Problems you've solved before. Error messages and their solutions.
+
+**Example:** "`next/font` crash on Vercel: caused by importing font in a client component that's also used server-side. Fix: move font import to layout.tsx."
+
+### Client Prefs (`client-prefs.md`)
+Client-specific preferences, design choices, requirements.
+
+**Example:** "Acme Corp: prefers dark mode, hates rounded corners, logo must be SVG not PNG, primary color #FF6B00."
+
+## Process
+
+### 1. Classify
+
+If description given, classify automatically. Otherwise ask:
+
+```
+What did you learn?
+1. Pattern — approach that works (or doesn't)
+2. Fix — problem and its solution
+3. Client preference — client-specific requirement
+```
+
+### 2. Format Entry
+
+```markdown
+### {Title} ({date})
+**Project:** {current project name or "general"}
+**Context:** {brief context — what you were building when you learned this}
+
+{The learning — be specific enough that future-you understands without context}
+```
+
+### 3. Append to Knowledge File
+
+```bash
+# Append to the right file
+echo "{formatted entry}" >> ~/.claude/knowledge/{type}.md
+```
+
+- Pattern → `~/.claude/knowledge/learned-patterns.md`
+- Fix → `~/.claude/knowledge/common-fixes.md`
+- Client pref → `~/.claude/knowledge/client-prefs.md`
+
+### 4. Confirm
+
+```
+◆ Saved to {file}
+  "{title}"
+```
+
+## Reading Knowledge
+
+Skills can read knowledge files for context:
+```bash
+cat ~/.claude/knowledge/learned-patterns.md 2>/dev/null
+cat ~/.claude/knowledge/common-fixes.md 2>/dev/null
+cat ~/.claude/knowledge/client-prefs.md 2>/dev/null
+```
+
+The `/qualia-debug` skill should check `common-fixes.md` before investigating.
+The `/qualia-new` skill should check `client-prefs.md` when setting up client projects.
+The `/qualia-plan` skill should check `learned-patterns.md` when planning phases.