ci(release): add GitHub release workflow

.oc_local/commands/codegeist-release.md

@@ -0,0 +1,102 @@
+---
+description: Validate main, tag, publish, and verify a Codegeist GitHub release
+agent: build
+---
+
+Release Codegeist from `main` through the GitHub-hosted release workflow.
+
+User request:
+
+```text
+$ARGUMENTS
+```
+
+Expected syntax:
+
+```text
+/codegeist-release v0.1.0
+```
+
+Apply `.oc_local/rules/codegeist-release.md`, `.opencode/rules/semver.md`, and
+the repository commit and command-execution rules.
+
+## Workflow
+
+1. Parse the requested tag from `$ARGUMENTS`. It must match `vMAJOR.MINOR.PATCH`
+   or an explicit SemVer prerelease such as `v0.1.0-rc.1`.
+2. Derive `release_version` by removing the leading `v`.
+3. Run `gh auth status`. If GitHub CLI is not authenticated, use the `gh-auth`
+   skill and stop unless authentication succeeds.
+4. Read `docs/developer/release/github-release-build.md`,
+   `.github/workflows/release.yml`, and `docs/memory-bank/chat.md` for current
+   release context.
+5. Verify that the current worktree is clean with
+   `git --no-pager status --short --branch`. Stop if any uncommitted changes are
+   present.
+6. Verify the requested tag does not already exist:
+   - `git --no-pager tag --list '<tag>'`
+   - `git ls-remote --tags origin '<tag>'`
+   - `gh release view '<tag>'`
+   Stop if any of these show an existing tag or release.
+7. Fetch `origin` and verify that local `main` and `origin/main` point to the same
+   commit, or fast-forward local `main` to `origin/main` when it is safe and the
+   worktree is clean. Do not create a merge commit.
+8. Verify `.github/workflows/release.yml` exists on `main`.
+9. Start pre-tag validation on `main`:
+
+```bash
+gh workflow run release.yml --ref main -f release_version=<version>
+```
+
+10. Locate the created run with `gh run list --workflow release.yml --branch main`
+    or the run id returned by GitHub CLI, then wait for it:
+
+```bash
+gh run watch <run-id> --exit-status
+```
+
+11. Stop if pre-tag validation does not conclude with `success`.
+12. Create and push an annotated release tag from the validated `main` commit:
+
+```bash
+git tag -a <tag> -m "Codegeist <tag>"
+git push origin <tag>
+```
+
+13. Locate and watch the tag-triggered release run. It must conclude with
+    `success`.
+14. Verify the GitHub Release exists, is not a draft, and has the expected tag:
+
+```bash
+gh release view <tag> --json tagName,isDraft,isPrerelease,url,assets
+```
+
+15. Verify the expected assets are present:
+
+```text
+codegeist-<version>-jvm-any.jar
+codegeist-<version>-linux-x64.tar.gz
+codegeist-<version>-windows-x64.zip
+codegeist-<version>-macos-x64.tar.gz
+codegeist-<version>-SHA256SUMS.txt
+```
+
+16. Download the release assets into a temporary directory under `/tmp/opencode`
+    and verify checksums:
+
+```bash
+gh release download <tag> --dir <tmp-dir>
+sha256sum -c codegeist-<version>-SHA256SUMS.txt
+```
+
+17. Report the release URL, tag, validated workflow run ids, assets, checksum
+    result, and any warnings such as GitHub Actions deprecation notices.
+
+## Rules
+
+- Do not create the tag before pre-tag validation passes.
+- Do not publish from branch or `workflow_dispatch` runs.
+- Do not use `git reset`, force-push, delete tags, or overwrite a release.
+- Do not continue when an expected asset or checksum is missing.
+- Do not mark the release complete until the GitHub Release is published and the
+  downloaded checksums verify.

.oc_local/opencode.json

@@ -2,6 +2,7 @@
   "$schema": "https://opencode.ai/config.json",
   "instructions": [
     ".oc_local/rules/architecture-doc.md",
+    ".oc_local/rules/codegeist-release.md",
     ".oc_local/rules/codegeist-task-specification.md",
     ".oc_local/rules/third-party-analysis-workflow.md"
   ]

.oc_local/rules/codegeist-release.md

