ai-devx 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 kmamtora
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,325 @@
+# 🤖 AI-DEVX
+
+> AI Agent templates with Skills, Agents, and Workflows for enhanced coding assistance
+
+[![npm version](https://badge.fury.io/js/ai-devx.svg)](https://www.npmjs.com/package/ai-devx)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+AI-DEVX is a powerful CLI tool that installs AI agent templates into your projects, enabling AI-powered editors like Cursor and Windsurf to provide specialized assistance through agents, skills, and workflows.
+
+## ✨ Features
+
+- **9 Specialist Agents**: Frontend, Backend, Security, Database, DevOps, Testing, Debugging, Planning, and Orchestration
+- **5+ Domain Skills**: React, API Patterns, Testing, Database Design, Docker, and more
+- **9 Workflow Commands**: `/plan`, `/create`, `/debug`, `/test`, `/deploy`, `/security`, and more
+- **Validation Scripts**: Automated code quality, security, and testing checks
+- **Multi-Agent Coordination**: Complex tasks handled by multiple specialists
+- **Zero Learning Curve**: Just describe what you need
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Using npx (recommended)
+npx ai-devx init
+
+# Or install globally
+npm install -g ai-devx
+ai-devx init
+```
+
+This installs the `.agent` folder containing all templates into your project.
+
+### Important: Git Configuration
+
+If you are using AI-powered editors like **Cursor** or **Windsurf**, adding the `.agent/` folder to your `.gitignore` may prevent the IDE from indexing the workflows. This results in slash commands (like `/plan`, `/debug`) not appearing in the chat suggestion dropdown.
+
+**Recommended Solution:** To keep the `.agent/` folder local (not tracked by Git) while maintaining AI functionality:
+
+1. Ensure `.agent/` is **NOT** in your project's `.gitignore`
+2. Instead, add it to your local exclude file: `.git/info/exclude`
+
+```bash
+echo ".agent/" >> .git/info/exclude
+```
+
+## 📦 What's Included
+
+| Component | Count | Description |
+|-----------|-------|-------------|
+| **Agents** | 9 | Specialist AI personas |
+| **Skills** | 5+ | Domain-specific knowledge modules |
+| **Workflows** | 9 | Slash command procedures |
+| **Scripts** | 2 | Validation and automation tools |
+
+### Agents
+
+- **@frontend-specialist** - React, Vue, Angular, TypeScript, UI/UX
+- **@backend-specialist** - Node.js, Python, Go, API Design
+- **@security-auditor** - Vulnerability scanning, OWASP, Security best practices
+- **@database-architect** - Schema design, SQL optimization, migrations
+- **@devops-engineer** - Docker, CI/CD, Cloud deployment
+- **@test-engineer** - Unit, integration, E2E testing
+- **@debugger** - Systematic debugging and root cause analysis
+- **@project-planner** - Task breakdown, estimation, architecture
+- **@orchestrator** - Multi-agent coordination for complex tasks
+
+## 🎯 Usage
+
+### Using Agents
+
+**No need to mention agents explicitly!** The system automatically detects and applies the right specialist(s):
+
+```
+You: "Add JWT authentication"
+AI: 🤖 Applying @security-auditor + @backend-specialist...
+
+You: "Fix the dark mode button"
+AI: 🤖 Using @frontend-specialist...
+
+You: "Login returns 500 error"
+AI: 🤖 Using @debugger for systematic analysis...
+```
+
+**How it works:**
+- Analyzes your request silently
+- Detects domain(s) automatically (frontend, backend, security, etc.)
+- Selects the best specialist(s)
+- Informs you which expertise is being applied
+- You get specialist-level responses without needing to know the system architecture
+
+**Benefits:**
+- ✅ Zero learning curve - just describe what you need
+- ✅ Always get expert responses
+- ✅ Transparent - shows which agent is being used
+- ✅ Can still override by mentioning agent explicitly
+
+### Using Workflows
+
+Invoke workflows with slash commands:
+
+| Command | Description |
+|---------|-------------|
+| `/plan` | Create task breakdown and implementation plan |
+| `/create` | Create new features or apps |
+| `/debug` | Systematic debugging |
+| `/test` | Generate and run tests |
+| `/deploy` | Deploy application |
+| `/security` | Security audit and fixes |
+
+Example:
+```
+/plan user authentication system
+/create login form component
+/debug why API returns 500 error
+/test UserService
+/deploy production
+```
+
+### Using Skills
+
+Skills are loaded automatically based on task context. The AI reads skill descriptions and applies relevant knowledge.
+
+**Available Skills:**
+- **react-best-practices** - React hooks, patterns, performance
+- **api-patterns** - REST API design, authentication, best practices
+- **testing-patterns** - Unit, integration, E2E testing strategies
+- **database-design** - Schema design, normalization, optimization
+- **docker-expert** - Containerization, multi-stage builds, deployment
+
+## 🛠️ CLI Tool
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `ai-devx init` | Install `.agent` folder into your project |
+| `ai-devx update` | Update to the latest version |
+| `ai-devx status` | Check installation status |
+
+### Options
+
+```bash
+ai-devx init --force        # Overwrite existing .agent folder
+ai-devx init --path ./myapp # Install in specific directory
+ai-devx init --branch dev   # Use specific branch
+ai-devx init --quiet        # Suppress output (for CI/CD)
+ai-devx init --dry-run      # Preview actions without executing
+ai-devx update --backup     # Create backup before updating
+```
+
+### Validation Scripts
+
+After installation, use the validation scripts:
+
+```bash
+# Quick check (security, lint, types, tests)
+node .agent/scripts/checklist.js
+
+# Security scan
+node .agent/scripts/security_scan.js
+```
+
+## 📁 Project Structure
+
+```
+.agent/
+├── agents/              # Agent definitions
+│   ├── frontend-specialist.md
+│   ├── backend-specialist.md
+│   ├── security-auditor.md
+│   └── ...
+├── skills/              # Skill modules
+│   ├── react-best-practices/
+│   ├── api-patterns/
+│   ├── testing-patterns/
+│   └── ...
+├── workflows/           # Workflow definitions
+│   ├── plan.md
+│   ├── create.md
+│   ├── debug.md
+│   └── ...
+├── scripts/             # Validation scripts
+│   ├── checklist.js
+│   └── security_scan.js
+├── VERSION              # Current version
+└── config.json          # Installation config
+```
+
+## 🔄 How It Works
+
+```
+User Request
+    ↓
+Request Classification
+    ↓
+┌──────────────────┬──────────────────┐
+│ Workflow Command │ Direct Agent     │
+│ (Slash Command)  │ Assignment       │
+└────────┬─────────┴────────┬─────────┘
+         │                  │
+         ↓                  ↓
+    Agent Selection
+    Skills Loading
+         ↓
+    Task Execution
+         ↓
+    Validation Layer
+         ↓
+    Result Delivery
+```
+
+## 🎨 Example Usage
+
+### Building a Feature
+
+```
+User: /plan Build a user dashboard
+
+AI: 🤖 Applying @project-planner...
+
+## Plan: User Dashboard
+
+### Tasks
+| ID | Task | Estimate |
+|----|------|----------|
+| T1 | Design user schema | 2h |
+| T2 | Create user API | 4h |
+| T3 | Build dashboard UI | 8h |
+
+Total: 14 hours
+
+Next steps:
+1. Create database schema
+2. Implement API endpoints
+3. Build React components
+```
+
+### Debugging
+
+```
+User: /debug Login button not working
+
+AI: 🤖 Applying @debugger...
+
+## Issue Analysis
+
+### Root Cause
+Event handler not bound correctly in React component.
+
+### Solution
+```tsx
+// Before
+<button onClick={handleLogin}>Login</button>
+
+// After  
+<button onClick={() => handleLogin()}>Login</button>
+```
+
+### Verification
+✅ Button now triggers login function
+```
+
+### Security Audit
+
+```
+User: /security
+
+AI: 🤖 Applying @security-auditor...
+
+## Security Scan Results
+
+🔴 Critical: 1
+🟠 High: 0
+🟡 Medium: 2
+
+### Critical Issue
+Hardcoded API key in src/config.ts:15
+
+Fix: Move to environment variables
+```
+
+## 🛡️ Security
+
+AI-DEVX follows security best practices:
+
+- No sensitive data in templates
+- Environment variable usage patterns
+- Security scanning built-in
+- OWASP compliance guidelines
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Adding New Agents
+
+1. Create `.agent/agents/my-agent.md`
+2. Follow the frontmatter format
+3. Include role, capabilities, and guidelines
+4. Submit a PR
+
+### Adding New Skills
+
+1. Create `.agent/skills/my-skill/SKILL.md`
+2. Define the skill metadata
+3. Add examples and best practices
+4. Submit a PR
+
+## 📄 License
+
+MIT © [kmamtora](https://github.com/kmamtora)
+
+## 🙏 Acknowledgments
+
+Inspired by [antigravity-kit](https://github.com/vudovn/antigravity-kit) - An amazing AI agent toolkit.
+
+## 📞 Support
+
+- GitHub Issues: [Report a bug](https://github.com/kmamtora/ai-devx/issues)
+- Discussions: [Ask a question](https://github.com/kmamtora/ai-devx/discussions)
+
+---
+
+**Happy Coding!** 🤖✨

package/bin/cli.js

@@ -0,0 +1,65 @@
+#!/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');
+
+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');
+
+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')
+  .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')
+  .action(updateCommand);
+
+program
+  .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.parse();
+
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "ai-devx",
+  "version": "1.0.0",
+  "description": "AI Agent templates with Skills, Agents, and Workflows for enhanced coding assistance",
+  "main": "src/index.js",
+  "bin": {
+    "ai-devx": "./bin/cli.js",
+    "aex": "./bin/cli.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "test:cli": "node bin/cli.js --version",
+    "lint": "eslint src/ bin/",
+    "format": "prettier --write .",
+    "prepublishOnly": "npm test",
+    "local-link": "npm link",
+    "local-unlink": "npm unlink -g ai-devx"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "cli",
+    "templates",
+    "cursor",
+    "windsurf",
+    "coding-assistant",
+    "development-tools",
+    "productivity"
+  ],
+  "author": "kmamtora",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kmamtora/ai-devx.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kmamtora/ai-devx/issues"
+  },
+  "homepage": "https://github.com/kmamtora/ai-devx#readme",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "commander": "^11.1.0",
+    "chalk": "^4.1.2",
+    "fs-extra": "^11.2.0",
+    "ora": "^5.4.1",
+    "inquirer": "^8.2.6",
+    "axios": "^1.6.2",
+    "adm-zip": "^0.5.10"
+  },
+  "devDependencies": {
+    "eslint": "^8.56.0",
+    "prettier": "^3.1.1"
+  }
+}

package/src/commands/init.js

@@ -0,0 +1,86 @@
+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();
+  
+  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.blank();
+      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.step(`Install templates to: ${agentPath}`);
+      if (isInstalled) logger.step('Overwrite existing installation');
+      return;
+    }
+    
+    // Determine source path
+    const sourcePath = path.join(__dirname, '../../templates/.agent');
+    
+    // Copy templates
+    if (spinner) spinner.text = 'Copying template files...';
+    await fileUtils.copyDir(sourcePath, agentPath, { force });
+    
+    // Write version file
+    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');
+    await fileUtils.writeJson(configFile, {
+      version: '1.0.0',
+      installedAt: new Date().toISOString(),
+      source: source
+    });
+    
+    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.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.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.blank();
+      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');
+    }
+    
+  } catch (error) {
+    if (spinner) spinner.fail('Installation failed');
+    logger.error(error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = initCommand;

package/src/commands/status.js

@@ -0,0 +1,60 @@
+const path = require('path');
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const fileUtils = require('../utils/fileSystem');
+const config = require('../config');
+
+async function statusCommand(options) {
+  const { path: targetPath } = options;
+  const absolutePath = path.resolve(targetPath);
+  const agentPath = path.join(absolutePath, config.AGENT_FOLDER);
+  
+  logger.blank();
+  logger.info('AI-DEVX Status');
+  logger.blank();
+  
+  const isInstalled = await fileUtils.isInstalled(absolutePath);
+  
+  if (!isInstalled) {
+    logger.error('Not installed');
+    logger.info(`Directory: ${absolutePath}`);
+    logger.blank();
+    logger.info('Run "ai-devx init" to install');
+    return;
+  }
+  
+  // Get version
+  const version = await fileUtils.getVersion(agentPath);
+  const configData = await fileUtils.readJson(path.join(agentPath, 'config.json'));
+  
+  logger.success('Installed');
+  logger.blank();
+  logger.info(`Directory: ${agentPath}`);
+  logger.info(`Version: ${chalk.green(version || 'unknown')}`);
+  
+  if (configData) {
+    if (configData.installedAt) {
+      logger.info(`Installed: ${new Date(configData.installedAt).toLocaleDateString()}`);
+    }
+    if (configData.updatedAt) {
+      logger.info(`Last updated: ${new Date(configData.updatedAt).toLocaleDateString()}`);
+    }
+  }
+  
+  logger.blank();
+  logger.info('Available Components:');
+  logger.step(`Agents: 9 specialist personas`);
+  logger.step(`Skills: Multiple domain knowledge modules`);
+  logger.step(`Workflows: 9 slash commands`);
+  logger.step(`Scripts: Validation and automation tools`);
+  
+  logger.blank();
+  logger.info('Quick Commands:');
+  config.WORKFLOWS.slice(0, 5).forEach(wf => {
+    logger.step(`${chalk.cyan(wf.command)} - ${wf.description}`);
+  });
+  
+  logger.blank();
+}
+
+module.exports = statusCommand;

package/src/commands/update.js

@@ -0,0 +1,77 @@
+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 updateCommand(options) {
+  const { force, backup, quiet } = options;
+  
+  const spinner = quiet ? null : ora('Checking for updates...').start();
+  
+  try {
+    const cwd = process.cwd();
+    const isInstalled = await fileUtils.isInstalled(cwd);
+    
+    if (!isInstalled) {
+      if (spinner) spinner.stop();
+      logger.error('AI-DEVX is not installed in this directory.');
+      logger.info('Run "ai-devx init" first.');
+      return;
+    }
+    
+    const agentPath = path.join(cwd, config.AGENT_FOLDER);
+    const currentVersion = await fileUtils.getVersion(agentPath);
+    const latestVersion = '1.0.0'; // In real implementation, fetch from GitHub
+    
+    if (currentVersion === latestVersion && !force) {
+      if (spinner) spinner.stop();
+      logger.success('AI-DEVX is already up to date!');
+      logger.info(`Version: ${currentVersion}`);
+      return;
+    }
+    
+    if (spinner) spinner.text = 'Updating templates...';
+    
+    // Create backup if requested
+    if (backup) {
+      const backupPath = await fileUtils.backup(cwd);
+      if (backupPath && !quiet) {
+        logger.info(`Backup created: ${backupPath}`);
+      }
+    }
+    
+    // Copy updated templates
+    const sourcePath = path.join(__dirname, '../../templates/.agent');
+    await fileUtils.copyDir(sourcePath, agentPath, { force: true });
+    
+    // Update version file
+    const versionFile = path.join(agentPath, 'VERSION');
+    await fs.writeFile(versionFile, latestVersion);
+    
+    // Update config
+    const configFile = path.join(agentPath, 'config.json');
+    const existingConfig = await fileUtils.readJson(configFile) || {};
+    existingConfig.version = latestVersion;
+    existingConfig.updatedAt = new Date().toISOString();
+    await fileUtils.writeJson(configFile, existingConfig);
+    
+    if (spinner) spinner.succeed('AI-DEVX updated successfully!');
+    
+    if (!quiet) {
+      logger.blank();
+      logger.success(`Updated to version: ${latestVersion}`);
+      if (currentVersion) {
+        logger.info(`Previous version: ${currentVersion}`);
+      }
+    }
+    
+  } catch (error) {
+    if (spinner) spinner.fail('Update failed');
+    logger.error(error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = updateCommand;