Initial commit

Author: YichengDWu

.cursor/rules/general_behavior_rules.mdc

@@ -0,0 +1,22 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+# This file is currently loaded through cursor settings (global rules).
+
+When creating code, you must:
+- Prioritize straightforward and simple code solutions.
+- Do not make assumptions about the problem or the codebase. Always investigate and validate the ENTIRE codebase and context before you make suggestions or modifications. Use external tools such as `codebase_search` and terminal commands (e.g., `pwd` and `tree -L 4 --gitignore | cat`).
+- Always prefer existing solutions over creating new ones. You may suggest fundamental changes but you should have good reasons why.
+- Always use descriptive variable names.
+- Manage configurations with environment variables.
+- Ensure robust error handling and logging, include rich context.
+- Properly document code with type hints and docstrings (detailed and concisely).
+- Always use assertions to guarantee code functionality.
+- Always use a virtual environment (do not install anything in global pip).
+- Always ensure your operations are relative to the workspace root, not your current shell position.
+
+<!-- When writing explanations, you must:
+- Be as descriptive and technical as possible, assuming that you are talking to a highly experienced roboticist and computer scientist. Never use fluffy expressions and non-descriptive statements.
+- Always explain your thought process before solving a task, do not explain after the fact. -->

.cursor/rules/git.mdc