@@ -0,0 +1,64 @@
+# Codegeist Release Workflow
+
+Use this rule for Codegeist GitHub release work, especially `/codegeist-release`,
+`.github/workflows/release.yml`, release tags, release assets, and checksum
+verification.
+
+## Release Shape
+
+- Use SemVer tags with a leading `v`, for example `v0.1.0`.
+- Pass the Maven release version without the leading `v`, for example
+  `-Drevision=0.1.0`.
+- Keep the default Maven revision as `0.1.0-SNAPSHOT` between release runs.
+- Use a `release/v*` branch for workflow development and branch validation before
+  merging release automation to `main`.
+
+## Required Validation Order
+
+1. Validate workflow changes on a `release/v*` branch. Branch runs must build,
+   smoke, checksum, and upload workflow artifacts without publishing a GitHub
+   Release.
+2. Merge the validated branch to `main`.
+3. Run pre-tag validation from `main` with `workflow_dispatch` and
+   `release_version=<version>`.
+4. Create and push the annotated `v*` tag only after pre-tag validation passes.
+5. Let the tag-triggered workflow publish the GitHub Release automatically.
+6. Verify the published release assets and checksums after the tag run passes.
+
+## Publication Policy
+
+- Only pushed `v*` tags may publish GitHub Releases.
+- `release/v*` branch runs and `workflow_dispatch` runs must not publish releases.
+- Tag runs publish releases automatically; they must not leave the release as a
+  draft.
+- Do not publish manually uploaded assets that bypass the workflow.
+- Do not create or push the final tag if the pre-tag validation run fails,
+  remains cancelled, or is skipped without an explicit release decision.
+
+## Expected Assets
+
+Each release must include exactly the expected Codegeist artifact family for the
+selected version:
+
+```text
+codegeist-<version>-jvm-any.jar
+codegeist-<version>-linux-x64.tar.gz
+codegeist-<version>-windows-x64.zip
+codegeist-<version>-macos-x64.tar.gz
+codegeist-<version>-SHA256SUMS.txt
+```
+
+Verify `codegeist-<version>-SHA256SUMS.txt` against the downloaded release assets
+before reporting the release as complete.
+
+## Safety Rules
+
+- Run `gh auth status` before using `gh workflow`, `gh run`, or `gh release`.
+- Confirm the tag does not already exist locally, remotely, or as a GitHub Release
+  before creating it.
+- Keep the worktree clean before tagging.
+- Prefer annotated tags for human-facing Codegeist releases.
+- Never use `git reset`, force-push, or delete tags as part of the normal release
+  command. If a bad release tag or release exists, stop and ask for an explicit
+  recovery decision.
+- Keep release docs and project memory synchronized when workflow behavior changes.

.oc_local/rules/codegeist-task-specification.md

@@ -88,6 +88,10 @@ This overlay adds only Codegeist-specific guidance. Keep generic phase behavior
   before creating the final `v*` release tag. Keep local Windows validation on a
   real Windows VM over SSH or a matching GitHub Windows runner; do not add local
   compatibility-layer smoke paths for Windows release validation.
+- For publishing a Codegeist GitHub Release, prefer `/codegeist-release v<version>`
+  after the validated release workflow is on `main`. The command owns pre-tag
+  validation, annotated tag creation, automatic tag-run publication, and published
+  asset checksum verification.
 - For Spring Shell command-line arguments such as `--version`, keep the current
   default command path noninteractive with
   `spring.shell.interactive.enabled=false` until a task intentionally implements

README.md

@@ -22,6 +22,9 @@ vision:
 - a Spring Shell `--version` command backed by Spring Boot build metadata
 - a GraalVM native-image Maven profile and local native smoke check
 - local Linux and Windows smoke scripts under `scripts/tests/`
+- a GitHub Actions release workflow for branch validation, pre-tag validation,
+  tag-triggered published releases, checksums, and Linux/Windows/macOS native
+  smokes
 - repo-local agent workflow rules, commands, and configuration
 - lightweight project memory in `docs/memory-bank/chat.md`
 
@@ -128,6 +131,26 @@ Native release downloads are planned as platform archives, not true single-file
 executables. See `docs/developer/release/native-distribution-packaging.md` for the
 Linux `tar.gz`, Windows `zip`, sidecar-library, and no-single-executable rationale.
 
+## GitHub Release Build
+
+The GitHub release workflow lives at `.github/workflows/release.yml`.
+
+It validates versioned release artifacts on GitHub-hosted runners:
+
+- `codegeist-<version>-jvm-any.jar`
+- `codegeist-<version>-linux-x64.tar.gz`
+- `codegeist-<version>-windows-x64.zip`
+- `codegeist-<version>-macos-x64.tar.gz`
+- `codegeist-<version>-SHA256SUMS.txt`
+
+Push a versioned release branch such as
+`release/v0.1.0-github-release-build` to test the workflow without publishing.
+After the workflow is on `main`, use `gh workflow run release.yml --ref main -f
+release_version=0.1.0` for pre-tag validation. A pushed `v*` tag starts the same
+workflow and publishes the assets to a GitHub Release.
+
+See `docs/developer/release/github-release-build.md` for the full operator flow.
+
 ## Getting Started
 
 1. Clone the repository with `git clone --recurse-submodules <repo-url>` so the nested `.opencode` and `.devcontainer` checkouts are available from the start.
