diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 0000000..fe3fd38
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,52 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # The marketplace resolves the plugin from this repo, so plugin.json's version
+      # IS what users install. A tag that disagrees with it ships a plugin lying about
+      # its own version, and the installed_plugins.json pin silently mismatches.
+      - name: Version matches tag
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF#refs/tags/v}"
+          manifest=$(jq -r .version .claude-plugin/plugin.json)
+          [ "$tag" = "$manifest" ] || {
+            echo "::error::tag v$tag != plugin.json $manifest"; exit 1; }
+
+      - name: Extract release notes from CHANGELOG.md
+        id: notes
+        # Body comes from the hand-written CHANGELOG section for this tag. Refuse to
+        # publish a blank release rather than ship an empty one.
+        run: |
+          set -euo pipefail
+          version="${GITHUB_REF#refs/tags/v}"
+          notes=$(awk -v h="## [$version]" '
+            !seen && index($0, h) == 1 { seen = 1; next }
+            seen && index($0, "## [") == 1 { exit }
+            seen { print }
+          ' CHANGELOG.md)
+          [ -n "$notes" ] || {
+            echo "::error::no CHANGELOG.md entry for $version"; exit 1; }
+          {
+            echo "notes<<__EOF__"
+            echo "$notes"
+            echo "__EOF__"
+          } >> "$GITHUB_OUTPUT"
+
+      - uses: softprops/action-gh-release@v2
+        with:
+          body: ${{ steps.notes.outputs.notes }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 82876a6..a0e1025 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,9 +4,9 @@ All notable changes to the CLDK DevTools plugin are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.4.0] — unreleased
+## [0.4.0] — 2026-08-04
 
-### Added
+### ✨ Added
 
 - **`planning-cldk-work`** — a new mode upstream of design, for work that cannot be
   stated as a single contract decision: a theme that decomposes into several
@@ -22,7 +22,7 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [0.3.0] — 2026-08-03
 
-### Changed — **BREAKING** (behavioural)
+### ⚠️ Changed — **BREAKING** (behavioural)
 
 This release changes how agents decompose and track work. Sessions running under
 0.2.0 conventions will behave differently after updating; anyone relying on the old
@@ -52,7 +52,7 @@ shape should read this before upgrading.
   invoking the next skill. An end-to-end run is materially more interactive than
   under 0.2.0.
 
-### Added
+### ✨ Added
 
 - Issue bodies now come from org-level forms in `codellm-devkit/.github`
   (`epic.yml`, `work_item.yml`), with the convention in that repo's