@paths.design/caws-cli 4.0.0 → 4.1.0

package/templates/.cursor/rules/03-infrastructure-standards.mdc

@@ -1,251 +0,0 @@
----
-description: Infrastructure, deployment, and operational standards
-globs:
-alwaysApply: true
----
-
-# Infrastructure & Deployment Standards
-
-## Database Standards
-
-### Connection Management
-
-- **Connection Pooling**: Always use connection pools, never single connections
-- **Pool Configuration**: Set appropriate min/max connections based on load
-- **Timeout Handling**: Configure connection, query, and idle timeouts
-- **Health Checks**: Implement connection health validation
-- **Graceful Shutdown**: Properly close connections on application shutdown
-
-### Schema Management
-
-- **Migration Scripts**: Version-controlled, transactional migrations
-- **Downgrade Scripts**: Provide rollback migrations for all changes
-- **Idempotent Operations**: Migrations safe to run multiple times
-- **Testing**: All migrations tested against production-like data
-- **Documentation**: Migration purpose and impact clearly documented
-
-### Data Integrity
-
-- **Constraints**: Foreign keys, unique constraints, check constraints
-- **Transactions**: All multi-table operations in transactions
-- **Atomicity**: Either all changes succeed or all fail
-- **Consistency**: Database always in valid state
-- **Isolation**: Concurrent operations don't interfere
-
-## API Standards
-
-### RESTful Design
-
-- **Resource Naming**: Plural nouns, consistent casing
-- **HTTP Methods**: GET (read), POST (create), PUT/PATCH (update), DELETE
-- **Status Codes**: Proper HTTP status codes (200, 201, 400, 404, 500, etc.)
-- **Content Types**: JSON for data, appropriate content-type headers
-- **Versioning**: API versioning strategy (URL, headers, or content negotiation)
-
-### Error Handling
-
-- **Structured Errors**: Consistent error response format
-- **Error Codes**: Machine-readable error codes with human-readable messages
-- **Logging**: All errors logged with appropriate severity
-- **Client Guidance**: Error responses include actionable information
-- **No Information Leakage**: Sensitive information not exposed in errors
-
-## Security Standards
-
-### Authentication & Authorization
-
-- **Token Management**: Secure token storage and validation
-- **Session Handling**: Proper session lifecycle management
-- **Role-Based Access**: Clear role definitions and enforcement
-- **Permission Checking**: Every operation validates permissions
-- **Audit Logging**: All security events logged
-
-### Input Validation
-
-- **Schema Validation**: All inputs validated against schemas
-- **Sanitization**: User input sanitized before processing
-- **Type Safety**: Runtime type checking for external inputs
-- **Length Limits**: Reasonable limits on input sizes
-- **Content Filtering**: Malicious content detection and blocking
-
-## Monitoring & Observability
-
-### Logging Standards
-
-- **Structured Logging**: JSON format with consistent field names
-- **Log Levels**: ERROR, WARN, INFO, DEBUG appropriately used
-- **Context Information**: Request IDs, user context, operation details
-- **Performance Logging**: Response times, resource usage
-- **Error Correlation**: Related events linked together
-
-### Metrics Collection
-
-- **Business Metrics**: User registrations, API calls, conversion rates
-- **Performance Metrics**: Response times, throughput, error rates
-- **Resource Metrics**: CPU, memory, disk, network usage
-- **Custom Metrics**: Application-specific KPIs
-- **Alert Thresholds**: Defined thresholds for automated alerts
-
-### Health Checks
-
-- **Application Health**: Service availability and responsiveness
-- **Dependency Health**: Database, external APIs, message queues
-- **Resource Health**: Disk space, memory, connection pools
-- **Business Health**: Core business operations functional
-- **Automated Recovery**: Self-healing capabilities
-
-## Deployment Standards
-
-### Environment Configuration
-
-- **Environment Variables**: No hardcoded configuration values
-- **Configuration Files**: Version-controlled, environment-specific configs
-- **Secrets Management**: Secure storage and access for secrets
-- **Validation**: Configuration validated at startup
-- **Documentation**: All configuration options documented
-
-### Container Standards
-
-- **Base Images**: Minimal, secure base images
-- **Layer Optimization**: Efficient layer caching and ordering
-- **Security Scanning**: Container images scanned for vulnerabilities
-- **Resource Limits**: CPU and memory limits set appropriately
-- **Health Checks**: Container health checks implemented
-
-### CI/CD Pipeline
-
-- **Automated Testing**: Full test suite runs on every commit
-- **Security Scanning**: Automated security scans in pipeline
-- **Performance Testing**: Automated performance regression tests
-- **Deployment Automation**: Zero-touch deployment processes
-- **Rollback Capability**: Automated rollback procedures
-
-## Reliability Standards
-
-### Circuit Breaker Pattern
-
-- **Failure Threshold**: Configurable failure count before opening
-- **Recovery Timeout**: Time before attempting recovery
-- **Success Threshold**: Successes needed to close circuit
-- **Fallback Behavior**: Graceful degradation when circuit open
-- **Monitoring**: Circuit state and failure rates monitored
-
-### Retry Logic
-
-- **Exponential Backoff**: Increasing delay between retries
-- **Jitter**: Randomization to prevent thundering herd
-- **Maximum Retries**: Configurable retry limits
-- **Retry Conditions**: Only retry appropriate error types
-- **Circuit Integration**: Retry logic respects circuit breaker state
-
-### Graceful Degradation
-
-- **Feature Flags**: Ability to disable features under load
-- **Fallback Content**: Cached or simplified content when services fail
-- **Progressive Enhancement**: Core functionality works without extras
-- **User Communication**: Clear messaging about degraded functionality
-- **Automatic Recovery**: Services automatically recover when possible
-
-## Performance Standards
-
-### Response Time SLAs
-
-- **API Endpoints**: P95 response times defined and monitored
-- **Page Load Times**: Frontend performance budgets
-- **Database Queries**: Query performance thresholds
-- **Background Jobs**: Job completion time limits
-- **Real-time Operations**: Sub-second response requirements
-
-### Resource Management
-
-- **Memory Usage**: Monitor and limit memory consumption
-- **CPU Utilization**: Efficient CPU usage patterns
-- **Disk I/O**: Optimize file system operations
-- **Network Usage**: Efficient network communication
-- **Connection Pools**: Proper sizing of database and external connections
-
-### Caching Strategy
-
-- **Cache Invalidation**: Proper cache invalidation strategies
-- **Cache Penetration**: Protection against cache penetration attacks
-- **Cache Warming**: Proactive cache population for hot data
-- **Distributed Caching**: Scalable caching across multiple instances
-- **Cache Monitoring**: Cache hit rates and performance monitoring
-
-## Scalability Standards
-
-### Horizontal Scaling
-
-- **Stateless Design**: Applications designed for horizontal scaling
-- **Shared Nothing**: Instances don't share local state
-- **Load Balancing**: Proper load distribution across instances
-- **Session Management**: Distributed session storage
-- **Configuration**: Centralized configuration management
-
-### Database Scaling
-
-- **Read Replicas**: Read operations distributed across replicas
-- **Sharding Strategy**: Data partitioning strategy defined
-- **Connection Pooling**: Efficient connection management
-- **Query Optimization**: Efficient query patterns
-- **Indexing Strategy**: Appropriate indexes for query patterns
-
-### Asynchronous Processing
-
-- **Message Queues**: Asynchronous task processing
-- **Background Jobs**: Long-running tasks processed asynchronously
-- **Event-Driven Architecture**: Loose coupling through events
-- **Dead Letter Queues**: Handling of failed message processing
-- **Monitoring**: Queue depth and processing rate monitoring
-
-## Backup & Recovery
-
-### Data Backup
-
-- **Regular Backups**: Automated backup schedules
-- **Backup Verification**: Backup integrity validation
-- **Retention Policies**: Backup retention periods defined
-- **Encryption**: Backup data encrypted at rest and in transit
-- **Testing**: Backup restoration regularly tested
-
-### Disaster Recovery
-
-- **Recovery Time Objective (RTO)**: Maximum acceptable downtime
-- **Recovery Point Objective (RPO)**: Maximum data loss acceptable
-- **Multi-Region Deployment**: Geographic redundancy
-- **Failover Procedures**: Automated and manual failover processes
-- **Recovery Testing**: Regular disaster recovery drills
-
-### Business Continuity
-
-- **Service Level Agreements**: Defined uptime and performance guarantees
-- **Incident Response**: Defined incident response procedures
-- **Communication Plans**: Stakeholder communication during incidents
-- **Post-Mortem Process**: Incident analysis and improvement process
-- **Continuous Improvement**: Regular review and improvement of processes
-
-## Compliance & Governance
-
-### Security Compliance
-
-- **Data Encryption**: Data encrypted at rest and in transit
-- **Access Controls**: Principle of least privilege enforced
-- **Audit Trails**: Comprehensive audit logging
-- **Vulnerability Management**: Regular security assessments
-- **Incident Response**: Security incident response procedures
-
-### Data Privacy
-
-- **Data Classification**: Sensitive data properly classified
-- **Retention Policies**: Data retention periods defined
-- **Consent Management**: User consent properly managed
-- **Data Deletion**: Right to deletion implemented
-- **Privacy Impact Assessments**: Privacy risks assessed
-
-### Regulatory Compliance
-
-- **GDPR Compliance**: EU data protection regulations
-- **CCPA Compliance**: California consumer privacy regulations
-- **Industry Standards**: Relevant industry compliance requirements
-- **Audit Readiness**: Systems designed for regulatory audits
-- **Documentation**: Compliance evidence properly documented

