com.elestrago.unity.package-tools 2.3.0 → 2.4.0

package/CAHNGELOG.md

@@ -2,6 +2,14 @@
 
 ---
 
+## [2.4.0](https://gitlab.com/elestrago-pkg/package-tool/-/tags/2.4.0)
+
+### Added
+
+- Added `unity-package-release` skill sample for cutting `V-{version}` release commits.
+
+---
+
 ## [2.3.0](https://gitlab.com/elestrago-pkg/package-tool/-/tags/2.3.0)
 
 ### Added

package/README.md

@@ -29,7 +29,7 @@ Add the package to `Packages/manifest.json`:
     }
   ],
   "dependencies": {
-    "com.elestrago.unity.package-tools": "2.3.0"
+    "com.elestrago.unity.package-tools": "2.4.0"
   }
 }
 ```

package/Samples~/ClaudeSkills/unity-package-release/SKILL.md

@@ -0,0 +1,373 @@
+---
+name: unity-package-release
+description: Cut a release commit for any Unity package that uses the `com.elestrago.unity.package-tools` editor tool (the one that drives a `PackageManifestConfig` ScriptableObject and exports via the **Export Package Source** Inspector button). Discovers the config asset, package name, changelog filename, README install snippet, and publish flow at runtime via `scripts/discover_package.py`, so the same skill works in every package-tool consumer regardless of layout. Bumps the SO's `packageVersion`, updates the consumer-install version line in the project-root README (if one exists), prepends or appends an entry to the changelog (whatever filename the config's `changelogPath` resolves to), prompts the maintainer to run **Export Package Source** in Unity so the exported `Assets/Package/<X>/` artifacts and `Release/package.json` regenerate, stages exactly the touched files, and proposes a `V-{version} {summary}` commit. Detects the publish flow (GitLab elestrago CI, GitLab generic, GitHub Actions, or manual) and prints the matching handoff block — the skill never tags or pushes itself. Use whenever a package-tool maintainer wants to wrap pending changes into a release — phrasings like "bump the version", "cut a release", "update changelog and commit", "ship this as 2.x.y", "make a V- commit", or after a `/unity-package-tool-developer` run finishes its code edits. Refuses to run if no `PackageManifestConfig.asset` is found under `Assets/`.
+---
+
+# unity-package-release
+
+Maintainer skill for any Unity-package repo that uses `com.elestrago.unity.package-tools` (the editor tool whose `PackageManifestConfig` ScriptableObject + **Export Package Source** Inspector button drive the package build). Walks the version-bump → changelog → Export → commit pipeline for whatever changes are already on disk.
+
+**Repo-agnostic by design.** Other than relying on the `PackageManifestConfig` shape, the skill makes no assumptions about layout: the config asset can live anywhere under `Assets/`; the changelog filename is whatever `changelogPath` resolves to (commonly `CHANGELOG.md`, occasionally `CAHNGELOG.md` due to a long-standing typo in the upstream tool's example); the README may or may not contain a consumer-install snippet; the publish step may be a GitLab pipeline, a GitHub workflow, or a manual `npm publish`. Everything repo-specific is discovered by `scripts/discover_package.py` at the start of each run.
+
+**Out of scope.** The skill never writes code (`.cs` files belong to the developer skill if there is one; otherwise to the maintainer). It never invokes Unity. It never tags. It never pushes. Tagging and publishing happen in whatever the project's chosen flow is — the skill prints a handoff block matched to that flow and stops.
+
+Two common entry points:
+
+- **After a developer-skill run** — e.g. `unity-package-tool-developer` ends by asking whether to hand off here. The change is fresh on disk, the user accepts, and this skill picks up at Step 1.
+- **Stand-alone** — the maintainer edited files by hand and now wants a clean release commit. Run `/unity-package-release` directly.
+
+## Output contract (strict)
+
+This skill writes only inside this allow-list, all discovered at runtime by `scripts/discover_package.py` (path field shown for each):
+
+- **The `PackageManifestConfig.asset`** (`config_asset.path`) — overwrites only the line whose number is `config_asset.package_version_line`. Never touches `packageVersion` lines elsewhere in the file (they belong to nested `dependencies:` entries, identified by a four-space indent; the skill targets only the SO's own two-space-indented field).
+- **The project-root changelog** (`changelog.resolved_path`) — prepends one entry, or appends a bullet to the in-flight entry. This is the only changelog the skill writes; never write to any copy under the destination path (those are export artifacts regenerated by `FileTools.CopyOrReplaceFileToDirectory` on every export).
+- **The project-root README** (`readme.resolved_path`) — only the version string inside the consumer-install snippet at `readme.install_snippet.line`. Skipped entirely when `readme.install_snippet` is `null` (the README documents installation a different way, or there is no README). Bumped in lockstep with `packageVersion`.
+
+This skill **never** writes outside that allow-list. Specifically, it never touches:
+
+- Any `.cs` file — code changes belong elsewhere.
+- The export destination directory (`package.destination_path`, commonly `Release/` but configurable) — those files are regenerated by Unity when the maintainer clicks **Export Package Source**.
+- Any pipeline file (`.gitlab-ci.yml`, `.github/workflows/*.yml`) — the skill reads them to detect the publish flow but does not modify them.
+- The documentation directory (`package.documentation_path`, commonly `Documentation~/`) — owned by the project's docs skill or by the maintainer.
+- The exported package source folder under the destination path (its `CAHNGELOG.md` / `CHANGELOG.md` / `README.md` / `LICENSE` / docs) — these are export artifacts. Edit the project-root files instead. If a diff touches them, treat it as a misroute and re-apply to the project-root files.
+
+The skill **does** stage the regenerated export-artifact files after the user confirms the Export ran (Step 5 option (a)). Staging is not the same as writing — Unity wrote them; the skill just adds them to the commit.
+
+For git, the skill **stages and commits** the allow-list files (plus any `.cs` files the user explicitly lists as part of the release) after explicit user confirmation in Step 7; it never pushes, tags, or amends.
+
+## Skill args
+
+Parse from the user's prompt (defaults shown):
+
+- `dry-run=false` — when `true`, print intended edits and the commit plan to the conversation but do not write or stage.
+- `version=<semver>` — when present, set `packageVersion` to this exact value instead of asking. Skips the in-flight/new-version prompt.
+- `mode=<in-flight|new-version|ask>` — default `ask`. `in-flight` skips the version-bump prompt and appends a bullet to the existing entry. `new-version` skips the prompt and increments per `segment`.
+- `segment=<patch|minor|major>` — only meaningful with `mode=new-version` (or when the user picks "new version" in the prompt and `version=` is not set). Default `patch`.
+- `category=<Added|Changed|Fixed|Removed|Security|Deprecated>` — when the kind of change is unambiguous from the prompt, set the changelog category directly. Otherwise asked once.
+- `summary=<text>` — when present, use as the changelog bullet text and the commit summary. Otherwise asked once.
+- `config-asset=<path>` — explicit path to the `PackageManifestConfig.asset`. Use only in repos that ship more than one config; otherwise the script picks the closest-to-root candidate automatically.
+- `publish-flow=<gitlab-elestrago-ci|gitlab-generic|github-actions|manual>` — override the auto-detected publish flow when Step 8 picks the wrong handoff block. The detection is best-effort; this argument lets the maintainer pin it.
+- `skip-docs=false` — when `true`, skip the docs regeneration prompt (Step 4).
+- `skip-export=false` — when `true`, skip the Export Package Source prompt (Step 5) and stage only project-root files. Same staleness warning applies.
+
+## Preflight (refuse to run on failure)
+
+1. Run `scripts/discover_package.py` from the skill's own directory (resolve `${SKILL_DIR}` at runtime — do not hardcode):
+
+   ```bash
+   python3 "${SKILL_DIR}/scripts/discover_package.py" --repo .
+   ```
+
+   If the script exits non-zero or `ok` is `false`, the repo does not look like a package-tool consumer (no `PackageManifestConfig.asset` under `Assets/`). Abort with the script's error message.
+
+2. The `git.status_porcelain` field of the JSON output is the same as `git status --porcelain`. Inspect for pre-staged paths from a prior session that would otherwise ride along silently — call them out before proceeding so the maintainer can unstage anything that doesn't belong in this release commit. Do not fail; just make the existing diff visible.
+
+## Pipeline (execute in order)
+
+### Step 1 — Read current state
+
+Use the JSON from the preflight `discover_package.py` run. The relevant fields are:
+
+- `config_asset.path` and `config_asset.package_version_line` — for the targeted version-bump rewrite.
+- `package.name`, `package.display_name`, `package.version` — the current SO state.
+- `package.destination_path` — the export target (e.g. `Release`, `Build`, `Packages/<package>`, etc.).
+- `changelog.resolved_path`, `changelog.exists`, `changelog.latest_heading` — including the heading's `version`, `url`, and `tag_url_format` (with `{version}` placeholder) so Step 3 can mirror the existing URL pattern.
+- `readme.resolved_path`, `readme.install_snippet` (which may be `null`) — for the targeted README rewrite.
+- `release_package_json` — the exported `package.json` inside the destination, if any, and its `version`. Used in Step 5 to warn when the user is about to skip the Export and silently break the publish trigger.
+- `publish_flow.detected_flow` — for Step 8.
+- `git.branch`, `git.remote_url`, `git.recent_commits`, `git.diff_stat_head` — for context.
+
+Show the user the relevant subset (current `packageVersion`, README install-snippet version, latest changelog heading, recent commits, diff stat) and explicitly surface any drift between the three version sources. Drift is common during in-flight work but worth flagging so the user can confirm intent.
+
+### Step 2 — Decide the version (asks user via `AskUserQuestion` unless args say otherwise)
+
+If `version=` was passed, use that exact value (no prompt). Apply Step 2c.
+
+If `mode=in-flight` was passed, fold into the in-flight version (no bump). Skip to Step 3.
+
+If `mode=new-version` was passed, increment per `segment` (default patch). Apply Step 2c.
+
+Otherwise ask via `AskUserQuestion`:
+
+- (a) **Fold into in-flight version (no bump)** — append a bullet to the existing `## [{current-version}]` entry. Use when several bullets are accumulating into one release across multiple commits.
+- (b) **Start a new version (patch)** — most common for routine changes.
+- (c) **Start a new version (minor)** — for new user-facing features.
+- (d) **Start a new version (major)** — for breaking changes.
+
+The in-flight option leads the list because the most common drift signal (latest changelog heading equal to current `packageVersion` with no matching `V-{version}` commit) means a release is being assembled across multiple commits and auto-incrementing is wrong.
+
+**Step 2c** (only when a new version was chosen or `version=` was set):
+
+Write the new version to both files, preserving the rest of each file byte-for-byte:
+
+- The `PackageManifestConfig.asset` at `config_asset.path`, line `config_asset.package_version_line` — replace only the version on that line. Never touch other `packageVersion:` lines (they're nested under `dependencies:` and indented one level deeper).
+- The project-root README at `readme.resolved_path`, line `readme.install_snippet.line` — replace only the version inside the snippet's `"<package-name>": "X.Y.Z"`. Skip this when `readme.install_snippet` is `null`.
+
+### Step 3 — Write the changelog entry
+
+Edit the project-root changelog at `changelog.resolved_path`. Do **not** edit any copy that lives inside the export destination — those are regenerated by `FileTools.CopyDocumentationToDirectory` on every export, so manual edits there are overwritten on the next `CreateOrUpdatePackageSource`.
+
+Detect the existing format from `changelog.latest_heading`. The canonical format used by package-tool consumers is:
+
+```markdown
+## [{version}]({tag-url})
+
+### {Category}
+
+- One-bullet description.
+
+---
+```
+
+Where `{tag-url}` is `changelog.latest_heading.url` with the version substituted — use `changelog.latest_heading.tag_url_format` directly (it already has `{version}` in place of the previous version's number). If `tag_url_format` is `null` (the existing changelog uses plain `## [version]` headings without a link, or there is no previous entry to copy from), write a plain `## [{version}]` heading and ask the user once whether to add a link target — different repos point at GitLab tags, GitHub releases, openupm pages, or no link at all.
+
+If Step 2 folded into the in-flight version: append the new bullet under the matching category in the existing entry (creating the category heading if missing).
+
+If Step 2 started a new version: prepend a new entry above the most recent.
+
+**Category.** If `category=` was passed, use it. Otherwise ask via `AskUserQuestion`. Categories are the Keep-a-Changelog set: `Added`, `Changed`, `Fixed`, `Removed`, `Security`, `Deprecated`.
+
+**Summary.** If `summary=` was passed, use it. Otherwise ask the user once, showing a draft based on `git.diff_stat_head`.
+
+**Format rules — strict.** The changelog is a bullet list, not a release-notes paragraph. Each change is **one bullet**, ideally one sentence (≈15 words), absolute hard cap two short sentences. Third-person past-style imperative (`Added X`, `Fixed Y`, `Moved Z`). Name the user-facing symbol (`copyEntries`, `CIUtils.Generate`, `Tools/PackageTools/<menu>`) so the reader can grep. **No semantics, edge cases, pipeline order, fallback behavior, or design rationale in the bullet** — that prose belongs in the docs directory. If you find yourself reaching for em-dashes, "such that", or a second clause to explain *how* it works, stop and move that detail to docs. Anti-example: a five-sentence bullet listing fallback paths, ordering inside the pipeline, and overwrite semantics. Correct example: `Added copyEntries on PackageManifestConfig for staging external content before export. See Documentation~/manual.md.`
+
+### Step 4 — Documentation prompt
+
+If the change has *any* user-facing semantics beyond a self-evident button or menu — new config fields, new pipeline behavior, fallback or merge rules, new CLI flags, new template tokens, or anything a user would need to read prose to use correctly — the long explanation belongs in the docs directory (`package.documentation_path`), not the changelog.
+
+Skip this step when `skip-docs=true`. Otherwise ask the user via `AskUserQuestion`:
+
+- (a) **Run the project's docs skill now (recommended)** — if the repo has a docs-generation skill installed (e.g. `unity-package-docs`), invoke it; it will read the updated source and rewrite the docs directory. Recommended whenever any prose in the changelog cross-references a docs section.
+- (b) **Defer** — note the deferred work in the summary so the user can batch it with other changes before the next release commit. The cross-reference in the changelog still names the *intended* target the user will fill in on the next docs run.
+- (c) **Skip** — only when the change is purely internal (refactor, helper rename, dependency-free constant) with no user-facing effect.
+
+Do not silently invoke a docs skill — wait for the answer, since regeneration touches a wide file set and the user may want to stage other changes first. The changelog bullet (Step 3) must cross-reference the doc section regardless of which option is chosen.
+
+### Step 5 — Export Package Source confirmation
+
+The export artifacts inside `package.destination_path` (the destination's `README.md`, the changelog copy, the docs directory, the `package.json`) are regenerated by `FileTools.CreateOrUpdatePackageSource` when the maintainer clicks **Export Package Source** on the `PackageManifestConfig.asset` in the Unity inspector. The skill cannot trigger this — Unity must be open.
+
+Without this step the commit ships project-root README/changelog files that disagree with what consumers actually pull (the destination copy is what gets packed), and `release_package_json.path` does not get a fresh `version`, which means CI flows that watch that file for a version delta will not publish even though the changelog and config asset advertise a new version.
+
+Surface the current `release_package_json.version` vs. the new `packageVersion` in the prompt so the maintainer can see whether the destination is stale.
+
+Skip this step when `skip-export=true` (treat as option (b) below).
+
+Otherwise prompt the user once via `AskUserQuestion`:
+
+- (a) **Done — I ran Export Package Source (recommended)** — proceed to Step 6 and stage both the project-root files and the regenerated destination artifacts in the same commit.
+- (b) **Skip Export — commit project-root files only** — proceed to Step 6 staging only the project-root files. Print a warning that the next consumer pull will see stale artifacts, and (if applicable) that CI publish triggers may not fire until the next export runs. Use only for in-progress work that the maintainer will rebuild before publishing.
+- (c) **Cancel commit** — exit. Step 2 and Step 3 edits stay on disk; the maintainer will stage and commit by hand.
+
+Do not proceed past this prompt without an answer.
+
+### Step 6 — Stage the right files
+
+Build the staging list from what this run actually changed (not a blanket `git add -A`, which would sweep in the maintainer's unrelated work-in-progress):
+
+- The project-root changelog at `changelog.resolved_path` (always, if Step 3 wrote).
+- The project-root README at `readme.resolved_path` (only if Step 2 bumped and `readme.install_snippet` was non-null).
+- The `PackageManifestConfig.asset` at `config_asset.path` (only if Step 2 bumped).
+- Inside `package.destination_path`: the regenerated changelog/README/docs copies and `package.json` — only when Step 5's answer was (a). Filter by mtime newer than the start of this skill run so untouched files don't ride along.
+- Any `.cs` files (or asmdef edits) the user explicitly lists as part of this release — typically the output of a recent developer-skill run. Ask the user if it's not obvious from the unstaged diff which files belong in this commit.
+
+Show the user the exact `git add` invocation listing each file. Ask for confirmation if anything looks off (e.g. an unexpected `.meta` file slipped in — meta files are normally regenerated and may or may not belong in the release commit). Run it.
+
+After staging, re-check `git status --porcelain` and surface anything in the index that this skill did not stage — see [[feedback_staging_isolation]]: prior-session staged changes ride along silently otherwise. If extras are present, ask the user before committing.
+
+### Step 7 — Propose the commit message and commit
+
+Commit message format (see [[feedback_commit_message]]):
+
+```
+V-{version} {imperative summary}
+```
+
+Where:
+
+- `{version}` is the value now in the SO after Step 2. For an in-flight change (option (a) in Step 2), this is the unchanged version — the commit still reads `V-{version}` with the existing one, signalling that more bullets are accumulating under that heading.
+- `{imperative summary}` is short, third-person past-style imperative, mirroring the changelog bullet just written (≤ ~72 chars on the subject line — keep it greppable, not a paragraph). When several bullets are landing across multiple skill runs into the same in-flight version, each commit has its own summary describing what *that* commit added; do not try to summarize the whole release.
+
+Optional body lines are fine when the summary alone leaves the diff ambiguous, but keep it short — the changelog and docs directory carry the long-form prose.
+
+Show the user the proposed `git commit -m "..."` command and ask via `AskUserQuestion`:
+
+- (a) **Commit now (recommended)** — skill runs `git commit -m "..."` and reports the new SHA.
+- (b) **Print only** — print the command, do not execute. Use when the maintainer wants to tweak the wording first.
+- (c) **Cancel** — leave the staging area as-is and exit. The maintainer will inspect and commit by hand.
+
+Never pass `--amend`, `--no-verify`, or `-c commit.gpgsign=false`. If a pre-commit hook fails, surface the hook output verbatim, fix the underlying issue, and create a fresh commit rather than amending.
+
+### Step 8 — Publish handoff (do not tag, do not push tags)
+
+The skill never tags and never pushes. The publish step varies per repo; pick the matching block by `publish_flow.detected_flow` (or by the `publish-flow=` argument override), and print it for the maintainer. Substitute `{version}` with the value committed in Step 7 and `<current-branch>` with `git.branch`.
+
+For **`gitlab-elestrago-ci`** (`.gitlab-ci.yml` includes the shared `elestrago/ci-pipelines` `unity-package-npm-publish.yml`):
+
+```
+Commit landed. Next steps are manual + CI:
+  1. Push the working branch:        git push -u origin <current-branch>
+  2. Open a merge request to main.
+  3. On merge, .gitlab-ci.yml -> elestrago/ci-pipelines unity-package-npm-publish.yml
+     detects the version change in {release-package-json-path}, creates tag {version},
+     and publishes to the npm registry.
+```
+
+For an in-flight commit (no version bump this run), replace step 3 with: "Tag and publish wait until the release-closing commit lands on main with a fresh `{release-package-json-path}` version. This commit does not change the version, so CI does nothing."
+
+For **`gitlab-generic`** (a `.gitlab-ci.yml` exists but does not include the shared elestrago pipeline):
+
+```
+Commit landed. Next steps are manual + CI:
+  1. Push the working branch:        git push -u origin <current-branch>
+  2. GitLab CI is configured (.gitlab-ci.yml) but the publish flow is project-specific.
+     Check the pipeline definition for the release/publish trigger conditions
+     and follow the project's documented process.
+  3. If publishing is gated on tags, the tag for this release is {version}.
+     This skill does not create tags — create it manually after merging.
+```
+
+For **`github-actions`** (`.github/workflows/` contains at least one workflow):
+
+```
+Commit landed. Next steps are manual + CI:
+  1. Push the working branch:        git push -u origin <current-branch>
+  2. GitHub Actions workflows are configured ({github-workflow-files}). Check the
+     workflows for the release/publish trigger conditions (push to main, tag
+     creation, manual dispatch, etc.) and follow the project's documented process.
+  3. If publishing is gated on tags, the tag for this release is {version}.
+     This skill does not create tags — create it manually after merging.
+```
+
+For **`manual`** (no CI configuration detected):
+
+```
+Commit landed. Next steps are manual:
+  1. Push the working branch:        git push -u origin <current-branch>
+  2. Open a merge/pull request to the project's main branch and merge.
+  3. Tag the release:                git tag {version} && git push origin {version}
+  4. Publish via the project's chosen mechanism (npm publish, openupm submit,
+     UPM Git URL, manual asset upload, etc.) — this skill does not know which
+     applies here. Ask the maintainer if uncertain.
+```
+
+In every case, do not execute the printed commands — push and publish are the maintainer's call (they may want to amend other in-flight commits first, rebase, or hold for review).
+
+## Idempotency and safety
+
+- The skill never overwrites files outside the Output contract allow-list (plus the `.cs` files the user explicitly lists as part of the release in Step 6).
+- Re-running on a clean repo: surfaces no edits, no prompts, and exits cleanly.
+- The changelog entry is prepended/appended once — re-runs with the same `summary=` do not duplicate; matching-bullet detection lives on the exact bullet text.
+- Step 6 skips itself when the staging list is empty — re-running after a successful commit does not produce a second empty commit.
+- `dry-run=true` prints the intended file edits, staging list, and commit message without writing anything, staging anything, or running git commands that mutate state.
+
+## Examples
+
+### Example 1 — straight handoff in a GitLab-elestrago-CI repo
+
+The user just finished a `/unity-package-tool-developer` run that added a `Tools/PackageTools/Refresh All Configs` menu item to the `com.elestrago.unity.package-tools` repo. The developer skill's handoff asked whether to invoke `/unity-package-release`; the user picked yes.
+
+`scripts/discover_package.py` reports:
+
+- `config_asset.path: Assets/PackageManifest/PackageManifestConfig.asset` (line 27)
+- `package.name: com.elestrago.unity.package-tools`, `package.version: 2.0.11`, `package.destination_path: Release`
+- `changelog.resolved_path: CAHNGELOG.md` (the typo'd filename from this repo's config — used verbatim because the script read `changelogPath` from the asset)
+- `changelog.latest_heading.tag_url_format: https://gitlab.com/elestrago-pkg/package-tool/-/tags/{version}`
+- `readme.install_snippet.line: 32`, `readme.install_snippet.version: 2.0.11`
+- `release_package_json.version: 2.0.11`
+- `publish_flow.detected_flow: gitlab-elestrago-ci`
+
+Step 2: user picks (b) **Start a new version (patch)**. New version `2.0.12`. Skill rewrites line 27 of the asset and line 32 of `README.md`.
+
+Step 3: category `Added`, summary drafted from the diff. Skill prepends:
+
+```markdown
+## [2.0.12](https://gitlab.com/elestrago-pkg/package-tool/-/tags/2.0.12)
+
+### Added
+
+- `Tools/PackageTools/Refresh All Configs` menu item that logs all discovered `PackageManifestConfig` assets.
+
+---
+```
+
+(The URL was built by substituting `2.0.12` into `tag_url_format`.)
+
+Step 4: trivial menu item, no semantics → user picks (c) **Skip**.
+
+Step 5: user clicks **Export Package Source** in Unity, returns, picks (a) **Done**.
+
+Step 6 stages: `git add Assets/Package/PackageTool/Editor/MenuItems.cs Assets/PackageManifest/PackageManifestConfig.asset CAHNGELOG.md README.md Assets/Package/PackageTool/CAHNGELOG.md Assets/Package/PackageTool/README.md Release/package.json`.
+
+Step 7: `git commit -m "V-2.0.12 Add Refresh All Configs menu item; update version to 2.0.12."`
+
+Step 8 prints the **gitlab-elestrago-ci** block with `git push -u origin develop` and the `Release/package.json` watch.
+
+### Example 2 — different consumer repo, `CHANGELOG.md` filename, GitHub Actions
+
+Same maintainer, different repo (`com.example.unity.tween-helpers`). Discovery reports:
+
+- `config_asset.path: Assets/Editor/Config/TweenPackageManifest.asset` (the config asset is named differently and lives elsewhere — the script finds it by signature)
+- `package.name: com.example.unity.tween-helpers`, `package.version: 0.4.2`, `package.destination_path: Build/UPM`
+- `changelog.resolved_path: CHANGELOG.md` (no typo here — the consumer uses the default `changelogPath`)
+- `changelog.latest_heading.tag_url_format: https://github.com/example/unity-tween-helpers/releases/tag/v{version}` (extracted from the existing entry; uses GitHub releases, not GitLab tags)
+- `readme.install_snippet.line: 18`
+- `release_package_json.path: Build/UPM/package.json`
+- `publish_flow.detected_flow: github-actions`, `publish_flow.github_workflow_files: [.github/workflows/upm-publish.yml]`
+
+The maintainer ran `/unity-package-release fix tween easing overshoot for negative durations`. The skill detects `fix` in the prompt, suggests `category=Fixed`, and the user accepts.
+
+Step 2: user picks (b) **Start a new version (patch)** → `0.4.3`. Skill writes the new version into the SO at `Assets/Editor/Config/TweenPackageManifest.asset` (the line number reported by the script) and into the consumer-install snippet at `README.md:18`.
+
+Step 3: prepends the changelog entry, building the URL from the GitHub releases `tag_url_format`:
+
+```markdown
+## [0.4.3](https://github.com/example/unity-tween-helpers/releases/tag/v0.4.3)
+
+### Fixed
+
+- Tween easing overshoot on negative-duration tweens.
+
+---
+```
+
+Step 5: Export done.
+
+Step 6 stages: `git add Assets/Editor/Config/TweenPackageManifest.asset CHANGELOG.md README.md Build/UPM/CHANGELOG.md Build/UPM/README.md Build/UPM/package.json Assets/Runtime/Tween/Easing.cs`.
+
+Step 7: `git commit -m "V-0.4.3 Fix tween easing overshoot on negative-duration tweens."`
+
+Step 8 prints the **github-actions** block:
+
+```
+Commit landed. Next steps are manual + CI:
+  1. Push the working branch:        git push -u origin fix/tween-easing
+  2. GitHub Actions workflows are configured (.github/workflows/upm-publish.yml). Check the
+     workflows for the release/publish trigger conditions (push to main, tag
+     creation, manual dispatch, etc.) and follow the project's documented process.
+  3. If publishing is gated on tags, the tag for this release is 0.4.3.
+     This skill does not create tags — create it manually after merging.
+```
+
+### Example 3 — third repo, no CI, in-flight version
+
+`com.example.unity.gizmo-tools` — small internal package, no `.gitlab-ci.yml`, no `.github/workflows/`. Discovery reports `publish_flow.detected_flow: manual`. Latest changelog heading is `## [1.2.0]` (no link) with two bullets, no matching `V-1.2.0` commit yet — release is mid-assembly.
+
+User runs `/unity-package-release add gizmo color cycling helper`.
+
+Step 1 surfaces the in-flight state and the missing tag-URL format (`changelog.latest_heading.tag_url_format: null`).
+
+Step 2: user picks (a) **Fold into in-flight version (no bump)**.
+
+Step 3 detects the null `tag_url_format` and asks once: "The existing changelog uses plain `## [version]` headings without a link target. Continue with no link, or paste a URL pattern?" User picks "no link". Skill appends under `### Added` in the existing entry.
+
+Step 4: behavior change → user picks (b) **Defer**.
+
+Step 5: Export done.
+
+Step 6 stages: `git add Assets/Tools/GizmoConfig.asset CHANGELOG.md Packages/com.example.unity.gizmo-tools/CHANGELOG.md Packages/com.example.unity.gizmo-tools/package.json Assets/Runtime/Gizmos/ColorCycle.cs`.
+
+Step 7: `git commit -m "V-1.2.0 Add gizmo color cycling helper."`
+
+Step 8 prints the **manual** block — no CI, the maintainer tags and publishes by hand whenever they choose.

package/Samples~/ClaudeSkills/unity-package-release/scripts/discover_package.py

@@ -0,0 +1,366 @@
+"""Discover the PackageManifestConfig.asset in a Unity-package repo and report
+the fields and files the release skill needs to drive its pipeline.
+
+The skill must not hardcode paths or line numbers because it is shipped to
+multiple repos that all use the same `com.elestrago.unity.package-tools` editor
+tool but differ in their layout, package name, changelog filename, README
+location, and publish flow. Everything repo-specific is read at runtime.
+
+Run from the repo root (default) or pass `--repo <path>`:
+
+    python3 .claude/skills/unity-package-release/scripts/discover_package.py
+
+Output is a single JSON object on stdout. Errors go to stderr; non-zero exit
+codes mean the caller cannot proceed safely.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+
+# A PackageManifestConfig asset is a Unity ScriptableObject with a recognisable
+# set of fields. We detect by signature rather than by path, since the canonical
+# location varies between repos (the package-tool repo keeps it under
+# Assets/PackageManifest/, but consumers are free to put it anywhere under
+# Assets/).
+CONFIG_SIGNATURE_FIELDS = (
+	"packageName:",
+	"packageVersion:",
+	"packageDestinationPath:",
+	"changelogPath:",
+)
+
+# Top-level SO fields in Unity YAML are indented two spaces under `MonoBehaviour:`.
+# Dependency entries are inside a `dependencies:` list and indent four spaces, so
+# the rule "first line matching exactly `^  <field>: `" reliably picks the SO's
+# own value and skips nested `packageVersion:` entries inside dependencies.
+TOP_LEVEL_FIELD_RE = re.compile(r"^  (?P<field>[A-Za-z_][A-Za-z0-9_]*): ?(?P<value>.*)$")
+
+# Inline-list `[a, b, c]` and `[]` show up for string-array fields. We don't
+# parse them here — none of the fields the release skill cares about are arrays
+# of primitives — but the regex above tolerates them by capturing the whole
+# right-hand side as a string.
+
+
+def find_config_asset(repo: Path) -> Path | None:
+	"""Walk `<repo>/Assets/` for the first `.asset` file whose contents contain
+	all of the PackageManifestConfig signature fields. Returns None when no
+	candidate is found — the caller should refuse to proceed in that case."""
+	assets_dir = repo / "Assets"
+	if not assets_dir.is_dir():
+		return None
+	candidates: list[Path] = []
+	for path in assets_dir.rglob("*.asset"):
+		try:
+			head = path.read_text(encoding="utf-8", errors="replace")[:4096]
+		except OSError:
+			continue
+		if all(sig in head for sig in CONFIG_SIGNATURE_FIELDS):
+			candidates.append(path)
+	if not candidates:
+		return None
+	# If multiple configs exist (some repos package more than one), prefer the
+	# one nearest the repo root by path-segment count, then by name for
+	# determinism. Multi-package repos are out of scope for this skill — the
+	# user should pass --config-asset to disambiguate.
+	candidates.sort(key=lambda p: (len(p.relative_to(repo).parts), str(p)))
+	return candidates[0]
+
+
+def parse_config_fields(asset_path: Path) -> dict[str, Any]:
+	"""Extract the top-level scalar fields of a PackageManifestConfig asset.
+	Returns a dict mapping field-name → {"value": str, "line": int} for every
+	top-level field encountered, and a flat dict of values under "_values" for
+	convenience. Skips list-element fields under `dependencies:`, `samples:`,
+	`copyEntries:`, etc., because they sit at four-space indent."""
+	lines = asset_path.read_text(encoding="utf-8").splitlines()
+	fields: dict[str, dict[str, Any]] = {}
+	values: dict[str, str] = {}
+	for idx, raw in enumerate(lines, start=1):
+		m = TOP_LEVEL_FIELD_RE.match(raw)
+		if not m:
+			continue
+		name = m.group("field")
+		val = m.group("value").strip()
+		# Re-occurrences at top level shadow earlier ones; the SO YAML doesn't
+		# normally do that for scalars, but be defensive.
+		fields[name] = {"value": val, "line": idx}
+		values[name] = val
+	return {"_fields": fields, "_values": values}
+
+
+def resolve_repo_relative(repo: Path, value: str) -> Path:
+	"""Mirror the runtime path resolution that
+	`FileTools.CopyOrReplaceFileToDirectory` uses: `Path.GetFullPath(value)` is
+	resolved against the current working directory, which Unity sets to the
+	project root. So a relative path in the asset means "relative to repo
+	root"."""
+	p = Path(value)
+	if p.is_absolute():
+		return p
+	return (repo / p).resolve()
+
+
+def read_last_changelog_heading(changelog_path: Path) -> dict[str, Any] | None:
+	"""Read the first `## ` heading from the changelog and try to extract the
+	version and the URL it links to, so the skill can mirror the same format
+	when prepending a new entry. The skill should not assume any particular URL
+	host — it's free-form text per repo."""
+	if not changelog_path.is_file():
+		return None
+	heading_re = re.compile(r"^##\s+(.*)$")
+	version_in_heading_re = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
+	plain_version_re = re.compile(r"\[?([0-9]+\.[0-9]+\.[0-9]+(?:-[A-Za-z0-9.+-]+)?)\]?")
+	try:
+		text = changelog_path.read_text(encoding="utf-8")
+	except OSError:
+		return None
+	for line in text.splitlines():
+		m = heading_re.match(line)
+		if not m:
+			continue
+		body = m.group(1).strip()
+		linked = version_in_heading_re.search(body)
+		if linked:
+			version = linked.group(1).strip()
+			url = linked.group(2).strip()
+			tag_url_format = url.replace(version, "{version}", 1) if version and version in url else None
+			return {
+				"heading": line.rstrip(),
+				"version": version,
+				"url": url,
+				"tag_url_format": tag_url_format,
+			}
+		# Heading without a markdown link — still useful for showing the user.
+		plain = plain_version_re.search(body)
+		return {
+			"heading": line.rstrip(),
+			"version": plain.group(1) if plain else None,
+			"url": None,
+			"tag_url_format": None,
+		}
+	return None
+
+
+def find_readme_install_snippet(readme_path: Path, package_name: str) -> dict[str, Any] | None:
+	"""Find the consumer-install snippet line in the project-root README — the
+	one that looks like `"com.example.foo": "X.Y.Z"`. Returns the line number,
+	the version string, and the raw line so the skill can do a targeted rewrite
+	without touching anything else in the README. Returns None when the README
+	has no such snippet (some repos document installation differently)."""
+	if not readme_path.is_file():
+		return None
+	pattern = re.compile(r'"' + re.escape(package_name) + r'"\s*:\s*"([^"]+)"')
+	try:
+		text = readme_path.read_text(encoding="utf-8")
+	except OSError:
+		return None
+	for idx, line in enumerate(text.splitlines(), start=1):
+		m = pattern.search(line)
+		if m:
+			return {"line": idx, "version": m.group(1), "raw": line}
+	return None
+
+
+def detect_publish_flow(repo: Path) -> dict[str, Any]:
+	"""Sniff out what publish flow this repo uses. The release skill prints a
+	different handoff block per flow, and the maintainer can override via the
+	`publish-flow=` skill arg. Detection is best-effort — when ambiguous, the
+	skill should ask the user rather than guessing."""
+	gitlab_ci = repo / ".gitlab-ci.yml"
+	github_workflows_dir = repo / ".github" / "workflows"
+	flow: dict[str, Any] = {
+		"gitlab_ci_present": gitlab_ci.is_file(),
+		"gitlab_ci_includes_elestrago_unity_npm": False,
+		"github_workflows_present": github_workflows_dir.is_dir() and any(
+			p.is_file() and p.suffix in {".yml", ".yaml"}
+			for p in github_workflows_dir.iterdir()
+		),
+		"github_workflow_files": [],
+		"detected_flow": "manual",
+	}
+	if gitlab_ci.is_file():
+		try:
+			ci_text = gitlab_ci.read_text(encoding="utf-8")
+		except OSError:
+			ci_text = ""
+		# The shared pipeline include is the signal the skill's original CI
+		# handoff block was written for. Any other GitLab CI setup we treat as
+		# "gitlab-generic" so the skill can degrade gracefully.
+		if "unity-package-npm-publish" in ci_text or "elestrago/ci-pipelines" in ci_text:
+			flow["gitlab_ci_includes_elestrago_unity_npm"] = True
+	if flow["github_workflows_present"]:
+		flow["github_workflow_files"] = sorted(
+			str(p.relative_to(repo)) for p in github_workflows_dir.iterdir()
+			if p.is_file() and p.suffix in {".yml", ".yaml"}
+		)
+	# Prioritise: the elestrago-CI signal is the most specific, then any other
+	# GitLab CI, then GitHub Actions, then manual.
+	if flow["gitlab_ci_includes_elestrago_unity_npm"]:
+		flow["detected_flow"] = "gitlab-elestrago-ci"
+	elif flow["gitlab_ci_present"]:
+		flow["detected_flow"] = "gitlab-generic"
+	elif flow["github_workflows_present"]:
+		flow["detected_flow"] = "github-actions"
+	else:
+		flow["detected_flow"] = "manual"
+	return flow
+
+
+def read_release_package_json(repo: Path, destination_path: str) -> dict[str, Any] | None:
+	"""Read the `package.json` inside the exported destination if it exists.
+	Some CI flows (notably gitlab-elestrago-ci) trigger publishing on a version
+	delta of this file, so the skill needs to know whether it exists and what
+	version it currently advertises — so it can warn when the user is about to
+	skip the Export Package Source step and silently break the publish."""
+	if not destination_path:
+		return None
+	dest = resolve_repo_relative(repo, destination_path)
+	package_json = dest / "package.json"
+	if not package_json.is_file():
+		return {
+			"path": str(package_json.relative_to(repo)) if dest.is_relative_to(repo) else str(package_json),
+			"present": False,
+			"version": None,
+		}
+	try:
+		import json as _json
+		data = _json.loads(package_json.read_text(encoding="utf-8"))
+		version = data.get("version") if isinstance(data, dict) else None
+	except (OSError, ValueError):
+		version = None
+	return {
+		"path": str(package_json.relative_to(repo)) if dest.is_relative_to(repo) else str(package_json),
+		"present": True,
+		"version": version,
+	}
+
+
+def read_git_state(repo: Path) -> dict[str, Any]:
+	"""Best-effort git state. Failures (missing git, not a repo) reduce to
+	empty/null fields rather than aborting — the skill can still do its job
+	without git, just without the convenience signals."""
+	def _run(args: list[str]) -> str | None:
+		try:
+			out = subprocess.check_output(
+				args, cwd=str(repo), stderr=subprocess.DEVNULL, text=True
+			)
+			return out.strip()
+		except (subprocess.CalledProcessError, FileNotFoundError):
+			return None
+	return {
+		"branch": _run(["git", "rev-parse", "--abbrev-ref", "HEAD"]),
+		"remote_url": _run(["git", "remote", "get-url", "origin"]),
+		"recent_commits": _run(["git", "log", "--oneline", "-5"]),
+		"status_porcelain": _run(["git", "status", "--porcelain"]),
+		"diff_stat_head": _run(["git", "diff", "--stat", "HEAD"]),
+	}
+
+
+def discover(repo: Path, override_config: Path | None = None) -> dict[str, Any]:
+	asset = override_config if override_config else find_config_asset(repo)
+	if asset is None or not asset.is_file():
+		return {
+			"ok": False,
+			"error": (
+				"No PackageManifestConfig.asset found under Assets/. This skill "
+				"requires the com.elestrago.unity.package-tools editor tool to be "
+				"installed in the project (it provides the ScriptableObject this "
+				"skill drives)."
+			),
+		}
+	parsed = parse_config_fields(asset)
+	values = parsed["_values"]
+	fields = parsed["_fields"]
+
+	package_name = values.get("packageName", "")
+	package_version = values.get("packageVersion")
+	changelog_path_raw = values.get("changelogPath", "")
+	readme_path_raw = values.get("readmePath", "")
+	license_path_raw = values.get("licensePath", "")
+	documentation_path_raw = values.get("documentationPath", "")
+	destination_path_raw = values.get("packageDestinationPath", "")
+
+	changelog_resolved = resolve_repo_relative(repo, changelog_path_raw) if changelog_path_raw else None
+	readme_resolved = resolve_repo_relative(repo, readme_path_raw) if readme_path_raw else None
+
+	changelog_info = read_last_changelog_heading(changelog_resolved) if changelog_resolved else None
+	readme_snippet = (
+		find_readme_install_snippet(readme_resolved, package_name)
+		if readme_resolved and package_name else None
+	)
+
+	release_json_info = read_release_package_json(repo, destination_path_raw)
+	publish_flow = detect_publish_flow(repo)
+	git_state = read_git_state(repo)
+
+	return {
+		"ok": True,
+		"repo": str(repo),
+		"config_asset": {
+			"path": str(asset.relative_to(repo)) if asset.is_relative_to(repo) else str(asset),
+			"package_version_line": fields.get("packageVersion", {}).get("line"),
+		},
+		"package": {
+			"name": package_name,
+			"display_name": values.get("displayName"),
+			"version": package_version,
+			"unity_version": values.get("unityVersion"),
+			"documentation_path": documentation_path_raw or None,
+			"destination_path": destination_path_raw or None,
+		},
+		"changelog": {
+			"path_in_config": changelog_path_raw or None,
+			"resolved_path": str(changelog_resolved.relative_to(repo)) if changelog_resolved and changelog_resolved.is_relative_to(repo) else (str(changelog_resolved) if changelog_resolved else None),
+			"exists": bool(changelog_resolved and changelog_resolved.is_file()),
+			"latest_heading": changelog_info,
+		},
+		"readme": {
+			"path_in_config": readme_path_raw or None,
+			"resolved_path": str(readme_resolved.relative_to(repo)) if readme_resolved and readme_resolved.is_relative_to(repo) else (str(readme_resolved) if readme_resolved else None),
+			"exists": bool(readme_resolved and readme_resolved.is_file()),
+			"install_snippet": readme_snippet,
+		},
+		"license": {
+			"path_in_config": license_path_raw or None,
+		},
+		"release_package_json": release_json_info,
+		"publish_flow": publish_flow,
+		"git": git_state,
+	}
+
+
+def main() -> int:
+	parser = argparse.ArgumentParser(description=__doc__)
+	parser.add_argument(
+		"--repo",
+		default=os.getcwd(),
+		help="Repository root (defaults to current working directory).",
+	)
+	parser.add_argument(
+		"--config-asset",
+		default=None,
+		help=(
+			"Explicit path to PackageManifestConfig.asset. Use to disambiguate "
+			"in repos that ship multiple configs."
+		),
+	)
+	args = parser.parse_args()
+	repo = Path(args.repo).resolve()
+	override = Path(args.config_asset).resolve() if args.config_asset else None
+	result = discover(repo, override)
+	json.dump(result, sys.stdout, indent=2)
+	sys.stdout.write("\n")
+	return 0 if result.get("ok") else 2
+
+
+if __name__ == "__main__":
+	sys.exit(main())

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "com.elestrago.unity.package-tools",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "displayName": "Package Tool",
   "description": "Tool for create unity packages",
   "category": "unity",
   "unity": "2021.3",
   "homepage": "https://gitlab.com/elestrago-pkg/package-tool",
-  "documentationUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.3.0/README.md",
-  "changelogUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.3.0/CHANGELOG.md",
-  "licensesUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.3.0/LICENSE",
+  "documentationUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.4.0/README.md",
+  "changelogUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.4.0/CHANGELOG.md",
+  "licensesUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.4.0/LICENSE",
   "license": "MIT",
   "keywords": [
     "unity",