ai-devx 1.0.3 → 1.0.5

package/bin/cli.js

@@ -1,61 +1,102 @@
 #!/usr/bin/env node
 
-const { program } = require('commander');
-const chalk = require('chalk');
-const pkg = require('../package.json');
-const initCommand = require('../src/commands/init');
-const updateCommand = require('../src/commands/update');
-const statusCommand = require('../src/commands/status');
+const { program } = require("commander");
+const chalk = require("chalk");
+const pkg = require("../package.json");
+const initCommand = require("../src/commands/init");
+const updateCommand = require("../src/commands/update");
+const statusCommand = require("../src/commands/status");
+const shellCommand = require("../src/commands/shell");
 
-console.log(chalk.cyan.bold(`
+console.log(
+  chalk.cyan.bold(`
 ╔════════════════════════════════════╗
 ║     🤖 AI-DEVX ${pkg.version.padEnd(8)}            ║
 ║  AI Agent Templates & Workflows    ║
 ╚════════════════════════════════════╝
-`));
+`),
+);
 
 program
-  .name('ai-devx')
-  .description('AI Agent templates with Skills, Agents, and Workflows')
-  .version(pkg.version, '-v, --version', 'Display version number');
+  .name("ai-devx")
+  .description("AI Agent templates with Skills, Agents, and Workflows")
+  .version(pkg.version, "-v, --version", "Display version number");
 
 program
-  .command('init')
-  .description('Install .agent folder into your project')
-  .option('-f, --force', 'Overwrite existing .agent folder')
-  .option('-p, --path <path>', 'Install in specific directory', process.cwd())
-  .option('-b, --branch <branch>', 'Use specific branch from repository', 'main')
-  .option('-q, --quiet', 'Suppress output (for CI/CD)')
-  .option('--dry-run', 'Preview actions without executing')
-  .option('-s, --source <url>', 'Custom template source (GitHub repo)', 'kmamtora/ai-devx')
+  .command("init")
+  .description("Install .agent folder into your project")
+  .option("-f, --force", "Overwrite existing .agent folder")
+  .option("-p, --path <path>", "Install in specific directory", process.cwd())
+  .option(
+    "-b, --branch <branch>",
+    "Use specific branch from repository",
+    "main",
+  )
+  .option("-q, --quiet", "Suppress output (for CI/CD)")
+  .option("--dry-run", "Preview actions without executing")
+  .option(
+    "-s, --source <url>",
+    "Custom template source (GitHub repo)",
+    "kmamtora/ai-devx",
+  )
+  .option(
+    "-a, --assistant <assistants>",
+    "Comma-separated list of assistants (claude,gemini,all)",
+    "all",
+  )
   .action(initCommand);
 
 program
-  .command('update')
-  .description('Update to the latest version of templates')
-  .option('-f, --force', 'Force update even if up-to-date')
-  .option('--backup', 'Create backup before updating')
-  .option('-q, --quiet', 'Suppress output')
+  .command("update")
+  .description("Update to the latest version of templates")
+  .option("-f, --force", "Force update even if up-to-date")
+  .option("--backup", "Create backup before updating")
+  .option("-q, --quiet", "Suppress output")
   .action(updateCommand);
 
 program
-  .command('status')
-  .description('Check installation status and version info')
-  .option('-p, --path <path>', 'Check specific directory', process.cwd())
+  .command("status")
+  .description("Check installation status and version info")
+  .option("-p, --path <path>", "Check specific directory", process.cwd())
   .action(statusCommand);
 