@@ -171,8 +194,7 @@ If an older checkout is missing nested submodules, initialize them with
 
 ## Status
 
-The repository is still early, but it now has a real application entrypoint and
-an end-to-end local build/run workflow in the devcontainer. It also has local
-Linux and Windows smoke-test entrypoints for the current `--version` artifact
-contract. The next release-readiness step is GitHub-hosted release automation for
-Linux, Windows, and macOS artifacts.
+The repository is still early, but it now has a real application entrypoint, an
+end-to-end local build/run workflow in the devcontainer, local Linux and Windows
+smoke-test entrypoints, and GitHub-hosted release automation for the current
+`--version` artifact contract.

app/codegeist/cli/pom.xml

@@ -12,13 +12,14 @@
 
     <groupId>ai.codegeist</groupId>
     <artifactId>codegeist</artifactId>
-    <version>0.1.0-SNAPSHOT</version>
+    <version>${revision}</version>
     <name>${project.artifactId}</name>
     <description>Bootstrap application for codegeist.ai</description>
 
     <!-- Java 25 is the pinned baseline for the current Spring Boot 4 stack. -->
     <properties>
         <java.version>25</java.version>
+        <revision>0.1.0-SNAPSHOT</revision>
         <maven.compiler.release>${java.version}</maven.compiler.release>
         <graalvm.buildtools.version>0.10.6</graalvm.buildtools.version>
         <spring-ai.version>2.0.0-M6</spring-ai.version>

docs/developer/README.md

@@ -11,6 +11,8 @@ constraints here.
 
 ## Release Documents
 
+- `release/github-release-build.md` - GitHub-hosted release workflow triggers,
+  artifacts, branch validation, pre-tag validation, and published release behavior.
 - `release/local-build-smoke.md` - local Linux and Windows build-smoke entrypoints
   and final local smoke-suite usage.
 - `release/native-distribution-packaging.md` - native archive layout, sidecar

docs/developer/architecture/architecture.md

@@ -42,6 +42,7 @@ The current application build is defined by `app/codegeist/cli/pom.xml`.
 | Spring AI Agent Utils | BOM and core artifact `0.7.0` |
 | GraalVM | Native Maven profile using `native-maven-plugin` `0.10.6` |
 | Packaging | Spring Boot executable jar named `target/codegeist.jar` |
+| Release CI | `.github/workflows/release.yml` validates versioned JVM and native artifacts on GitHub-hosted Linux, Windows, and macOS runners, and publishes GitHub Releases only from `v*` tags |
 | Tests | Spring Boot context-load test, Spring-context command test, focused version output tests, native version smoke, local Linux smoke, Windows QEMU smoke, and final local smoke suite |
 
 Spring AI provider starters are not present. Spring AI Agent Utils is present as a
@@ -50,6 +51,8 @@ dependency baseline, but no Agent Utils runtime utility is wired into the app ye
 ## Implemented File Layout
 
 ```text
+.github/workflows/
+  release.yml
 app/codegeist/cli/
   pom.xml
   Taskfile.yml
@@ -183,6 +186,32 @@ download or VM prerequisites.
 | `task final-smoke-suite` | Runs `scripts/tests/final-smoke-suite.sh` | Local Linux and Windows smoke suite; both platforms must pass by default |
 | `task run` | `java -jar target/codegeist.jar` after `build` | Starts the packaged Spring Boot application |
 
+## GitHub Release Flow
+
+`.github/workflows/release.yml` is the implemented GitHub-hosted release build
+path. It accepts three trigger shapes:
+
+- push to `release/v*` for branch validation without publishing;
+- `workflow_dispatch` for pre-tag validation or reruns without publishing;
+- push to `v*` tags for release-cycle automation and GitHub Release publication.
+
+The workflow resolves a non-SNAPSHOT SemVer release version, passes it to Maven as
+`-Drevision=<version>`, runs Maven tests before packaging, builds and smoke-tests a
+versioned JVM jar, then builds native archives on GitHub-hosted Linux x64, Windows
+x64, and macOS x64 runners. The Windows native job activates the MSVC tools
+environment before running Maven native compilation. The checksum job generates and
+verifies `codegeist-<version>-SHA256SUMS.txt`; the release job uploads the jar,
+native archives, and checksum file to a published GitHub Release only for matching
+`v*` tags.
+
+The implemented release artifact names are:
+
+- `codegeist-<version>-jvm-any.jar`
+- `codegeist-<version>-linux-x64.tar.gz`
+- `codegeist-<version>-windows-x64.zip`
+- `codegeist-<version>-macos-x64.tar.gz`
+- `codegeist-<version>-SHA256SUMS.txt`
+
 ## Not Implemented Yet
 
 The following concepts are discussed in strategy docs but are not implemented in