## 🔄 Project Awareness & Context
- **Always read `PLANNING.md`** at the start of a new conversation to understand the project's architecture, goals, style, and constraints. - **Check `TASK.md`** before starting a new task. If the task isn't listed, add it with a brief description and today's date. - **Use consistent naming conventions, file structure, and architecture patterns** as described in `PLANNING.md`. - **Maintain awareness of the technical stack**: Electron, React, and related technologies for this desktop application. - **Consider API limitations**: Be aware of Harvest API rate limits and authentication requirements.
## 🧱 Code Structure & Modularity
- **Never create a file longer than 500 lines of code.** If a file approaches this limit, refactor by splitting it into modules or helper files. - **Organize code into clearly separated modules**, grouped by feature or responsibility. - **Use clear, consistent imports** (prefer relative imports within packages). - **Follow the application layer structure** defined in PLANNING.md:
  - UI Layer (Electron with React components)
  - State Management Layer (Redux or Context API)
  - Service Layer (API communication)
  - Data Layer (Local storage)
- **Create reusable components** for UI elements that appear in multiple places. - **Separate API calls into service modules** organized by resource type.
## 📝 Coding Standards
- **Follow consistent code style** using the project's ESLint and Prettier configurations. - **Write meaningful comments** for complex logic but avoid redundant comments. - **Add JSDoc comments** for functions, components, and modules. - **Use TypeScript interfaces/types** for all data structures. - **Handle errors gracefully** at appropriate levels of abstraction. - **Implement proper loading states** for asynchronous operations. - **Log important events and errors** using the application's logging system.
## ✅ Task Completion
- **Mark completed tasks in `TASK.md`** immediately after finishing them. - **Add new sub-tasks or TODOs** discovered during development to `TASK.md` under a "Discovered During Work" section. - **Document any API quirks or limitations** encountered during implementation. - **Update relevant documentation** when completing tasks that change functionality. - **Create or update tests** for new or modified functionality.
## 🧠 AI Behavior Rules
- **Never assume missing context. Ask questions if uncertain.** - **Never hallucinate libraries or functions** – only use known, verified packages from the project's dependencies. - **Always confirm file paths and module names** exist before referencing them in code or tests. - **Never delete or overwrite existing code** unless explicitly instructed to or if part of a task from `TASK.md`. - **Present multiple approaches** for complex problems, explaining trade-offs. - **Recommend performance optimizations** when you identify potential issues. - **Highlight potential security concerns** related to API tokens, data storage, etc.
## 🔒 Security & Best Practices
- **Never hardcode API credentials** in application code. - **Store sensitive data securely** using appropriate electron-secure-storage or similar libraries. - **Implement proper token refresh** and secure storage for OAuth tokens. - **Follow OWASP security guidelines** for web applications. - **Validate all user inputs** before processing or sending to API. - **Handle API errors gracefully** with appropriate user feedback.
## 📊 Data Handling
- **Implement proper data caching** for offline functionality. - **Create clear data models** with validation. - **Use optimistic UI updates** with rollback capabilities for network operations. - **Implement robust synchronization logic** for handling offline/online transitions. - **Handle edge cases** such as timezone differences and date formatting issues.
## 📱 UI/UX Guidelines
- **Follow modern UI patterns** consistent with desktop applications. - **Ensure accessibility** by using proper semantic elements and ARIA attributes. - **Support keyboard navigation** throughout the application. - **Implement responsive designs** that work well at different window sizes. - **Use consistent visual language** for actions, notifications and system status. - **Follow the visualization guidelines** for charts and reports as outlined in the planning document.
## 🧪 Testing Guidelines
- **Write tests for all critical functionality** using Jest and Playwright. - **Create unit tests for utility functions** and service layer components. - **Implement integration tests** for component interactions. - **Write end-to-end tests** for critical user flows. - **Test offline functionality** thoroughly with network interruption scenarios.

## 📦 Build & Deployment
- **Follow the defined build process** for packaging the Electron application. - **Test builds on all target platforms** (Windows, macOS, Linux). - **Implement auto-update mechanisms** for seamless user experience. - **Document any platform-specific considerations** or limitations.
## 🔄 Version Control
- **Follow Git best practices** with meaningful commit messages. - **Create feature branches** for new functionality. - **Submit detailed pull request descriptions** explaining changes and implementation details. - **Keep commits focused and atomic** to facilitate code review.