-program.on('--help', () => {
-  console.log('');
-  console.log(chalk.bold('Examples:'));
-  console.log('  $ ai-devx init                          # Install in current directory');
-  console.log('  $ ai-devx init --path ./my-project      # Install in specific directory');
-  console.log('  $ ai-devx init --force                  # Overwrite existing installation');
-  console.log('  $ ai-devx update                        # Update templates');
-  console.log('  $ ai-devx status                        # Check installation status');
-  console.log('');
-  console.log(chalk.bold('Quick Start:'));
-  console.log('  $ npx ai-devx init');
-  console.log('');
+program
+  .command("shell [path]")
+  .description(
+    "Start interactive shell to browse skills, agents, and workflows",
+  )
+  .action(shellCommand);
+
+program.on("--help", () => {
+  console.log("");
+  console.log(chalk.bold("Examples:"));
+  console.log(
+    "  $ ai-devx init                          # Install in current directory",
+  );
+  console.log(
+    "  $ ai-devx init --path ./my-project      # Install in specific directory",
+  );
+  console.log(
+    "  $ ai-devx init --force                  # Overwrite existing installation",
+  );
+  console.log(
+    "  $ ai-devx init --assistant claude       # Install with only Claude rules",
+  );
+  console.log(
+    "  $ ai-devx init --assistant claude,gemini # Install with both assistants",
+  );
+  console.log(
+    "  $ ai-devx shell                         # Start interactive shell",
+  );
+  console.log("  $ ai-devx update                        # Update templates");
+  console.log(
+    "  $ ai-devx status                        # Check installation status",
+  );
+  console.log("");
+  console.log(chalk.bold("Quick Start:"));
+  console.log("  $ npx ai-devx init");
+  console.log("  $ npx ai-devx shell");
+  console.log("");
 });
 
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-devx",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "AI Agent templates with Skills, Agents, and Workflows for enhanced coding assistance",
   "main": "src/index.js",
   "bin": {

package/src/commands/init.js

@@ -1,83 +1,119 @@
-const path = require('path');
-const fs = require('fs-extra');
-const ora = require('ora');
-const logger = require('../utils/logger');
-const fileUtils = require('../utils/fileSystem');
-const config = require('../config');
+const path = require("path");
+const fs = require("fs-extra");
+const ora = require("ora");
+const logger = require("../utils/logger");
+const fileUtils = require("../utils/fileSystem");
+const config = require("../config");
 
 async function initCommand(options) {
-  const { force, path: targetPath, branch, quiet, dryRun, source } = options;
-  
-  const spinner = quiet ? null : ora('Installing AI-DEVX templates...').start();
-  
+  const {
+    force,
+    path: targetPath,
+    branch,
+    quiet,
+    dryRun,
+    source,
+    assistant,
+  } = options;
+
+  const spinner = quiet ? null : ora("Installing AI-DEVX templates...").start();
+
   try {
     const absolutePath = path.resolve(targetPath);
     const agentPath = path.join(absolutePath, config.AGENT_FOLDER);
-    
+
     // Check if already installed
     const isInstalled = await fileUtils.isInstalled(absolutePath);
-    
+
     if (isInstalled && !force && !dryRun) {
       if (spinner) spinner.stop();
-      logger.warning('AI-DEVX is already installed in this directory.');
-      logger.info('Use --force to overwrite or run "ai-devx update" to update.');
+      logger.warning("AI-DEVX is already installed in this directory.");
+      logger.info(
+        'Use --force to overwrite or run "ai-devx update" to update.',
+      );
       logger.blank();
-      logger.info('To keep .agent/ local without git tracking:');
+      logger.info("To keep .agent/ local without git tracking:");
       logger.step('Add ".agent/" to .git/info/exclude (not .gitignore)');
       return;
     }
-    
+
     if (dryRun) {
       if (spinner) spinner.stop();
-      logger.info('DRY RUN - Actions that would be taken:');
+      logger.info("DRY RUN - Actions that would be taken:");
       logger.step(`Install templates to: ${agentPath}`);
-      if (isInstalled) logger.step('Overwrite existing installation');
+      if (isInstalled) logger.step("Overwrite existing installation");
       return;
     }
-    
+
     // Determine source path
-    const sourcePath = path.join(__dirname, '../../templates/.agent');
-    
+    const sourcePath = path.join(__dirname, "../../templates/.agent");
+
     // Copy templates
-    if (spinner) spinner.text = 'Copying template files...';
+    if (spinner) spinner.text = "Copying template files...";
     await fileUtils.copyDir(sourcePath, agentPath, { force });
-    
+
+    // Handle assistant selection
+    if (spinner) spinner.text = "Configuring assistants...";
+    const selectedAssistants =
+      assistant === "all"
+        ? ["claude", "gemini"]
+        : assistant
+            .toLowerCase()
+            .split(",")
+            .map((a) => a.trim());
+
+    const rulesPath = path.join(agentPath, "rules");
+    const validAssistants = ["claude", "gemini"];
+
+    // Remove rules for unselected assistants
+    for (const ast of validAssistants) {
+      if (!selectedAssistants.includes(ast)) {
+        const ruleFile = path.join(rulesPath, `${ast.toUpperCase()}.md`);
+        try {
+          await fs.remove(ruleFile);
+        } catch (e) {
+          // File might not exist, ignore
+        }
+      }
+    }
+
     // Write version file
-    const versionFile = path.join(agentPath, 'VERSION');
-    await fs.writeFile(versionFile, config.version || '1.0.0');
-    
+    const versionFile = path.join(agentPath, "VERSION");
+    await fs.writeFile(versionFile, config.version || "1.0.0");
+
     // Write config file
-    const configFile = path.join(agentPath, 'config.json');
+    const configFile = path.join(agentPath, "config.json");
     await fileUtils.writeJson(configFile, {
-      version: '1.0.0',
+      version: "1.0.0",
       installedAt: new Date().toISOString(),
-      source: source
+      source: source,
+      assistants: selectedAssistants,
     });
-    
-    if (spinner) spinner.succeed('AI-DEVX templates installed successfully!');
-    
+
+    if (spinner) spinner.succeed("AI-DEVX templates installed successfully!");
+
     if (!quiet) {
       logger.blank();
       logger.success(`Installed in: ${agentPath}`);
       logger.blank();
-      logger.info('What\'s included:');
+      logger.info("What's included:");
       logger.step(`Agents: 9 specialist personas`);
       logger.step(`Skills: Domain-specific knowledge modules`);
       logger.step(`Workflows: Slash commands (/plan, /create, /debug, etc.)`);
       logger.step(`Scripts: Validation and automation tools`);
+      logger.step(`Assistants: ${selectedAssistants.join(", ")}`);
       logger.blank();
-      logger.info('Quick Start:');
-      logger.step('Type /plan to create a task breakdown');
-      logger.step('Type /create to build new features');
-      logger.step('Type /debug for systematic debugging');
+      logger.info("Quick Start:");
+      logger.step("Type /plan to create a task breakdown");
+      logger.step("Type /create to build new features");
+      logger.step("Type /debug for systematic debugging");
       logger.blank();
-      logger.warning('Important: For Cursor/Windsurf compatibility');
+      logger.warning("Important: For Cursor/Windsurf compatibility");
       logger.step('Add ".agent/" to .git/info/exclude (NOT .gitignore)');
-      logger.step('This keeps templates local while allowing AI indexing');
+      logger.step("This keeps templates local while allowing AI indexing");
     }
-    
   } catch (error) {
-    if (spinner) spinner.fail('Installation failed');
+    if (spinner) spinner.fail("Installation failed");
     logger.error(error.message);
     process.exit(1);
   }

package/src/commands/shell.js

@@ -0,0 +1,349 @@
+const path = require("path");
+const fs = require("fs-extra");
+const chalk = require("chalk");
+const readline = require("readline");
+
+class InteractiveCLI {
+  constructor(agentPath) {
+    this.agentPath = agentPath;
+    this.workflows = [];
+    this.skills = [];
+    this.agents = [];
+    this.scripts = [];
+    this.rules = [];
+    this.shared = [];
+    this.workflowsPath = path.join(agentPath, "workflows");
+    this.skillsPath = path.join(agentPath, "skills");
+    this.agentsPath = path.join(agentPath, "agents");
+    this.scriptsPath = path.join(agentPath, "scripts");
+    this.rulesPath = path.join(agentPath, "rules");
+    this.sharedPath = path.join(agentPath, ".shared");
+  }
+
+  async loadResources() {
+    // Load workflows
+    if (await fs.pathExists(this.workflowsPath)) {
+      const files = await fs.readdir(this.workflowsPath);
+      this.workflows = files
+        .filter((f) => f.endsWith(".md"))
+        .map((f) => ({
+          name: `/${path.basename(f, ".md")}`,
+          file: f,
+          type: "workflow",
+        }));
+    }
+
+    // Load skills
+    if (await fs.pathExists(this.skillsPath)) {
+      const entries = await fs.readdir(this.skillsPath, {
+        withFileTypes: true,
+      });
+      this.skills = entries
+        .filter((e) => e.isDirectory())
+        .map((e) => ({
+          name: e.name,
+          path: path.join(this.skillsPath, e.name),
+          type: "skill",
+        }));
+    }
+
+    // Load agents
+    if (await fs.pathExists(this.agentsPath)) {
+      const files = await fs.readdir(this.agentsPath);
+      this.agents = files
+        .filter((f) => f.endsWith(".md"))
+        .map((f) => ({
+          name: `@${path.basename(f, ".md")}`,
+          file: f,
+          type: "agent",
+        }));
+    }
+
+    // Load scripts
+    if (await fs.pathExists(this.scriptsPath)) {
+      const files = await fs.readdir(this.scriptsPath);
+      this.scripts = files
+        .filter((f) => f.endsWith(".py"))
+        .map((f) => ({
+          name: f,
+          file: f,
+          type: "script",
+        }));
+    }
+
+    // Load rules
+    if (await fs.pathExists(this.rulesPath)) {
+      const files = await fs.readdir(this.rulesPath);
+      this.rules = files
+        .filter((f) => f.endsWith(".md"))
+        .map((f) => ({
+          name: path.basename(f, ".md"),
+          file: f,
+          type: "rule",
+        }));
+    }
+
+    // Load shared
+    if (await fs.pathExists(this.sharedPath)) {
+      const entries = await fs.readdir(this.sharedPath, {
+        withFileTypes: true,
+      });
+      this.shared = entries
+        .filter((e) => e.isDirectory())
+        .map((e) => ({
+          name: e.name,
+          path: path.join(this.sharedPath, e.name),
+          type: "shared",
+        }));
+    }
+  }
+
+  showHelp() {
+    console.log(chalk.bold("\n📚 Available Commands:\n"));
+
+    console.log(chalk.yellow.bold("Slash Commands (Workflows):"));
+    this.workflows.forEach((w) => {
+      console.log(`  ${chalk.cyan(w.name)} - Workflow command`);
+    });
+
+    console.log(chalk.yellow.bold("\nSkills:"));
+    this.skills.slice(0, 15).forEach((s) => {
+      console.log(`  ${chalk.green(s.name)} - Domain knowledge module`);
+    });
+    if (this.skills.length > 15) {
+      console.log(`  ${chalk.gray(`... and ${this.skills.length - 15} more`)}`);
+    }
+
+    console.log(chalk.yellow.bold("\nAgents:"));
+    this.agents.slice(0, 10).forEach((a) => {
+      console.log(`  ${chalk.magenta(a.name)} - Specialist agent`);
+    });
+    if (this.agents.length > 10) {
+      console.log(`  ${chalk.gray(`... and ${this.agents.length - 10} more`)}`);
+    }
+
+    console.log(chalk.yellow.bold("\nScripts:"));
+    this.scripts.slice(0, 8).forEach((s) => {
+      console.log(`  ${chalk.blue(s.name)} - Automation script`);
+    });
+    if (this.scripts.length > 8) {
+      console.log(`  ${chalk.gray(`... and ${this.scripts.length - 8} more`)}`);
+    }
+
+    console.log(chalk.yellow.bold("\nRules:"));
+    this.rules.forEach((r) => {
+      console.log(`  ${chalk.red(r.name)} - Assistant rules`);
+    });
+
+    if (this.shared.length > 0) {
+      console.log(chalk.yellow.bold("\nShared Resources:"));
+      this.shared.forEach((s) => {
+        console.log(`  ${chalk.gray(s.name)} - Shared utilities`);
+      });
+    }
+
+    console.log(chalk.yellow.bold("\nOther Commands:"));
+    console.log(`  ${chalk.cyan("/help")} - Show this menu`);
+    console.log(`  ${chalk.cyan("/exit")} - Exit interactive mode`);
+    console.log(`  ${chalk.cyan("clear")} - Clear screen`);
+    console.log();
+  }
+
+  async executeWorkflow(workflowName, args = "") {
+    const workflow = this.workflows.find((w) => w.name === workflowName);
+    if (!workflow) {
+      console.log(chalk.red(`❌ Workflow '${workflowName}' not found`));
+      return;
+    }
+
+    const workflowPath = path.join(this.workflowsPath, workflow.file);
+    try {
+      const content = await fs.readFile(workflowPath, "utf-8");
+      console.log(chalk.bold(`\n📄 Workflow: ${workflowName}\n`));
+
+      // Show first 50 lines or until first separator
+      const lines = content.split("\n");
+      const previewLines = [];
+      for (const line of lines) {
+        if (line.startsWith("---") && previewLines.length > 0) break;
+        previewLines.push(line);
+        if (previewLines.length >= 30) break;
+      }
+
+      console.log(previewLines.join("\n"));
+      console.log(chalk.gray("\n... (truncated)"));
+      console.log(chalk.yellow(`\nFull file: ${workflowPath}\n`));
+    } catch (error) {
+      console.log(chalk.red(`❌ Error reading workflow: ${error.message}`));
+    }
+  }
+
+  async executeSkill(skillName) {
+    const skill = this.skills.find((s) => s.name === skillName);
+    if (!skill) {
+      console.log(chalk.red(`❌ Skill '${skillName}' not found`));
+      return;
+    }
+
+    const skillMdPath = path.join(skill.path, "SKILL.md");
+    try {
+      if (await fs.pathExists(skillMdPath)) {
+        const content = await fs.readFile(skillMdPath, "utf-8");
+        console.log(chalk.bold(`\n📚 Skill: ${skillName}\n`));
+
+        const lines = content.split("\n").slice(0, 40);
+        console.log(lines.join("\n"));
+        console.log(chalk.gray("\n... (truncated)"));
+        console.log(chalk.yellow(`\nFull file: ${skillMdPath}\n`));
+      } else {
+        console.log(chalk.bold(`\n📚 Skill: ${skillName}\n`));
+        console.log(`Path: ${skill.path}`);
+
+        const files = await fs.readdir(skill.path);
+        console.log("\nContents:");
+        files.forEach((f) => console.log(`  - ${f}`));
+        console.log();
+      }
+    } catch (error) {
+      console.log(chalk.red(`❌ Error reading skill: ${error.message}`));
+    }
+  }
+
+  async executeAgent(agentName) {
+    const agent = this.agents.find((a) => a.name === agentName);
+    if (!agent) {
+      console.log(chalk.red(`❌ Agent '${agentName}' not found`));
+      return;
+    }
+
+    const agentPath = path.join(this.agentsPath, agent.file);
+    try {
+      const content = await fs.readFile(agentPath, "utf-8");
+      console.log(chalk.bold(`\n🤖 Agent: ${agentName}\n`));
+
+      const lines = content.split("\n").slice(0, 40);
+      console.log(lines.join("\n"));
+      console.log(chalk.gray("\n... (truncated)"));
+      console.log(chalk.yellow(`\nFull file: ${agentPath}\n`));
+    } catch (error) {
+      console.log(chalk.red(`❌ Error reading agent: ${error.message}`));
+    }
+  }
+
+  async executeRule(ruleName) {
+    const rule = this.rules.find((r) => r.name === ruleName);
+    if (!rule) {
+      console.log(chalk.red(`❌ Rule '${ruleName}' not found`));
+      return;
+    }
+
+    const rulePath = path.join(this.rulesPath, rule.file);
+    try {
+      const content = await fs.readFile(rulePath, "utf-8");
+      console.log(chalk.bold(`\n📜 Rule: ${ruleName}\n`));
+
+      const lines = content.split("\n").slice(0, 40);
+      console.log(lines.join("\n"));
+      console.log(chalk.gray("\n... (truncated)"));
+      console.log(chalk.yellow(`\nFull file: ${rulePath}\n`));
+    } catch (error) {
+      console.log(chalk.red(`❌ Error reading rule: ${error.message}`));
+    }
+  }
+
+  async start() {
+    await this.loadResources();
+
+    console.log(
+      chalk.cyan.bold(`
+╔════════════════════════════════════════════════╗
+║     🤖 AI-DEVX Interactive Shell               ║
+║  Type / to see all commands and resources        ║
+║  Type /help for help or /exit to quit            ║
+╚════════════════════════════════════════════════╝
+`),
+    );
+
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      prompt: chalk.cyan("ai-devx> "),
+    });
+
+    rl.prompt();
+
+    rl.on("line", async (line) => {
+      const input = line.trim();
+
+      if (input === "/exit" || input === "exit" || input === "quit") {
+        console.log(chalk.yellow("👋 Goodbye!"));
+        rl.close();
+        return;
+      }
+
+      if (input === "" || input === "/") {
+        this.showHelp();
+      } else if (input === "/help" || input === "help") {
+        console.log(chalk.bold("\n🎯 Quick Guide:\n"));
+        console.log("Type any of the following:");
+        console.log(
+          `  ${chalk.cyan("/")} - Show all available commands and resources`,
+        );
+        console.log(
+          `  ${chalk.cyan("/<workflow>")} - View workflow details (e.g., /plan)`,
+        );
+        console.log(
+          `  ${chalk.cyan("@<agent>")} - View agent details (e.g., @orchestrator)`,
+        );
+        console.log(
+          `  ${chalk.cyan("<skill-name>")} - View skill details (e.g., clean-code)`,
+        );
+        console.log(
+          `  ${chalk.cyan("<rule-name>")} - View rule details (e.g., CLAUDE)`,
+        );
+        console.log(`  ${chalk.cyan("clear")} - Clear the screen`);
+        console.log(`  ${chalk.cyan("/exit")} - Exit interactive mode\n`);
+      } else if (input === "clear") {
+        console.clear();
+      } else if (input.startsWith("/")) {
+        // Workflow command
+        await this.executeWorkflow(input);
+      } else if (input.startsWith("@")) {
+        // Agent command
+        await this.executeAgent(input);
+      } else if (this.skills.find((s) => s.name === input)) {
+        // Skill command
+        await this.executeSkill(input);
+      } else if (this.rules.find((r) => r.name === input)) {
+        // Rule command
+        await this.executeRule(input);
+      } else {
+        console.log(chalk.yellow(`⚠️ Unknown command: ${input}`));
+        console.log(chalk.gray("Type / to see available commands\n"));
+      }
+
+      rl.prompt();
+    });
+
+    rl.on("close", () => {
+      console.log(chalk.yellow("\n👋 Goodbye!"));
+      process.exit(0);
+    });
+  }
+}
+
+async function shellCommand(targetPath) {
+  const cwd = targetPath || process.cwd();
+  const agentPath = path.join(path.resolve(cwd), ".agent");
+
+  if (!(await fs.pathExists(agentPath))) {
+    console.log(chalk.red(`❌ AI-DEVX not installed in ${cwd}`));
+    console.log(chalk.yellow("Run: npx ai-devx init"));
+    process.exit(1);
+  }
+
+  const cli = new InteractiveCLI(agentPath);
+  await cli.start();
+}
+
+module.exports = shellCommand;

package/templates/.agent/rules/CLAUDE.md

@@ -0,0 +1,273 @@
+---
+trigger: always_on
+---
+
+# CLAUDE.md - Intelligence Core
+
+> This file defines how Claude behaves in this workspace.
+
+---
+
+## CRITICAL: AGENT & SKILL PROTOCOL (START HERE)
+
+> **MANDATORY:** You MUST read the appropriate agent file and its skills BEFORE performing any implementation. This is the highest priority rule.
+
+### 1. Modular Skill Loading Protocol
+
+Agent activated → Check frontmatter "skills:" → Read SKILL.md (INDEX) → Read specific sections.
+
+- **Selective Reading:** DO NOT read ALL files in a skill folder. Read `SKILL.md` first, then only read sections matching the user's request.
+- **Rule Priority:** P0 (CLAUDE.md) > P1 (Agent .md) > P2 (SKILL.md). All rules are binding.
+
+### 2. Enforcement Protocol
+
+1. **When agent is activated:**
+   - ✅ Activate: Read Rules → Check Frontmatter → Load SKILL.md → Apply All.
+2. **Forbidden:** Never skip reading agent rules or skill instructions. "Read → Understand → Apply" is mandatory.
+
+---
+
+## 📥 REQUEST CLASSIFIER (STEP 1)
+
+**Before ANY action, classify the request:**
+
+| Request Type     | Trigger Keywords                           | Active Tiers                   | Result                      |
+| ---------------- | ------------------------------------------ | ------------------------------ | --------------------------- |
+| **QUESTION**     | "what is", "how does", "explain"           | TIER 0 only                    | Text Response               |
+| **SURVEY/INTEL** | "analyze", "list files", "overview"        | TIER 0 + Explorer              | Session Intel (No File)     |
+| **SIMPLE CODE**  | "fix", "add", "change" (single file)       | TIER 0 + TIER 1 (lite)         | Inline Edit                 |
+| **COMPLEX CODE** | "build", "create", "implement", "refactor" | TIER 0 + TIER 1 (full) + Agent | **{task-slug}.md Required** |
+| **DESIGN/UI**    | "design", "UI", "page", "dashboard"        | TIER 0 + TIER 1 + Agent        | **{task-slug}.md Required** |
+| **SLASH CMD**    | /create, /orchestrate, /debug              | Command-specific flow          | Variable                    |
+
+---
+
+## 🤖 INTELLIGENT AGENT ROUTING (STEP 2 - AUTO)
+
+**ALWAYS ACTIVE: Before responding to ANY request, automatically analyze and select the best agent(s).**
+
+> 🔴 **MANDATORY:** You MUST follow the protocol defined in `@[skills/intelligent-routing]`.
+
+### Auto-Selection Protocol
+
+1. **Analyze (Silent)**: Detect domains (Frontend, Backend, Security, etc.) from user request.
+2. **Select Agent(s)**: Choose the most appropriate specialist(s).
+3. **Inform User**: Concisely state which expertise is being applied.
+4. **Apply**: Generate response using the selected agent's persona and rules.
+
+### Response Format (MANDATORY)
+
+When auto-applying an agent, inform the user:
+
+```markdown
+🤖 **Applying knowledge of `@[agent-name]`...**
+
+[Continue with specialized response]
+```
+
+**Rules:**
+
+1. **Silent Analysis**: No verbose meta-commentary ("I am analyzing...").
+2. **Respect Overrides**: If user mentions `@agent`, use it.
+3. **Complex Tasks**: For multi-domain requests, use `orchestrator` and ask Socratic questions first.
+
+### ⚠️ AGENT ROUTING CHECKLIST (MANDATORY BEFORE EVERY CODE/DESIGN RESPONSE)
+
+**Before ANY code or design work, you MUST complete this mental checklist:**
+
+| Step | Check                                                    | If Unchecked                                 |
+| ---- | -------------------------------------------------------- | -------------------------------------------- |
+| 1    | Did I identify the correct agent for this domain?        | → STOP. Analyze request domain first.        |
+| 2    | Did I READ the agent's `.md` file (or recall its rules)? | → STOP. Open `.agent/agents/{agent}.md`      |
+| 3    | Did I announce `🤖 Applying knowledge of @[agent]...`?   | → STOP. Add announcement before response.    |
+| 4    | Did I load required skills from agent's frontmatter?     | → STOP. Check `skills:` field and read them. |
+
+**Failure Conditions:**
+
+- ❌ Writing code without identifying an agent = **PROTOCOL VIOLATION**
+- ❌ Skipping the announcement = **USER CANNOT VERIFY AGENT WAS USED**
+- ❌ Ignoring agent-specific rules (e.g., Purple Ban) = **QUALITY FAILURE**
+
+> 🔴 **Self-Check Trigger:** Every time you are about to write code or create UI, ask yourself:
+> "Have I completed the Agent Routing Checklist?" If NO → Complete it first.
+
+---
+
+## TIER 0: UNIVERSAL RULES (Always Active)
+
+### 🌐 Language Handling
+
+When user's prompt is NOT in English:
+
+1. **Internally translate** for better comprehension
+2. **Respond in user's language** - match their communication
+3. **Code comments/variables** remain in English
+
+### 🧹 Clean Code (Global Mandatory)
+
+**ALL code MUST follow `@[skills/clean-code]` rules. No exceptions.**
+
+- **Code**: Concise, direct, no over-engineering. Self-documenting.
+- **Testing**: Mandatory. Pyramid (Unit > Int > E2E) + AAA Pattern.
+- **Performance**: Measure first. Adhere to 2025 standards (Core Web Vitals).
+- **Infra/Safety**: 5-Phase Deployment. Verify secrets security.
+
+### 📁 File Dependency Awareness
+
+**Before modifying ANY file:**
+
+1. Check `CODEBASE.md` → File Dependencies
+2. Identify dependent files
+3. Update ALL affected files together
+
+### 🗺️ System Map Read
+
+> 🔴 **MANDATORY:** Read `ARCHITECTURE.md` at session start to understand Agents, Skills, and Scripts.
+
+**Path Awareness:**
+
+- Agents: `.agent/` (Project)
+- Skills: `.agent/skills/` (Project)
+- Runtime Scripts: `.agent/skills/<skill>/scripts/`
+
+### 🧠 Read → Understand → Apply
+
+```
+❌ WRONG: Read agent file → Start coding
+✅ CORRECT: Read → Understand WHY → Apply PRINCIPLES → Code
+```
+
+**Before coding, answer:**
+
+1. What is the GOAL of this agent/skill?
+2. What PRINCIPLES must I apply?
+3. How does this DIFFER from generic output?
+
+---
+
+## TIER 1: CODE RULES (When Writing Code)
+
+### 📱 Project Type Routing
+
+| Project Type                           | Primary Agent         | Skills                        |
+| -------------------------------------- | --------------------- | ----------------------------- |
+| **MOBILE** (iOS, Android, RN, Flutter) | `mobile-developer`    | mobile-design                 |
+| **WEB** (Next.js, React web)           | `frontend-specialist` | frontend-design               |
+| **BACKEND** (API, server, DB)          | `backend-specialist`  | api-patterns, database-design |
+
+> 🔴 **Mobile + frontend-specialist = WRONG.** Mobile = mobile-developer ONLY.
+
+### 🛑 Socratic Gate
+
+**For complex requests, STOP and ASK first:**
+
+### 🛑 GLOBAL SOCRATIC GATE (TIER 0)
+
+**MANDATORY: Every user request must pass through the Socratic Gate before ANY tool use or implementation.**
+
+| Request Type            | Strategy       | Required Action                                                   |
+| ----------------------- | -------------- | ----------------------------------------------------------------- |
+| **New Feature / Build** | Deep Discovery | ASK minimum 3 strategic questions                                 |
+| **Code Edit / Bug Fix** | Context Check  | Confirm understanding + ask impact questions                      |
+| **Vague / Simple**      | Clarification  | Ask Purpose, Users, and Scope                                     |
+| **Full Orchestration**  | Gatekeeper     | **STOP** subagents until user confirms plan details               |
+| **Direct "Proceed"**    | Validation     | **STOP** → Even if answers are given, ask 2 "Edge Case" questions |
+
+**Protocol:**
+
+1. **Never Assume:** If even 1% is unclear, ASK.
+2. **Handle Spec-heavy Requests:** When user gives a list (Answers 1, 2, 3...), do NOT skip the gate. Instead, ask about **Trade-offs** or **Edge Cases** (e.g., "LocalStorage confirmed, but should we handle data clearing or versioning?") before starting.
+3. **Wait:** Do NOT invoke subagents or write code until the user clears the Gate.
+4. **Reference:** Full protocol in `@[skills/brainstorming]`.
+
+### 🏁 Final Checklist Protocol
+
+**Trigger:** When the user says "final checks", "run all tests", "verify everything", or similar phrases.
+
+| Task Stage       | Command                                            | Purpose                        |
+| ---------------- | -------------------------------------------------- | ------------------------------ |
+| **Manual Audit** | `python .agent/scripts/checklist.py .`             | Priority-based project audit   |
+| **Pre-Deploy**   | `python .agent/scripts/checklist.py . --url <URL>` | Full Suite + Performance + E2E |
+
+**Priority Execution Order:**
+
+1. **Security** → 2. **Lint** → 3. **Schema** → 4. **Tests** → 5. **UX** → 6. **Seo** → 7. **Lighthouse/E2E**
+
+**Rules:**
+
+- **Completion:** A task is NOT finished until `checklist.py` returns success.
+- **Reporting:** If it fails, fix the **Critical** blockers first (Security/Lint).
+
+**Available Scripts (12 total):**
+
+| Script                     | Skill                 | When to Use         |
+| -------------------------- | --------------------- | ------------------- |
+| `security_scan.py`         | vulnerability-scanner | Always on deploy    |
+| `dependency_analyzer.py`   | vulnerability-scanner | Weekly / Deploy     |
+| `lint_runner.py`           | lint-and-validate     | Every code change   |
+| `test_runner.py`           | testing-patterns      | After logic change  |
+| `schema_validator.py`      | database-design       | After DB change     |
+| `ux_audit.py`              | frontend-design       | After UI change     |
+| `accessibility_checker.py` | frontend-design       | After UI change     |
+| `seo_checker.py`           | seo-fundamentals      | After page change   |
+| `bundle_analyzer.py`       | performance-profiling | Before deploy       |
+| `mobile_audit.py`          | mobile-design         | After mobile change |
+| `lighthouse_audit.py`      | performance-profiling | Before deploy       |
+| `playwright_runner.py`     | webapp-testing        | Before deploy       |
+
+> 🔴 **Agents & Skills can invoke ANY script** via `python .agent/skills/<skill>/scripts/<script>.py`
+
+### 🎭 Claude Mode Mapping
+
+| Mode     | Agent             | Behavior                                     |
+| -------- | ----------------- | -------------------------------------------- |
+| **plan** | `project-planner` | 4-phase methodology. NO CODE before Phase 4. |
+| **ask**  | -                 | Focus on understanding. Ask questions.       |
+| **edit** | `orchestrator`    | Execute. Check `{task-slug}.md` first.       |
+
+**Plan Mode (4-Phase):**
+
+1. ANALYSIS → Research, questions
+2. PLANNING → `{task-slug}.md`, task breakdown
+3. SOLUTIONING → Architecture, design (NO CODE!)
+4. IMPLEMENTATION → Code + tests
+
+> 🔴 **Edit mode:** If multi-file or structural change → Offer to create `{task-slug}.md`. For single-file fixes → Proceed directly.
+
+---
+
+## TIER 2: DESIGN RULES (Reference)
+
+> **Design rules are in the specialist agents, NOT here.**
+
+| Task         | Read                            |
+| ------------ | ------------------------------- |
+| Web UI/UX    | `.agent/frontend-specialist.md` |
+| Mobile UI/UX | `.agent/mobile-developer.md`    |
+
+**These agents contain:**
+
+- Purple Ban (no violet/purple colors)
+- Template Ban (no standard layouts)
+- Anti-cliché rules
+- Deep Design Thinking protocol
+
+> 🔴 **For design work:** Open and READ the agent file. Rules are there.
+
+---
+
+## 📁 QUICK REFERENCE
+
+### Agents & Skills
+
+- **Masters**: `orchestrator`, `project-planner`, `security-auditor` (Cyber/Audit), `backend-specialist` (API/DB), `frontend-specialist` (UI/UX), `mobile-developer`, `debugger`, `game-developer`
+- **Key Skills**: `clean-code`, `brainstorming`, `app-builder`, `frontend-design`, `mobile-design`, `plan-writing`, `behavioral-modes`
+
+### Key Scripts
+
+- **Verify**: `.agent/scripts/verify_all.py`, `.agent/scripts/checklist.py`
+- **Scanners**: `security_scan.py`, `dependency_analyzer.py`
+- **Audits**: `ux_audit.py`, `mobile_audit.py`, `lighthouse_audit.py`, `seo_checker.py`
+- **Test**: `playwright_runner.py`, `test_runner.py`
+
+---