agents-templated 1.2.0 → 1.2.2

package/bin/cli.js

@@ -26,7 +26,7 @@ const program = new Command();
 program
   .name('agents-templated')
   .description('Technology-agnostic development template with multi-AI agent support')
-  .version('1.2.0');
+  .version('1.2.1');
 
 program
   .command('init')
@@ -102,7 +102,7 @@ program
             message: 'Select components to install:',
             choices: [
               { name: 'All components', value: 'all' },
-              { name: 'Documentation files (AGENTS.MD, CLAUDE.md, etc.)', value: 'docs' },
+              { name: 'Documentation files (agent-docs/)', value: 'docs' },
               { name: 'Agent rules (agents/rules/*.mdc)', value: 'rules' },
               { name: 'Skills (agents/skills/*)', value: 'skills' },
               { name: 'AI Agent instructions (Cursor, Copilot, VSCode, Gemini)', value: 'github' }
@@ -134,12 +134,10 @@ program
       // 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);
+        const sourceDir = path.join(templateDir, 'agent-docs');
+        const targetDir = path.join(targetDir, 'agent-docs');
+        await fs.ensureDir(targetDir);
+        await copyDirectory(sourceDir, targetDir, options.force);
       }
 
       // Install agent rules
@@ -182,10 +180,11 @@ program
 
       console.log(chalk.green.bold('\nInstallation 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'));
