qualia-framework 2.1.0

package/README.md

@@ -0,0 +1,50 @@
+# Qualia Framework
+
+Claude Code framework installer for Qualia Solutions team members.
+
+## Install
+
+```bash
+npx github:Qualiasolutions/qualia-framework
+```
+
+Enter your employee code when prompted. Contact Fawzi for your code.
+
+## Update
+
+Pull latest framework changes (skills, hooks, agents) without touching your config:
+
+```bash
+npx github:Qualiasolutions/qualia-framework update
+```
+
+## Verify
+
+Check your installation is healthy:
+
+```bash
+npx github:Qualiasolutions/qualia-framework verify
+```
+
+## What Gets Installed
+
+- `~/.claude/skills/` — 63 Claude Code skills
+- `~/.claude/hooks/` — 13 hook scripts (pre-commit, deploy gate, etc.)
+- `~/.claude/agents/` — 19 agent definitions
+- `~/.claude/rules/` — Security, frontend, deployment, speed rules
+- `~/.claude/qualia-engine/` — Workflow engine
+- `~/.claude/knowledge/` — Shared knowledge base
+- `~/.claude/CLAUDE.md` — Personalized to your role
+- `~/.claude/settings.json` — Merged with your existing config
+
+## Employee Codes
+
+| Code | Person |
+|------|--------|
+| `QS-HASAN-2026` | Hasan |
+| `QS-MOAYAD-2025` | Moayad |
+
+## After Install
+
+1. Fill in your API keys in `~/.claude/.env.claude`
+2. Run `/qualia-start` in Claude Code to activate the framework

package/bin/cli.js