@@ -0,0 +1,86 @@
+---
+description: This rule outlines best practices for effective use of Git, including code organization, commit strategies, branching models, and collaborative workflows.
+globs:
+alwaysApply: false
+---
+- **Commit Strategies:**
+  - **Atomic Commits:** Keep commits small and focused. Each commit should address a single, logical change. This makes it easier to understand the history and revert changes if needed.
+  - **Descriptive Commit Messages:** Write clear, concise, and informative commit messages. Explain the *why* behind the change, not just *what* was changed. Use a consistent format (e.g., imperative mood: "Fix bug", "Add feature").
+  - **Commit Frequently:** Commit early and often. This helps avoid losing work and makes it easier to track progress.
+  - **Avoid Committing Broken Code:** Ensure your code compiles and passes basic tests before committing.
+  - **Sign Your Commits (Optional but Recommended):** Use GPG signing to verify the authenticity of your commits.
+
+- **Branching Model:**
+  - **Use Feature Branches:** Create branches for each new feature or bug fix. This isolates changes and allows for easier code review.
+  - **Gitflow or Similar:** Consider adopting a branching model like Gitflow for managing releases, hotfixes, and feature development.
+  - **Short-Lived Branches:** Keep branches short-lived. The longer a branch exists, the harder it becomes to merge.
+  - **Regularly Rebase or Merge:** Keep your feature branches up-to-date with the main branch (e.g., `main`, `develop`) by rebasing or merging regularly.
+  - **Avoid Direct Commits to Main Branch:**  Protect your main branch from direct commits.  Use pull requests for all changes.
+
+- **Code Organization:**
+  - **Consistent Formatting:**  Use a consistent coding style guide (e.g., PEP 8 for Python, Google Style Guide for other languages) and enforce it with linters and formatters (e.g., `flake8`, `pylint`, `prettier`).
+  - **Modular Code:** Break down your codebase into smaller, manageable modules or components. This improves readability, maintainability, and testability.
+  - **Well-Defined Interfaces:**  Define clear interfaces between modules and components to promote loose coupling.
+  - **Avoid Global State:** Minimize the use of global variables and state to reduce complexity and potential conflicts.
+  - **Documentation:** Document your code with comments and docstrings. Explain the purpose of functions, classes, and modules.
+
+- **Collaboration and Code Review:**
+  - **Pull Requests:** Use pull requests for all code changes. This provides an opportunity for code review and discussion.
+  - **Code Review Checklist:** Create a code review checklist to ensure consistency and thoroughness.
+  - **Constructive Feedback:** Provide constructive feedback during code reviews. Focus on improving the code, not criticizing the author.
+  - **Address Feedback:** Respond to and address feedback from code reviews promptly.
+  - **Pair Programming:** Consider pair programming for complex or critical tasks.
+
+- **Ignoring Files and Directories:**
+  - **.gitignore:** Use a `.gitignore` file to exclude files and directories that should not be tracked by Git (e.g., build artifacts, temporary files, secrets).
+  - **Global .gitignore:** Configure a global `.gitignore` file to exclude files that you never want to track in any Git repository.
+
+- **Handling Secrets and Sensitive Information:**
+  - **Never Commit Secrets:** Never commit secrets, passwords, API keys, or other sensitive information to your Git repository.
+  - **Environment Variables:** Store secrets in environment variables and access them at runtime.
+  - **Secret Management Tools:** Use secret management tools like HashiCorp Vault or AWS Secrets Manager to store and manage secrets securely.
+  - **git-secret or similar:** If secrets must exist in the repo (strongly discouraged), encrypt them.
+
+- **Submodules and Subtrees:**
+  - **Use Sparingly:** Use Git submodules and subtrees sparingly, as they can add complexity.
+  - **Understand the Implications:** Understand the implications of using submodules and subtrees before adopting them.
+  - **Consider Alternatives:** Consider alternatives to submodules and subtrees, such as package managers or build systems.
+
+- **Large File Storage (LFS):**
+  - **Use for Large Files:** Use Git LFS for storing large files (e.g., images, videos, audio files).  This prevents your repository from becoming bloated.
+  - **Configure LFS:** Configure Git LFS properly to track the large files in your repository.
+
+- **Reverting and Resetting:**
+  - **Understand the Differences:** Understand the differences between `git revert`, `git reset`, and `git checkout` before using them.
+  - **Use with Caution:** Use `git reset` and `git checkout` with caution, as they can potentially lose data.
+  - **Revert Public Commits:** Use `git revert` to undo changes that have already been pushed to a public repository. This creates a new commit that reverses the changes.
+
+- **Tagging Releases:**
+  - **Create Tags:** Create tags to mark significant releases or milestones.
+  - **Semantic Versioning:** Follow semantic versioning (SemVer) when tagging releases.
+  - **Annotated Tags:** Use annotated tags to provide additional information about the release.
+
+- **Dealing with Merge Conflicts:**
+  - **Understand the Conflict:** Understand the source of the merge conflict before attempting to resolve it.
+  - **Communicate with Others:** Communicate with other developers who may be affected by the conflict.
+  - **Use a Merge Tool:** Use a merge tool to help resolve the conflict.
+  - **Test After Resolving:** Test your code thoroughly after resolving the conflict.
+
+- **Repository Maintenance:**
+  - **Regularly Clean Up:** Regularly clean up your Git repository by removing unused branches and tags.
+  - **Optimize the Repository:** Optimize the repository with `git gc` to improve performance.
+
+- **CI/CD Integration:**
+  - **Automate Testing:** Integrate Git with a CI/CD system to automate testing and deployment.
+  - **Run Tests on Every Commit:** Run tests on every commit to ensure code quality.
+
+- **Common Pitfalls and Gotchas:**
+  - **Accidental Commits:** Accidentally committing sensitive information or large files.
+  - **Merge Conflicts:** Difficulty resolving merge conflicts.
+  - **Losing Work:** Losing work due to incorrect use of `git reset` or `git checkout`.
+  - **Ignoring .gitignore:** Forgetting to add files to `.gitignore`.
+
+- **Tooling and Environment:**
+  - **Git Clients:** Use a Git client that suits your needs (e.g., command line, GUI).
+  - **IDE Integration:** Use Git integration in your IDE to streamline workflows.
+  - **Online Repositories:** Use a reliable online Git repository hosting service (e.g., GitHub, GitLab, Bitbucket).

.cursor/rules/max_development.mdc

