agents-templated 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agents Templated
+
+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,367 @@
+# Technology-Agnostic Development Template
+
+A flexible, enterprise-grade development template that adapts to any modern technology stack while maintaining security-first development patterns, comprehensive testing, and excellent developer experience. Built with AI assistant integration for Cursor, GitHub Copilot, and other AI coding tools.
+
+## Overview
+
+This template provides a proven agent-based development structure that works with any technology stack. It includes comprehensive rules, patterns, and guidelines that help both developers and AI assistants maintain consistent, secure, and high-quality code across different projects.
+
+## Key Features
+
+- **Technology-Agnostic**: Works with React, Vue, Angular, Node.js, Python, Go, Rust, or any modern stack
+- **AI Assistant Ready**: Pre-configured for Cursor, GitHub Copilot, and other AI coding tools
+- **Security-First**: Built-in OWASP Top 10 protection patterns and security guidelines
+- **Comprehensive Testing**: Testing strategy with unit, integration, and E2E coverage targets
+- **Agent-Based Architecture**: Specialized agents for frontend, backend, database, testing, and security
+- **Type-Safe Patterns**: Strong typing and validation patterns across the stack
+- **Accessibility Compliant**: WCAG 2.1 AA standards built into development patterns
+
+## Quick Start
+
+### Installation Options
+
+**Option 1: NPM Package (Recommended for Existing Projects)**
+
+Install globally and use in any project:
+
+```bash
+# Install globally
+npm install -g agents-templated
+
+# Use in any existing project
+cd your-existing-project
+agents-templated init
+```
+
+Or install locally per project:
+
+```bash
+# Install as dev dependency
+npm install --save-dev agents-templated
+
+# Initialize templates
+npx agents-templated init
+```
+
+**Option 2: Clone Template (New Projects)**
+
+```bash
+git clone <this-repo> my-project
+cd my-project
+```
+
+### CLI Usage
+
+```bash
+# Install all components
+agents-templated init --all
+
+# Install specific components
+agents-templated init --docs        # Documentation only
+agents-templated init --rules       # Agent rules only
+agents-templated init --skills      # Skills only
+agents-templated init --github      # GitHub Copilot config
+
+# Force overwrite existing files
+agents-templated init --all --force
+
+# List available components
+agents-templated list
+```
+
+### Choose Your Technology Stack
+
+This template adapts to your preferred technologies:
+
+**Frontend Options:**
+- React/Next.js, Vue/Nuxt, Angular, Svelte/SvelteKit, or traditional SSR
+
+**Backend Options:**
+- Node.js (Express/Fastify), Python (Django/FastAPI), Go, Rust, Java/Spring
+
+**Database Options:**
+- PostgreSQL/MySQL with ORM, MongoDB/NoSQL, or cloud solutions like Supabase
+
+### Configure AI Assistants
+
+The template includes configuration files for multiple AI assistants:
+
+- **Cursor**: Uses `.cursorrules` and `agents/rules/*.mdc` files (auto-loaded)
+- **GitHub Copilot**: Uses `.github/copilot-instructions.md` (auto-loaded)
+- **Other AI Tools**: Reference `AI_INSTRUCTIONS.md` in your prompts
+
+### Initialize Your Project
+
+Set up your chosen technologies:
+
+```bash
+# Example for Node.js + React
+npm init -y
+npm install react next typescript
+
+# Example for Python + Django
+pip install django djangorestframework
+django-admin startproject myproject .
+
+# Example for Go + Gin
+go mod init myproject
+go get github.com/gin-gonic/gin
+```
+
+## Programmatic API
+
+Use agents-templated programmatically in your build scripts:
+
+```javascript
+const agentsTemplated = require('agents-templated');
+
+// Install all components
+await agentsTemplated.install('./my-project', {
+  force: true
+});
+
+// Install specific components
+await agentsTemplated.install('./my-project', {
+  docs: true,
+  rules: true,
+  skills: false,
+  github: true,
+  force: false
+});
+```
+
+## Directory Structure
+
+```
+├── agents/                          # Agent rules and skills
+│   ├── rules/                      # Development rules and patterns
+│   │   ├── core.mdc               # Core architecture guidelines
+│   │   ├── security.mdc           # Security patterns and requirements
+│   │   ├── testing.mdc            # Testing strategy and patterns
+│   │   ├── frontend.mdc           # Frontend development patterns
+│   │   ├── database.mdc           # Database design and patterns
+│   │   └── style.mdc              # Code style and formatting rules
+│   └── skills/                     # Reusable agent skills
+│       ├── web-design-guidelines/  # Web interface guidelines skill
+│       └── find-skills/           # Skill discovery utilities
+├── .github/
+│   └── copilot-instructions.md    # GitHub Copilot configuration
+├── AGENTS.md                       # Agent responsibilities and usage guide
+├── CLAUDE.md                       # Project guidelines and architecture
+├── AI_INSTRUCTIONS.md              # Universal AI assistant instructions
+├── .cursorrules                    # Cursor AI assistant configuration
+├── .aiderignore                    # Aider AI assistant ignore patterns
+├── .editorconfig                   # Editor configuration
+├── .gitignore                      # Git ignore patterns
+└── README.md                       # This file
+```
+
+## Core Configuration Files
+
+### Documentation Files
+
+- **`CLAUDE.md`** - Overall project guidelines, architecture principles, and technology stack selection
+- **`AGENTS.md`** - Agent delegation patterns, responsibilities, and when to use each agent
+- **`AI_INSTRUCTIONS.md`** - Universal instructions for any AI assistant (reference explicitly)
+
+### AI Assistant Configuration
+
+- **`.cursorrules`** - Cursor-specific rules (auto-loaded by Cursor)
+- **`.github/copilot-instructions.md`** - GitHub Copilot instructions (auto-loaded)
+- **`agents/rules/*.mdc`** - Detailed rules with `alwaysApply: true` for auto-loading in Cursor
+
+### Rule Files
+
+- **`agents/rules/core.mdc`** - Core architecture principles and best practices
+- **`agents/rules/security.mdc`** - Security patterns, OWASP Top 10 protection
+- **`agents/rules/testing.mdc`** - Testing strategy, coverage targets, patterns
+- **`agents/rules/frontend.mdc`** - Frontend development patterns and accessibility
+- **`agents/rules/database.mdc`** - Database schema design and query optimization
+- **`agents/rules/style.mdc`** - Code style guidelines and formatting rules
+
+## Agent-Based Development
+
+This template uses specialized agents for different aspects of development:
+
+### FrontendAgent
+Handles UI/UX development, component creation, design system implementation, and accessibility compliance.
+
+### BackendAgent
+Manages API development, business logic, authentication, authorization, rate limiting, and security middleware.
+
+### DatabaseAgent
+Owns database schema design, migrations, query optimization, and data access patterns.
+
+### TestAgent
+Implements comprehensive testing strategy across unit, integration, E2E, accessibility, and security testing.
+
+### SecurityAgent
+Ensures security-first development with input validation, authentication patterns, authorization checks, and OWASP compliance.
+
+### ReviewerAgent
+Performs code reviews focusing on correctness, security, performance, test coverage, and accessibility.
+
+## Core Principles
+
+### Security-First Development
+- Validate all inputs at application boundaries with schema validation
+- Authenticate and authorize every protected endpoint
+- Rate limit public endpoints to prevent abuse
+- Sanitize outputs to prevent injection attacks
+- Never expose sensitive data in error messages or logs
+
+### Testing Strategy
+- **Unit Tests**: 80% coverage for business logic
+- **Integration Tests**: 15% coverage for API endpoints and database operations
+- **E2E Tests**: 5% coverage for critical user journeys
+- **Accessibility Tests**: WCAG 2.1 AA compliance for all UI
+
+### Type Safety
+- Use strong typing systems available in your chosen language
+- Implement runtime validation for all external/user-provided data
+- Validate at boundaries: API endpoints, form submissions, configuration
+- Generate types from schemas when possible (OpenAPI, GraphQL, database schemas)
+
+### Code Quality
+- Maintain consistent patterns throughout the codebase
+- Follow established code style guidelines
+- Ensure proper error handling and logging
+- Keep documentation updated with code changes
+
+## Security Patterns
+
+### Input Validation Example
+
+```typescript
+// TypeScript with Zod
+import { z } from 'zod'
+
+const userSchema = z.object({
+  email: z.string().email().toLowerCase(),
+  password: z.string().min(8)
+})
+```
+
+```python
+# Python with Pydantic
+from pydantic import BaseModel, EmailStr
+
+class User(BaseModel):
+    email: EmailStr
+    password: str
+```
+
+### Rate Limiting Example
+
+```javascript
+// Node.js with express-rate-limit
+const rateLimit = require('express-rate-limit')
+
+const authLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 5, // 5 attempts per window
+  message: 'Too many authentication attempts'
+})
+```
+
+## Testing Strategy
+
+### Coverage Targets
+- **Unit Tests**: 80% coverage for business logic
+- **Integration Tests**: 15% coverage for API endpoints and database operations
+- **E2E Tests**: 5% coverage for critical user journeys
+
+### Testing Tools by Technology
+
+**JavaScript/TypeScript:**
+- Unit/Integration: Jest, Vitest, or framework-specific test runners
+- E2E: Playwright, Cypress, or Selenium
+- Component: Testing Library, Enzyme
+
+**Python:**
+- Unit/Integration: pytest, unittest
+- E2E: Selenium, Playwright
+- API: requests, httpx
+
+**Go:**
+- Unit/Integration: Built-in testing package, testify
+- E2E: Selenium, Playwright
+- HTTP: httptest package
+
+## AI Assistant Integration
+
+### Cursor
+Rules are automatically loaded from:
+- `.cursorrules` file
+- `agents/rules/*.mdc` files with `alwaysApply: true`
+- `AGENTS.md` and `CLAUDE.md` (via workspace rules)
+
+### GitHub Copilot
+Instructions are automatically loaded from:
+- `.github/copilot-instructions.md`
+
+### Other AI Assistants
+Reference `AI_INSTRUCTIONS.md` explicitly in your prompts:
+- "Follow the patterns in `AI_INSTRUCTIONS.md`"
+- "Check `AGENTS.md` for agent delegation"
+- "Apply security patterns from `agents/rules/security.mdc`"
+
+## Usage Examples
+
+### Frontend Development
+```
+"Create a responsive navigation component with accessibility support"
+"Redesign the user profile page following our design system"
+"Implement the login form with proper validation"
+```
+
+### Backend Development
+```
+"Create a secure user registration endpoint with rate limiting"
+"Implement JWT authentication middleware"
+"Add password reset functionality with email verification"
+```
+
+### Database Operations
+```
+"Design a user roles and permissions schema"
+"Create a migration to add audit logging"
+"Optimize the user query to prevent N+1 problems"
+```
+
+## Documentation
+
+### Getting Started
+1. Review `CLAUDE.md` for architecture and technology selection guidance
+2. Check `AGENTS.md` for agent responsibilities and delegation patterns
+3. Reference `agents/rules/*.mdc` files for detailed implementation patterns
+4. Configure your AI assistant using the appropriate configuration file
+
+### Additional Resources
+- **Architecture**: See `CLAUDE.md` for detailed architecture guidelines
+- **Agent Usage**: See `AGENTS.md` for detailed agent responsibilities
+- **Security**: See `agents/rules/security.mdc` for security patterns
+- **Testing**: See `agents/rules/testing.mdc` for testing strategy
+- **Code Style**: See `agents/rules/style.mdc` for formatting rules
+
+## Quality Gates
+
+All code must meet these standards:
+- Pass linting and formatting checks
+- Meet minimum test coverage thresholds (80% unit, 15% integration, 5% E2E)
+- Pass security scans without high-severity issues
+- Pass accessibility tests for user-facing features
+- Follow established patterns and conventions
+
+## Contributing
+
+When contributing to this template:
+1. Maintain technology-agnostic patterns
+2. Update relevant rule files in `agents/rules/`
+3. Keep documentation synchronized with code changes
+4. Follow security and testing patterns
+5. Ensure AI assistant configurations remain compatible
+
+---
+
+**Ready to start building?** Choose your technology stack, adapt the configuration files, and begin development with enterprise-grade patterns from day one.

