agents-templated 2.2.19 → 2.2.21

package/templates/agents/rules/ai-integration.md

@@ -0,0 +1,54 @@
+---
+title: "AI / LLM Integration"
+description: "Apply when integrating LLMs, RAG pipelines, prompt engineering, or building AI-powered features. Covers safety, cost, and quality"
+version: "3.0.0"
+tags: ["ai", "llm", "openai", "anthropic", "rag", "prompt-engineering", "safety"]
+alwaysApply: false
+globs: ["**/*llm*", "**/*openai*", "**/*anthropic*", "**/*langchain*", "**/*rag*", "**/ai/**"]
+---
+
+## 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/agents/rules/core.md

@@ -0,0 +1,173 @@
+---
+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:
+  - "*"
+---
+
+## 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 `agents/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.

package/templates/agents/rules/database.md

@@ -0,0 +1,305 @@
+---
+title: "Database and Data Layer Guidelines"
+description: "Apply when designing schema, building data access layers, optimizing queries, or managing database operations"
+alwaysApply: true
+version: "3.0.0"
+tags: ["database", "backend", "data", "orm", "schema"]
+globs:
+  - "src/models/**/*"
+  - "src/data/**/*"
+---
+
+# Database and Data Layer Guidelines
+
+Technology-agnostic patterns for secure, maintainable data access.
+
+## Core Principles
+
+### Design First
+- **Schema design** - Think through relationships and constraints
+- **Normalization** - Minimize data duplication and anomalies
+- **Scalability** - Design for growth and performance
+- **Consistency** - ACID transactions when needed (SQL) or eventual consistency patterns (NoSQL)
+- **Security** - Access controls at database and application level
+
+### Access Patterns
+- **ORM/ODM only** - Use abstraction layer, never raw SQL/queries
+- **Parameterized queries** - Prevent injection attacks
+- **Query optimization** - Avoid N+1 problems and slow queries
+- **Connection pooling** - Manage resources efficiently
+- **Error handling** - Graceful degradation when database unavailable
+
+### Migration Strategy
+- **Version control** - All schema changes tracked
+- **Idempotent migrations** - Can run multiple times safely
+- **Reversible migrations** - Can rollback if needed
+- **Testing** - Test migrations in all environments
+- **Documentation** - Document significant schema decisions
+
+## Database Strategy Options
+
+### SQL Databases (PostgreSQL, MySQL, SQLite, SQL Server)
+
+Characteristics:
+- Structured schema with defined tables and relationships
+- ACID transactions for data consistency
+- Powerful querying with SQL
+- Good for relational data
+- Mature tooling and libraries
+
+Tools:
+- ORM: Sequelize (Node.js), SQLAlchemy (Python), Hibernate (Java), Entity Framework (.NET)
+- Query Builder: Knex.js (Node.js), SqlAlchemy Core (Python), QueryDSL (Java)
+- Migration tools: Prisma Migrate, Flyway, Liquibase, Alembic
+
+Best for:
+- Complex relationships between entities
+- Strong consistency requirements
+- Transactional integrity
+- Complex queries
+- Team comfortable with SQL
+
+### NoSQL Databases (MongoDB, DynamoDB, CouchDB, Firestore)
+
+Characteristics:
+- Flexible/schemaless documents
+- Eventual consistency
+- Good horizontal scaling
+- Fast for simple lookups
+- Dev-friendly for rapid iteration
+
+Tools:
+- ODM: Mongoose (MongoDB), AWS SDK (DynamoDB), Firebase SDK (Firestore)
+- Schema validation: JSONSchema, Zod, Joi
+
+Best for:
+- Flexible/evolving data structures
+- Horizontal scaling
+- Fast document lookups
+- Real-time updates
+- Prototyping and MVPs
+
+### Managed Database Services (Supabase, Firebase, AWS RDS)
+
+Characteristics:
+- Hosted by cloud provider
+- Automatic backups and scaling
+- Built-in authentication
+- Real-time subscriptions (some)
+- Reduced infrastructure complexity
+
+Best for:
+- Rapid prototyping
+- Teams without DevOps expertise
+- Projects needing built-in features
+- Compliance-heavy requirements
+- Teams preferring managed services
+
+## Schema Design Patterns
+
+### Core Tables/Collections
+
+Base entities:
+- **Users**: Authentication and identity data
+- **Roles**: Permission groups
+- **Audit logs**: Track changes for compliance
+
+Related data:
+- Define relationships clearly
+- Use appropriate constraints (foreign keys, unique constraints)
+- Add indexes for common queries
+- Document connection between tables
+
+### Timestamps
+
+Include timestamps:
+- **Created at**: When record created (immutable)
+- **Updated at**: When record last modified
+- **Deleted at**: For soft deletes (when applicable)
+
+### IDs and Keys
+
+ID strategy:
+- **Primary key**: Uniquely identifies record
+- **Foreign key**: References another table (relational)
+- **Unique constraints**: Prevent duplicates
+- **Non-sequential IDs**: Use UUID or similar for security
+
+### Data Validation
+
+At database level:
+- Required fields (NOT NULL)
+- Data type constraints
+- Length constraints (for strings)
+- Enum constraints (for limited values)
+- Range constraints (for numbers)
+
+At application level:
+- Validate before insert/update
+- Validate format (email, URL, etc.)
+- Validate business rules
+- Return clear error messages
+
+## Query Patterns
+
+### Efficient Queries
+
+Do:
+- Use WHERE clauses to filter
+- Use indexes on filtered fields
+- Use SELECT specific columns
+- Use LIMIT for pagination
+- Use JOIN for related data
+- Use aggregation functions
+- Batch operations when possible
+
+Don't:
+- SELECT *  (select all columns)
+- N+1 queries (query in loop)
+- Unindexed large scans
+- Complex JOINs without indexes
+- Missing WHERE clause
+- Fetching unused data
+
+### Pagination
+
+Pagination pattern:
+1. Accept limit and offset parameters
+2. Validate reasonable limit (max 100-1000)
+3. Query with LIMIT and OFFSET
+4. Return total count optionally
+5. Include nextPage/previousPage links
+
+### Relationships
+
+Query related data:
+- One-to-many: JOIN or separate queries
+- Many-to-many: Junction table with JOINs
+- One-to-one: JOIN or embed in document
+- Hierarchical: Recursive queries or denormalization
+
+## Security
+
+### Access Control
+
+Implement at database:
+- Row-level security (RLS in PostgreSQL, Firestore)
+- Column-level access restrictions
+- Database-level user permissions
+
+Implement at application:
+- Verify user owns resource before returning
+- Check permissions before allowing modifications
+- Log access to sensitive data
+- Rate limit database operations
+
+### Sensitive Data
+
+Protect sensitive data:
+- Hash passwords (never store plaintext)
+- Encrypt PII at rest
+- Never log sensitive data
+- Mask sensitive data in backups
+- Use parameterized queries to prevent injection
+
+### Backup & Recovery
+
+Backup strategy:
+- Automated daily backups
+- Test recovery procedures
+- Retain backups for compliance period
+- Encrypt backups at rest
+- Store backups separately from primary database
+
+## Performance
+
+### Indexing
+
+Index columns that are:
+- Frequently filtered (WHERE clause)
+- Used in JOINs
+- Used in ORDER BY
+- Used in DISTINCT
+
+Don't over-index:
+- Too many indexes slow down writes
+- Indexes require storage space
+- Maintain only used indexes
+
+### Connection Management
+
+Connection pooling:
+- Reuse connections across requests
+- Configure reasonable pool size (10-20 connections)
+- Set idle timeout
+- Monitor connection usage
+- Alert on connection exhaustion
+
+### Query Optimization
+
+Optimize slow queries:
+1. Profile query execution time
+2. Check execution plan
+3. Add missing indexes
+4. Rewrite queries if needed
+5. Consider denormalization if needed
+6. Verify schema design
+
+## Monitoring & Maintenance
+
+### Health Checks
+
+Monitor:
+- Database connectivity
+- Query performance (slow query logs)
+- Connection pool status
+- Storage space usage
+- Backup completion
+- Replication lag (if applicable)
+
+### Database Maintenance
+
+Regular tasks:
+- Update statistics/analyze
+- Vacuum/compact (depending on DB)
+- Rebuild indexes if needed
+- Clean up old audit logs
+- Review and optimize slow queries
+
+## Testing
+
+### Test Data
+
+Setup:
+- Use separate test database
+- Reset data before each test
+- Use factories for consistent test data
+- Seed with realistic data
+
+Testing patterns:
+- Test CRUD operations
+- Test relationships
+- Test constraints
+- Test error cases
+- Test performance
+
+### Test Examples
+
+Test: Create and retrieve user
+1. Create user with valid data
+2. Retrieve by ID
+3. Verify data matches
+
+Test: Enforce unique constraint
+1. Create user with email
+2. Attempt to create another with same email
+3. Verify error is returned
+
+Test: Cascade delete
+1. Create parent and child records
+2. Delete parent
+3. Verify child is deleted
+
+---
+
+Remember: Good database design prevents bugs, improves performance, and makes your application maintainable.