@@ -0,0 +1,519 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { execSync } = require('child_process');
+
+const CLAUDE_DIR = path.join(require('os').homedir(), '.claude');
+const PKG_ROOT = path.resolve(__dirname, '..');
+const FRAMEWORK_DIR = path.join(PKG_ROOT, 'framework');
+const PROFILES_DIR = path.join(PKG_ROOT, 'profiles');
+const TEMPLATES_DIR = path.join(PKG_ROOT, 'templates');
+
+// ── Colors ──
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
+  magenta: '\x1b[35m',
+};
+
+function log(msg) { console.log(msg); }
+function ok(msg) { log(`      ${c.green}\u2713${c.reset} ${msg}`); }
+function warn(msg) { log(`      ${c.yellow}\u26A0${c.reset} ${msg}`); }
+function fail(msg) { log(`      ${c.red}\u2717${c.reset} ${msg}`); }
+function step(n, total, msg) { log(`\n${c.cyan}[${n}/${total}]${c.reset} ${msg}`); }
+
+// ── Helpers ──
+function copyDirSync(src, 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()) {
+      copyDirSync(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function countDir(dir, type) {
+  if (!fs.existsSync(dir)) return 0;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  if (type === 'dirs') return entries.filter(e => e.isDirectory()).length;
+  return entries.filter(e => e.isFile()).length;
+}
+
+function deepMerge(target, source) {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])
+        && target[key] && typeof target[key] === 'object' && !Array.isArray(target[key])) {
+      result[key] = deepMerge(target[key], source[key]);
+    } else if (result[key] === undefined || result[key] === null || result[key] === '') {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}
+
+function loadProfiles() {
+  const profiles = {};
+  for (const file of fs.readdirSync(PROFILES_DIR)) {
+    if (!file.endsWith('.json')) continue;
+    const profile = JSON.parse(fs.readFileSync(path.join(PROFILES_DIR, file), 'utf8'));
+    profiles[profile.code.toUpperCase()] = profile;
+  }
+  return profiles;
+}
+
+function renderCLAUDEmd(profile) {
+  let template = fs.readFileSync(path.join(TEMPLATES_DIR, 'CLAUDE.md.hbs'), 'utf8');
+
+  const isOwner = profile.role === 'OWNER';
+  const isDeveloper = profile.role === 'DEVELOPER';
+  const isArabic = profile.language && profile.language.includes('ar');
+
+  const roleTitle = isOwner ? 'Founder' : (profile.type === 'full-time' ? 'Full-time Developer' : 'Developer');
+
+  const replacements = {
+    '{{fullName}}': profile.fullName || profile.name,
+    '{{name}}': profile.name,
+    '{{role}}': profile.role,
+    '{{roleTitle}}': roleTitle,
+    '{{location}}': profile.location || '',
+  };
+
+  for (const [key, val] of Object.entries(replacements)) {
+    template = template.replace(new RegExp(escapeRegex(key), 'g'), val);
+  }
+
+  // Handle conditionals — inner first, then outer
+  template = processConditional(template, 'canDeploy', profile.permissions?.canDeploy);
+  template = processConditional(template, 'canAccessAllProjects', profile.permissions?.canAccessAllProjects);
+  template = processConditional(template, 'isOwner', isOwner);
+  template = processConditional(template, 'isDeveloper', isDeveloper);
+  template = processConditional(template, 'isArabic', isArabic);
+
+  // Clean up empty lines
+  template = template.replace(/\n{3,}/g, '\n\n');
+
+  return template;
+}
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function processConditional(text, name, value) {
+  const ifRegex = new RegExp(`\\{\\{#if ${name}\\}\\}([\\s\\S]*?)(?:\\{\\{else\\}\\}([\\s\\S]*?))?\\{\\{/if\\}\\}`, 'g');
+  return text.replace(ifRegex, (_, ifBlock, elseBlock) => {
+    return value ? ifBlock : (elseBlock || '');
+  });
+}
+
+function mergeSettings(existingPath, templatePath) {
+  const template = JSON.parse(fs.readFileSync(templatePath, 'utf8'));
+
+  if (!fs.existsSync(existingPath)) return template;
+
+  const existing = JSON.parse(fs.readFileSync(existingPath, 'utf8'));
+
+  // Preserve existing env values (API keys), merge in new ones
+  const merged = { ...template };
+  if (existing.env) {
+    merged.env = { ...template.env };
+    for (const [key, val] of Object.entries(existing.env)) {
+      if (val && val !== '' && !val.startsWith('$')) {
+        merged.env[key] = val;
+      }
+    }
+  }
+
+  // Overwrite hooks, permissions, statusLine from template (framework-managed)
+  merged.hooks = template.hooks;
+  merged.permissions = template.permissions;
+  merged.statusLine = template.statusLine;
+
+  // Preserve user's existing plugins and MCP servers
+  if (existing.enabledPlugins) {
+    merged.enabledPlugins = existing.enabledPlugins;
+  }
+  if (existing.mcpServers) {
+    merged.mcpServers = existing.mcpServers;
+  }
+
+  return merged;
+}
+
+function prompt(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question(question, answer => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+// ── Main ──
+async function main() {
+  const command = process.argv[2];
+
+  if (command === 'update') {
+    await runUpdate();
+  } else if (command === 'verify') {
+    runVerify();
+  } else {
+    await runInstall();
+  }
+}
+
+async function runInstall() {
+  log('');
+  log(`${c.cyan}\u2554${'═'.repeat(54)}\u2557${c.reset}`);
+  log(`${c.cyan}\u2551${c.reset}${c.bold}          QUALIA FRAMEWORK \u2014 INSTALLER                ${c.reset}${c.cyan}\u2551${c.reset}`);
+  log(`${c.cyan}\u255A${'═'.repeat(54)}\u255D${c.reset}`);
+  log('');
+
+  const profiles = loadProfiles();
+  const code = await prompt(`  Enter your employee code: `);
+  const profile = profiles[code.toUpperCase()];
+
+  if (!profile) {
+    log('');
+    fail(`Unknown code "${code}". Contact Fawzi for your employee code.`);
+    log(`${c.dim}  Available format: QS-NAME-YEAR${c.reset}`);
+    process.exit(1);
+  }
+
+  log('');
+  log(`  ${c.green}\u2192${c.reset} Welcome, ${c.bold}${profile.name}${c.reset}! Setting up your Qualia environment...`);
+
+  const TOTAL = 6;
+
+  // Step 1: Backup existing
+  step(1, TOTAL, 'Checking existing ~/.claude/ ...');
+  if (fs.existsSync(CLAUDE_DIR)) {
+    const date = new Date().toISOString().split('T')[0];
+    const backupDir = `${CLAUDE_DIR}.backup-${date}`;
+    if (!fs.existsSync(backupDir)) {
+      // Don't backup the whole thing — just the config files we'll overwrite
+      fs.mkdirSync(backupDir, { recursive: true });
+      for (const f of ['CLAUDE.md', 'settings.json', '.env.claude']) {
+        const src = path.join(CLAUDE_DIR, f);
+        if (fs.existsSync(src)) {
+          fs.copyFileSync(src, path.join(backupDir, f));
+        }
+      }
+      ok(`Config backed up to ${c.dim}~/.claude.backup-${date}/${c.reset}`);
+    } else {
+      ok('Backup already exists for today');
+    }
+  } else {
+    fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+    ok('Created ~/.claude/');
+  }
+
+  // Step 2: Copy framework files
+  step(2, TOTAL, 'Installing framework files ...');
+
+  const dirs = ['skills', 'hooks', 'agents', 'rules', 'qualia-engine', 'scripts', 'knowledge'];
+  for (const dir of dirs) {
+    const src = path.join(FRAMEWORK_DIR, dir);
+    const dest = path.join(CLAUDE_DIR, dir);
+    if (fs.existsSync(src)) {
+      copyDirSync(src, dest);
+    }
+  }
+
+  // Copy standalone files
+  for (const f of ['statusline-command.sh', 'askpass.sh']) {
+    const src = path.join(FRAMEWORK_DIR, f);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, path.join(CLAUDE_DIR, f));
+    }
+  }
+
+  // Make hooks executable
+  const hooksDir = path.join(CLAUDE_DIR, 'hooks');
+  if (fs.existsSync(hooksDir)) {
+    for (const f of fs.readdirSync(hooksDir)) {
+      if (f.endsWith('.sh')) {
+        fs.chmodSync(path.join(hooksDir, f), 0o755);
+      }
+    }
+  }
+  // Make standalone scripts executable
+  for (const f of ['statusline-command.sh', 'askpass.sh']) {
+    const p = path.join(CLAUDE_DIR, f);
+    if (fs.existsSync(p)) fs.chmodSync(p, 0o755);
+  }
+  // Make qualia-engine bin executable
+  const engineBin = path.join(CLAUDE_DIR, 'qualia-engine', 'bin');
+  if (fs.existsSync(engineBin)) {
+    for (const f of fs.readdirSync(engineBin)) {
+      const p = path.join(engineBin, f);
+      try { fs.chmodSync(p, 0o755); } catch {}
+    }
+  }
+
+  ok(`${countDir(path.join(CLAUDE_DIR, 'skills'), 'dirs')} skills`);
+  ok(`${countDir(hooksDir, 'files')} hooks (chmod +x)`);
+  ok(`${countDir(path.join(CLAUDE_DIR, 'agents'), 'files')} agents`);
+  ok(`${countDir(path.join(CLAUDE_DIR, 'rules'), 'files')} rule files`);
+  ok('qualia-engine');
+  ok('knowledge base');
+
+  // Step 3: Generate CLAUDE.md
+  step(3, TOTAL, 'Generating your CLAUDE.md ...');
+  const claudeMd = renderCLAUDEmd(profile);
+  fs.writeFileSync(path.join(CLAUDE_DIR, 'CLAUDE.md'), claudeMd);
+
+  const roleDesc = profile.role === 'OWNER' ? 'Full authority' :
+    `Feature branches${profile.permissions?.canDeploy ? ', can deploy' : ', no prod deploy'}`;
+  ok(`Identity: ${profile.name} \u2014 ${profile.role === 'OWNER' ? 'Founder' : 'Developer'} at Qualia Solutions`);
+  ok(`Role: ${profile.role} (${roleDesc})`);
+
+  // Step 4: Configure settings.json
+  step(4, TOTAL, 'Configuring settings.json ...');
+  const settingsPath = path.join(CLAUDE_DIR, 'settings.json');
+  const templateSettingsPath = path.join(TEMPLATES_DIR, 'settings.json');
+  const mergedSettings = mergeSettings(settingsPath, templateSettingsPath);
+
+  // Fix SUDO_ASKPASS to absolute path
+  mergedSettings.env.SUDO_ASKPASS = path.join(CLAUDE_DIR, 'askpass.sh');
+  mergedSettings.env.CLAUDE_ENV_FILE = path.join(CLAUDE_DIR, '.env.claude');
+
+  fs.writeFileSync(settingsPath, JSON.stringify(mergedSettings, null, 2) + '\n');
+  ok('Hooks wired');
+  ok('Preserved your existing API keys');
+  ok('Settings configured');
+
+  // Step 5: Environment
+  step(5, TOTAL, 'Setting up environment ...');
+  const envPath = path.join(CLAUDE_DIR, '.env.claude');
+  if (fs.existsSync(envPath)) {
+    ok('.env.claude already exists (preserved)');
+  } else {
+    fs.copyFileSync(path.join(TEMPLATES_DIR, 'env.claude.template'), envPath);
+    fs.chmodSync(envPath, 0o600);
+    warn(`Fill in your API keys: ${c.dim}~/.claude/.env.claude${c.reset}`);
+  }
+
+  // Create required directories
+  for (const d of ['projects', 'session-env', 'backups']) {
+    fs.mkdirSync(path.join(CLAUDE_DIR, d), { recursive: true });
+  }
+
+  // Step 6: Verify
+  step(6, TOTAL, 'Verifying installation ...');
+
+  let hooksOk = 0;
+  const hooksTotal = fs.readdirSync(hooksDir).filter(f => f.endsWith('.sh')).length;
+  for (const f of fs.readdirSync(hooksDir)) {
+    if (!f.endsWith('.sh')) continue;
+    try {
+      const stat = fs.statSync(path.join(hooksDir, f));
+      if (stat.mode & 0o111) hooksOk++;
+    } catch {}
+  }
+  if (hooksOk === hooksTotal) {
+    ok(`${hooksOk}/${hooksTotal} hooks executable`);
+  } else {
+    warn(`${hooksOk}/${hooksTotal} hooks executable`);
+  }
+
+  try {
+    JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    ok('settings.json valid JSON');
+  } catch {
+    fail('settings.json invalid JSON!');
+  }
+
+  if (fs.existsSync(path.join(CLAUDE_DIR, 'CLAUDE.md'))) {
+    ok('CLAUDE.md generated');
+  } else {
+    fail('CLAUDE.md missing!');
+  }
+
+  // Done
+  log('');
+  log(`${c.green}\u2554${'═'.repeat(54)}\u2557${c.reset}`);
+  log(`${c.green}\u2551${c.reset}${c.bold}  \u2713 INSTALLED \u2014 Run /qualia-start in Claude Code     ${c.reset}${c.green}\u2551${c.reset}`);
+  log(`${c.green}\u255A${'═'.repeat(54)}\u255D${c.reset}`);
+  log('');
+  log(`  ${c.dim}Update later: npx github:Qualiasolutions/qualia-framework update${c.reset}`);
+  log('');
+}
+
+async function runUpdate() {
+  log('');
+  log(`${c.cyan}\u25C6 Qualia Framework \u2014 Update${c.reset}`);
+  log('');
+
+  if (!fs.existsSync(CLAUDE_DIR)) {
+    fail('No ~/.claude/ found. Run the installer first (without "update").');
+    process.exit(1);
+  }
+
+  // Authenticate — always require code on update
+  const profiles = loadProfiles();
+  const code = await prompt(`  Enter your employee code: `);
+  const profile = profiles[code.toUpperCase()];
+
+  if (!profile) {
+    log('');
+    fail(`Unknown code "${code}". Contact Fawzi for your employee code.`);
+    process.exit(1);
+  }
+
+  log(`  ${c.green}\u2192${c.reset} Updating for ${c.bold}${profile.name}${c.reset} (${profile.role})`);
+  log('');
+
+  // Count what's changing
+  const frameworkDirs = ['skills', 'hooks', 'agents', 'rules', 'qualia-engine', 'scripts', 'knowledge'];
+  const counts = {};
+  let totalFiles = 0;
+
+  for (const dir of frameworkDirs) {
+    const src = path.join(FRAMEWORK_DIR, dir);
+    if (fs.existsSync(src)) {
+      const count = countFilesRecursive(src);
+      counts[dir] = count;
+      totalFiles += count;
+    }
+  }
+
+  // Show what will be updated
+  log(`  ${c.bold}Components to update:${c.reset}`);
+  for (const [dir, count] of Object.entries(counts)) {
+    log(`    ${c.dim}\u2022${c.reset} ${dir} (${count} files)`);
+  }
+  log(`    ${c.bold}Total: ${totalFiles} files${c.reset}`);
+  log('');
+
+  // Update framework files
+  let updated = 0;
+  for (const dir of frameworkDirs) {
+    const src = path.join(FRAMEWORK_DIR, dir);
+    const dest = path.join(CLAUDE_DIR, dir);
+    if (fs.existsSync(src)) {
+      copyDirSync(src, dest);
+      updated++;
+      ok(`${dir} (${counts[dir]} files)`);
+    }
+  }
+
+  // Copy standalone files
+  for (const f of ['statusline-command.sh', 'askpass.sh']) {
+    const src = path.join(FRAMEWORK_DIR, f);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, path.join(CLAUDE_DIR, f));
+      fs.chmodSync(path.join(CLAUDE_DIR, f), 0o755);
+    }
+  }
+
+  // Re-chmod hooks
+  const hooksDir = path.join(CLAUDE_DIR, 'hooks');
+  if (fs.existsSync(hooksDir)) {
+    for (const f of fs.readdirSync(hooksDir)) {
+      if (f.endsWith('.sh')) fs.chmodSync(path.join(hooksDir, f), 0o755);
+    }
+  }
+
+  // Re-chmod engine bin
+  const engineBin = path.join(CLAUDE_DIR, 'qualia-engine', 'bin');
+  if (fs.existsSync(engineBin)) {
+    for (const f of fs.readdirSync(engineBin)) {
+      try { fs.chmodSync(path.join(engineBin, f), 0o755); } catch {}
+    }
+  }
+
+  // Regenerate CLAUDE.md for this person's role
+  const claudeMd = renderCLAUDEmd(profile);
+  fs.writeFileSync(path.join(CLAUDE_DIR, 'CLAUDE.md'), claudeMd);
+  ok(`CLAUDE.md regenerated for ${profile.name} (${profile.role})`);
+
+  // Merge settings.json hooks (add new hooks without overwriting user config)
+  const settingsPath = path.join(CLAUDE_DIR, 'settings.json');
+  const templateSettingsPath = path.join(TEMPLATES_DIR, 'settings.json');
+  if (fs.existsSync(settingsPath) && fs.existsSync(templateSettingsPath)) {
+    const mergedSettings = mergeSettings(settingsPath, templateSettingsPath);
+    mergedSettings.env.SUDO_ASKPASS = path.join(CLAUDE_DIR, 'askpass.sh');
+    mergedSettings.env.CLAUDE_ENV_FILE = path.join(CLAUDE_DIR, '.env.claude');
+    fs.writeFileSync(settingsPath, JSON.stringify(mergedSettings, null, 2) + '\n');
+    ok('settings.json hooks merged');
+  }
+
+  // Clean up removed directories from old versions
+  for (const stale of ['commands', 'config', 'core']) {
+    const p = path.join(CLAUDE_DIR, stale);
+    if (fs.existsSync(p)) {
+      fs.rmSync(p, { recursive: true, force: true });
+      ok(`removed stale ${stale}/`);
+    }
+  }
+
+  log('');
+  log(`${c.green}\u25C6${c.reset} ${c.bold}Updated ${updated} components (${totalFiles} files)${c.reset}`);
+  log(`${c.dim}  .env.claude preserved. CLAUDE.md regenerated for ${profile.name}.${c.reset}`);
+  log('');
+}
+
+function countFilesRecursive(dir) {
+  let count = 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      count += countFilesRecursive(path.join(dir, entry.name));
+    } else {
+      count++;
+    }
+  }
+  return count;
+}
+
+function runVerify() {
+  log('');
+  log(`${c.cyan}Qualia Framework \u2014 Verify${c.reset}`);
+  log('');
+
+  let pass = 0;
+  let total = 0;
+
+  const checks = [
+    ['CLAUDE.md', () => fs.existsSync(path.join(CLAUDE_DIR, 'CLAUDE.md'))],
+    ['settings.json', () => { try { JSON.parse(fs.readFileSync(path.join(CLAUDE_DIR, 'settings.json'), 'utf8')); return true; } catch { return false; } }],
+    ['hooks/', () => fs.existsSync(path.join(CLAUDE_DIR, 'hooks'))],
+    ['skills/', () => countDir(path.join(CLAUDE_DIR, 'skills'), 'dirs') > 50],
+    ['agents/', () => countDir(path.join(CLAUDE_DIR, 'agents'), 'files') > 15],
+    ['qualia-engine/', () => fs.existsSync(path.join(CLAUDE_DIR, 'qualia-engine', 'bin'))],
+    ['rules/', () => countDir(path.join(CLAUDE_DIR, 'rules'), 'files') >= 4],
+    ['.env.claude', () => fs.existsSync(path.join(CLAUDE_DIR, '.env.claude'))],
+  ];
+
+  for (const [name, check] of checks) {
+    total++;
+    if (check()) { ok(name); pass++; }
+    else { fail(name); }
+  }
+
+  log('');
+  if (pass === total) {
+    log(`${c.green}All ${total} checks passed.${c.reset}`);
+  } else {
+    log(`${c.yellow}${pass}/${total} checks passed.${c.reset}`);
+  }
+  log('');
+}
+
+main().catch(err => {
+  console.error(`${c.red}Error:${c.reset}`, err.message);
+  process.exit(1);
+});

