agents-templated 2.2.0 → 2.2.2

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/agents-templated.svg)](https://www.npmjs.com/package/agents-templated)
 [![npm downloads](https://img.shields.io/npm/dm/agents-templated.svg)](https://www.npmjs.com/package/agents-templated)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![GitHub stars](https://img.shields.io/github/stars/rickandrew2/agents-projects-templated?style=social)](https://github.com/rickandrew2/agents-templated)
+[![GitHub stars](https://img.shields.io/github/stars/rickandrew2/agents-templated?style=social)](https://github.com/rickandrew2/agents-templated)
 
 > **Agents Templated** is a CLI tool and npm package that instantly scaffolds production-ready project structures with enterprise-grade development patterns, security guidelines, and AI assistant configurations. Designed for developers who want to start projects the right way—with proven OWASP security practices, comprehensive testing strategies (80/15/5 coverage targets), and agent-based architecture patterns—without being locked into specific frameworks. It generates unified configuration files that work seamlessly with Cursor, GitHub Copilot, Claude, and Google Gemini, allowing AI assistants to automatically follow best practices from day one. Whether you're building a Next.js app, Django API, Go microservice, or any custom stack, Agents Templated provides the guardrails and patterns you need while giving you complete freedom to choose your technology.
 
@@ -28,13 +28,13 @@ Agents Templated scaffolds your project with:
 - Deterministic slash-command standard in `AGENTS.MD` and modular contracts in `agents/commands/`
 - Implicit natural-language routing support (`slash-command-auto`) for non-technical prompts
 - New workflow/routing/hardening rule set:
-  - `agents/rules/intent-routing.mdc`
-  - `agents/rules/system-workflow.mdc`
-  - `agents/rules/hardening.mdc`
+  - `.github/instructions/rules/intent-routing.mdc`
+  - `.github/instructions/rules/system-workflow.mdc`
+  - `.github/instructions/rules/hardening.mdc`
 - New baseline skills:
-  - `agents/skills/feature-delivery/`
-  - `agents/skills/bug-triage/`
-  - `agents/skills/app-hardening/`
+  - `.github/skills/feature-delivery/`
+  - `.github/skills/bug-triage/`
+  - `.github/skills/app-hardening/`
 - Release and audit contracts now require hardening evidence when risk profile requires it
 
 ---
@@ -124,7 +124,7 @@ Agents Templated automatically configures compatible wrappers for major AI codin
 | **Claude** | `CLAUDE.md` | ✅ Compatible |
 | **Generic agents** | `AGENTS.MD` | ✅ Compatible |
 
-**Single source of truth:** `instructions/source/core.md` drives generated tool-compatible instruction files.
+**Single source of truth:** `CLAUDE.md` drives generated tool-compatible instruction files.
 
 ---
 
@@ -421,7 +421,7 @@ await agentsTemplated.install('./my-project', {
 
 When contributing to this template:
 1. Maintain technology-agnostic patterns
-2. Update relevant rule files in `agents/rules/`
+2. Update relevant rule files in `.github/instructions/rules/`
 3. Keep documentation synchronized with code changes
 4. Follow security and testing patterns
 5. Ensure AI assistant configurations remain compatible

package/bin/cli.js

@@ -125,7 +125,7 @@ program
               { name: 'Agent rules (.github/instructions/rules/*.mdc)', value: 'rules' },
               { name: 'Skills (.github/skills/*)', value: 'skills' },
               { name: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github' },
-              { name: 'Agent subagents (agents/subagents/*.md)', value: 'subagents' }
+              { name: 'Agent subagents (.claude/agents/*.md)', value: 'subagents' }
             ],
             default: ['all']
           },
@@ -190,6 +190,7 @@ program
         await writeGeneratedInstructions(targetDir, templateDir, options.force);
         console.log(chalk.gray('  ✓ Claude (CLAUDE.md — canonical source)'));
         console.log(chalk.gray('  ✓ GitHub Copilot (.github/copilot-instructions.md pointer)'));
+        console.log(chalk.gray('  ✓ Cursor (.cursorrules pointer)'));
         console.log(chalk.gray('  ✓ Generic AGENTS (AGENTS.MD pointer)'));
       }
 
@@ -198,7 +199,7 @@ program
         console.log(chalk.yellow('Installing agent subagents...'));
         await fs.ensureDir(path.join(targetDir, LAYOUT.canonical.subagentsDir));
         await copyDirectory(
-          path.join(templateDir, 'agents', 'subagents'),
+          path.join(templateDir, '.claude', 'agents'),
           path.join(targetDir, LAYOUT.canonical.subagentsDir),
           options.force
         );
@@ -257,7 +258,7 @@ program
                 { name: 'Agent Rules (security, testing, database, etc.)', value: 'rules' },
                 { name: 'Skills (reusable agent capabilities)', value: 'skills' },
                 { name: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github' },
-                { name: 'Agent subagents (agents/subagents/*.md)', value: 'subagents' }
+                { name: 'Agent subagents (.claude/agents/*.md)', value: 'subagents' }
               ],
               validate: (answer) => {
                 if (answer.length === 0) {
@@ -294,7 +295,7 @@ program
             { name: 'Agent Rules (security, testing, database, etc.)', value: 'rules', checked: true },
             { name: 'Skills (reusable agent capabilities)', value: 'skills', checked: true },
             { name: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github', checked: true },
-            { name: 'Agent subagents (agents/subagents/*.md)', value: 'subagents', checked: true }
+            { name: 'Agent subagents (.claude/agents/*.md)', value: 'subagents', checked: true }
           ],
           validate: (answer) => {
             if (answer.length === 0) {
@@ -369,7 +370,7 @@ program
         console.log(chalk.yellow('Installing agent subagents...'));
         await fs.ensureDir(path.join(targetDir, LAYOUT.canonical.subagentsDir));
         await copyDirectory(
-          path.join(templateDir, 'agents', 'subagents'),
+          path.join(templateDir, '.claude', 'agents'),
           path.join(targetDir, LAYOUT.canonical.subagentsDir),
           options.force
         );
@@ -405,7 +406,7 @@ program
     console.log(chalk.yellow('rules') + '   - Agent rules (.github/instructions/rules/*.mdc)');
     console.log(chalk.yellow('skills') + '  - Agent skills (.github/skills/*)');
     console.log(chalk.yellow('github') + '  - AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)');
-    console.log(chalk.yellow('subagents') + ' - Agent subagents (agents/subagents/*.md)');
+    console.log(chalk.yellow('subagents') + ' - Agent subagents (.claude/agents/*.md)');
     console.log(chalk.yellow('all') + '     - All components');
     
     console.log(chalk.blue.bold('\n\nAvailable Presets:\n'));
@@ -653,7 +654,6 @@ async function cleanupLegacyInstructionFiles(targetDir) {
   // Files removed in v2.0.0: orphaned wrappers that contained duplicated policy
   // content and were not managed/validated by the generator.
   const legacyFiles = [
-    '.cursorrules',
     '.github/instructions/AGENTS.md',
     // Pre-v1.2.13 paths
     '.claude/CLAUDE.md'
@@ -714,7 +714,7 @@ async function updateSelectedComponents(targetDir, templateDir, selectedComponen
     console.log(chalk.yellow('Updating agent subagents...'));
     await fs.ensureDir(path.join(targetDir, LAYOUT.canonical.subagentsDir));
     await copyDirectory(
-      path.join(templateDir, 'agents', 'subagents'),
+      path.join(templateDir, '.claude', 'agents'),
       path.join(targetDir, LAYOUT.canonical.subagentsDir),
       overwrite
     );
@@ -1031,7 +1031,7 @@ program
 
 program
   .command('new-subagent <name>')
-  .description('Scaffold a new subagent in agents/subagents/<name>.md')
+  .description('Scaffold a new subagent in .claude/agents/<name>.md')
   .action(async (name) => {
     try {
       const targetDir = process.cwd();

package/index.js

@@ -16,12 +16,13 @@ const { CANONICAL_INSTRUCTION_FILE, writeGeneratedInstructions } = require('./li
  * @param {boolean} options.rules - Install agent rules
  * @param {boolean} options.skills - Install skills
  * @param {boolean} options.github - Install GitHub Copilot instructions
+ * @param {boolean} options.subagents - Install agent subagents
  * @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 installAll = !options.docs && !options.rules && !options.skills && !options.github && !options.subagents;
 
   const files = [];
 
@@ -73,6 +74,16 @@ async function install(targetDir, options = {}) {
     await fs.ensureDir(path.join(targetDir, '.github', 'instructions'));
     await writeGeneratedInstructions(targetDir, templateDir, options.force);
   }
+
+  // Agent subagents (.claude/agents/)
+  if (installAll || options.subagents) {
+    await fs.ensureDir(path.join(targetDir, '.claude', 'agents'));
+    await copyDirectory(
+      path.join(templateDir, '.claude', 'agents'),
+      path.join(targetDir, '.claude', 'agents'),
+      options.force
+    );
+  }
 }
 
 async function copyDirectory(sourceDir, targetDir, force = false) {

package/lib/instructions.js

@@ -7,7 +7,8 @@ const CANONICAL_INSTRUCTION_FILE = 'CLAUDE.md';
 // Thin compatibility pointer files — policy lives in CLAUDE.md, not here.
 const POINTER_FILES = {
   agents: 'AGENTS.MD',
-  copilot: '.github/copilot-instructions.md'
+  copilot: '.github/copilot-instructions.md',
+  cursor: '.cursorrules'
 };
 
 function buildAgentsPointer() {
@@ -31,6 +32,17 @@ function buildCopilotPointer() {
   ].join('\n');
 }
 
+function buildCursorPointer() {
+  return [
+    '<!-- Tool profile: cursor-compat -->',
+    '# Cursor Rules',
+    '',
+    'Primary policy source: `CLAUDE.md`.',
+    'Load policy only from the canonical source file above.',
+    'If this file and CLAUDE.md conflict, CLAUDE.md wins.'
+  ].join('\n');
+}
+
 async function writeGeneratedInstructions(targetDir, templateDir, force = false) {
   // Copy CLAUDE.md from template if not present (or forced)
   const targetClaude = path.join(targetDir, CANONICAL_INSTRUCTION_FILE);
@@ -42,7 +54,8 @@ async function writeGeneratedInstructions(targetDir, templateDir, force = false)
   // Write thin pointer files
   const pointers = {
     [POINTER_FILES.agents]: buildAgentsPointer(),
-    [POINTER_FILES.copilot]: buildCopilotPointer()
+    [POINTER_FILES.copilot]: buildCopilotPointer(),
+    [POINTER_FILES.cursor]: buildCursorPointer()
   };
 
   for (const [relPath, content] of Object.entries(pointers)) {
@@ -63,7 +76,8 @@ async function validateInstructionDrift(targetDir) {
   const driftFiles = [];
   const expectedPointers = {
     [POINTER_FILES.agents]: buildAgentsPointer(),
-    [POINTER_FILES.copilot]: buildCopilotPointer()
+    [POINTER_FILES.copilot]: buildCopilotPointer(),
+    [POINTER_FILES.cursor]: buildCursorPointer()
   };
 
   for (const [relPath, expectedContent] of Object.entries(expectedPointers)) {
@@ -158,10 +172,10 @@ async function scaffoldRule(targetDir, ruleName) {
 }
 
 async function scaffoldSubagent(targetDir, name) {
-  const subagentFile = path.join(targetDir, 'agents', 'subagents', `${name}.md`);
+  const subagentFile = path.join(targetDir, '.claude', 'agents', `${name}.md`);
 
   if (await fs.pathExists(subagentFile)) {
-    throw new Error(`Subagent already exists: agents/subagents/${name}.md`);
+    throw new Error(`Subagent already exists: .claude/agents/${name}.md`);
   }
 
   const title = name.split('-').map(w => w[0].toUpperCase() + w.slice(1)).join(' ');
@@ -195,7 +209,7 @@ async function scaffoldSubagent(targetDir, name) {
 
   await fs.ensureDir(path.dirname(subagentFile));
   await fs.writeFile(subagentFile, content, 'utf8');
-  return `agents/subagents/${name}.md`;
+  return `.claude/agents/${name}.md`;
 }
 
 module.exports = {

package/lib/layout.js

@@ -6,7 +6,7 @@ const LAYOUT = {
     docsDir: 'agent-docs',
     rulesDir: '.github/instructions/rules',
     skillsDir: '.github/skills',
-    subagentsDir: 'agents/subagents'
+    subagentsDir: '.claude/agents'
   },
   legacy: {
     rulesDirs: ['agents/rules'],
@@ -41,7 +41,7 @@ function resolveSkillsDir(baseDir) {
 }
 
 function resolveSubagentsDir(baseDir) {
-  const candidates = [LAYOUT.canonical.subagentsDir];
+  const candidates = [LAYOUT.canonical.subagentsDir, 'agents/subagents'];
   return firstExistingPath(baseDir, candidates) || LAYOUT.canonical.subagentsDir;
 }
 
@@ -50,6 +50,7 @@ async function hasAnyLayout(baseDir) {
     path.join(baseDir, LAYOUT.canonical.rulesDir),
     path.join(baseDir, LAYOUT.canonical.skillsDir),
     path.join(baseDir, LAYOUT.canonical.subagentsDir),
+    path.join(baseDir, 'agents', 'subagents'),
     ...LAYOUT.compatible.rulesDirs.map((relPath) => path.join(baseDir, relPath)),
     ...LAYOUT.compatible.skillsDirs.map((relPath) => path.join(baseDir, relPath)),
     ...LAYOUT.legacy.rulesDirs.map((relPath) => path.join(baseDir, relPath)),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-templated",
-  "version": "2.2.0",
+  "version": "2.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/{agents/subagents → .claude/agents}/README.md

@@ -41,12 +41,12 @@ Subagents are invoked automatically based on `description` matching, or explicit
 ```
 
 ### Other tools (Copilot, Cursor, Windsurf)
-Reference the subagent file directly in your prompt or instruct your AI to follow the workflow defined in `agents/subagents/<name>.md`.
+Reference the subagent file directly in your prompt or instruct your AI to follow the workflow defined in `.claude/agents/<name>.md`.
 
 ## File Structure
 
 ```
-agents/subagents/
+.claude/agents/
 ├── README.md                  ← This file
 ├── planner.md
 ├── architect.md

package/templates/.claude/rules/ai-integration.mdc

@@ -0,0 +1,60 @@
+---
+title: "AI / LLM Integration"
+description: "Apply when integrating LLMs, RAG pipelines, prompt engineering, or working with AI-powered features"
+version: "1.0.0"
+tags: ["ai", "llm", "openai", "anthropic", "rag", "prompt-engineering", "safety"]
+alwaysApply: false
+globs: ["**/*llm*", "**/*openai*", "**/*anthropic*", "**/*langchain*", "**/*rag*", "**/ai/**"]
+triggers:
+  - "Integrating OpenAI, Claude, or other LLM APIs"
+  - "Building RAG (Retrieval-Augmented Generation) pipeline"
+  - "Engineering prompts or prompt chains"
+  - "Implementing LLM-powered features"
+  - "Evaluating LLM outputs or quality"
+---
+
+## Purpose
+
+Govern LLM integrations safely: prevent prompt injection, enforce cost boundaries, define fallback behavior, and ensure model outputs are validated before use in any user-facing or downstream context.
+
+## Security Requirements
+
+1. **Prompt injection prevention** — Never interpolate raw user input directly into system prompts. Delimit user content explicitly (e.g., `<user_input>…</user_input>` tags or equivalent structural separation).
+2. **Output validation** — Treat all LLM outputs as untrusted data. Validate schema, sanitize before rendering in UI, and never execute LLM-generated code without a human or automated review gate.
+3. **Secret isolation** — API keys must live in environment variables only. Never log full request/response payloads that may contain sensitive user data.
+4. **Rate limiting** — Apply per-user and global rate limits on all LLM-backed endpoints to prevent abuse and runaway costs.
+
+## Cost Controls
+
+- Set explicit `max_tokens` on every API call — never rely on model defaults.
+- Log token usage per request; alert on anomalies (> 2× rolling baseline).
+- Prefer streaming for long generations to enable early cancellation.
+- Use smaller/cheaper models for classification, routing, or validation tasks; reserve large models for generation.
+
+## Model Selection
+
+| Task | Preferred approach |
+|------|--------------------|
+| Classification / intent detection | Small fast model or fine-tuned classifier |
+| Retrieval-augmented generation | Embed → retrieve → generate pipeline |
+| Code generation | Model with strong code benchmarks; always review output |
+| Summarization | Mid-tier model with explicit length constraints |
+| Production generation | Model with provider SLA; never experimental endpoints in prod |
+
+## Fallback & Reliability
+
+- Every LLM call must have a timeout and retry with exponential backoff (max 3 retries).
+- Define a graceful degradation path for every LLM-powered feature (static response, cached answer, or user-facing degradation message).
+- Do not block critical user flows on LLM availability.
+
+## RAG Pipeline Rules
+
+- Chunk documents at semantic boundaries (paragraph, section), not arbitrary byte offsets.
+- Score retrieved chunks; discard chunks below relevance threshold before injecting into prompt.
+- Cite sources in output when content is retrieved — never present retrieved facts as model-generated knowledge.
+
+## Evaluation Requirements
+
+- New LLM features must include an evaluation suite before production: minimum 20 representative examples with expected outputs.
+- Track: accuracy, latency (p50/p95), token cost per request, failure rate.
+- Accuracy regressions > 5% block promotion to production.

package/templates/.claude/rules/core.mdc

@@ -0,0 +1,180 @@
+---
+title: "Core Project Guidelines"
+description: "Apply to all architecture, type safety, code organization, and enterprise quality standards. Foundation for every feature"
+alwaysApply: true
+version: "3.0.0"
+tags: ["architecture", "core", "enterprise", "technology-agnostic"]
+globs:
+  - "*"
+triggers:
+  - "Designing application architecture"
+  - "Setting up new project or module"
+  - "Defining type systems and validation"
+  - "Organizing code structure"
+  - "Improving code quality standards"
+  - "Making testing or performance decisions"
+---
+
+## Developer Identity
+
+- The AI assistant should provide clear, step-by-step solutions
+- Focus on security-first thinking in all recommendations
+- Provide concise but comprehensive instructions
+- Adapt all patterns to the chosen technology stack
+
+## Architecture Principles
+
+### Security-First Development
+- **Validate all inputs** at application boundaries with appropriate validation libraries
+- **Authenticate and authorize** every protected endpoint with secure session management
+- **Rate limit** public endpoints to prevent abuse and DoS attacks
+- **Sanitize outputs** to prevent injection attacks and data leaks
+- **Use encryption** for sensitive data in transit and at rest
+- **Log security events** appropriately without exposing sensitive information
+
+### Performance-Focused
+- **Optimize asset delivery** with compression, caching, and lazy loading
+- **Monitor performance metrics** specific to your platform (Web Vitals, response times, etc.)
+- **Implement appropriate caching strategies** for your data freshness requirements
+- **Optimize critical paths** - database queries, API responses, asset loading
+- **Profile and benchmark** before and after optimization changes
+
+### Type Safety & Validation
+- **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
+- **Document type contracts** between system components
+- **Generate types** from schemas when possible (OpenAPI, GraphQL, database schemas)
+
+### Testing Strategy
+- **Unit tests** for business logic and utility functions (80% of test effort)
+- **Integration tests** for API endpoints and data access layers (15% of test effort)
+- **E2E tests** for critical user journeys and workflows (5% of test effort)
+- **Accessibility tests** for all user-facing interfaces
+- **Performance tests** for critical paths and known bottlenecks
+- **Security tests** for authentication, authorization, and validation flows
+
+## Code Quality Standards
+
+### Architecture & Organization
+- **Feature-based structure** - organize code by business domain, not just technical layer
+- **Separation of concerns** - keep UI, business logic, and data access separate
+- **DRY principle** - don't repeat yourself, extract common patterns
+- **SOLID principles** - single responsibility, open/closed, Liskov substitution, interface segregation, dependency inversion
+- **Consistent naming** conventions throughout the codebase
+
+### Code Style
+- **Consistent formatting** with automated tools (prettier, black, gofmt, rustfmt, etc.)
+- **Linting rules** enforced via pre-commit hooks or CI/CD
+- **Clear comments** for complex logic, architectural decisions, and gotchas
+- **Self-documenting code** with meaningful variable and function names
+- **No magic numbers** - extract constants with descriptive names
+
+### Component/Module Standards (Framework-Specific)
+- **Single responsibility** - each component/module should have one clear purpose
+- **Reusable units** - build components/modules that can be used in multiple places
+- **Proper error handling** for production resilience
+- **Accessibility attributes** included for user-facing components
+- **Proper documentation** of public APIs and interfaces
+
+### Database Standards
+- **Choose ONE approach** and maintain consistency (SQL with ORM, NoSQL, managed service, etc.)
+- **Schema migrations only** for schema changes (never manual database edits in production)
+- **ORM/ODM patterns** to prevent injection attacks (no raw SQL unless performance-critical)
+- **Connection pooling** for all production deployments
+- **Audit logs** for sensitive data operations
+- **Proper indexing** to prevent N+1 query problems
+
+## Development Workflow
+
+### Quality Gates
+- **Automated formatting** checks before code submission
+- **Type checking** must pass (strict mode where available)
+- **Linting** must pass with zero critical violations
+- **Unit tests** must pass with adequate coverage (>80% for business logic)
+- **Integration tests** must pass for API and data layer changes
+- **Security scans** must pass without high-severity issues
+- **Code review** approval required before merging
+
+### Environment Management
+- **Environment variables** with runtime validation at startup
+- **Secrets management** never in code, version control, or logs
+- **Database migrations** applied consistently across environments
+- **Feature flags** for gradual rollouts and A/B testing
+- **Health checks** for deployment validation and monitoring
+
+### Performance Standards
+- **Monitor resource usage** - memory, CPU, disk, network
+- **Track performance metrics** specific to your platform
+- **Profile critical paths** regularly to identify bottlenecks
+- **Implement caching** appropriately for your use case
+- **Alert on regressions** when performance degrades
+
+## Technology Stack Selection
+
+This template is technology-agnostic. Choose your stack based on:
+- **Team expertise** and preferred languages/frameworks
+- **Project requirements** - performance needs, scalability, real-time features
+- **Deployment environment** - cloud platform, container requirements, resources
+- **Time constraints** - rapid prototyping vs. long-term maintenance
+
+### Frontend Tiers
+- **Full-stack frameworks**: Next.js, Nuxt, SvelteKit, Remix
+- **Component libraries**: React, Vue, Angular, Svelte, Solid
+- **Traditional**: Server-side rendering with templates (Django, Rails, Laravel)
+- **Mobile-first**: React Native, Flutter, Kotlin, Swift
+
+### Backend Tiers
+- **Node.js**: Express, Fastify, NestJS, Koa
+- **Python**: Django, FastAPI, Flask
+- **Go**: Gin, Echo, Fiber
+- **Rust**: Actix-web, Axum, Rocket
+- **Java**: Spring Boot, Quarkus, Ktor
+- **Other**: Ruby on Rails, C#/.NET, PHP, etc.
+
+### Database Tiers
+- **SQL**: PostgreSQL, MySQL, SQLite, SQL Server
+- **NoSQL**: MongoDB, DynamoDB, CouchDB, Firestore
+- **Cloud-native**: Supabase, Firebase, AWS RDS, Azure SQL
+- **Search**: Elasticsearch, Meilisearch, Algolia
+
+### Authentication
+- **Self-managed**: Custom implementation with JWT, sessions, or cookies
+- **Framework-integrated**: NextAuth, Passport, Django's auth system
+- **SaaS**: Auth0, Firebase Auth, AWS Cognito, Supabase Auth
+
+## Maintenance & Evolution
+
+### Regular Reviews
+- **Dependency updates** - keep packages current with security patches
+- **Security audits** - regular vulnerability scanning and code review
+- **Performance monitoring** - track metrics and address regressions
+- **Code quality** - refactoring and technical debt management
+- **Documentation** - keep docs current with code changes
+
+### Technology Updates
+- **Framework versions** - planned upgrades with migration strategies
+- **Critical patches** - immediate application of security updates
+- **Feature adoption** - stay current with language/framework improvements
+- **Deprecation management** - handle deprecated APIs and patterns
+
+## Documentation and Research
+
+When deciding what to recommend or implement:
+
+- **Local rules** (this file and other `.claude/rules/*.mdc`): Use as the primary source for architecture, security, testing, and style. Follow these when the stack is generic or already covered.
+- **Context7 MCP**: Use for **up-to-date library and framework documentation**. When suggesting or implementing patterns for a specific stack (e.g. Next.js, Express, React), query Context7 (`resolve-library-id` then `query-docs`) so recommendations match current APIs and official guidance.
+- **NotebookLM MCP**: Use for **research and best-practice discourse** (e.g. OWASP, building-systems advice, template design). Query when adding or changing guidelines, or when the audit/planning needs external best practices. Not for real-time API docs—use Context7 for that.
+
+## Communication & Collaboration
+
+- When providing solutions, be explicit about what to change
+- Show code examples in the language/framework being used
+- Focus on actionable steps, minimize unnecessary explanation
+- Explain security implications of code changes
+- Flag performance implications of design decisions
+
+---
+
+Remember: This template adapts to **any modern technology stack** while maintaining **enterprise-grade quality standards**.
+Choose your technologies wisely, apply these principles consistently, and keep your codebase maintainable.