qualia-framework-v2 2.1.2 → 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:
@@ -19,18 +25,29 @@ Open Claude Code in any project directory:
 ```
 /qualia-new       # Set up a new project
 /qualia           # What should I do next?
+/qualia-idk       # I'm stuck — smart advisor
 /qualia-plan      # Plan the current phase
-/qualia-build     # Build it
-/qualia-verify    # Verify it works
-/qualia-ship      # Deploy
-/qualia-report    # Log your work
+/qualia-build     # Build it (parallel tasks)
+/qualia-verify    # Verify it actually works
+/qualia-design    # One-shot design transformation
+/qualia-debug     # Structured debugging
+/qualia-review    # Production audit
+/qualia-quick     # Skip planning, just do it
+/qualia-task      # Build one thing properly
+/qualia-polish    # Design and UX pass
+/qualia-ship      # Deploy to production
+/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)
 ```
 
 See `guide.md` for the full developer guide.
 
 ## What's Inside
 
-- **11 skills** — slash commands that guide you from setup to handoff
+- **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
@@ -56,6 +73,10 @@ The `settings.json` hooks are real ops engineering, not theoretical:
 - **Env block** — Prevents Claude from touching `.env` files
 - **Pre-compact** — Saves state before context compression
 
+### Enforced State Machine
+
+Every workflow step calls `state.js` — a Node.js state machine that validates preconditions, updates both STATE.md and tracking.json atomically, and tracks gap-closure cycles. You can't build without planning, can't verify without building, and can't loop on gap-closure more than twice before escalating.
+
 ### 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.
@@ -71,9 +92,11 @@ npx qualia-framework-v2 install
      |
      v
 ~/.claude/
-  ├── skills/          11 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

@@ -198,6 +198,20 @@ async function main() {
     warn(`CLAUDE.md — ${e.message}`);
   }
 
+  // ─── Scripts ─────────────────────────────────────────────
+  log(`${WHITE}Scripts${RESET}`);
+  try {
+    const binDest = path.join(CLAUDE_DIR, "bin");
+    if (!fs.existsSync(binDest)) fs.mkdirSync(binDest, { recursive: true });
+    copy(
+      path.join(FRAMEWORK_DIR, "bin", "state.js"),
+      path.join(binDest, "state.js")
+    );
+    ok("state.js (state machine)");
+  } catch (e) {
+    warn(`state.js — ${e.message}`);
+  }
+
   // ─── Guide ─────────────────────────────────────────────
   try {
     copy(
@@ -209,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}`);
@@ -383,6 +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 — 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}`);