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
- **`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