refactor: restructure cursor rules with new meta-rule architecture
- Remove legacy rule files (documentation.mdc, general_development.mdc, etc.) - Implement new meta-rule system with core, app, and feature categories - Add meta-rule files for different workflows (bug diagnosis, feature planning, etc.) - Create organized directory structure: core/, app/, features/, database/, etc. - Add comprehensive README.md for rules documentation - Establish new rule architecture with always-on and workflow-specific rules This restructuring improves rule organization, enables better workflow management, and provides clearer separation of concerns for different development tasks.
This commit is contained in:
Matthew Raymer
186
.cursor/rules/architecture/build_architecture_guard.mdc
Normal file
186
.cursor/rules/architecture/build_architecture_guard.mdc
Normal file
@@ -0,0 +1,186 @@
|
||||
|
||||
# Build Architecture Guard Directive
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-08-22
|
||||
**Status**: 🎯 **ACTIVE** - Build system protection guidelines
|
||||
|
||||
## Purpose
|
||||
|
||||
Protect the TimeSafari building architecture from unauthorized changes that
|
||||
could break the multi-platform build pipeline, deployment processes, or
|
||||
development workflow. This directive ensures all build system modifications
|
||||
follow proper review, testing, and documentation procedures.
|
||||
|
||||
**Note**: Recent Android build system enhancements (2025-08-22) include
|
||||
sophisticated asset validation, platform-specific API routing, and automatic
|
||||
resource regeneration. These features require enhanced testing and validation
|
||||
procedures.
|
||||
|
||||
## Protected Architecture Components
|
||||
|
||||
### Core Build Infrastructure
|
||||
|
||||
- **Vite Configuration Files**: `vite.config.*.mts` files
|
||||
|
||||
- **Build Scripts**: All scripts in `scripts/` directory
|
||||
|
||||
- **Package Scripts**: `package.json` build-related scripts
|
||||
|
||||
- **Platform Configs**: `capacitor.config.ts`, `electron/`, `android/`,
|
||||
|
||||
`ios/`
|
||||
|
||||
- **Docker Configuration**: `Dockerfile`, `docker-compose.yml`
|
||||
|
||||
- **Environment Files**: `.env.*`, `.nvmrc`, `.node-version`
|
||||
|
||||
### Android-Specific Build Validation
|
||||
|
||||
- **Asset Validation Scripts**:
|
||||
|
||||
`validate_android_assets()` function and resource checking
|
||||
|
||||
- **Resource Generation**: `capacitor-assets` integration and verification
|
||||
|
||||
- **Platform-Specific IP Handling**:
|
||||
|
||||
Android emulator vs physical device API routing
|
||||
|
||||
- **Build Mode Validation**: Development/test/production mode handling
|
||||
|
||||
- **Resource Fallback Logic**:
|
||||
|
||||
Automatic regeneration of missing Android resources
|
||||
|
||||
### Critical Build Dependencies
|
||||
|
||||
- **Build Tools**: Vite, Capacitor, Electron, Android SDK, Xcode
|
||||
|
||||
- **Asset Management**: `capacitor-assets.config.json`, asset scripts
|
||||
|
||||
- **Testing Infrastructure**: Playwright, Jest, mobile test scripts
|
||||
|
||||
- **CI/CD Pipeline**: GitHub Actions, build validation scripts
|
||||
|
||||
- **Service Worker Assembly**: `sw_scripts/`, `sw_combine.js`, WASM copy steps
|
||||
|
||||
## Change Authorization Requirements
|
||||
|
||||
### Level 1: Minor Changes (Requires Review)
|
||||
|
||||
- Documentation updates to `BUILDING.md`
|
||||
|
||||
- Non-breaking script improvements
|
||||
|
||||
- Test additions or improvements
|
||||
|
||||
- Asset configuration updates
|
||||
|
||||
**Process**: Code review + basic testing
|
||||
|
||||
### Level 2: Moderate Changes (Requires Testing)
|
||||
|
||||
- New build script additions
|
||||
|
||||
- Environment variable changes
|
||||
|
||||
- Dependency version updates
|
||||
|
||||
- Platform-specific optimizations
|
||||
|
||||
- **Build script argument parsing**:
|
||||
|
||||
New flag handling (--api-ip, --auto-run, --deploy)
|
||||
|
||||
- **Platform-specific environment overrides**:
|
||||
|
||||
Android API server IP customization
|
||||
|
||||
- **Asset regeneration logic**: Automatic fallback for missing Android resources
|
||||
|
||||
**Process**: Code review + platform testing + documentation update
|
||||
|
||||
### Level 3: Major Changes (Requires ADR)
|
||||
|
||||
- Build system architecture changes
|
||||
|
||||
- New platform support
|
||||
|
||||
- Breaking changes to build scripts
|
||||
|
||||
- Major dependency migrations
|
||||
|
||||
**Process**: ADR creation + comprehensive testing + team review
|
||||
|
||||
## Prohibited Actions
|
||||
|
||||
### ❌ Never Allow Without ADR
|
||||
|
||||
- **Delete or rename** core build scripts
|
||||
|
||||
- **Modify** `package.json` build script names
|
||||
|
||||
- **Change** Vite configuration structure
|
||||
|
||||
- **Remove** platform-specific build targets
|
||||
|
||||
- **Alter** Docker build process
|
||||
|
||||
- **Modify** CI/CD pipeline without testing
|
||||
|
||||
### ❌ Never Allow Without Testing
|
||||
|
||||
- **Update** build dependencies
|
||||
|
||||
- **Change** environment configurations
|
||||
|
||||
- **Modify** asset generation scripts
|
||||
|
||||
- **Alter** test infrastructure
|
||||
|
||||
- **Update** platform SDK versions
|
||||
|
||||
---
|
||||
|
||||
**See also**:
|
||||
|
||||
- `.cursor/rules/architecture/build_validation.mdc` for
|
||||
|
||||
detailed validation procedures
|
||||
|
||||
- `.cursor/rules/architecture/build_testing.mdc` for testing requirements
|
||||
|
||||
**Status**: Active build protection guidelines
|
||||
**Priority**: Critical
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: None
|
||||
**Stakeholders**: Development team, DevOps team, Build team
|
||||
|
||||
**Estimated Effort**: Ongoing vigilance
|
||||
**Dependencies**: All build system components
|
||||
**Stakeholders**: Development team, DevOps, Platform owners
|
||||
**Next Review**: 2025-09-22
|
||||
|
||||
## Model Implementation Checklist
|
||||
|
||||
### Before Build Changes
|
||||
|
||||
- [ ] **Change Level**: Determine if change is L1, L2, or L3
|
||||
- [ ] **Impact Assessment**: Assess impact on build system architecture
|
||||
- [ ] **ADR Requirement**: Check if ADR is required for major changes
|
||||
- [ ] **Testing Planning**: Plan appropriate testing for change level
|
||||
|
||||
### During Build Changes
|
||||
|
||||
- [ ] **Guard Compliance**: Ensure changes comply with build architecture guard
|
||||
- [ ] **Documentation**: Document changes according to level requirements
|
||||
- [ ] **Testing**: Execute appropriate testing for change level
|
||||
- [ ] **Review Process**: Follow required review process for change level
|
||||
|
||||
### After Build Changes
|
||||
|
||||
- [ ] **Validation**: Verify build system still functions correctly
|
||||
- [ ] **Documentation Update**: Update relevant documentation
|
||||
- [ ] **Team Communication**: Communicate changes to affected teams
|
||||
- [ ] **Monitoring**: Monitor for any build system issues
|
||||
Reference in New Issue
Block a user