🤖 AI-DEVX

AI Agent templates with Skills, Agents, and Workflows for enhanced coding assistance

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

AI-DEVX supports assistant-specific installations with different folder names:

# Default installation (universal, all assistants)
npx ai-devx init
# Creates: .agent/ folder (includes both Claude and Gemini)

# Claude-specific installation
npx ai-devx init --assistant claude
# Creates: .claude/ folder (includes only Claude rules)

# Gemini-specific installation
npx ai-devx init --assistant gemini
# Creates: .gemini/ folder (includes only Gemini rules)

# Or install globally
npm install -g ai-devx
ai-devx init --assistant claude

Folder Mapping:

• No --assistant flag → .agent/ folder (universal, all assistants)
• --assistant claude → .claude/ folder (Claude-specific)
• --assistant gemini → .gemini/ folder (Gemini-specific)

This allows you to have separate configurations for different AI assistants in the same 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 the agent folder (.agent/, .claude/, or .gemini/) is NOT in your project's .gitignore
2. Instead, add it to your local exclude file: .git/info/exclude

# For .agent/ folder
echo ".agent/" >> .git/info/exclude

# For .claude/ folder
echo ".claude/" >> .git/info/exclude

# For .gemini/ folder
echo ".gemini/" >> .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 init --assistant claude | Install .claude folder (Claude-specific) | | ai-devx init --assistant gemini | Install .gemini folder (Gemini-specific) | | ai-devx shell | Start interactive shell to browse resources | | ai-devx update | Update to the latest version | | ai-devx status | Check installation status |

Options

# Installation options
ai-devx init                              # Install to .agent/ (universal)
ai-devx init --assistant claude           # Install to .claude/ (Claude-specific)
ai-devx init --assistant gemini           # Install to .gemini/ (Gemini-specific)
ai-devx init --force                      # Overwrite existing 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

# Update options
ai-devx update --backup                   # Create backup before updating

Validation Scripts

After installation, use the validation scripts:

# Quick check (security, lint, types, tests)
node .agent/scripts/checklist.js

# Security scan
node .agent/scripts/security_scan.js

📁 Project Structure

AI-DEVX can be installed to different folders depending on your assistant preference:

Universal Installation (.agent/)

.agent/
├── agents/              # Agent definitions
├── skills/              # Skill modules
├── workflows/           # Workflow definitions
├── scripts/             # Validation scripts
├── rules/               # Assistant rules
│   ├── CLAUDE.md
│   └── GEMINI.md
├── VERSION              # Current version
└── config.json          # Installation config

Claude-Specific Installation (.claude/)

.claude/
├── agents/              # Agent definitions
├── skills/              # Skill modules
├── workflows/           # Workflow definitions
├── scripts/             # Validation scripts
├── rules/
│   └── CLAUDE.md        # Only Claude rules
└── config.json

Gemini-Specific Installation (.gemini/)

.gemini/
├── agents/              # Agent definitions
├── skills/              # Skill modules
├── workflows/           # Workflow definitions
├── scripts/             # Validation scripts
├── rules/
│   └── GEMINI.md        # Only Gemini rules
└── config.json

🔄 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)

## 📞 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!** 🤖✨