+          console.log(chalk.white('  1. Review agent-docs/AI_INSTRUCTIONS.md for AI assistance guide'));
+      console.log(chalk.white('  2. Review agent-docs/ARCHITECTURE.md for project guidelines'));
+      console.log(chalk.white('  3. Review agent-docs/AGENTS.MD for agent patterns'));
+      console.log(chalk.white('  4. Configure your AI assistant (Cursor, Copilot, etc.)'));
+      console.log(chalk.white('  5. Adapt the rules to your technology stack\n'));
 
     } catch (error) {
       console.error(chalk.red('Error:'), error.message);
@@ -284,10 +283,10 @@ program
           name: 'components',
           message: 'Select components to install:',
           choices: [
-            { name: 'Documentation (AGENTS.MD, CLAUDE.md, etc.)', value: 'docs', checked: true },
+            { name: 'Documentation (agent-docs/)', value: 'docs', checked: true },
             { name: 'Agent Rules (security, testing, database, etc.)', value: 'rules', checked: true },
             { name: 'Skills (reusable agent capabilities)', value: 'skills', checked: true },
-            { name: 'GitHub Copilot Configuration', value: 'github', checked: true }
+            { name: 'AI Agent instructions (Cursor, Copilot, VSCode, Gemini)', value: 'github', checked: true }
           ],
           validate: (answer) => {
             if (answer.length === 0) {
@@ -319,12 +318,10 @@ program
       // Install documentation files
       if (options.docs) {
         console.log(chalk.yellow('Installing documentation files...'));
-        await copyFiles(templateDir, targetDir, [
-          'AGENTS.MD',
-          'CLAUDE.md',
-          'AI_INSTRUCTIONS.md',
-          'README.md'
-        ], options.force);
+        const sourceDocsDir = path.join(templateDir, 'agent-docs');
+        const targetDocsDir = path.join(targetDir, 'agent-docs');
+        await fs.ensureDir(targetDocsDir);
+        await copyDirectory(sourceDocsDir, targetDocsDir, options.force);
       }
 
       // Install agent rules
@@ -349,13 +346,20 @@ program
         );
       }
 
-      // Install GitHub Copilot instructions
+      // Install AI Agent instructions (Cursor, Copilot, VSCode, Gemini)
       if (options.github) {
-        console.log(chalk.yellow('Installing GitHub Copilot instructions...'));
+        console.log(chalk.yellow('Installing AI agent instructions...'));
         await fs.ensureDir(path.join(targetDir, '.github'));
         await copyFiles(templateDir, targetDir, [
-          '.github/copilot-instructions.md'
+          '.cursorrules',
+          '.github/copilot-instructions.md',
+          '.vscode-ai-rules.md',
+          '.gemini-instructions.md'
         ], options.force);
+        console.log(chalk.gray('  ✓ Cursor (.cursorrules)'));
+        console.log(chalk.gray('  ✓ GitHub Copilot (.github/copilot-instructions.md)'));
+        console.log(chalk.gray('  ✓ VSCode (.vscode-ai-rules.md)'));
+        console.log(chalk.gray('  ✓ Google Gemini (.gemini-instructions.md)'));
       }
 
       // Step 4: Show recommendations
@@ -367,8 +371,9 @@ program
       if (techStack.database) console.log(chalk.white(`   Database: ${techStack.database}`));
       
       console.log(chalk.cyan('\n📚 Next Steps:\n'));
-      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('   1. Review agent-docs/AI_INSTRUCTIONS.md for AI assistance guide'));
+      console.log(chalk.white('   2. Review agent-docs/ARCHITECTURE.md for project guidelines'));
+      console.log(chalk.white('   3. Review agent-docs/AGENTS.MD for agent patterns'));
       console.log(chalk.white('   3. Customize agents/rules/*.mdc for your tech stack'));
       
       if (techStack.frontend || techStack.backend) {
@@ -418,10 +423,10 @@ program
   .description('List available components and presets')
   .action(() => {
     console.log(chalk.blue.bold('\nAvailable Components:\n'));
-    console.log(chalk.yellow('docs') + '    - Documentation files (AGENTS.MD, CLAUDE.md, AI_INSTRUCTIONS.md, README.md)');
+    console.log(chalk.yellow('docs') + '    - Documentation files (agent-docs/ directory)');
     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('github') + '  - AI Agent instructions (Cursor, Copilot, VSCode, Gemini)');
     console.log(chalk.yellow('all') + '     - All components');
     
     console.log(chalk.blue.bold('\n\nAvailable Presets:\n'));
@@ -447,13 +452,19 @@ program
       let passed = [];
 
       // Check documentation files
-      const docFiles = ['AGENTS.MD', 'CLAUDE.md', 'AI_INSTRUCTIONS.md'];
-      for (const file of docFiles) {
-        if (await fs.pathExists(path.join(targetDir, file))) {
-          passed.push(`✓ ${file} found`);
-        } else {
-          warnings.push(`⚠ ${file} missing - run 'agents-templated init --docs'`);
+      const docFiles = ['AGENTS.MD', 'ARCHITECTURE.md', 'AI_INSTRUCTIONS.md'];
+      const docsDir = path.join(targetDir, 'agent-docs');
+      
+      if (await fs.pathExists(docsDir)) {
+        for (const file of docFiles) {
+          if (await fs.pathExists(path.join(docsDir, file))) {
+            passed.push(`✓ agent-docs/${file} found`);
+          } else {
+            warnings.push(`⚠ agent-docs/${file} missing`);
+          }
         }
+      } else {
+        warnings.push(`⚠ agent-docs directory missing - run 'agents-templated init --docs'`);
       }
 
       // Check agent rules
@@ -644,9 +655,9 @@ program
       // List potential updates
       const updates = [];
       const checkFiles = [
-        { file: 'AGENTS.MD', component: 'docs' },
-        { file: 'CLAUDE.md', component: 'docs' },
-        { file: 'AI_INSTRUCTIONS.md', component: 'docs' },
+        { file: 'agent-docs/AGENTS.MD', component: 'docs' },
+        { file: 'agent-docs/ARCHITECTURE.md', component: 'docs' },
+        { file: 'agent-docs/AI_INSTRUCTIONS.md', component: 'docs' },
         { file: 'agents/rules/security.mdc', component: 'rules' },
         { file: 'agents/rules/testing.mdc', component: 'rules' },
         { file: 'agents/rules/core.mdc', component: 'rules' },

package/index.js

@@ -26,10 +26,10 @@ async function install(targetDir, options = {}) {
   // Documentation files
   if (installAll || options.docs) {
     files.push(
-      'AGENTS.MD',
-      'CLAUDE.md',
-      'AI_INSTRUCTIONS.md',
-      'README.md'
+      'agent-docs/AGENTS.MD',
+      'agent-docs/ARCHITECTURE.md',
+      'agent-docs/AI_INSTRUCTIONS.md',
+      'agent-docs/README.md'
     );
   }
 
@@ -68,15 +68,15 @@ async function install(targetDir, options = {}) {
     );
   }
 
-  // AI Agent instructions (Cursor, Copilot, VSCode, Gemini)
+  // AI Agent instructions (Cursor, Copilot, Claude, Gemini)
   if (installAll || options.github) {
     await fs.ensureDir(path.join(targetDir, '.github'));
     
     // Copy all AI agent config files
     const agentConfigs = [
       '.cursorrules',
-      '.vscode-ai-rules.md',
-      '.gemini-instructions.md'
+      'CLAUDE.md',
+      'GEMINI.md'
     ];
     
     for (const config of agentConfigs) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-templated",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Technology-agnostic development template with multi-AI agent support (Cursor, Copilot, VSCode, Gemini), security-first patterns, and comprehensive testing guidelines",
   "main": "index.js",
   "bin": {

package/templates/.cursorrules

@@ -35,7 +35,7 @@
 - **Performance**: Monitor bundle/binary size, implement lazy loading patterns
 - **Accessibility**: WCAG 2.1 AA compliance for user-facing components
 - **Testing**: All business logic and user flows must have appropriate tests
-- **Documentation**: Keep README, CLAUDE.md, and AGENTS.md updated
+- **Documentation**: Keep README, agent-docs/ARCHITECTURE.md, and agent-docs/AGENTS.md updated
 
 ## Technology Stack Adaptation
 Choose your stack and apply these patterns consistently:
@@ -55,7 +55,7 @@ Choose your stack and apply these patterns consistently:
 - **NoSQL**: MongoDB, DynamoDB with ODM patterns
 - **Cloud**: Supabase, Firebase, managed database services
 
-## Agent Delegation (See AGENTS.md for details)
+## Agent Delegation (See agent-docs/AGENTS.md for details)
 - **UI/Design work** → FrontendAgent
 - **API/Business logic** → BackendAgent  
 - **Database/Schema** → DatabaseAgent

package/templates/.github/copilot-instructions.md

@@ -4,8 +4,9 @@ This project follows enterprise-grade, technology-agnostic development patterns.
 
 ## Quick Start
 
-- **Project Guidelines**: See `CLAUDE.md`
-- **Agent Patterns**: See `AGENTS.md`
+- **AI Guide**: See `agent-docs/AI_INSTRUCTIONS.md` for comprehensive instructions
+- **Architecture**: See `agent-docs/ARCHITECTURE.md` for project guidelines
+- **Agent Patterns**: See `agent-docs/AGENTS.md` for delegation patterns
 - **Detailed Rules**: See `agents/rules/*.mdc` files
 
 ## Always Apply
@@ -21,7 +22,7 @@ This project follows enterprise-grade, technology-agnostic development patterns.
 
 ## Agent Delegation
 
-When implementing features, follow agent patterns from `AGENTS.md`:
+When implementing features, follow agent patterns from `agent-docs/AGENTS.md`:
 - **UI/Design** → FrontendAgent patterns (`agents/rules/frontend.mdc`)
 - **API/Logic** → BackendAgent patterns (`agents/rules/security.mdc`)
 - **Database** → DatabaseAgent patterns (`agents/rules/database.mdc`)
@@ -40,8 +41,9 @@ When implementing features, follow agent patterns from `AGENTS.md`:
 
 ## Reference Files
 
-- `CLAUDE.md` - Architecture and technology stack guidance
-- `AGENTS.md` - Agent responsibilities and delegation
+- `agent-docs/AI_INSTRUCTIONS.md` - Primary AI assistant guide
+- `agent-docs/ARCHITECTURE.md` - Architecture and technology stack guidance
+- `agent-docs/AGENTS.md` - Agent responsibilities and delegation
 - `agents/rules/core.mdc` - Core principles
 - `agents/rules/security.mdc` - Security patterns (CRITICAL)
 - `agents/rules/testing.mdc` - Testing strategy (CRITICAL)

package/templates/CLAUDE.md

@@ -1,261 +1,56 @@
-## Project Guidelines
+# Claude AI Instructions
 
-This is a **technology-agnostic development template** with enterprise-grade patterns for security, testing, and developer experience.
-These guidelines are for both humans and AI assistants working with any technology stack.
+This project uses enterprise-grade, technology-agnostic development patterns for Claude AI assistance.
 
-- High-level **project and architecture** guidelines live here in `CLAUDE.md`.
-- **Agent responsibilities** and MCP integration are documented in `AGENTS.MD`.
-- **Detailed implementation rules** live in `agents/rules/*.mdc` files.
+## Quick Start
 
-Read this file first to understand the architecture, then consult `AGENTS.md` for agent delegation.
+- **AI Guide**: See `agent-docs/AI_INSTRUCTIONS.md` for comprehensive instructions
+- **Architecture**: See `agent-docs/ARCHITECTURE.md` for project guidelines
+- **Agent Patterns**: See `agent-docs/AGENTS.md` for delegation patterns
+- **Detailed Rules**: See `agents/rules/*.mdc` files
 
----
-
-## Technology Stack Selection
-
-This template is designed to work with **any modern technology stack**. Choose the technologies that best fit your project requirements:
-
-### Frontend Framework Options
-
-#### Option A: React Ecosystem
-- ✅ **Best for**: Complex UIs, large teams, extensive ecosystem
-- ✅ **Variants**: Next.js (full-stack), Create React App, Vite + React
-- ✅ **Use when**: Building complex SPAs or full-stack applications
-
-#### Option B: Vue.js Ecosystem  
-- ✅ **Best for**: Progressive adoption, gentle learning curve
-- ✅ **Variants**: Nuxt.js (full-stack), Vue CLI, Vite + Vue
-- ✅ **Use when**: Migrating existing apps or rapid prototyping
-
-#### Option C: Angular
-- ✅ **Best for**: Enterprise applications, TypeScript-first development
-- ✅ **Features**: Built-in TypeScript, comprehensive CLI, enterprise patterns
-- ✅ **Use when**: Building large-scale enterprise applications
-
-#### Option D: Svelte/SvelteKit
-- ✅ **Best for**: Performance-critical applications, smaller bundle sizes
-- ✅ **Features**: Compile-time optimization, minimal runtime overhead
-- ✅ **Use when**: Performance is the primary concern
-
-#### Option E: Traditional Server-Side
-- ✅ **Best for**: SEO-critical sites, progressive enhancement
-- ✅ **Variants**: Django templates, Rails views, PHP templates
-- ✅ **Use when**: Building traditional web applications with SSR
-
-### Backend Framework Options
-
-#### Option A: Node.js
-- ✅ **Frameworks**: Express, Fastify, Koa, Next.js API routes
-- ✅ **Best for**: JavaScript/TypeScript full-stack development
-- ✅ **Use when**: Team has JavaScript expertise, need API + frontend
-
-#### Option B: Python
-- ✅ **Frameworks**: Django, FastAPI, Flask
-- ✅ **Best for**: Data-heavy applications, AI/ML integration, rapid development
-- ✅ **Use when**: Building APIs with complex business logic
-
-#### Option C: Go
-- ✅ **Frameworks**: Gin, Echo, Fiber
-- ✅ **Best for**: High-performance APIs, microservices
-- ✅ **Use when**: Performance and concurrency are critical
-
-#### Option D: Rust
-- ✅ **Frameworks**: Actix-web, Warp, Rocket
-- ✅ **Best for**: System-level performance, memory safety
-- ✅ **Use when**: Building high-performance, secure backends
-
-#### Option E: Java/Kotlin
-- ✅ **Frameworks**: Spring Boot, Ktor, Quarkus
-- ✅ **Best for**: Enterprise applications, existing Java ecosystem
-- ✅ **Use when**: Working in enterprise Java environments
-
-### Database Strategy Options
-
-#### Option A: SQL Databases
-- ✅ **Databases**: PostgreSQL, MySQL, SQLite
-- ✅ **ORMs**: Prisma, TypeORM, Sequelize (JS), SQLAlchemy (Python), GORM (Go)
-- ✅ **Best for**: Complex relationships, ACID transactions, reporting
-
-#### Option B: NoSQL Databases
-- ✅ **Databases**: MongoDB, DynamoDB, CouchDB
-- ✅ **ODMs**: Mongoose, AWS SDK, PouchDB
-- ✅ **Best for**: Flexible schemas, horizontal scaling, document storage
-
-#### Option C: Cloud-Native Solutions
-- ✅ **Options**: Supabase, Firebase, AWS RDS, Azure SQL, PlanetScale
-- ✅ **Best for**: Rapid development, managed infrastructure, built-in features
-- ✅ **Use when**: Want managed database with additional services
-
-### Authentication Options
-
-#### Option A: Self-Managed
-- ✅ **Solutions**: NextAuth.js, Passport.js, Django Auth, custom JWT
-- ✅ **Best for**: Custom requirements, full control, specific workflows
-- ✅ **Use when**: Need custom authentication logic
-
-#### Option B: Authentication as a Service
-- ✅ **Solutions**: Auth0, Firebase Auth, AWS Cognito, Supabase Auth
-- ✅ **Best for**: Rapid development, enterprise SSO, compliance requirements
-- ✅ **Use when**: Want managed authentication with social providers
-
----
+## Always Apply
 
-## Core Architecture Principles
+1. **Security-first**: Validate inputs, authenticate endpoints, rate limit public APIs
+   - Reference: `agents/rules/security.mdc`
 
-### Security-First Development
-- **Input Validation**: Validate all user inputs at application boundaries
-- **Authentication**: Implement secure session management and MFA where appropriate
-- **Authorization**: Role-based access control with proper middleware
-- **Data Protection**: Encrypt sensitive data, sanitize outputs, secure error handling
-- **Rate Limiting**: Protect against DoS attacks with appropriate limiting strategies
+2. **Testing**: Unit (80%), Integration (15%), E2E (5%) coverage
+   - Reference: `agents/rules/testing.mdc`
 
-### Performance Optimization
-- **Asset Optimization**: Compress images, minify code, implement caching
-- **Loading Strategies**: Lazy loading, code splitting, progressive loading
-- **Database Optimization**: Efficient queries, connection pooling, caching layers
-- **Monitoring**: Performance metrics, error tracking, user experience monitoring
+3. **Type Safety**: Strong typing with runtime validation at boundaries
+   - Reference: `agents/rules/core.mdc`
 
-### Type Safety & Validation
-- **Static Typing**: Use TypeScript, Flow, or language-native typing systems
-- **Runtime Validation**: Schema validation at API boundaries and form inputs
-- **API Contracts**: OpenAPI/GraphQL schemas for API documentation and validation
-- **Database Schemas**: Proper constraints and validation at the database level
+## Agent Delegation
 
-### Testing Strategy
-- **Unit Testing**: Test individual functions and components (80% of tests)
-- **Integration Testing**: Test API endpoints and database operations (15% of tests)
-- **End-to-End Testing**: Test critical user journeys (5% of tests)
-- **Accessibility Testing**: Automated WCAG compliance checking
-- **Security Testing**: Input validation and authentication flow testing
+When implementing features, follow agent patterns from `agent-docs/AGENTS.md`:
+- **UI/Design** → FrontendAgent patterns (`agents/rules/frontend.mdc`)
+- **API/Logic** → BackendAgent patterns (`agents/rules/security.mdc`)
+- **Database** → DatabaseAgent patterns (`agents/rules/database.mdc`)
+- **Testing** → TestAgent patterns (`agents/rules/testing.mdc`)
+- **Security** → SecurityAgent patterns (`agents/rules/security.mdc`)
 
-### Developer Experience
-- **Development Tools**: Hot reload, debugging tools, comprehensive logging
-- **Code Quality**: Linting, formatting, pre-commit hooks, automated quality gates
-- **Documentation**: API docs, component storybooks, architectural decision records
-- **Deployment**: CI/CD pipelines, environment management, rollback strategies
+## Critical Rules
 
----
-
-## Project Structure Patterns
-
-### Feature-Based Structure
-Organize code by business domain rather than technical layer:
-
-```
-src/
-├── features/
-│   ├── auth/
-│   │   ├── components/
-│   │   ├── services/
-│   │   ├── types/
-│   │   └── tests/
-│   └── dashboard/
-│       ├── components/
-│       ├── services/
-│       ├── types/
-│       └── tests/
-├── shared/
-│   ├── components/
-│   ├── utilities/
-│   ├── types/
-│   └── constants/
-└── tests/
-    ├── integration/
-    └── e2e/
-```
-
-### Technology-Specific Adaptations
-
-**React/Vue/Angular Projects:**
-- Component-based architecture with proper state management
-- Shared component library with consistent design tokens
-- Custom hooks/composables for reusable logic
-
-**Backend API Projects:**
-- Service layer for business logic
-- Repository pattern for data access
-- Middleware for cross-cutting concerns
-
-**Full-Stack Projects:**
-- Shared types between frontend and backend
-- API route organization matching frontend features
-- Consistent error handling patterns
-
----
-
-## Quality Standards
-
-### Code Quality
-- **Consistency**: Follow established patterns throughout the codebase
-- **Readability**: Clear naming, proper documentation, logical organization
-- **Maintainability**: Modular design, separation of concerns, SOLID principles
-- **Performance**: Efficient algorithms, appropriate caching, resource optimization
+- Validate ALL user inputs with schema validation
+- Authenticate and authorize protected endpoints
+- Rate limit public endpoints
+- Write tests for all business logic
+- Ensure WCAG 2.1 AA accessibility compliance
+- Use ORM/ODM patterns, avoid raw queries
+- Never expose sensitive data in errors/logs
 
-### Security Standards
-- **OWASP Top 10**: Address all major web application security risks
-- **Input Validation**: Comprehensive validation with appropriate error handling
-- **Authentication**: Secure session management with proper token handling
-- **Authorization**: Granular permissions with proper access control
-- **Data Protection**: Encryption at rest and in transit, secure data handling
+## Reference Files
 
-### Testing Standards
-- **Coverage**: Maintain >80% test coverage for business logic
-- **Reliability**: Tests should be deterministic and fast
-- **Maintainability**: Clear test organization and proper mocking patterns
-- **Accessibility**: All user-facing features tested for WCAG compliance
-
-### Documentation Standards
-- **API Documentation**: Complete endpoint documentation with examples
-- **Component Documentation**: Props, usage examples, accessibility notes
-- **Architecture Documentation**: Decision records, system diagrams, setup guides
-- **User Documentation**: Feature guides, troubleshooting, FAQ
-
----
-
-## Getting Started
-
-### 1. Choose Your Stack
-Review the options above and select technologies that fit your:
-- **Team expertise** and learning preferences  
-- **Project requirements** and performance needs
-- **Deployment environment** and infrastructure constraints
-- **Timeline** and development velocity requirements
-
-### 2. Adapt the Template
-- Update `agents/rules/*.mdc` files with technology-specific patterns
-- Modify `.cursorrules` to include your chosen stack details
-- Update this `CLAUDE.md` file with stack-specific guidelines
-- Create appropriate configuration files for your chosen tools
-
-### 3. Implement Core Patterns
-- Set up your chosen security patterns (validation, auth, rate limiting)
-- Implement testing tools and maintain quality gates
-- Configure development tools (linting, formatting, debugging)
-- Set up deployment pipelines and environment management
-
-### 4. Follow Agent Patterns
-- Use the agents defined in `AGENTS.MD` for specialized tasks
-- Maintain consistency with established patterns
-- Regular code reviews using `ReviewerAgent` patterns
-- Document architectural decisions as you build
+- `agent-docs/AI_INSTRUCTIONS.md` - Primary AI assistant guide
+- `agent-docs/ARCHITECTURE.md` - Architecture and technology stack guidance
+- `agent-docs/AGENTS.md` - Agent responsibilities and delegation
+- `agents/rules/core.mdc` - Core principles
+- `agents/rules/security.mdc` - Security patterns (CRITICAL)
+- `agents/rules/testing.mdc` - Testing strategy (CRITICAL)
+- `agents/rules/frontend.mdc` - Frontend patterns
+- `agents/rules/database.mdc` - Database patterns
+- `agents/rules/style.mdc` - Code style guidelines
 
 ---
 
-## Maintenance & Evolution
-
-### Regular Reviews
-- **Security audits**: Regular dependency updates and vulnerability scanning
-- **Performance monitoring**: Track metrics and optimize bottlenecks
-- **Code quality**: Regular refactoring and technical debt management
-- **Documentation**: Keep docs current with code changes
-
-### Technology Updates
-- **Dependencies**: Regular updates with proper testing
-- **Framework versions**: Planned upgrades with migration strategies
-- **Security patches**: Immediate application of critical security updates
-- **Performance improvements**: Adoption of new optimization techniques
-
-### How We Improve This Package (Maintainers)
-When improving the agents-templated package itself, maintainers use **NotebookLM** (research and best-practice discourse) and **Context7** (up-to-date library and framework docs) to gather insights. Use both to improve the **system itself**—templates, rules, and skills—by querying Cursor rules best practices, agent-rules patterns, and template/scaffolding guides, then refining rules, skills, and template content. Run the audit dimensions (docs, rules, CLI, presets, validate/doctor, tests), prioritize changes, then validate with `agents-templated validate` and `doctor`. See the README section "Improvement and Maintenance" for the full process.
-
-This template provides a solid foundation while remaining flexible for any technology stack you choose to implement.
+**Note**: This is technology-agnostic. Adapt patterns to your chosen stack while maintaining security and quality standards.

package/templates/{.gemini-instructions.md → GEMINI.md}

@@ -8,8 +8,9 @@ This project uses enterprise-grade, technology-agnostic development patterns for
 
 ## Quick Start
 
-- **Project Guidelines**: See `CLAUDE.md`
-- **Agent Patterns**: See `AGENTS.md`
+- **AI Guide**: See `agent-docs/AI_INSTRUCTIONS.md` for comprehensive instructions
+- **Architecture**: See `agent-docs/ARCHITECTURE.md` for project guidelines
+- **Agent Patterns**: See `agent-docs/AGENTS.md` for delegation patterns
 - **Detailed Rules**: See `agents/rules/*.mdc` files
 - **Available Skills**: See `agents/skills/` directory
 
@@ -99,8 +100,9 @@ These patterns apply regardless of your tech stack. Adapt them to your chosen fr
 
 | File | Purpose | When to Use |
 |------|---------|------------|
-| `CLAUDE.md` | Architecture and technology stack decisions | Need architectural guidance |
-| `AGENTS.md` | Agent responsibilities and delegation | Deciding who should implement a feature |
+| `agent-docs/AI_INSTRUCTIONS.md` | Primary AI assistant guide | Always start here |
+| `agent-docs/ARCHITECTURE.md` | Architecture and technology stack decisions | Need architectural guidance |
+| `agent-docs/AGENTS.md` | Agent responsibilities and delegation | Deciding who should implement a feature |
 | `agents/rules/core.mdc` | Core development principles | General development questions |
 | `agents/rules/security.mdc` | Security patterns and implementations | Building secure features |
 | `agents/rules/testing.mdc` | Testing strategy and best practices | Writing tests or test strategy |
@@ -111,8 +113,9 @@ These patterns apply regardless of your tech stack. Adapt them to your chosen fr
 
 ## Workflow Recommendations
 
-1. **Read CLAUDE.md** first to understand the overall architecture
-2. **Check AGENTS.md** to identify which agent should lead the implementation
+1. **Read agent-docs/AI_INSTRUCTIONS.md** for comprehensive AI assistance guidance
+2. **Read agent-docs/ARCHITECTURE.md** to understand the overall architecture
+3. **Check agent-docs/AGENTS.md** to identify which agent should lead the implementation
 3. **Reference the appropriate rule file** for implementation patterns
 4. **Look in agents/skills/** for domain-specific guidance
 5. **Follow all critical rules** without exception
@@ -127,4 +130,4 @@ These patterns apply regardless of your tech stack. Adapt them to your chosen fr
 
 ---
 
-For best results with Gemini AI assistance, reference the appropriate rules files and provide the relevant context from `CLAUDE.md` and `AGENTS.md` in your prompts.
+For best results with Gemini AI assistance, reference the appropriate rules files and provide the relevant context from `agent-docs/AI_INSTRUCTIONS.md`, `agent-docs/ARCHITECTURE.md`, and `agent-docs/AGENTS.md` in your prompts.