Cline rules

1# Project Workflow Guidelines for GraphQL Filter Demo
2 
3This document outlines the workflow and practices to be followed during the development of the GraphQL Filter Demo project.
4 
5⚠️ CRITICAL: DO NOT USE attempt_completion BEFORE TESTING ⚠️
6⚠️ CRITICAL: DO NOT USE browse_action. ASK USER TO BROWSE AND REPORT THE RESULTS ⚠️
7⚠️ CRITICAL: NEVER PERFORM A PUSH TO REMOTE REPOSITORY ⚠️
8 
9## Changelog Management
10 
11*   Maintain a `changelog.md` file at the root of the project.
12*   Record all significant changes, new features, bug fixes, and breaking changes.
13*   Follow a consistent format (e.g., "Keep a Changelog" format is recommended).
14*   Update the changelog as part of the completion of each major task or before creating a new release/tag.
15 
16## Task Tracking
17 
18*   Maintain a `tasks.md` file at the root of the project.
19*   List all planned development tasks using a checklist format (e.g., `- [ ] Task description`).
20*   Mark tasks as completed by changing `[ ]` to `[x]`.
21*   Refer to this file to understand the current progress and remaining work.
22 
23## Git Commit Messages
24 
25*   Write clear, concise, and descriptive Git commit messages.
26*   Use the imperative mood in the subject line (e.g., "Add feature X", "Fix bug Y").
27*   Include a body in the commit message for more detailed explanations if necessary.
28*   Perform a commit after completing every task with a subsequent successfull code execution.
29*   After completing a stage from the `tasks.md` and its child tasks, Use the `git tag` command to create a taf with the stage number (e.g., `stage-1.0`) and a corresponding release note in the `changelog.md`.
30 
31## Testing
32 
33*   For every feature developed, write unit and behavioral tests to validate its functionality as planned.
34*   Tests must be executed whenever the code is changed to ensure no regressions are introduced.
35*   Tests should be reviewed and updated throughout the development process to reflect any changes in requirements or implementation.
36 
37## README.md
38 
39*   Maintain a comprehensive `README.md` file at the root of the project.
40*   Include instructions on setting up the development environment (using the devcontainer), installing dependencies, running the application, and a brief overview of the project and API.
41*   Keep the README updated as the project evolves.
42 
43## Iterative Development
44 
45*   Follow the planned development stages.
46*   Complete tasks incrementally, ensuring each step is stable before moving to the next.
47*   Utilize the provided tools effectively to accomplish tasks.
48 
49## Key Considerations
50 
51- Only run and test the code inside a the devcontainer.
52 
53## Dependency Management
54 
55This project uses a hybrid approach for Python package management:
56*   **Inside the Devcontainer:** Standard `pip` is used for managing dependencies. The devcontainer environment is pre-configured with Python and `pip`.
57*   **Outside the Devcontainer (on the Host):** `uv` is recommended for creating and managing a virtual environment and installing dependencies.
58 
59### Inside the Devcontainer (using `pip`)
60 
61*   The devcontainer comes with Python and `pip` ready to use. No separate virtual environment activation is typically needed as the container itself provides isolation.
62*   **Managing Dependencies:**
63    *   **Installing from `requirements.txt`:** `pip install -r requirements.txt`
64    *   **Adding a new package:** `pip install <package_name>`
65    *   **Updating a package:** `pip install --upgrade <package_name>`
66*   **Maintaining `requirements.txt`:**
67    *   **Crucial:** After adding, removing, or updating any package, **immediately** update the `requirements.txt` file using: `pip freeze > requirements.txt`
68    *   This ensures that the `requirements.txt` file always reflects the exact state of the project's dependencies.
69 
70### Outside the Devcontainer (on the Host, using `uv`)
71 
72*   `uv` is a fast Python package installer and resolver.
73*   **Installation of `uv`:** Follow the official `uv` installation guide if not already installed.
74*   **Creating a Virtual Environment (Recommended):**
75    *   `uv venv .venv` (Creates a virtual environment in a `.venv` directory)
76    *   Activate the environment:
77        *   Linux/macOS: `source .venv/bin/activate`
78        *   Windows (PowerShell): `.venv\Scripts\Activate.ps1`
79        *   Windows (CMD): `.venv\Scripts\activate.bat`
80*   **Managing Dependencies (with `uv` in an activated venv):**
81    *   **Installing from `requirements.txt`:** `uv pip install -r requirements.txt`
82    *   **Adding a new package:** `uv pip install <package_name>`
83    *   **Updating a package:** `uv pip install --upgrade <package_name>`
84*   **Maintaining `requirements.txt` (with `uv` in an activated venv):**
85    *   **Crucial:** After adding, removing, or updating any package, **immediately** update the `requirements.txt` file using: `uv pip freeze > requirements.txt`
86    *   This ensures that the `requirements.txt` file always reflects the exact state of the project's dependencies.
87*   **Important:** When working outside the devcontainer, always ensure your `uv` commands are run within the activated virtual environment.
88