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

.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:

{
  "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:

{
  "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:

{
  "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:

# 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