package/framework/agents/architecture-strategist.md

@@ -0,0 +1,53 @@
+---
+name: architecture-strategist
+description: "Use this agent when you need to analyze code changes from an architectural perspective, evaluate system design decisions, or ensure that modifications align with established architectural patterns. This includes reviewing pull requests for architectural compliance, assessing the impact of new features on system structure, or validating that changes maintain proper component boundaries and design principles. <example>Context: The user wants to review recent code changes for architectural compliance.\\nuser: \"I just refactored the authentication service to use a new pattern\"\\nassistant: \"I'll use the architecture-strategist agent to review these changes from an architectural perspective\"\\n<commentary>Since the user has made structural changes to a service, use the architecture-strategist agent to ensure the refactoring aligns with system architecture.</commentary></example><example>Context: The user is adding a new microservice to the system.\\nuser: \"I've added a new notification service that integrates with our existing services\"\\nassistant: \"Let me analyze this with the architecture-strategist agent to ensure it fits properly within our system architecture\"\\n<commentary>New service additions require architectural review to verify proper boundaries and integration patterns.</commentary></example>"
+model: inherit
+tools: Read, Bash, Grep, Glob
+---
+
+You are a System Architecture Expert specializing in analyzing code changes and system design decisions. Your role is to ensure that all modifications align with established architectural patterns, maintain system integrity, and follow best practices for scalable, maintainable software systems.
+
+Your analysis follows this systematic approach:
+
+1. **Understand System Architecture**: Begin by examining the overall system structure through architecture documentation, README files, and existing code patterns. Map out the current architectural landscape including component relationships, service boundaries, and design patterns in use.
+
+2. **Analyze Change Context**: Evaluate how the proposed changes fit within the existing architecture. Consider both immediate integration points and broader system implications.
+
+3. **Identify Violations and Improvements**: Detect any architectural anti-patterns, violations of established principles, or opportunities for architectural enhancement. Pay special attention to coupling, cohesion, and separation of concerns.
+
+4. **Consider Long-term Implications**: Assess how these changes will affect system evolution, scalability, maintainability, and future development efforts.
+
+When conducting your analysis, you will:
+
+- Read and analyze architecture documentation and README files to understand the intended system design
+- Map component dependencies by examining import statements and module relationships
+- Analyze coupling metrics including import depth and potential circular dependencies
+- Verify compliance with SOLID principles (Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion)
+- Assess microservice boundaries and inter-service communication patterns where applicable
+- Evaluate API contracts and interface stability
+- Check for proper abstraction levels and layering violations
+
+Your evaluation must verify:
+- Changes align with the documented and implicit architecture
+- No new circular dependencies are introduced
+- Component boundaries are properly respected
+- Appropriate abstraction levels are maintained throughout
+- API contracts and interfaces remain stable or are properly versioned
+- Design patterns are consistently applied
+- Architectural decisions are properly documented when significant
+
+Provide your analysis in a structured format that includes:
+1. **Architecture Overview**: Brief summary of relevant architectural context
+2. **Change Assessment**: How the changes fit within the architecture
+3. **Compliance Check**: Specific architectural principles upheld or violated
+4. **Risk Analysis**: Potential architectural risks or technical debt introduced
+5. **Recommendations**: Specific suggestions for architectural improvements or corrections
+
+Be proactive in identifying architectural smells such as:
+- Inappropriate intimacy between components
+- Leaky abstractions
+- Violation of dependency rules
+- Inconsistent architectural patterns
+- Missing or inadequate architectural boundaries
+
+When you identify issues, provide concrete, actionable recommendations that maintain architectural integrity while being practical for implementation. Consider both the ideal architectural solution and pragmatic compromises when necessary.