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
306
.cursor/rules/README.md
Normal file
306
.cursor/rules/README.md
Normal file
@@ -0,0 +1,306 @@
|
||||
# .cursor Rules Organization
|
||||
|
||||
This directory contains all the rules and guidelines for AI assistants working
|
||||
with the TimeSafari project.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
### **`core/`** - Core Principles and Context
|
||||
|
||||
Core rules that apply to all AI interactions and provide fundamental context.
|
||||
|
||||
- **`base_context.mdc`** - Human competence first principles and interaction guidelines
|
||||
- **`harbor_pilot_universal.mdc`** - Technical guide creation and investigation rules
|
||||
- **`less_complex.mdc`** - Minimalist solution principle and complexity guidelines
|
||||
|
||||
### **`development/`** - Development Practices and Standards
|
||||
|
||||
Rules for software development, coding standards, and development workflows.
|
||||
|
||||
- **`software_development.mdc`** - Core development principles and evidence requirements
|
||||
- **`type_safety_guide.mdc`** - TypeScript type safety guidelines and best practices
|
||||
- **`development_guide.mdc`** - Development environment setup and standards
|
||||
- **`logging_standards.mdc`** - Logging implementation standards and rules
|
||||
- **`logging_migration.mdc`** - Migration from console.* to structured logging
|
||||
- **`time.mdc`** - Time handling principles and UTC standards
|
||||
- **`time_examples.mdc`** - Practical time implementation examples
|
||||
- **`time_implementation.mdc`** - Detailed time implementation guidelines
|
||||
- **`realistic_time_estimation.mdc`** - Time estimation framework and principles
|
||||
- **`planning_examples.mdc`** - Planning examples and best practices
|
||||
- **`complexity_assessment.mdc`** - Complexity evaluation and assessment
|
||||
- **`dependency_management.mdc`** - Dependency management and version control
|
||||
- **`asset_configuration.mdc`** - Asset configuration and build integration
|
||||
- **`research_diagnostic.mdc`** - Research and investigation workflows
|
||||
- **`investigation_report_example.mdc`** - Investigation report templates and examples
|
||||
- **`historical_comment_management.mdc`** - Historical comment transformation rules
|
||||
- **`historical_comment_patterns.mdc`** - Comment transformation patterns and examples
|
||||
|
||||
### **`architecture/`** - Architecture and Design Patterns
|
||||
|
||||
Rules for architectural decisions, patterns, and system design.
|
||||
|
||||
- **`build_architecture_guard.mdc`** - Build system protection and change levels
|
||||
- **`build_validation.mdc`** - Build validation procedures and testing
|
||||
- **`build_testing.mdc`** - Build testing requirements and feedback collection
|
||||
|
||||
### **`app/`** - Application-Specific Rules
|
||||
|
||||
Rules specific to the TimeSafari application and its architecture.
|
||||
|
||||
- **`timesafari.mdc`** - Core application context and principles
|
||||
- **`timesafari_platforms.mdc`** - Platform-specific implementation guidelines
|
||||
- **`timesafari_development.mdc`** - TimeSafari development workflow
|
||||
- **`architectural_decision_record.mdc`** - ADR creation and management
|
||||
- **`architectural_implementation.mdc`** - Architecture implementation guidelines
|
||||
- **`architectural_patterns.mdc`** - Architectural patterns and examples
|
||||
- **`architectural_examples.mdc`** - Architecture examples and testing
|
||||
|
||||
### **`database/`** - Database and Data Management
|
||||
|
||||
Rules for database operations, migrations, and data handling.
|
||||
|
||||
- **`absurd-sql.mdc`** - Absurd SQL implementation and worker thread setup
|
||||
- **`legacy_dexie.mdc`** - Legacy Dexie migration guidelines
|
||||
|
||||
### **`workflow/`** - Process and Workflow Management
|
||||
|
||||
Rules for development workflows, version control, and process management.
|
||||
|
||||
- **`version_control.mdc`** - Version control principles and commit guidelines
|
||||
- **`version_sync.mdc`** - Version synchronization and changelog management
|
||||
- **`commit_messages.mdc`** - Commit message format and conventions
|
||||
|
||||
### **`features/** - Feature-Specific Implementations
|
||||
|
||||
Rules for implementing specific features across platforms.
|
||||
|
||||
- **`camera-implementation.mdc`** - Camera feature implementation overview
|
||||
- **`camera_technical.mdc`** - Technical camera implementation details
|
||||
- **`camera_platforms.mdc`** - Platform-specific camera implementation
|
||||
|
||||
### **`docs/`** - Documentation Standards
|
||||
|
||||
Rules for creating and maintaining documentation.
|
||||
|
||||
- **`markdown_core.mdc`** - Core markdown formatting standards
|
||||
- **`markdown_templates.mdc`** - Document templates and examples
|
||||
- **`markdown_workflow.mdc`** - Markdown validation and workflow
|
||||
- **`documentation.mdc`** - Documentation generation principles
|
||||
- **`meta_rule_usage_guide.md`** - How to use meta-rules in practice
|
||||
|
||||
### **`templates/`** - Templates and Examples
|
||||
|
||||
Template files and examples for various documentation types.
|
||||
|
||||
- **`adr_template.mdc`** - Architectural Decision Record template
|
||||
|
||||
### **Meta-Rules** - Workflow Bundling
|
||||
|
||||
High-level meta-rules that bundle related sub-rules for specific workflows.
|
||||
|
||||
- **`meta_core_always_on.mdc`** - Core rules that apply to every single prompt
|
||||
- **`meta_documentation.mdc`** - Documentation writing and education workflow
|
||||
- **`meta_feature_planning.mdc`** - Feature planning workflow bundling
|
||||
- **`meta_bug_diagnosis.mdc`** - Bug investigation workflow bundling
|
||||
- **`meta_bug_fixing.mdc`** - Bug fix implementation workflow bundling
|
||||
- **`meta_feature_implementation.mdc`** - Feature implementation workflow bundling
|
||||
- **`meta_research.mdc`** - Investigation and research workflow bundling
|
||||
|
||||
### **Workflow State Management**
|
||||
|
||||
The project uses a sophisticated workflow state management system to ensure systematic development processes and maintain code quality across all phases of development.
|
||||
|
||||
#### **Workflow State System**
|
||||
|
||||
The workflow state is managed through `.cursor/rules/.workflow_state.json` and enforces different modes with specific constraints. The system automatically tracks workflow progression and maintains a complete history of mode transitions.
|
||||
|
||||
**Available Modes**:
|
||||
- **`diagnosis`** - Investigation and analysis phase (read-only)
|
||||
- **`fixing`** - Implementation and bug fixing phase (full access)
|
||||
- **`planning`** - Design and architecture phase (design only)
|
||||
- **`research`** - Investigation and research phase (investigation only)
|
||||
- **`documentation`** - Documentation writing phase (writing only)
|
||||
|
||||
**Mode Constraints**:
|
||||
```json
|
||||
{
|
||||
"diagnosis": {
|
||||
"mode": "read_only",
|
||||
"forbidden": ["modify", "create", "build", "commit"],
|
||||
"allowed": ["read", "search", "analyze", "document"]
|
||||
},
|
||||
"fixing": {
|
||||
"mode": "implementation",
|
||||
"forbidden": [],
|
||||
"allowed": ["modify", "create", "build", "commit", "test"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Workflow History Tracking**:
|
||||
|
||||
The system automatically maintains a `workflowHistory` array that records all mode transitions and meta-rule invocations:
|
||||
|
||||
```json
|
||||
{
|
||||
"workflowHistory": [
|
||||
{
|
||||
"mode": "research",
|
||||
"invoked": "meta_core_always_on.mdc",
|
||||
"timestamp": "2025-08-25T02:14:37Z"
|
||||
},
|
||||
{
|
||||
"mode": "diagnosis",
|
||||
"invoked": "meta_bug_diagnosis.mdc",
|
||||
"timestamp": "2025-08-25T02:14:37Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**History Entry Format**:
|
||||
- **`mode`**: The workflow mode that was activated
|
||||
- **`invoked`**: The specific meta-rule that triggered the mode change
|
||||
- **`timestamp`**: UTC timestamp when the mode transition occurred
|
||||
|
||||
**History Purpose**:
|
||||
- **Workflow Continuity**: Track progression through development phases
|
||||
- **Meta-Rule Usage**: Monitor which rules are invoked and when
|
||||
- **Temporal Context**: Maintain chronological order of workflow changes
|
||||
- **State Persistence**: Preserve workflow history across development sessions
|
||||
- **Debugging Support**: Help diagnose workflow state issues
|
||||
- **Process Analysis**: Understand development patterns and meta-rule effectiveness
|
||||
|
||||
#### **Commit Override System**
|
||||
|
||||
The workflow includes a flexible commit override mechanism that allows commits on demand while maintaining workflow integrity:
|
||||
|
||||
```json
|
||||
{
|
||||
"overrides": {
|
||||
"commit": {
|
||||
"allowed": true,
|
||||
"requires_override": true,
|
||||
"override_reason": "user_requested"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Override Benefits**:
|
||||
- ✅ **Investigation Commits**: Document findings during diagnosis phases
|
||||
- ✅ **Work-in-Progress**: Commit partial solutions during complex investigations
|
||||
- ✅ **Emergency Fixes**: Commit critical fixes without mode transitions
|
||||
- ✅ **Flexible Workflow**: Maintain systematic approach while accommodating real needs
|
||||
|
||||
**Override Limitations**:
|
||||
- ❌ **Does NOT bypass**: Version control rules, commit message standards, or security requirements
|
||||
- ❌ **Does NOT bypass**: Code quality standards, testing requirements, or documentation requirements
|
||||
|
||||
#### **Workflow Enforcement**
|
||||
|
||||
The system automatically enforces workflow constraints through the core always-on rules:
|
||||
|
||||
**Before Every Interaction**:
|
||||
1. **Read current workflow state** from `.cursor/rules/.workflow_state.json`
|
||||
2. **Identify current mode** and its constraints
|
||||
3. **Validate user request** against current mode constraints
|
||||
4. **Enforce constraints** before generating response
|
||||
5. **Guide model behavior** based on current mode
|
||||
|
||||
**Mode-Specific Enforcement**:
|
||||
- **Diagnosis Mode**: Blocks modification, creation, building, and commits
|
||||
- **Fixing Mode**: Allows full implementation and testing capabilities
|
||||
- **Planning Mode**: Focuses on design and architecture, blocks implementation
|
||||
- **Research Mode**: Enables investigation and analysis, blocks modification
|
||||
- **Documentation Mode**: Allows writing and editing, blocks implementation
|
||||
|
||||
#### **Workflow Transitions**
|
||||
|
||||
To change workflow modes, invoke the appropriate meta-rule:
|
||||
|
||||
```bash
|
||||
# Switch to bug fixing mode
|
||||
@meta_bug_fixing.mdc
|
||||
|
||||
# Switch to feature planning mode
|
||||
@meta_feature_planning.mdc
|
||||
|
||||
# Switch to documentation mode
|
||||
@meta_documentation.mdc
|
||||
```
|
||||
|
||||
**Transition Requirements**:
|
||||
- **Mode Changes**: Require explicit meta-rule invocation
|
||||
- **State Updates**: Automatically update workflow state file
|
||||
- **Constraint Enforcement**: Immediately apply new mode constraints
|
||||
- **History Tracking**: Automatically maintained in `workflowHistory` array
|
||||
- **Timestamp Recording**: Each transition recorded with UTC timestamp
|
||||
|
||||
#### **Integration with Development Process**
|
||||
|
||||
The workflow system integrates seamlessly with existing development practices:
|
||||
|
||||
**Version Control**:
|
||||
- All commits must follow TimeSafari commit message standards
|
||||
- Security audit checklists are enforced regardless of workflow mode
|
||||
- Documentation updates are required for substantial changes
|
||||
|
||||
**Quality Assurance**:
|
||||
- Code quality standards (PEP8, TypeScript, etc.) are always enforced
|
||||
- Testing requirements apply to all implementation work
|
||||
- Documentation standards are maintained across all phases
|
||||
|
||||
**Build System**:
|
||||
- Build Architecture Guard protects critical build files
|
||||
- Platform-specific build processes respect workflow constraints
|
||||
- Asset generation follows established patterns
|
||||
|
||||
**Migration Context**:
|
||||
- Database migration work respects investigation vs. implementation phases
|
||||
- Component migration progress is tracked through workflow states
|
||||
|
||||
## Usage Guidelines
|
||||
|
||||
1. **Always-On Rules**: Start with `meta_core_always_on.mdc` for every
|
||||
single prompt
|
||||
2. **Core Rules**: Always apply rules from `core/` directory
|
||||
3. **Context-Specific**: Use rules from appropriate subdirectories based on
|
||||
your task
|
||||
4. **Meta-Rules**: Use workflow-specific meta-rules for specialized tasks
|
||||
- **Documentation**: Use `meta_documentation.mdc` for all documentation work
|
||||
- **Getting Started**: See `docs/meta_rule_usage_guide.md` for comprehensive usage instructions
|
||||
5. **Cross-References**: All files contain updated cross-references to
|
||||
reflect the new structure
|
||||
6. **Validation**: All files pass markdown validation and maintain
|
||||
consistent formatting
|
||||
|
||||
## Benefits of New Organization
|
||||
|
||||
1. **Logical grouping** - Related rules are now co-located
|
||||
2. **Easier navigation** - Developers can quickly find relevant rules
|
||||
3. **Better maintainability** - Clear separation of concerns
|
||||
4. **Scalable structure** - Easy to add new rules in appropriate categories
|
||||
5. **Consistent cross-references** - All file links updated and working
|
||||
6. **Workflow bundling** - Meta-rules provide high-level workflow guidance
|
||||
7. **Feedback integration** - Built-in feedback mechanisms for continuous improvement
|
||||
8. **Educational focus** - Documentation emphasizes human competence over technical description
|
||||
|
||||
## File Naming Convention
|
||||
|
||||
- **Lowercase with underscores**: `file_name.mdc`
|
||||
- **Descriptive names**: Names clearly indicate the rule's purpose
|
||||
- **Consistent extensions**: All files use `.mdc` extension
|
||||
|
||||
## Maintenance
|
||||
|
||||
- **Cross-references**: Update when moving files between directories
|
||||
- **Markdown validation**: Run `npm run markdown:check` after any changes
|
||||
- **Organization**: Keep related rules in appropriate subdirectories
|
||||
- **Documentation**: Update this README when adding new rules or directories
|
||||
|
||||
---
|
||||
|
||||
**Status**: Active organization structure
|
||||
**Last Updated**: 2025-08-21
|
||||
**Maintainer**: Development team
|
||||
Reference in New Issue
Block a user