package/templates/.cursor/rules/04-documentation-integrity.mdc

@@ -1,291 +0,0 @@
----
-description: Documentation must match implementation reality - no claims of unimplemented features
-globs:
-alwaysApply: true
----
-
-# Documentation Integrity & Reality Alignment
-
-## Core Principle
-
-**Documentation must accurately reflect implementation reality.** Never claim features exist that don't work, APIs that aren't implemented, or capabilities that are just placeholders.
-
-## Documentation Standards
-
-### README Accuracy
-
-- **Feature Claims**: Only document features that are fully implemented and tested
-- **Installation Instructions**: Must work on a clean environment
-- **Usage Examples**: Code examples must run without errors
-- **API Documentation**: All documented endpoints must exist and work
-- **Prerequisites**: All required dependencies and versions listed
-
-### API Documentation
-
-- **Endpoint Completeness**: All documented endpoints implemented
-- **Parameter Accuracy**: Request/response schemas match implementation
-- **Error Responses**: Documented error codes match actual errors
-- **Authentication**: Auth requirements match implementation
-- **Examples**: Working code examples for all major endpoints
-
-### Architecture Documentation
-
-- **Component Diagrams**: Reflect actual code structure
-- **Data Flow**: Match actual data processing paths
-- **Integration Points**: Document real integrations, not planned ones
-- **Deployment Architecture**: Match actual infrastructure
-- **Scaling Strategy**: Based on implemented capabilities
-
-## Implementation vs Documentation Verification
-
-### Feature Claims Verification
-
-Before documenting any feature, verify:
-
-- [ ] Feature fully implemented (not placeholder/mock)
-- [ ] Feature tested end-to-end
-- [ ] Feature handles error cases
-- [ ] Feature documented in user-facing docs
-- [ ] Feature matches acceptance criteria
-
-### API Documentation Verification
-
-For every documented API:
-
-- [ ] Endpoint exists and responds
-- [ ] Request/response formats match docs
-- [ ] Authentication works as documented
-- [ ] Error handling matches documentation
-- [ ] Rate limits implemented if documented
-
-### Code Documentation Verification
-
-For all public APIs:
-
-- [ ] JSDoc/TSDoc comments accurate
-- [ ] Parameter types match implementation
-- [ ] Return types correct
-- [ ] Error conditions documented
-- [ ] Usage examples work
-
-## Prohibited Documentation Patterns
-
-### ❌ Feature Bloat Documentation
-
-```markdown
-<!-- DON'T document unimplemented features -->
-
-## Features
-
-- ✅ User authentication
-- ✅ Real-time notifications
-- ✅ Advanced analytics dashboard <!-- Not implemented yet -->
-- ✅ Machine learning recommendations <!-- Placeholder only -->
-```
-
-### ❌ Vague Status Claims
-
-```markdown
-<!-- DON'T use ambiguous status -->
-
-Status: Production Ready (75% complete) <!-- Confusing -->
-Status: In Development (25% complete) <!-- Better -->
-```
-
-### ❌ Outdated Examples
-
-```javascript
-// DON'T: Example that doesn't work
-fetch("/api/users", {
-  method: "POST",
-  body: JSON.stringify({ name: "John" }), // Missing required email field
-});
-```
-
-### ❌ Missing Error Documentation
-
-```typescript
-// DON'T: Undocumented error conditions
-function processPayment(amount: number): Promise<PaymentResult> {
-  // What happens if amount < 0? Not documented
-}
-```
-
-## Documentation Maintenance Standards
-
-### Change Documentation Updates
-
-- **Breaking Changes**: Update documentation immediately
-- **New Features**: Document before release
-- **API Changes**: Update API docs in same PR
-- **Deprecations**: Mark deprecated features clearly
-- **Migration Guides**: Provide for breaking changes
-
-### Version Consistency
-
-- **Changelog**: Accurate for each version
-- **Version Numbers**: Match actual releases
-- **Deprecation Notices**: Clear timelines and alternatives
-- **Compatibility Matrix**: Accurate version compatibility
-
-### Documentation Testing
-
-- **Link Validation**: All links in docs work
-- **Code Example Testing**: Examples tested in CI
-- **Installation Verification**: Setup instructions tested
-- **Cross-Platform**: Docs work on documented platforms
-
-## Reality Alignment Checks
-
-### Implementation Inventory
-
-Maintain accurate inventory:
-
-- [ ] Count actual source files vs documented components
-- [ ] Verify test coverage matches claims
-- [ ] Check database schema matches docs
-- [ ] Validate configuration options exist
-- [ ] Confirm external integrations work
-
-### Feature Parity Audit
-
-Regular audits to ensure:
-
-- [ ] No documented features are missing
-- [ ] No implemented features are undocumented
-- [ ] No placeholder implementations documented as complete
-- [ ] No deprecated features still documented as current
-
-### User Experience Verification
-
-- [ ] Onboarding works as documented
-- [ ] Common use cases work end-to-end
-- [ ] Error messages helpful and accurate
-- [ ] Performance matches documented SLAs
-
-## Correct Documentation Patterns
-
-### ✅ Accurate Feature Status
-
-```markdown
-## Features
-
-### ✅ Implemented
-
-- User authentication with JWT tokens
-- Real-time notifications via WebSocket
-- Basic analytics dashboard
-
-### 🚧 In Development
-
-- Advanced ML recommendations (Q2 2025)
-- Multi-tenant isolation (Q1 2025)
-
-### 📋 Planned
-
-- AI-powered chat support (Q3 2025)
-```
-
-### ✅ Working Code Examples
-
-```javascript
-// POST /api/users
-const response = await fetch("/api/users", {
-  method: "POST",
-  headers: {
-    "Content-Type": "application/json",
-    Authorization: `Bearer ${token}`,
-  },
-  body: JSON.stringify({
-    name: "John Doe",
-    email: "john@example.com", // Required field included
-    password: "securePassword123",
-  }),
-});
-
-if (!response.ok) {
-  throw new Error(`Failed to create user: ${response.statusText}`);
-}
-
-const user = await response.json();
-console.log("Created user:", user);
-```
-
-### ✅ Complete API Documentation
-
-```typescript
-/**
- * Creates a new user account
- * @param userData User registration data
- * @returns Promise<User> The created user object
- * @throws ValidationError if email format invalid
- * @throws ConflictError if email already exists
- * @throws RateLimitError if too many requests
- */
-async function createUser(userData: CreateUserRequest): Promise<User> {
-  // Implementation
-}
-```
-
-### ✅ Realistic Status Claims
-
-```markdown
-# Project Status
-
-**Current Status**: In Development (Proof of Concept)
-
-**Production Readiness**: 25% - Core authentication and basic API working, but missing:
-
-- Database persistence (in-memory only)
-- Security hardening
-- Comprehensive testing
-- Production deployment pipeline
-
-**Next Milestone**: Alpha release (Q1 2025) with full persistence layer
-```
-
-## Documentation Quality Metrics
-
-### Completeness Score
-
-- **API Coverage**: % of public APIs documented
-- **Feature Documentation**: % of features with user docs
-- **Code Examples**: % of APIs with working examples
-- **Error Documentation**: % of error conditions documented
-
-### Accuracy Score
-
-- **Working Examples**: % of code examples that run successfully
-- **Link Validity**: % of documentation links that work
-- **Version Accuracy**: % of version references that are current
-- **Implementation Match**: % of documented features that work as described
-
-### Maintenance Score
-
-- **Update Frequency**: How often docs are updated vs code changes
-- **Review Coverage**: % of doc changes that are reviewed
-- **User Feedback**: Response time to documentation issues
-- **Cross-Platform**: % of supported platforms with verified docs
-
-## Enforcement Mechanisms
-
-### Automated Checks
-
-- **Documentation Tests**: CI runs documentation validation
-- **Link Checking**: Automated link validation in docs
-- **Example Testing**: Code examples executed in CI
-- **API Contract Testing**: Docs vs implementation validation
-
-### Review Requirements
-
-- **Documentation Reviews**: Require review for doc changes
-- **Implementation Reviews**: Check docs match implementation
-- **User Testing**: Validate docs from user perspective
-- **Cross-Functional Reviews**: Include different roles in reviews
-
-### Accountability Measures
-
-- **Documentation Debt**: Track unimplemented documented features
-- **Reality Gap Metrics**: Measure docs vs implementation accuracy
-- **User Feedback Integration**: Incorporate user-reported doc issues
-- **Continuous Improvement**: Regular documentation quality reviews