Cline rules

1---
2description: An intelligent workflow to automatically calculate and apply a new project version, update core files and documentation, and prepare a release commit.
3author: Frédéric Guigand
4version: 1.2
5category: "Workflow"
6tags: ["workflow", "release", "versioning", "semver", "changelog", "documentation", "automation"]
7globs: ["package.json", "app-config.*", "CHANGELOG.md", "README.md", "docs/**/*.md"]
8---
9 
10# Workflow: Intelligent Project Versioning & Documentation
11 
12This rule defines an automated, multi-step process for releasing a new version of the project. You MUST follow this logic precisely to ensure a correct and consistent release.
13 
14### Step 1: Determine New Version (Automated Logic)
15 
16Your primary task is to calculate the new version number. You MUST follow this decision tree in order:
17 
181.  **Check for Explicit User Input:**
19    - First, check if the user has provided an explicit version type (e.g., `major`, `minor`, `patch`, `fix`).
20    - If yes, this is the highest priority. Proceed to calculate the new version based on this input.
21 
222.  **Infer from `CHANGELOG.md`:**
23    - If no explicit type is given, you MUST infer it by analyzing the content under the `[Unreleased]` section of `CHANGELOG.md`.
24    - Apply the following Semantic Versioning logic:
25        - If you find `BREAKING CHANGE:` text or a `### Removed` section, it MUST be a **MAJOR** increment.
26        - If you find a `### Added` section, it MUST be a **MINOR** increment.
27        - If you only find `### Fixed`, `### Security`, or other minor sections, it MUST be a **PATCH** increment.
28 
293.  **Ask User on Ambiguity (Fallback):**
30    - ⚠️ **If inference is ambiguous** (e.g., only a `### Changed` section exists), you **MUST NOT GUESS**.
31    - Instead, you MUST ask the user for clarification. Present your analysis and provide clear choices.
32    - **✅ Use this template for asking:**
33      > "I have analyzed the changes in `[Unreleased]` and the version increment is ambiguous. Based on the changes, I suggest the following options:
34      > - **MINOR (`X.Y.Z`):** Choose this for new, backward-compatible features.
35      > - **PATCH (`A.B.C`):** Choose this for backward-compatible bug fixes.
36      >
37      > Please specify which version is correct."
38 
39### Step 2: Pre-flight Check & Confirmation
40 
41Before modifying any files, perform an internal verification and present a plan to the user.
42 
431.  **Internal Verification:** Use a thinking block to confirm you have all necessary information.
44```xml
45    <thinking>
46    1.  Current version source file identified (e.g., `package.json`).
47    2.  Current version read: [e.g., 1.9.3]
48    3.  Increment type determined: [e.g., minor (inferred)]
49    4.  Calculated new version: [e.g., 1.10.0]
50    5.  Required files are present and accessible.
51    Plan is ready for execution.
52    </thinking>
53```
542.  **State Your Plan:** Present the confirmed new version number to the user and ask for final approval before writing any changes. For example: "I will increment the version to `1.10.0`. Is this correct?"
55 
56### Step 3: Execute Core File Modifications
57 
58Once the user confirms, proceed with the following precise file modifications.
59 
601.  **Update Central Version Source:**
61    - Locate and update the version number in the identified source file (`package.json`, `app-config.yaml`, etc.).
62 
632.  **Update `CHANGELOG.md`:**
64    - Create a new version heading below `[Unreleased]` using the format `## [X.Y.Z] - YYYY-MM-DD`.
65    - Move the summarized changes from the `[Unreleased]` section to this new version section.
66    - Update the version comparison link at the bottom of the file.
67 
683.  **Update `README.md` Version Badge:**
69    - Find the version badge in `README.md` and update the version number.
70    - **✅ Template:** `[![Version](https://img.shields.io/badge/version-NEW.VERSION.HERE-blue.svg)](CHANGELOG.md)`
71 
72### Step 4: 🧠 Intelligently Update Project Documentation
73 
74Your goal is to ensure all technical and maintenance documentation reflects the new changes, not just list them.
75 
761.  **Analyze Changes:** Review the finalized changelog entries for this version.
772.  **Identify Affected Docs:** Scan the project for relevant documentation (e.g., files in `docs/`, `guides/`, or files like `ARCHITECTURE.md`, `MAINTENANCE.md`).
783.  **Synthesize and Propose Updates:** Based on the *type* of change, determine the required documentation update.
79    - **`Added`**: If a new feature was added (e.g., caching), find the relevant document (e.g., `architecture.md`) and propose adding a new section explaining it. If new configuration is required, propose updates to the setup guide.
80    - **`Changed`**: If a process was changed, locate its existing description and propose updates to reflect the new behavior (e.g., updating an API endpoint's documentation).
81    - **`Removed`**: If a feature was removed, find its documentation and propose either removing the section or clearly marking it as deprecated with migration steps.
82    - **`Fixed`**: Bug fixes typically do not require documentation updates unless they clarify a previously misunderstood behavior.
834.  **AWAIT USER APPROVAL:** 🚨 **CRITICAL:** You **MUST NOT** apply these changes directly. You MUST present a clear summary of the proposed documentation updates (e.g., as a `diff` or a before/after summary) to the user for review and approval before proceeding.
84 
85### Step 5: Prepare Git Commit Message
86 
87Once all file changes are approved and applied, prepare and output the following commit message text. **DO NOT execute the commit.**
88 
89**✅ Template:**
90```
91<version number> <short, descriptive title>
92 
93- A bulleted list summarizing the key feature/fix changes.
94- Update project documentation to reflect new changes.
95```
96 
97**Example Output:**
98```
991.10.0 Introduce User Profile Caching
100 
101- Implemented Redis caching for user profile data to reduce database load.
102- Added new environment variables for Redis connection.
103- Updated ARCHITECTURE.md with details on the new caching layer.
104 
105```