agents-templated 1.2.0 → 1.2.2

package/templates/agent-docs/ARCHITECTURE.md

@@ -0,0 +1,261 @@
+## Project Guidelines
+
+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.
+
+- 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.
+
+Read this file first to understand the architecture, then consult `AGENTS.md` for agent delegation.
+
+---
+
+## 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
+
+---
+
+## Core Architecture Principles
+
+### 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
+
+### 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
+
+### 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
+
+### 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
+
+### 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
+
+---
+
+## 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
+
+### 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
+
+### 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
+
+---
+
+## 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.

package/templates/agent-docs/README.md

@@ -0,0 +1,53 @@
+# Technology-Agnostic Development Template
+
+This template has been installed by the agents-templated npm package.
+
+## What's Included
+
+Depending on what you installed, you may have:
+
+- **AGENTS.MD**: Agent patterns and delegation guide
+- **ARCHITECTURE.md**: Project guidelines and architecture
+- **AI_INSTRUCTIONS.md**: Instructions for AI assistants
+- **agents/rules/**: Development rules and patterns (6 files)
+- **agents/skills/**: Reusable agent skills
+- **CLAUDE.md**: Claude AI configuration
+- **GEMINI.md**: Google Gemini configuration
+- **.github/copilot-instructions.md**: GitHub Copilot configuration
+- **.cursorrules**: Cursor IDE configuration
+
+## Installation Options
+
+If you're missing some components, you can install them:
+
+```bash
+# Install everything
+agents-templated init --all
+
+# Or install specific components
+agents-templated init --docs      # Documentation files only
+agents-templated init --rules     # Agent rules only
+agents-templated init --skills    # Skills only
+agents-templated init --github    # GitHub Copilot config only
+
+# List available components
+agents-templated list
+```
+
+## Rules and Skills
+
+- **Rules** (`agents/rules/*.mdc`): Markdown files with YAML frontmatter (`description`, `globs`, `alwaysApply`). AI agents use them to know when to apply each rule. Adapt the content to your stack.
+- **Skills** (`agents/skills/*/SKILL.md`): Extend agent capabilities (e.g. find-skills, web-design-guidelines). Each has a name, description, and when to use.
+
+## Getting Started
+
+1. Review AI_INSTRUCTIONS.md for AI assistance guidance
+2. Review ARCHITECTURE.md for overall project guidelines
+3. Review AGENTS.MD for agent patterns
+4. Adapt the rules to your specific technology stack
+5. Configure your AI assistant (Cursor, Copilot, Claude, Gemini)
+
+## Documentation
+
+For full documentation, visit: https://github.com/rickandrew2/agents-projects-templated
+

package/templates/.vscode-ai-rules.md

@@ -1,111 +0,0 @@
-# VSCode AI Rules
-
-This project uses enterprise-grade, technology-agnostic development patterns for all AI-powered development tools in VSCode, including:
-- GitHub Copilot Chat
-- IntelliCode
-- Other VSCode AI extensions
-
-## Quick References
-
-- **Project Guidelines**: See `CLAUDE.md`
-- **Agent Patterns**: See `AGENTS.md`
-- **Detailed Rules**: See `agents/rules/*.mdc` files
-- **Available Skills**: See `agents/skills/` directory
-
-## Core Rules for VSCode AI Assistants
-
-### 1. Security-First Development
-- Validate ALL user inputs with appropriate schema validation
-- Implement secure authentication flows with proper session management
-- Apply rate limiting to public API endpoints
-- Use role-based access control for authorization
-- Never expose sensitive data in error responses or logs
-- Reference: `agents/rules/security.mdc`
-
-### 2. Testing Strategy
-- Unit tests: 80% coverage of business logic
-- Integration tests: 15% coverage of API/database interactions
-- E2E tests: 5% coverage of critical user journeys
-- All business logic must have appropriate tests
-- Reference: `agents/rules/testing.mdc`
-
-### 3. Type Safety & Validation
-- Use strong typing available in your chosen language
-- Implement runtime validation at API boundaries
-- Apply schema validation to all form inputs and API requests
-- Reference: `agents/rules/core.mdc`
-
-## Agent Delegation Pattern
-
-When implementing features, follow the agent patterns from `AGENTS.md`:
-
-- **FrontendAgent**: UI/Design components, accessibility, responsive layouts
-- **BackendAgent**: API routes, business logic, authentication
-- **DatabaseAgent**: Schema design, migrations, data access patterns
-- **TestAgent**: Testing strategy, coverage, test organization
-- **SecurityAgent**: Security patterns, input validation, access control
-- **ReviewerAgent**: Code quality, performance, accessibility compliance
-
-## Technology Stack Adaptation
-
-These rules apply regardless of your chosen tech stack. Adapt them to your specific framework:
-
-### Frontend
-- **React/Next.js/Vue/Svelte**: Component-based with proper state management
-- **Angular**: Component + service architecture
-- **Traditional**: Server-side rendering with progressive enhancement
-
-### Backend
-- **Node.js**: Express, Fastify, or framework-specific patterns
-- **Python**: Django, FastAPI, Flask with ORM patterns
-- **Go**: Gin, Echo, or similar frameworks
-- **Other**: Adapt patterns to your chosen framework
-
-### Database
-- **SQL**: PostgreSQL, MySQL with ORM/migrations
-- **NoSQL**: MongoDB, DynamoDB with document validation
-- **Cloud**: Firebase, Supabase with row-level security
-
-## Critical Rules (MUST FOLLOW)
-
-1. **Input Validation**: ALL user inputs must be validated with schema validation
-2. **Authentication**: Implement secure, tested authentication flows
-3. **Rate Limiting**: Public endpoints MUST have rate limiting
-4. **Authorization**: Role-based access control with proper checks
-5. **Error Handling**: Never expose sensitive information in errors
-6. **Database**: Use ORM/ODM patterns, avoid raw queries
-7. **Testing**: All business logic must have appropriate test coverage
-8. **Accessibility**: WCAG 2.1 AA compliance for user-facing components
-9. **Documentation**: Keep README, CLAUDE.md, and AGENTS.md updated
-10. **Performance**: Monitor bundle size, implement lazy loading, optimize assets
-
-## Code Quality Standards
-
-- **Type Safety**: Strict typing, no loose type usage
-- **Readability**: Clear names, proper documentation, logical organization
-- **Performance**: Efficient algorithms, appropriate caching
-- **Maintainability**: Modular design, separation of concerns, SOLID principles
-
-## When to Reference Each File
-
-- **CLAUDE.md**: For architecture decisions and technology stack guidance
-- **AGENTS.md**: For agent responsibilities and when to delegate
-- **agents/rules/*.mdc**: For specific implementation patterns:
-  - `core.mdc`: Core principles and architecture
-  - `security.mdc`: Security patterns and best practices
-  - `testing.mdc`: Testing strategy and patterns
-  - `frontend.mdc`: Frontend development patterns
-  - `database.mdc`: Database and data access patterns
-  - `style.mdc`: Code style and formatting guidelines
-- **agents/skills/**: For reusable domain-specific implementations
-
-## For More Information
-
-Explore the `agents/skills/` directory for domain-specific guidance on common tasks:
-- Each skill provides specific, actionable guidance
-- Reference skills when implementing similar features
-- Skills build on the core rules above
-
----
-
-All AI assistants in VSCode should follow these rules consistently to maintain code quality, security, and maintainability across the project.