crowd-funder-for-time-pwa/.cursor/rules/README.md

.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

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