chore(release): unify SDLC flow and publish CLI artifacts (#215)

## Type
- [ ] `feat` — New feature
- [ ] `fix` — Bug fix
- [ ] `refactor` — Code restructure (no behavior change)
- [ ] `docs` — Documentation only
- [ ] `test` — Test coverage
- [x] `chore` — Build, CI, tooling
- [ ] `perf` — Performance improvement

## Summary
Unifies SDLC workflow policy around worktree-first development, removes
unnecessary Codecov token usage for public repository uploads, and
aligns contributor workflow docs with enforced CI safety practices.

## Changes
- add explicit worktree/branch safety rules and skill usage expectations
in AGENTS.md
- update CONTRIBUTING pull request workflow to require worktree-based
feature branches from updated main
- remove CODECOV_TOKEN dependency in ci workflow Codecov upload step

## Breaking Changes
None

## Validation
```bash
make fmt && make lint && make vuln && make test && make test-coverage
make cli-smoke-build && make cli-smoke-scaffold
```

## Checklist
- [x] Code follows project style (`make fmt` passes)
- [x] Linter passes (`make lint`)
- [x] Vulnerability scan passes (`make vuln`)
- [x] Tests pass (`make test`)
- [x] Coverage tests pass (`make test-coverage`)
- [x] CLI smoke checks pass (`make cli-smoke-build && make
cli-smoke-scaffold`)
- [ ] Tests added/updated for new functionality
- [x] Documentation updated (if applicable)
- [x] Commit messages follow Conventional Commits

## Resolves
N/A

## Notes
- Existing PR #215 updated with this template-aligned body.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Documentation**
* Added comprehensive release process guide covering CI workflow,
semantic versioning, and multi-platform artifact publishing.
* Updated contribution guidelines with enhanced development workflow,
including new linting and vulnerability scanning steps.

* **Chores**
* Configured multi-platform CLI release automation with support for
macOS, Linux, and Windows.
* Updated GitHub workflows with concurrency controls and enhanced
security scanning.
  * Updated repository contact links in issue templates.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: aryeko

.github/ISSUE_TEMPLATE/config.yml

@@ -1,8 +1,8 @@
 blank_issues_enabled: false
 contact_links:
   - name: Questions & Discussions
-    url: https://github.com/aryeko/modkit/discussions
+    url: https://github.com/go-modkit/modkit/discussions
     about: Ask questions and discuss ideas (don't open an issue)
   - name: Security Vulnerabilities
-    url: https://github.com/aryeko/modkit/security/policy
+    url: https://github.com/go-modkit/modkit/security/policy
     about: Report security issues privately

.github/pull_request_template.md

@@ -26,15 +26,19 @@
 
 <!-- Commands run and their results -->
 ```bash
-make fmt && make lint && make test
+make fmt && make lint && make vuln && make test && make test-coverage
+make cli-smoke-build && make cli-smoke-scaffold
 ```
 
 ## Checklist
 
 <!-- All boxes should be checked before requesting review -->
 - [ ] Code follows project style (`make fmt` passes)
 - [ ] Linter passes (`make lint`)
+- [ ] Vulnerability scan passes (`make vuln`)
 - [ ] Tests pass (`make test`)
+- [ ] Coverage tests pass (`make test-coverage`)
+- [ ] CLI smoke checks pass (`make cli-smoke-build && make cli-smoke-scaffold`)
 - [ ] Tests added/updated for new functionality
 - [ ] Documentation updated (if applicable)
 - [ ] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)

.github/workflows/ci.yml

@@ -6,6 +6,13 @@ on:
       - main
   pull_request:
 
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   pr-title:
     name: Validate PR Title
@@ -66,7 +73,6 @@ jobs:
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v5
         with:
-          token: ${{ secrets.CODECOV_TOKEN }}
           files: .coverage/coverage.out
           fail_ci_if_error: false
 

.github/workflows/release.yml

@@ -5,6 +5,10 @@ on:
     branches:
       - main
 
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
 permissions:
   contents: write
 
@@ -24,6 +28,28 @@ jobs:
           allow-initial-development-versions: true
           changelog-generator-opt: "emojis=true"
 
+      - name: Set up Go
+        if: steps.semrel.outputs.version != ''
+        uses: actions/setup-go@v6
+        with:
+          go-version: "1.25.7"
+          cache-dependency-path: |
+            tools/tools.go
+            go.mod
+
+      - name: Refresh tags
+        if: steps.semrel.outputs.version != ''
+        run: git fetch --force --tags
+
+      - name: Publish CLI release artifacts
+        if: steps.semrel.outputs.version != ''
+        uses: goreleaser/goreleaser-action@v6
+        with:
+          version: "~> v2"
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
       - name: Release info
         if: steps.semrel.outputs.version != ''
         run: |

.goreleaser.yml

@@ -0,0 +1,39 @@
+version: 2
+
+project_name: modkit
+
+builds:
+  - id: modkit
+    main: ./cmd/modkit
+    binary: modkit
+    env:
+      - CGO_ENABLED=0
+    goos:
+      - darwin
+      - linux
+      - windows
+    goarch:
+      - amd64
+      - arm64
+    ignore:
+      - goos: windows
+        goarch: arm64
+
+archives:
+  - id: modkit
+    builds:
+      - modkit
+    name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
+    format_overrides:
+      - goos: windows
+        format: zip
+
+checksum:
+  name_template: checksums.txt
+
+changelog:
+  disable: true
+
+release:
+  draft: false
+  prerelease: auto

AGENTS.md

@@ -73,6 +73,19 @@ High-signal packages by density:
 - If `make vuln` or `make test-coverage` is not run or fails, leave corresponding checklist items unchecked (or mark N/A with explicit reason).
 - After any new commit on the PR branch, rerun affected checks and re-reconcile the checklist.
 
+## WORKTREE AND BRANCH SAFETY
+- `main` is integration-only. Never commit directly on `main`/`master`.
+- Start each task from updated `origin/main`: `git fetch origin && git switch main && git pull --ff-only origin main`.
+- Create a dedicated branch in a dedicated worktree for each task: `git worktree add .worktrees/<task> -b <type>/<task> main`.
+- Do all edits, tests, and commits only inside that linked worktree branch.
+- Never push directly to `main`; all changes land through PR merge.
+- If a commit lands on `main` by mistake: create a rescue branch from the pre-revert state, cherry-pick or move intended commits there, then `git revert` on `main`.
+
+## SKILL USAGE EXPECTATION
+- Before acting, evaluate available skills and load matching skills for the task.
+- Use `superpowers/using-git-worktrees` when starting implementation work.
+- Use `superpowers/verification-before-completion` before declaring completion.
+
 ## COMMANDS
 ```bash
 make fmt

CONTRIBUTING.md

@@ -108,16 +108,11 @@ make cli-smoke-scaffold
 ### Install Development Tools
 
 ```bash
-# goimports (for make fmt)
-go install golang.org/x/tools/cmd/goimports@latest
-
-# golangci-lint (for make lint)
-go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
-
-# govulncheck (for make vuln)
-go install golang.org/x/vuln/cmd/govulncheck@latest
+make tools
 ```
 
+`make tools` installs tool versions pinned by the repository.
+
 ## Contribution Guidelines
 
 ### Before You Start
@@ -129,9 +124,13 @@ go install golang.org/x/vuln/cmd/govulncheck@latest
 ### Pull Request Process
 
 1. Fork the repository
-2. Create a feature branch (`git checkout -b feat/my-feature`)
+2. Update `main` and create a feature worktree branch:
+   - `git fetch origin && git switch main && git pull --ff-only origin main`
+   - `git worktree add .worktrees/my-feature -b feat/my-feature main`
+   - Work from `.worktrees/my-feature` (do not commit on `main`)
 3. Make your changes with tests
-4. Run `make fmt && make lint && make test`
+4. Run `make fmt && make lint && make vuln && make test && make test-coverage`
+   - Also run CLI gate: `make cli-smoke-build && make cli-smoke-scaffold`
 5. Commit with a conventional prefix (`feat:`, `fix:`, `docs:`, `chore:`)
 6. Open a pull request with a clear description
 

README.md

@@ -224,6 +224,7 @@ See [Architecture Guide](docs/architecture.md) for details.
 - [API Reference](docs/reference/api.md) — Types and functions
 - [Architecture](docs/architecture.md) — How modkit works under the hood
 - [FAQ](docs/faq.md) — Common questions
+- [Release Process](docs/guides/release-process.md) — CI and versioned CLI release flow
 
 **Examples:**
 - [hello-simple](examples/hello-simple/) — Minimal example, no Docker

docs/guides/release-process.md

@@ -0,0 +1,42 @@
+# Release Process
+
+This repository uses a unified SDLC flow for CI and releases:
+
+1. Pull request checks run on each PR:
+   - PR title semantic validation
+   - lint + vulnerability scan
+   - coverage tests
+   - CLI smoke scaffolding checks
+2. Merges to `main` trigger the release workflow.
+3. `go-semantic-release` determines whether a new semantic version should be released from Conventional Commits.
+4. If a version is released, GoReleaser builds and publishes CLI artifacts to the GitHub Release:
+   - `darwin/amd64`
+   - `darwin/arm64`
+   - `linux/amd64`
+   - `linux/arm64`
+   - `windows/amd64`
+5. Release assets include archives and `checksums.txt`.
+
+## Quality Gates
+
+Before creating or updating a PR, run:
+
+```bash
+make fmt && make lint && make vuln && make test && make test-coverage
+make cli-smoke-build && make cli-smoke-scaffold
+```
+
+Branch protection should require these workflow checks on pull requests:
+
+- `Validate PR Title`
+- `Quality (Lint & Vuln)`
+- `test`
+- `CLI Smoke Test`
+- `Analyze` (CodeQL)
+
+## Versioning Rules
+
+- `fix:` -> patch
+- `feat:` -> minor
+- `feat!:` / `BREAKING CHANGE:` -> major (or minor during initial development when configured)
+- docs/chore/test/ci-only commits do not release by default

docs/specs/design-release-versioning-sdlc-cli.md

@@ -56,9 +56,9 @@ Current release flow creates semantic versions and release notes, but it does no
 
 ## 6. Required CI Changes
 
-## 6.1. Add CLI Smoke-Test Job in `ci.yml`
+## 6.1. Maintain CLI Smoke-Test Job in `ci.yml`
 
-Add a new job `cli-smoke` that runs on pull requests and pushes.
+`cli-smoke` is already present in `ci.yml` and must remain a required check on pull requests and pushes.
 
 Validation sequence:
 
@@ -180,7 +180,7 @@ This initiative is complete when all are true:
 
 ### Phase 1: CI Guardrails
 
-- Add `cli-smoke` job to `ci.yml`.
+- Confirm `cli-smoke` job remains enforced in `ci.yml`.
 - Validate against current `main`.
 
 ### Phase 2: Release Artifacts
@@ -207,7 +207,7 @@ This initiative is complete when all are true:
 
 The follow-up PR (after `feat/cli-tooling` merge) should include:
 
-- [ ] `.github/workflows/ci.yml` updated with `cli-smoke` job.
+- [ ] `cli-smoke` job in `.github/workflows/ci.yml` is preserved and remains required.
 - [ ] `.github/workflows/release.yml` updated for CLI artifact publishing.
 - [ ] `.goreleaser.yml` added and validated.
 - [ ] README install section updated.