@rtorcato/repo-tooling 3.13.0 → 3.13.1

package/README.md

@@ -175,7 +175,7 @@ ln -sf ../../node_modules/@rtorcato/repo-tooling/tooling/claude/repo-tooling.md
 
 This repo is also a self-hosted Claude Code marketplace. Install the plugin to
 get three skills — `repo-tooling` (adopt/audit the presets via the CLI),
-`npm-publish` (the family's release rules) and `ai-issue-loop` (the label-driven
+`npm-publish` (never hand-cut a release) and `ai-issue-loop` (the label-driven
 issue → PR pipeline) — in any session:
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.13.0",
+	"version": "3.13.1",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [

package/skills/ai-issue-loop/SKILL.md

@@ -694,6 +694,16 @@ Then spawn a background implementer agent:
 > 3. Read the repo's `CLAUDE.md` and obey it — especially any pre-commit build
 >    step or committed build output.
 > 4. Do the work. Conventional Commits within the branch.
+>
+>    **Do not run `pnpm install`.** This worktree's `node_modules` is a symlink to
+>    the main checkout, so pnpm sees a foreign directory it must purge first and
+>    aborts with `ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY`. Dependencies are
+>    already present — run tests, lint and build directly. If the work *is* a
+>    dependency change, `pnpm install --lockfile-only` updates `pnpm-lock.yaml`
+>    without touching `node_modules`. When that leaves a verification step you
+>    cannot run, say so in the PR body — name the command you could not run and
+>    why — so the reviewer knows CI is the only check on it rather than assuming
+>    you ran it.
 > 5. Push and open the PR. The title must be a Conventional Commit — it becomes
 >    the squash subject on `main` and, in repos using semantic-release, decides
 >    whether a release goes out at all. Body must contain `Closes #<N>`.

package/skills/npm-publish/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: npm-publish
-description: Use before releasing or publishing any @rtorcato/* package (repo-tooling and the whole family publish the same way). Triggers on "publish", "cut a release", "bump the version", "tag a release", "npm publish", "how do releases work here". The hard rule — releases are automated by semantic-release on merge to main; an agent must NEVER run `npm publish`, `npm version`, or `git tag`, or hand-edit the version in package.json. NOT for the day-to-day tooling audit/fix flow — that's the repo-tooling skill.
+description: Use before releasing or publishing any package in a repo set up by @rtorcato/repo-tooling. Triggers on "publish", "cut a release", "bump the version", "tag a release", "npm publish", "how do releases work here". The hard rule — releases are automated by the repo's release tool (semantic-release, Changesets, or Release Please); an agent must NEVER run `npm publish`, `npm version`, or `git tag`, or hand-edit the version in package.json. NOT for the day-to-day tooling audit/fix flow — that's the repo-tooling skill.
 ---
 
 # npm-publish
 
-Every `@rtorcato/*` package releases through **semantic-release on push to `main`**.
-Versioning, the git tag, the GitHub release, the CHANGELOG, and the npm publish are
-all derived from the commit history. There is no manual release step.
+A repo set up by `@rtorcato/repo-tooling` releases through **automation on merge to
+`main`** — one of semantic-release, Changesets, or Release Please. Versioning, the
+git tag, the GitHub release, the CHANGELOG, and the npm publish all come from that
+pipeline. There is no manual release step under any of them.
 
 ## The rule
 
@@ -17,31 +18,78 @@ all derived from the commit history. There is no manual release step.
 - `npm version` (or editing `"version"` in `package.json`)
 - `git tag` / pushing tags
 - hand-editing `CHANGELOG.md`
+- merging the "Version Packages" PR (Changesets) or the release PR (Release Please) —
+  that merge *is* the publish, so it is the human's release decision, not yours
 
-If asked to "release" or "bump the version", the correct action is to land a
-**conventional commit** on `main` (via PR) and let the pipeline do the rest.
+This holds for all three tools. Only the "what to do instead" differs, so first
+work out which tool the repo uses.
 
-## How a release actually happens
+## Which release tool is this repo on?
 
-1. Work on a branch; commit with Conventional Commits (header ≤ 100 chars).
-2. Open a PR; merge to `main` after review + green CI.
-3. semantic-release runs on `main` and decides the bump from the commits:
-   - `fix:` → patch
-   - `feat:` → minor
-   - `feat!:` / `BREAKING CHANGE:` → major
-   - `chore:` / `docs:` / `refactor:` / `test:` → **no release**
-4. It writes the version, tag, GitHub release, CHANGELOG, and publishes to npm.
+Check the repo root, in this order — these are the same signals the CLI's
+`doctor` check uses (`usesChangesets` / `checkSemanticRelease` in
+`src/languages/js/checks.ts`):
+
+| Signal | Tool |
+|---|---|
+| `.changeset/config.json` exists | **Changesets** |
+| `release-please-config.json` exists | **Release Please** |
+| `.releaserc*` / `release.config.*` exists, or a `"release"` key in `package.json` | **semantic-release** |
+
+Or just ask the tooling: `npx @rtorcato/repo-tooling doctor --json` reports the
+`semantic-release` check as ok with a detail naming the tool actually in use.
+
+If more than one is configured that's drift, not a choice — stop and flag it.
+
+## What to do instead, per tool
+
+### semantic-release
+
+The bump is derived from the commit history, so the commit type *is* the release
+decision:
+
+- `fix:` → patch
+- `feat:` → minor
+- `feat!:` / `BREAKING CHANGE:` → major
+- `chore:` / `docs:` / `refactor:` / `test:` → **no release**
+
+To ship a change: give it the right commit type and merge to `main`.
+
+### Changesets
+
+The bump is declared in a changeset file, **not** inferred from commits. A PR with
+no changeset publishes nothing, silently — so this is a required step, not an
+optional one:
+
+```bash
+pnpm changeset        # pick the packages + bump level, write the summary
+```
+
+That writes `.changeset/<name>.md`. Commit it with the change. On merge to `main`
+the release action opens (or updates) a "Version Packages" PR; merging *that* is
+what publishes — so never merge it yourself, leave it for a human. Hand-authoring
+`.changeset/*.md` is fine — it is the one file in this flow you are meant to
+write. `CHANGELOG.md` is still generated; don't touch it.
+
+### Release Please
+
+Also commit-driven, same Conventional Commit → bump mapping as semantic-release.
+On merge to `main` it opens a release PR that carries the version bump and the
+CHANGELOG entry; merging that PR tags and publishes, so leave that merge to a
+human — never do it yourself. Don't edit `.release-please-manifest.json` by hand.
 
 ## What an agent should do
 
-- To ship a change: make sure it carries the right commit type, then merge to `main`.
+- To ship a change: right commit type, plus a changeset if the repo is on Changesets.
 - To check the last release: `git tag --sort=-creatordate | head -1`, or the GitHub
-  Releases page — don't infer it from `package.json` (that's `0.0.0-development` /
-  the placeholder until CI stamps it).
-- If a release seems stuck, inspect the release workflow run — do **not** publish by hand.
+  Releases page — don't infer it from `package.json` (under semantic-release that's
+  `0.0.0-development` / a placeholder until CI stamps it).
+- If a release seems stuck, inspect the release workflow run, and check for an open
+  release / "Version Packages" PR waiting to be merged — report it, do **not** merge
+  it yourself and do **not** publish by hand.
 
 ## Why
 
 Manual publishes skip provenance, the CHANGELOG, and the tag/version invariant the
-whole family relies on, and a stray `npm version` commit derails the next automated
-bump. One automated path keeps every sibling repo publishing identically.
+pipeline maintains, and a stray `npm version` commit derails the next automated bump.
+One automated path per repo keeps releases reproducible and reviewable.