package/bin/cli.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const inquirer = require('inquirer');
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+const program = new Command();
+
+program
+  .name('agents-templated')
+  .description('Technology-agnostic development template with AI assistant integration')
+  .version('1.0.0');
+
+program
+  .command('init')
+  .description('Initialize agents template in the current directory')
+  .option('-a, --all', 'Install all components')
+  .option('-d, --docs', 'Install documentation files only')
+  .option('-r, --rules', 'Install agent rules only')
+  .option('-s, --skills', 'Install skills only')
+  .option('-g, --github', 'Install GitHub Copilot instructions')
+  .option('-f, --force', 'Overwrite existing files')
+  .action(async (options) => {
+    try {
+      const targetDir = process.cwd();
+      const templateDir = path.join(__dirname, '..', 'templates');
+
+      console.log(chalk.blue.bold('\n🤖 Agents Templated - AI-Powered Development Setup\n'));
+
+      let choices = [];
+      
+      // If no specific options provided, prompt user
+      if (!options.all && !options.docs && !options.rules && !options.skills && !options.github) {
+        const answers = await inquirer.prompt([
+          {
+            type: 'checkbox',
+            name: 'components',
+            message: 'Select components to install:',
+            choices: [
+              { name: 'All components', value: 'all' },
+              { name: 'Documentation files (AGENTS.MD, CLAUDE.md, etc.)', value: 'docs' },
+              { name: 'Agent rules (agents/rules/*.mdc)', value: 'rules' },
+              { name: 'Skills (agents/skills/*)', value: 'skills' },
+              { name: 'GitHub Copilot instructions', value: 'github' }
+            ],
+            default: ['all']
+          },
+          {
+            type: 'confirm',
+            name: 'overwrite',
+            message: 'Overwrite existing files?',
+            default: false,
+            when: (answers) => answers.components.length > 0
+          }
+        ]);
+
+        choices = answers.components;
+        options.force = answers.overwrite;
+      } else {
+        // Use command line options
+        if (options.all) choices.push('all');
+        if (options.docs) choices.push('docs');
+        if (options.rules) choices.push('rules');
+        if (options.skills) choices.push('skills');
+        if (options.github) choices.push('github');
+      }
+
+      const installAll = choices.includes('all');
+
+      // Install documentation files
+      if (installAll || choices.includes('docs')) {
+        console.log(chalk.yellow('📄 Installing documentation files...'));
+        await copyFiles(templateDir, targetDir, [
+          'AGENTS.MD',
+          'CLAUDE.md',
+          'AI_INSTRUCTIONS.md',
+          'README.md'
+        ], options.force);
+      }
+
+      // Install agent rules
+      if (installAll || choices.includes('rules')) {
+        console.log(chalk.yellow('📋 Installing agent rules...'));
+        await fs.ensureDir(path.join(targetDir, 'agents', 'rules'));
+        await copyDirectory(
+          path.join(templateDir, 'agents', 'rules'),
+          path.join(targetDir, 'agents', 'rules'),
+          options.force
+        );
+      }
+
+      // Install skills
+      if (installAll || choices.includes('skills')) {
+        console.log(chalk.yellow('🎯 Installing skills...'));
+        await fs.ensureDir(path.join(targetDir, 'agents', 'skills'));
+        await copyDirectory(
+          path.join(templateDir, 'agents', 'skills'),
+          path.join(targetDir, 'agents', 'skills'),
+          options.force
+        );
+      }
+
+      // Install GitHub Copilot instructions
+      if (installAll || choices.includes('github')) {
+        console.log(chalk.yellow('🐙 Installing GitHub Copilot instructions...'));
+        await fs.ensureDir(path.join(targetDir, '.github'));
+        await copyFiles(templateDir, targetDir, [
+          '.github/copilot-instructions.md'
+        ], options.force);
+      }
+
+      console.log(chalk.green.bold('\n✅ Installation complete!\n'));
+      console.log(chalk.cyan('Next steps:'));
+      console.log(chalk.white('  1. Review CLAUDE.md for project guidelines'));
+      console.log(chalk.white('  2. Review AGENTS.MD for agent patterns'));
+      console.log(chalk.white('  3. Configure your AI assistant (Cursor, Copilot, etc.)'));
+      console.log(chalk.white('  4. Adapt the rules to your technology stack\n'));
+
+    } catch (error) {
+      console.error(chalk.red('❌ Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('list')
+  .description('List available components')
+  .action(() => {
+    console.log(chalk.blue.bold('\n📦 Available Components:\n'));
+    console.log(chalk.yellow('docs') + '    - Documentation files (AGENTS.MD, CLAUDE.md, AI_INSTRUCTIONS.md, README.md)');
+    console.log(chalk.yellow('rules') + '   - Agent rules (core, database, frontend, security, testing, style)');
+    console.log(chalk.yellow('skills') + '  - Agent skills (find-skills, web-design-guidelines)');
+    console.log(chalk.yellow('github') + '  - GitHub Copilot instructions (.github/copilot-instructions.md)');
+    console.log(chalk.yellow('all') + '     - All components\n');
+  });
+
+async function copyFiles(sourceDir, targetDir, files, force = false) {
+  for (const file of files) {
+    const sourcePath = path.join(sourceDir, file);
+    const targetPath = path.join(targetDir, file);
+
+    if (await fs.pathExists(sourcePath)) {
+      if (await fs.pathExists(targetPath) && !force) {
+        console.log(chalk.gray(`  ⏭️  Skipping ${file} (already exists)`));
+        continue;
+      }
+
+      await fs.ensureDir(path.dirname(targetPath));
+      await fs.copy(sourcePath, targetPath, { overwrite: force });
+      console.log(chalk.green(`  ✓ ${file}`));
+    }
+  }
+}
+
+async function copyDirectory(sourceDir, targetDir, force = false) {
+  if (!(await fs.pathExists(sourceDir))) {
+    console.log(chalk.gray(`  ⏭️  Directory not found: ${sourceDir}`));
+    return;
+  }
+
+  const files = await fs.readdir(sourceDir, { withFileTypes: true });
+
+  for (const file of files) {
+    const sourcePath = path.join(sourceDir, file.name);
+    const targetPath = path.join(targetDir, file.name);
+
+    if (file.isDirectory()) {
+      await fs.ensureDir(targetPath);
+      await copyDirectory(sourcePath, targetPath, force);
+    } else {
+      if (await fs.pathExists(targetPath) && !force) {
+        console.log(chalk.gray(`  ⏭️  Skipping ${path.relative(process.cwd(), targetPath)} (already exists)`));
+        continue;
+      }
+
+      await fs.copy(sourcePath, targetPath, { overwrite: force });
+      console.log(chalk.green(`  ✓ ${path.relative(process.cwd(), targetPath)}`));
+    }
+  }
+}
+
+program.parse(process.argv);
+
+// Show help if no command provided
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+}

package/index.js

@@ -0,0 +1,109 @@
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * Programmatic API for agents-templated
+ * Allows integration into other tools and scripts
+ */
+
+/**
+ * Copy template files to a target directory
+ * @param {string} targetDir - Destination directory
+ * @param {Object} options - Installation options
+ * @param {boolean} options.docs - Install documentation files
+ * @param {boolean} options.rules - Install agent rules
+ * @param {boolean} options.skills - Install skills
+ * @param {boolean} options.github - Install GitHub Copilot instructions
+ * @param {boolean} options.force - Overwrite existing files
+ * @returns {Promise<void>}
+ */
+async function install(targetDir, options = {}) {
+  const templateDir = path.join(__dirname, 'templates');
+  const installAll = !options.docs && !options.rules && !options.skills && !options.github;
+
+  const files = [];
+
+  // Documentation files
+  if (installAll || options.docs) {
+    files.push(
+      'AGENTS.MD',
+      'CLAUDE.md',
+      'AI_INSTRUCTIONS.md',
+      'README.md'
+    );
+  }
+
+  // Copy files
+  for (const file of files) {
+    const sourcePath = path.join(templateDir, file);
+    const targetPath = path.join(targetDir, file);
+
+    if (await fs.pathExists(sourcePath)) {
+      if (await fs.pathExists(targetPath) && !options.force) {
+        continue;
+      }
+
+      await fs.ensureDir(path.dirname(targetPath));
+      await fs.copy(sourcePath, targetPath, { overwrite: options.force });
+    }
+  }
+
+  // Agent rules
+  if (installAll || options.rules) {
+    await fs.ensureDir(path.join(targetDir, 'agents', 'rules'));
+    await copyDirectory(
+      path.join(templateDir, 'agents', 'rules'),
+      path.join(targetDir, 'agents', 'rules'),
+      options.force
+    );
+  }
+
+  // Skills
+  if (installAll || options.skills) {
+    await fs.ensureDir(path.join(targetDir, 'agents', 'skills'));
+    await copyDirectory(
+      path.join(templateDir, 'agents', 'skills'),
+      path.join(targetDir, 'agents', 'skills'),
+      options.force
+    );
+  }
+
+  // GitHub Copilot instructions
+  if (installAll || options.github) {
+    await fs.ensureDir(path.join(targetDir, '.github'));
+    const sourcePath = path.join(templateDir, '.github', 'copilot-instructions.md');
+    const targetPath = path.join(targetDir, '.github', 'copilot-instructions.md');
+    
+    if (await fs.pathExists(sourcePath)) {
+      await fs.copy(sourcePath, targetPath, { overwrite: options.force });
+    }
+  }
+}
+
+async function copyDirectory(sourceDir, targetDir, force = false) {
+  if (!(await fs.pathExists(sourceDir))) {
+    return;
+  }
+
+  const files = await fs.readdir(sourceDir, { withFileTypes: true });
+
+  for (const file of files) {
+    const sourcePath = path.join(sourceDir, file.name);
+    const targetPath = path.join(targetDir, file.name);
+
+    if (file.isDirectory()) {
+      await fs.ensureDir(targetPath);
+      await copyDirectory(sourcePath, targetPath, force);
+    } else {
+      if (await fs.pathExists(targetPath) && !force) {
+        continue;
+      }
+
+      await fs.copy(sourcePath, targetPath, { overwrite: force });
+    }
+  }
+}
+
+module.exports = {
+  install
+};