@@ -0,0 +1,109 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+You are an expert in developer in the current file's language, specializing in high-performance computing and AI model development.
+
+## 📜 Core Philosophy
+
+1. **Simplicity:** Prioritize simple, clear, and maintainable solutions. Avoid unnecessary complexity or over-engineering.
+2. **Iterate:** Prefer iterating on existing, working code rather than building entirely new solutions from scratch, unless fundamentally necessary or explicitly requested.
+3. **Focus:** Concentrate efforts on the specific task assigned. Avoid unrelated changes or scope creep.
+4. **Quality:** Strive for a clean, organized, well-tested, and secure codebase.
+5. **Collaboration:** This document guides both human developers and the AI assistant for effective teamwork.
+
+## 📚 Project Context & Understanding
+
+1. **Documentation First:**
+    * **Always** check for and thoroughly review relevant project documentation *before* starting any task. This includes:
+        * Product Requirements Documents (PRDs)
+        * `docs/README.md` (Project overview, setup, patterns, technology stack)
+        * `docs/internal/DesignPhilosophy.md` (System architecture, component relationships)
+        * `docs/internal/Development.md` (Technical specifications, established patterns)
+    * If documentation is missing, unclear, or conflicts with the request, **ask for clarification**.
+2. **Architecture Adherence:**
+    * Understand and respect module boundaries, data flow, system interfaces, and component dependencies outlined.
+    * Validate that changes comply with the established architecture. Warn and propose compliant solutions if a violation is detected.
+3. **Pattern & Tech Stack Awareness:**
+    * Reference `docs/README.md` and `docs/internal/DesignPhilosophy.md` to understand and utilize existing patterns and technologies.
+    * Exhaust options using existing implementations before proposing new patterns or libraries.
+
+## ⚙️ Task Execution & Workflow
+
+1. **Task Definition:**
+    * Clearly understand the task requirements, acceptance criteria, and any dependencies.
+2. **Systematic Change Protocol:** Before making significant changes:
+    * **Identify Impact:** Determine affected components, dependencies, and potential side effects.
+    * **Plan:** Outline the steps. Tackle one logical change or file at a time.
+    * **Verify Testing:** Confirm how the change will be tested. Add tests if necessary *before* implementing (see TDD).
+
+## 🤖 AI Collaboration & Prompting
+
+1. **Clarity is Key:** Provide clear, specific, and unambiguous instructions to the AI. Define the desired outcome, constraints, and context.
+2. **Context Referencing:** If a task spans multiple interactions, explicitly remind the AI of relevant previous context, decisions, or code snippets.
+3. **Suggest vs. Apply:** Clearly state whether the AI should *suggest* a change for human review or *apply* a change directly (use only when high confidence and task is well-defined). Use prefixes like "Suggestion:" or "Applying fix:".
+4. **Question AI Output:** Human developers should critically review AI-generated code. Question assumptions, verify logic, and don't blindly trust confident-sounding but potentially incorrect suggestions (hallucinations).
+5. **Focus the AI:** Guide the AI to work on specific, focused parts of the task. Avoid overly broad requests that might lead to architectural or logical errors.
+6. **Leverage Strengths:** Use the AI for tasks it excels at (boilerplate generation, refactoring specific patterns, finding syntax errors, generating test cases) but maintain human oversight for complex logic, architecture, and security.
+7. **Incremental Interaction:** Break down complex tasks into smaller steps for the AI. Review and confirm each step before proceeding.
+8. **Standard Check-in (for AI on large tasks):** Before providing significant code suggestions:
+    * "Confirming understanding: I've reviewed [specific document/previous context]. The goal is [task goal], adhering to [key pattern/constraint]. Proceeding with [planned step]." (This replaces the more robotic "STOP AND VERIFY").
+
+## ✨ Code Quality & Style
+
+1. **Python Guidelines:** Use strict typing (avoid `any`). Document complex logic or public APIs.
+2. **Readability & Maintainability:** Write clean, well-organized code.
+3. **Small Files & Components:**
+    * Keep files under **300 lines**. Refactor proactively.
+    * Break down large React components into smaller, single-responsibility components.
+4. **Avoid Duplication (DRY):** Actively look for and reuse existing functionality. Refactor to eliminate duplication.
+5. **Linting/Formatting:** Ensure all code conforms to project's ESLint/Prettier rules.
+6. **Pattern Consistency:** Adhere to established project patterns. Don't introduce new ones without discussion/explicit instruction. If replacing an old pattern, ensure the old implementation is fully removed.
+7. **File Naming:** Use clear, descriptive names. Avoid "temp", "refactored", "improved", etc., in permanent file names.
+8. **No One-Time Scripts:** Do not commit one-time utility scripts into the main codebase.
+
+## ♻️ Refactoring
+
+1. **Purposeful Refactoring:** Refactor to improve clarity, reduce duplication, simplify complexity, or adhere to architectural goals.
+2. **Holistic Check:** When refactoring, look for duplicate code, similar components/files, and opportunities for consolidation across the affected area.
+3. **Edit, Don't Copy:** Modify existing files directly. Do not duplicate files and rename them.
+4. **Verify Integrations:** After refactoring, ensure all callers, dependencies, and integration points function correctly. Run relevant tests.
+
+## ✅ Testing & Validation
+
+1. **Test-Driven Development (TDD):**
+    * **New Features:** Outline tests, write failing tests, implement code, refactor.
+    * **Bug Fixes:** Write a test reproducing the bug *before* fixing it.
+2. **Comprehensive Tests:** Write thorough unit, integration, and/or end-to-end tests covering critical paths, edge cases, and major functionality.
+3. **Tests Must Pass:** All tests **must** pass before committing or considering a task complete. Notify the human developer immediately if tests fail and cannot be easily fixed.
+4. **No Mock Data (Except Tests):** Use mock data *only* within test environments. Development and production should use real or realistic data sources.
+5. **Manual Verification:** Supplement automated tests with manual checks where appropriate, especially for UI changes.
+
+## 🐛 Debugging & Troubleshooting
+
+1. **Fix the Root Cause:** Prioritize fixing the underlying issue causing an error, rather than just masking or handling it, unless a temporary workaround is explicitly agreed upon.
+2. **Research:** Use available tools (Firecrawl, documentation search, etc.) to research solutions or best practices when stuck or unsure.
+
+## 🔒 Security
+
+1. **Server-Side Authority:** Keep sensitive logic, validation, and data manipulation strictly on the server-side. Use secure API endpoints.
+2. **Input Sanitization/Validation:** Always sanitize and validate user input on the server-side.
+3. **Dependency Awareness:** Be mindful of the security implications of adding or updating dependencies.
+4. **Credentials:** Never hardcode secrets or credentials in the codebase. Use environment variables or a secure secrets management solution.
+
+## 🌳 Version Control & Environment
+
+1. **Git Hygiene:**
+    * Commit frequently with clear, atomic messages.
+    * Keep the working directory clean; ensure no unrelated or temporary files are staged or committed.
+    * Use `.gitignore` effectively.
+2. **Branching Strategy:** Follow the project's established branching strategy. Do not create new branches unless requested or necessary for the workflow (e.g., feature branches).
+3. **.env Files:** **Never** commit `.env` files. Use `.env.example` for templates. Do not overwrite local `.env` files without confirmation.
+4. **Environment Awareness:** Code should function correctly across different environments (dev, test, prod). Use environment variables for configuration.
+5. **Server Management:** Kill related running servers before starting new ones. Restart servers after relevant configuration or backend changes.
+
+## 📄 Documentation Maintenance
+
+1. **Update Docs:** If code changes impact architecture, technical decisions, established patterns, or task status, update the relevant documentation.
+2. **Keep Rules Updated:** This `.cursorrules` file should be reviewed and updated periodically to reflect learned best practices and project evolution.