fix: address PR review feedback and update documentation

- Add test step to release.yml before publishing (Codacy + Copilot review)
- Restore prepublishOnly as safety net for local publishes (Codacy + Copilot review)
- Set NPM_CONFIG_PROVENANCE=true to preserve provenance signing (Copilot review)
- Update README CI/CD section with new changesets workflow
- Add versioning/changesets section to AGENTS.md with agent responsibilities
- Add agent self-documentation guidelines to AGENTS.md
- Update SPECS/deployment.md to reflect new release workflow

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: alerizzo

.github/workflows/release.yml

@@ -35,6 +35,9 @@ jobs:
       - name: Build
         run: npm run build
 
+      - name: Test
+        run: npm test
+
       - name: Create Release PR or Publish
         uses: changesets/action@6a0a831ff30acef54f2c6aa1cbbc1096b066edaf # v1
         with:
@@ -44,3 +47,4 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_CONFIG_PROVENANCE: true

AGENTS.md

@@ -24,6 +24,7 @@ This CLI wraps the [Codacy Cloud API v3](https://api.codacy.com/api/api-docs) us
 
 ```
 codacy-cloud-cli/
+├── .changeset/                  # Changesets config and pending changeset files
 ├── src/
 │   ├── index.ts                 # CLI entry point (Commander.js setup)
 │   ├── api/
@@ -173,6 +174,35 @@ The `SPECS/` folder at the project root is the single source of truth for specs
 4. Update `SPECS/README.md` (mark tasks done, add changelog entry) when completing work
 5. Add new tasks to `SPECS/README.md` pending table when discovered during work
 
+## Versioning & Releasing
+
+This project uses [changesets](https://github.com/changesets/changesets) for versioning and npm publishing.
+
+### How it works
+
+1. Every PR must include a changeset file (CI enforces this via the `changeset-check` job)
+2. Run `npx changeset` to create one — select the bump type (`patch`, `minor`, `major`) and describe the change
+3. For PRs that don't need a version bump (docs, CI, refactors), use `npx changeset --empty`
+4. On merge to `main`, the `release.yml` workflow creates a "chore: version packages" PR that bumps the version and updates `CHANGELOG.md`
+5. Merging that PR triggers the actual npm publish with provenance
+
+### Agent responsibilities for changesets
+
+When completing work that changes user-facing behavior or adds features, agents **must**:
+1. Run `npx changeset` and create an appropriate changeset file before committing
+2. Use `patch` for bug fixes, `minor` for new features or commands, `major` for breaking changes
+3. Write a clear, user-facing summary in the changeset (this becomes the CHANGELOG entry)
+
+For internal-only changes (refactors, docs, CI, test-only changes), use `npx changeset --empty`.
+
+### Agent responsibilities for self-documenting changes
+
+When completing work, agents **must** update relevant documentation:
+1. **`SPECS/README.md`** — mark tasks as done in the pending table, add a changelog entry
+2. **`README.md`** — if a new command was added or renamed, update the commands summary table (one row per command, no detailed args/options)
+3. **`AGENTS.md`** — if a new convention, pattern, or workflow was introduced that affects how agents work, add it to the relevant section
+4. **`SPECS/deployment.md`** — if CI/CD or publishing workflows changed, update this spec to match
+
 ## Environment Variables
 
 | Variable | Required | Description |

README.md

@@ -89,14 +89,17 @@ npm run update-api       # Update the auto-generated API client
 ### CI/CD
 
 - **CI**: Runs on every push to `main` and on PRs. Builds and tests across Node.js 18, 20, and 22.
-- **Publish**: Triggered on GitHub release creation. Builds, tests, and publishes to npm with provenance.
+- **Release**: Uses [changesets](https://github.com/changesets/changesets) for automated versioning and npm publishing.
 
-To publish a new version:
-1. Update the version in `package.json`
-2. Create a GitHub release with a tag matching the version (e.g. `v1.1.0`)
-3. The publish workflow will automatically build and push to npm
+#### Publishing a new version
 
-**Prerequisite**: Add an `NPM_TOKEN` secret to your GitHub repository settings.
+1. When making changes, run `npx changeset` and describe your change (select `patch`, `minor`, or `major`)
+2. Include the generated `.changeset/*.md` file in your PR
+3. CI enforces that every PR includes a changeset (use `npx changeset --empty` for changes that don't need a version bump, like docs or CI)
+4. When PRs are merged to `main`, the release workflow automatically creates a **"chore: version packages"** PR that bumps the version and updates `CHANGELOG.md`
+5. Merging that PR publishes to npm with provenance
+
+**Prerequisite**: An `NPM_TOKEN` secret must be configured in the GitHub repository settings.
 
 ## License
 

SPECS/deployment.md

@@ -1,13 +1,13 @@
 # Deployment & CI Spec
 
-**Status:** ✅ Done (2026-02-18)
+**Status:** ✅ Done (updated 2026-05-08)
 
 ## npm Package
 
 - **Binary name:** `codacy` (registered in `package.json` under `bin`)
 - **Included files:** `dist/` and `README.md` (via `files` field)
-- **Pre-publish:** `prepublishOnly` runs `npm run build` using `tsconfig.build.json`
-- **Engines:** requires Node.js >= 18
+- **Pre-publish:** `prepublishOnly` runs `npm run update-api && npm run build` as a safety net for local publishes
+- **Engines:** requires Node.js >= 20
 - **Install globally:** `npm install -g "@codacy/codacy-cloud-cli"`
 
 ## GitHub Actions
@@ -18,23 +18,26 @@ Triggers on: push and pull requests to `main`.
 
 Matrix: Node.js 18, 20, 22.
 
-Steps:
-1. Checkout
-2. Setup Node
-3. `npm ci`
-4. `npm run build`
-5. `npm test`
+Jobs:
+- **build-and-test**: checkout → setup node → install → generate API client → type check → build → test
+- **changeset-check** (PRs only): verifies at least one `.changeset/*.md` file is present in the PR diff
+
+### Release (`release.yml`)
 
-### Publish to npm (`publish.yml`)
+Triggers on: push to `main`.
 
-Triggers on: GitHub release published.
+Uses the [changesets/action](https://github.com/changesets/changesets) to automate versioning and publishing.
 
 Steps:
 1. Checkout
 2. Setup Node with `registry-url: https://registry.npmjs.org`
 3. `npm ci`
-4. `npm run build`
-5. `npm publish` (uses `NODE_AUTH_TOKEN` secret)
+4. Generate API client (`npm run update-api`)
+5. Build (`npm run build`)
+6. Test (`npm test`)
+7. `changesets/action` — either:
+   - Creates/updates a "chore: version packages" PR (bumps version, updates CHANGELOG.md)
+   - If that PR was just merged, runs `changeset publish` to publish to npm with provenance
 
 ## Homebrew Formula
 
@@ -44,5 +47,5 @@ Planned for future distribution as a separate brew formula for macOS/Linux/Windo
 
 | Secret | Used by |
 |---|---|
-| `NODE_AUTH_TOKEN` | npm publish workflow |
+| `NPM_TOKEN` | Release workflow (`NODE_AUTH_TOKEN` for npm publish) |
 | `CODACY_API_TOKEN` | CLI runtime (env var, not a secret in CI) |

package.json

@@ -23,6 +23,7 @@
     "changeset": "changeset",
     "version-packages": "changeset version",
     "release": "changeset publish",
+    "prepublishOnly": "npm run update-api && npm run build",
     "start": "npx ts-node src/index.ts",
     "start:dist": "node dist/index.js",
     "fetch-api": "curl https://artifacts.codacy.com/api/codacy-api/55.6.4/apiv3-bundled.yaml -o ./api-v3/api-swagger.yaml --create-dirs",