Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 33 additions & 27 deletions .agents/skills/release/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,14 @@ Cut a release of `pm-skills`. The version of record is the `version` field in
`package.json`. `.github/workflows/release.yml` creates the `v{version}` tag
and a GitHub release when `package.json` changes on `main`.

`.github/workflows/ci.yml` requires a version bump in any pull request that
changes `skills/**`, so a skills change cannot merge while `v{version}`
already exists. A pull request that touches nothing under `skills/` (docs,
CI, scripts, `.agents/skills/`) merges without one.
The major is the rules/skills version: the `version=N` start marker in
`skills/pm-setup/references/AGENTS-section.md`. `scripts/check-version.ts`
(CI and pre-push) requires any pull request that changes `skills/**` to
raise that marker past the one on `main`, so a skills change is always a
`major` bump. A pull request that touches nothing under `skills/` (docs, CI,
scripts, package metadata, `.agents/skills/`) keeps the major and may bump
the minor or patch. `scripts/validate.ts` requires this repository's own
`planning/config.md` and `AGENTS.md` to carry the marker version.

This skill is repository-only. It lives in `.agents/skills/`, outside the
shipped `skills/` set, and its frontmatter sets `metadata.internal: true`, so
Expand All @@ -27,17 +31,16 @@ inventory, or the `pm-help` guide.

- Work in the repository root. Read the version with
`node -p 'require("./package.json").version'`.
- If the working tree has uncommitted changes outside `package.json`, stop:
`Commit or stash <paths> first.` A release commit changes only
`package.json`.
- Change nothing else: not the skills, the managed section, the README, or the
`Rules version` in `skills/pm-init/templates/config.md`. The release version
and the rules/skills version are independent.
- If the branch changes `skills/pm-setup/references/AGENTS-section.md`, its
`version=N` start marker (and `Rules version` in
`skills/pm-init/templates/config.md`) must already be bumped, or CI fails
the pull request and `pm-setup` would never install the change. The rules
version is separate from the release version.
- If the working tree has uncommitted changes, stop:
`Commit or stash <paths> first.` A release commit changes only the files
the bump writes, and, for `major`, the files `pm-setup` writes.
- Change nothing else: not the skills, the README, or the rules text. A
`minor` or `patch` bump writes only `package.json`. A `major` bump also
writes the `version=N` marker and `Rules version` in
`skills/pm-init/templates/config.md`; then `pm-setup` installs the section
in `AGENTS.md` and writes `Rules version` in `planning/config.md`.
- When the branch already raises the marker past `main`, do not bump `major`
again: `package.json` is already `<N>.0.0`.
- Never create or delete tags, and never push or merge: print the command
instead. The Release workflow owns the tag.
- `v{version}` already existing is normal: it is the last release. The point of
Expand All @@ -50,20 +53,23 @@ inventory, or the `pm-help` guide.
(`git log --oneline v{version}..HEAD`). If `v{version}` is not a tag yet,
say so: the current version is unreleased, so this skill is only needed if
the user wants a different number.
2. **Recommend a part.** From the conventional commits since `v{version}`:
`major` for a breaking change (a `!` after the type or scope, or a
`BREAKING CHANGE:` footer); otherwise `minor` when any `feat` is present;
otherwise `patch`. State the part, the resulting version, and the commits
that decided it.
2. **Recommend a part.** `major` when `git diff --name-only
origin/main...HEAD` lists any path under `skills/` and the marker equals
the one on `main`. Otherwise, from the conventional commits since
`v{version}`: `minor` when any `feat` is present, else `patch`. Never
offer `major` without a skills change. State the part, the resulting
version, and the paths or commits that decided it.
3. **Confirm.** Ask one choice question: `Bump to which version?` with the
recommended `v<next> (<part>)` first, then the other two parts, each
labelled with its version, and `Keep v<current>`. Do not offer a version
that is already tagged.
recommended `v<next> (<part>)` first, then the parts `check-version.ts`
allows, each labelled with its version, and `Keep v<current>`. Do not
offer a version that is already tagged.
4. **Bump.** Run `bun scripts/bump-version.ts <part>` (or `just bump <part>`).
The script rewrites only the `version` field and fails when the target
`v<next>` tag already exists.
5. **Commit.** `git add package.json`, then
`git commit -m "chore(release): v<next>"`. Do not amend an existing commit.
The script fails when the target `v<next>` tag already exists. After
`major`, run `pm-setup` so `AGENTS.md` and `planning/config.md` carry the
new rules version, then `just validate` and `just version-check`.
5. **Commit.** `git add` the files the bump wrote, then
`git commit -m "chore(release): v<next>"`. `pm-setup` commits
`planning/` itself. Do not amend an existing commit.
6. **Report.** Print the new version, the commit, and the next command:
`git push` (or open a pull request). Merging to `main` triggers the Release
workflow, which creates the tag and the GitHub release.
Expand Down
2 changes: 2 additions & 0 deletions .config/lefthook.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,5 @@ pre-push:
jobs:
- name: lint
run: just lint-check
- name: version
run: just version-check
67 changes: 13 additions & 54 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -68,10 +68,12 @@ jobs:
- name: Build
run: bun run build

