feat: add automated release workflow

.github/internal/plans/MASTER.md

@@ -32,8 +32,8 @@ Each item links to its detailed implementation plan.
 | # | Topic | Status | Plan | Summary |
 |---|-------|--------|------|---------|
 | S1 | Commit Validation | 🟢 | [sdlc/01-commit-validation.md](sdlc/01-commit-validation.md) | Lefthook + Go commitlint |
-| S2 | Changelog Automation | ⏭️ | — | Auto-generate CHANGELOG.md from commits |
-| S3 | Release Workflow | ⏭️ | — | GitHub Actions with goreleaser |
+| S2 | Changelog Automation | 🟢 | — | Auto-generate CHANGELOG.md from commits |
+| S3 | Release Workflow | 🟢 | — | GitHub Actions with goreleaser |
 | S4 | Pre-commit Hooks | 🟢 | — | Run fmt/lint before commit |
 | S5 | Test Coverage | 🟢 | — | Coverage reporting in CI |
 

.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Semantic Release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - uses: go-semantic-release/action@v1
+        id: semrel
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          allow-initial-development-versions: true
+          changelog-generator-opt: "emojis=true"
+
+      - name: Release info
+        if: steps.semrel.outputs.version != ''
+        run: |
+          echo "Released version: ${{ steps.semrel.outputs.version }}"

CONTRIBUTING.md

@@ -156,3 +156,33 @@ New to modkit? Look for issues labeled [`good first issue`](https://github.com/a
 ## Questions?
 
 Open an issue or start a discussion. We're happy to help!
+
+## Releases
+
+Releases are automated using [go-semantic-release](https://github.com/go-semantic-release/semantic-release).
+
+### How It Works
+
+When changes are merged to `main`, the release workflow analyzes commit messages:
+
+| Commit Type | Release Action | Example |
+|-------------|----------------|---------|
+| `feat:` | Minor version bump (0.1.0 -> 0.2.0) | New API method |
+| `fix:` | Patch version bump (0.1.0 -> 0.1.1) | Bug fix |
+| `feat!:` or `BREAKING CHANGE` | Major version bump | Breaking API change |
+| `docs:`, `chore:`, `refactor:`, `test:`, `ci:` | No release | Documentation, tooling |
+
+### Versioning Strategy
+
+modkit follows [Semantic Versioning](https://semver.org/):
+
+- **v0.x.x** (current): API is evolving, breaking changes may occur in minor versions
+- **v1.0.0** (future): Stable API with backward compatibility guarantees
+- **v2+**: Major versions for breaking changes (requires `/v2` import path)
+
+### Using a Specific Version
+
+```bash
+go get github.com/aryeko/modkit@v0.1.0
+go get github.com/aryeko/modkit@latest
+```