ci: add tag-based release automation with git-cliff

Add GitHub Actions CI workflow for push and pull_request validation using JDK 21 and ./gradlew test.

Add tag-triggered release workflow for v* tags that builds/tests artifacts and publishes GitHub Releases.

Use git-cliff (cliff.toml) to generate release notes from commits between tags and publish them as release body.

Update README, STATUS, DONE, and ROADMAP with CI/CD and release-note automation details.

Update AGENTS.md with strict commit-prefix and one-commit-per-fix collaboration rules for cliff-compatible history.

Author: Beowolve

.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - "**"
+  pull_request:
+    branches:
+      - "**"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "21"
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Fetch tags for jgitver
+        run: git fetch --force --tags
+
+      - name: Run unit tests
+        run: ./gradlew --no-daemon test

.github/workflows/release.yml

@@ -0,0 +1,55 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "21"
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Fetch tags for jgitver
+        run: git fetch --force --tags
+
+      - name: Build and test
+        run: ./gradlew --no-daemon clean test distZip distTar
+
+      - name: Generate release notes (git-cliff)
+        id: git-cliff
+        uses: orhun/git-cliff-action@v4
+        with:
+          config: cliff.toml
+          args: --latest --strip header
+        env:
+          OUTPUT: RELEASE_NOTES.md
+
+      - name: Publish GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: SnapFX ${{ github.ref_name }}
+          tag_name: ${{ github.ref_name }}
+          body_path: RELEASE_NOTES.md
+          fail_on_unmatched_files: true
+          prerelease: ${{ contains(github.ref_name, '-') }}
+          files: |
+            build/distributions/*.zip
+            build/distributions/*.tar
+            build/libs/*.jar

AGENTS.md

@@ -12,7 +12,9 @@ These instructions are shared for all AI agents working on this workspace.
 - Always `git add` new files when preparing a commit.
 - Before creating a commit, always show the proposed commit message to the user and get confirmation.
 - Keep commits minimally mixed: one logical topic/fix per commit; avoid bundling unrelated changes.
+- Default to one commit per fix/feature so changes stay clearly separated and release notes remain precise.
 - For fix commits, use a multi-line commit message body with at least one explanation line per fix.
+- Use git-cliff-compatible commit prefixes in the subject line (`feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `perf:`, `ci:`, `build:`, `chore:`); domain prefixes like `floating:`, `dnd:`, `ui:`, `demo:` are also allowed when they map to cliff groups.
 - If a fixed collaboration rule is agreed with the user, add it to this `AGENTS.md` immediately.
 - Treat `AGENTS.md` as the source of truth for all persistent collaboration rules in this workspace.
 - As soon as a focused, sensible commit is ready, proactively show the proposed commit message without waiting for the user to ask.

DONE.md

@@ -209,6 +209,9 @@ SnapFX has been fully implemented with core functionality and is production-read
 ### Build & Deployment
 - ✅ Completed `runSimpleExample` Gradle task for launching `SimpleExample` with JavaFX module runtime support.
 - ✅ `SimpleExample` now logs a warning through `System.Logger` when `snapfx.css` is missing, without requiring a logging framework dependency.
+- ✅ Added GitHub Actions CI workflow for push/PR validation with `./gradlew test` on JDK 21.
+- ✅ Added GitHub Actions release workflow for `v*` tags that runs build/tests and publishes GitHub Releases with distribution artifacts.
+- ✅ Added `git-cliff` release-note generation (`cliff.toml`) and wired release workflow to publish generated notes.
 - ✅ **Gradle Build**: Modern Kotlin DSL build script
 - ✅ **Module Configuration**: Java 21 module support
 - ✅ **JavaFX Integration**: JavaFX Gradle plugin

README.md

@@ -294,6 +294,21 @@ Optional push:
 - Later phase: move integration to `develop`, keep `main` release-focused
 - Release flow after `develop` is introduced: merge `develop` -> `main`, then create/push release tag (`vX.Y.Z`)
 
+## CI/CD
+
+- GitHub Actions CI (`.github/workflows/ci.yml`) runs on every push and pull request
+- CI executes `./gradlew test` on JDK 21
+- GitHub Release workflow (`.github/workflows/release.yml`) runs only when a tag matching `v*` is pushed
+- Release workflow executes `./gradlew clean test distZip distTar` and publishes a GitHub Release with build artifacts
+- Release notes are generated by `git-cliff` (`cliff.toml`) and attached as the release body
+
+### Release Notes (git-cliff)
+
+- Config file: `cliff.toml`
+- Notes are generated from commits between tags
+- Prefix-based grouping is enabled (for example `feat:`, `fix:`, `docs:`, `ci:`, `floating:`)
+- Tag push flow: `git push origin main --tags`
+
 ## License
 
 This project is a demo framework for educational purposes.

ROADMAP.md

@@ -342,11 +342,12 @@ This roadmap lists planned work only; fixed issues are tracked in `STATUS.md`.
 ### 8.1 Packaging & Distribution
 **Priority**: 🟡 High
 
+- ✅ **GitHub tag release workflow**: Pushing `v*` tags now runs build/test and publishes a GitHub Release with distribution artifacts
+- ✅ **Release notes automation**: `git-cliff` now generates tag-based release notes used as GitHub Release body
 - 📋 **Maven Central**: Publish to Maven Central
 - 📋 **jlink support**: Create custom runtime images
 - 📋 **jpackage support**: Native installers
 - 📋 **Version management**: Semantic versioning
-- 📋 **Release notes**: Automated changelog
 
 **Estimated Time**: 2-3 days
 

STATUS.md

@@ -7,7 +7,9 @@
 ✅ **Build**: `BUILD SUCCESSFUL`  
 ✅ **Tests**: All 155 tests passing (latest full suite)  
 ✅ **Module System**: Fully implemented (JPMS)  
-✅ **Demo App**: Running successfully
+✅ **Demo App**: Running successfully  
+✅ **CI Automation**: GitHub Actions workflows added for push/PR tests and tag-triggered releases  
+✅ **Release Notes Automation**: `git-cliff` generates tag-based GitHub Release notes
 
 ## Implementation Progress
 
@@ -177,6 +179,9 @@
 - ✅ 2026-02-15: Floating Window - Drag & drop visual feedback is now shown inside floating windows
 - ✅ 2026-02-15: Floating Window - Pin button behavior is now configurable (`ALWAYS`/`AUTO`/`NEVER`) with default pinned state, lock-mode policy, and optional user-toggle disable.
 - ✅ 2026-02-15: Persistence - Floating window always-on-top state is now serialized/restored and exposed through source-aware pin change callbacks.
+- ✅ 2026-02-15: CI - Added GitHub Actions workflow for push/PR validation (`./gradlew test`) with tag fetch for `gradle-jgitver`.
+- ✅ 2026-02-15: Release - Added tag-triggered GitHub Release workflow for `v*` tags that builds/tests and publishes distribution artifacts.
+- ✅ 2026-02-15: Release - Integrated `git-cliff` (`cliff.toml`) to generate grouped release notes from commits between tags.
 - ✅ 2026-02-15: Floating Window - Double-click on maximized title bar now restores previous window bounds
 - ✅ 2026-02-15: Floating Window - Dragging a maximized title bar now restores and continues move (Windows-style behavior)
 - ✅ 2026-02-15: UI - Tab float button clicks are no longer intercepted by drag handling
@@ -220,6 +225,8 @@
 - Added SnapFX SVG logo to README for shared GitHub/GitHub Pages branding usage.
 - Added roadmap item for a full GitHub Pages documentation portal.
 - Updated `AGENTS.md` collaboration rules: fix commits require per-fix explanation lines and multi-statement UI callbacks must be extracted to named methods.
+- Added CI/CD documentation for GitHub Actions push/PR checks and tag-based release publishing.
+- Added `git-cliff` release-notes documentation and repository configuration (`cliff.toml`).
 
 ### UI Styling
 - Removed `DockControlIcons` vector icon usage from dock/floating controls and switched to stylesheet-driven glyph classes.

cliff.toml

@@ -0,0 +1,38 @@
+[changelog]
+header = """
+# Changelog
+
+All notable changes to this project are documented in this file.
+"""
+
+body = """
+{% if version %}
+## {{ version }} - {{ timestamp | date(format="%Y-%m-%d") }}
+{% else %}
+## Unreleased
+{% endif %}
+{% for group, commits in commits | group_by(attribute="group") %}
+### {{ group | striptags | trim }}
+{% for commit in commits %}
+- {{ commit.message | split(pat="\n") | first | trim }} ({{ commit.id | truncate(length=7, end="") }})
+{% endfor %}
+{% endfor %}
+"""
+
+trim = true
+
+[git]
+tag_pattern = "v[0-9].*"
+filter_unconventional = false
+sort_commits = "newest"
+
+commit_parsers = [
+  { message = "^(feat|feature)(\\(.+\\))?:", group = "Features" },
+  { message = "^(fix|bugfix|hotfix)(\\(.+\\))?:", group = "Fixes" },
+  { message = "^(floating|dnd|ui|demo)(\\(.+\\))?:", group = "UI and Interaction" },
+  { message = "^(perf|refactor)(\\(.+\\))?:", group = "Refactoring" },
+  { message = "^(test|tests)(\\(.+\\))?:", group = "Tests" },
+  { message = "^(docs|doc)(\\(.+\\))?:", group = "Documentation" },
+  { message = "^(build|ci|chore)(\\(.+\\))?:", group = "Build and Tooling" },
+  { message = "^[a-zA-Z0-9_-]+(\\(.+\\))?:", group = "Other Changes" },
+]