# A skills change ships in a release, so it needs a new package.json
# version; anything else (docs, CI, scripts, .agents/skills) merges without
# one. A change to the managed rules must also bump the rules version, or
# pm-setup and the upgrade check never see it.
# Mirrors `just version-check` (the lefthook pre-push hook): a skills change
# ships in a release, so it must raise the rules version and package.json
# past the version on main; anything else (docs, CI, scripts, package
# metadata) merges on the same rules version. The validate job keeps
# package.json's major, planning/config.md, and AGENTS.md on the rules
# version, so this repository runs the release it ships.
# Scoped to pull requests: on main the release tag already exists.
version:
name: Version bump
Expand All @@ -83,53 +85,10 @@ jobs:
with:
fetch-depth: 0

- name: Require a version bump for skills changes
shell: bash
env:
BASE: ${{ github.event.pull_request.base.sha }}
run: |
set -euo pipefail
changed="$(git diff --name-only "${BASE}...HEAD")"

# Non-skills changes (docs, CI, scripts, this file) need no bump.
if ! grep -q '^skills/' <<< "$changed"; then
echo "No skills changed; a version bump is not required."
exit 0
fi

read_version() { sed -n 's/^[[:space:]]*"version":[[:space:]]*"\([^"]*\)".*/\1/p' "$1"; }
git show "${BASE}:package.json" > /tmp/base-package.json
current="$(read_version package.json)"
base="$(read_version /tmp/base-package.json)"
if [ -z "$current" ] || [ -z "$base" ]; then
echo "::error::cannot read the version from package.json."
exit 1
fi

if [ "$current" = "$base" ]; then
echo "::error::skills changed but package.json is still v${current}. Bump it: run the release skill, or 'just bump patch|minor|major'."
exit 1
fi
if git rev-parse -q --verify "refs/tags/v${current}" >/dev/null; then
echo "::error::package.json is v${current}, but tag v${current} already exists. Bump it to an unused version."
exit 1
fi
echo "Skills changed; v${base} -> v${current} is unused."

# The managed rules only reach a consumer when the rules version
# changes, so a section edit must move version=N (templates/config.md
# follows; scripts/validate.ts keeps the two equal).
section="skills/pm-setup/references/AGENTS-section.md"
if grep -qx "$section" <<< "$changed"; then
marker="$(sed -n 's/^<!-- pm-skills:start version=\([0-9][0-9]*\) -->$/\1/p' "$section")"
base_marker="$(git show "${BASE}:${section}" 2>/dev/null | sed -n 's/^<!-- pm-skills:start version=\([0-9][0-9]*\) -->$/\1/p' || true)"
if [ -z "$marker" ] || [ -z "$base_marker" ]; then
echo "::error::${section} has no 'version=N' start marker."
exit 1
fi
if [ "$marker" = "$base_marker" ]; then
echo "::error::${section} changed but its rules version is still v${marker}. Bump version=N in the marker (templates/config.md follows) so pm-setup and the upgrade check take effect."
exit 1
fi
echo "Rules version bumped v${base_marker} -> v${marker}."
fi
- name: Set up Bun
uses: oven-sh/setup-bun@v2
with:
bun-version: latest

- name: Check the version against main
run: bun scripts/check-version.ts "${{ github.event.pull_request.base.sha }}"
Loading
Loading