| name | pre-pr |
| description | Runs the pre-PR checklist for this repo: applies the version gate only when the repository has a root `version.gradle.kts`, runs a scope-dependent build/check command per `.agents/guidelines/running-builds.md` (proto → `clean build`; code/deps → `build`; doc-only `.kt`/`.java` edit → `dokkaGenerate`; Markdown-only → no build; no documented command → skipped), and running `dokkaGenerate` for any `.kt`/`.java` source change (alongside `build` for code edits, alone for KDoc/Javadoc-only edits) so unresolved KDoc/Javadoc links fail locally instead of in CI's Dokka run, and invokes the relevant reviewers (`kotlin-engineer`, `spine-code-review`, `review-docs`, `dependency-audit`, `check-links`) against the branch diff. On success, writes the `pre-pr.ok` sentinel into the repository's git directory so the `gh pr create` hook can verify the checklist ran for the current HEAD. Use before opening a PR, or when CI rejected a branch and a fast local repro is wanted.
|
Pre-PR checklist (repo-specific)
You are the pre-PR gate for this repository. You compose the existing
reviewers and the documented repository rules into a single pass that must
succeed before a pull request is opened.
This skill supports both versioned Gradle Build Tools projects and repositories
that intentionally do not have version.gradle.kts. Do not create
version.gradle.kts just to satisfy this checklist. When the file is absent
from the project root, the version-bump check is not applicable.
The authoritative standards live in .agents/:
.agents/guidelines/version-policy.md — applies only when the repository has a root
version.gradle.kts..agents/guidelines/running-builds.md — which build/check command to run..agents/guidelines/safety-rules.md and .agents/guidelines/advanced-safety-rules.md — hard
constraints checked by the reviewers.
Procedure
Run steps 1–4 fully before aggregating. Collect all findings; do not stop at
the first failure.
Copy this checklist into your reply and tick each item as you finish it:
Pre-PR progress:
- [ ] 1. Scope + repository capabilities; classify the changed files
- [ ] 2. Version-bump check (auto-fix via `bump-version` when it applies)
- [ ] 3. Build/check; dokkaGenerate on any `.kt`/`.java` source change (alone if doc-only)
- [ ] 4. Reviewers dispatched for the changed file types
- [ ] 5. Aggregate to PASS / FAIL
- [ ] 6. Write the `pre-pr.ok` sentinel
1. Determine scope and repository capabilities
- Base ref:
master unless the user provides a different one.
- Changed files:
git diff <base>...HEAD --name-only
- Repository root:
git rev-parse --show-toplevel
- Repository kind: detect the
config repository by scanning git remote -v
for any URL matching [:/]SpineEventEngine/config(\.git)?$.
- Filter changed files using
AGENTS.md § Code review:
- In
config itself, skip only gradlew and gradlew.bat; every other
config-distributed path is owned by this repo and stays in scope.
- In any consumer repo, remove the full config-distributed skip list. A
PR that contains only config-distributed files needs no build, no
reviewers, and should PASS immediately — skip to step 6 with
build=skipped, build_status=skipped, reviewers=none,
version=not-applicable.
- Version gate: check only the repository-root
version.gradle.kts.
- Absent at both sides →
not-applicable, continue.
- Present at
HEAD → enforce in step 2.
- Present at
<base> but missing at HEAD → fail unless the user
explicitly asked to migrate away from Gradle Build Tools versioning.
- Hugo site: detect a site only when
docs/ or site/ contains one of
hugo.toml, hugo.yaml, config/hugo.toml, config/hugo.yaml,
config/_default/hugo.toml, or config/_default/hugo.yaml.
- Classify changes:
- proto — any
*.proto changed
- code — any
*.kt, *.kts, or *.java changed
- build — any Gradle/build file changed that is not already code
(a
*.gradle.kts counts as code) or a deps file — e.g. *.gradle,
settings.gradle, gradle.properties, libs.versions.toml, or any other
*.versions.toml
- docs — any
*.md or doc-only source edits changed
- doc-source (non-JVM) — a doc-comment or prose change in a
*.ts,
*.tsx, *.js, *.jsx, *.mjs, *.cjs, or *.go file. These trigger
no Gradle build and no code reviewer; review-docs reviews their prose
(step 4)
- deps — any file under
buildSrc/src/main/kotlin/io/spine/dependency/ changed
- site — a Hugo site exists and any file under
docs/** or lychee.toml
changed (triggers Hugo link check; pure README.md or KDoc-only changes do
not count). If lychee.toml changes but no Hugo site exists, keep
site=false and note that check-links is not applicable if the skipped
reviewer needs explanation.
2. Version-bump check
- Skip when version gate is
not-applicable.
- Read
version.gradle.kts at HEAD. Read <base> only if the file exists
there; if it does not, the file is newly introduced — record the introduced
version and continue.
- When both sides have the file: if the version is not strictly greater (semver
- Spine snapshot rules in
.agents/guidelines/version-policy.md): if
.agents/skills/bump-version/ exists, auto-fix immediately by running
the bump-version skill without asking; otherwise record a Must-fix and continue.
bump-version is idempotent — it runs its own gate and stops without
committing when the branch is already ahead of base — so this auto-fix never
stacks a second bump even if Step 2 runs more than once on the branch.
Re-read the file after the fix. If the version is still not strictly greater,
record a Must-fix and continue. If the auto-fix succeeded, recompute the
changed-file list (git diff <base>...HEAD --name-only) before proceeding to
Step 3 — the bump commit adds version.gradle.kts to the diff.
3. Build or check
Pick the base target per .agents/guidelines/running-builds.md. A .kt/.java
change is either a code edit or a doc-only edit (only KDoc/Javadoc or
comment lines changed); inspect the diff to tell them apart, because a doc-only
source edit needs Dokka but no compile or tests (.agents/guidelines/running-builds.md
item 3):
- proto changed →
./gradlew clean build
- Else
.kt/.java code change, or a build/deps file → ./gradlew build
- Else doc-only
.kt/.java edit (no code change) → ./gradlew dokkaGenerate
(no build, no tests)
- Else Markdown or non-JVM doc-source only (
*.md, or *.ts/*.js/*.go
and the like) → no Gradle build required; the reviewers (and check-links
for a Hugo site) cover it. Record build_status=skipped with the reason.
Append dokkaGenerate to a build target whenever a .kt/.java source file
changed — a code edit can rename or move a type an existing doc comment links
to, breaking the link. The build task does not run Dokka, so an unresolved
link passes ./gradlew build locally yet fails CI's Dokka run — the PR build
runs dokkaGenerate, with the Publish to Maven repositories job as a
backstop. Combine them in one
invocation. Do not add a second dokkaGenerate when it is already the base
command (the doc-only source path above), and do not append it for changes
with no .kt/.java source (Markdown, *.kts build scripts, deps).
Putting it together:
- proto +
.kt/.java source → ./gradlew clean build dokkaGenerate
- proto only (no
.kt/.java) → ./gradlew clean build
.kt/.java code change → ./gradlew build dokkaGenerate.kt/.java doc-only edit → ./gradlew dokkaGenerate (no build, no tests)- build/deps/
*.kts-only (no .kt/.java) → ./gradlew build
- Markdown or non-JVM doc-source only → no Dokka, no build
Use dokkaGenerate, never the bare dokka task — the latter is ambiguous
under the Dokka v2 Gradle plugin and aborts the build. If dokkaGenerate is
not a registered task (the project does not apply Dokka), skip the Dokka run
with a note rather than failing.
If ./gradlew is absent, read .agents/guidelines/running-builds.md for the
repository-specific command. If that file is also absent, or if none is
documented for the change type, record build_status=skipped with the
reason and continue.
Run the chosen command. On failure, record the first failing task and
continue to step 4 — do not abort. Pass build_status=FAIL in the context
given to reviewers so they can discount false positives from non-compiling
code. A dokkaGenerate failure (typically an unresolved-link warning) is a
Must-fix; record the failing module and link.
4. Reviewers
Run every relevant reviewer and collect all verdicts before aggregating. In a
single Codex session, run the reviewer skills one by one and batch independent
search/read commands inside each reviewer. If multi-agent tools are available,
parallel reviewer dispatch is optional but not required.
Before running a reviewer, check that the skill directory exists under
.agents/skills/; if a skill is absent, skip it with a note "not applicable
for this repo" rather than failing.
- code changed → dispatch by file type, not as a fixed pair:
spine-code-review (repo-specific rules) when .kt, .kts, or .java
changed.kotlin-engineer (general Kotlin language standards) only when .kt
or .kts changed.
When .kt / .kts changed, both run and cover disjoint concerns without
double-reporting. A Java-only diff dispatches spine-code-review alone.
- build changed →
spine-code-review (its scope includes build changes —
repo-specific safety rules and the version gate apply to build files too).
kotlin-engineer does not apply to non-Kotlin build files.
- De-duplicate reviewers. A diff can match both code and build
(e.g. a
.gradle.kts change plus gradle.properties), selecting
spine-code-review from both bullets. Dispatch each reviewer at most once
over the whole changed-file set — never run the same reviewer twice.
- Documentation review → dispatch
review-docs whenever a changed hunk
touches doc-comment or prose lines, not only on a docs-classified diff:
- any
*.md change (docs);
- any
*.proto change — its doc comments (type, field, service) are an API
surface, so a proto edit dispatches review-docs in addition to
triggering the build;
- a code change to
.kt / .kts / .java whose diff also touches
KDoc/Javadoc or other comment lines — dispatch review-docs alongside the
code reviewers; it scopes itself to the prose;
- a doc-source (non-JVM) change — a
.ts / .tsx / .js / .jsx /
.mjs / .cjs / .go diff whose hunks touch doc comments or other
comments. These have no Gradle build and no code reviewer, so review-docs
is their only gate.
A source diff that touches only executable lines does not need review-docs.
- deps changed →
dependency-audit
- site changed →
check-links (unless the sentinel short-circuit below
applies)
- Line length. Findings on changed Kotlin / Java / Markdown lines are
reported by the dispatched reviewers (
spine-code-review, review-docs);
pre-pr itself does not re-check.
check-links sentinel short-circuit. Read check-links.ok from the git
directory (if present). If head= equals the current full HEAD SHA and
status=PASS, skip the link check and record APPROVE with note "cached from
check-links.ok"
(caching its ~30 s rebuild+serve cycle; the result is deterministic for a given
HEAD). Otherwise run check-links normally.
Pass each reviewer: base ref, changed-file list, build result, version result.
When the version check is not-applicable, say so explicitly so reviewers don't flag a
missing version bump.
Auto-fix policy for reviewer findings:
- Findings from
kotlin-engineer, spine-code-review, review-docs, or
dependency-audit → record as Must-fix or Should-fix; do not auto-apply.
Surface them and wait for user action.
- If a reviewer reports a missing version bump after Step 2 already ran, the
auto-fix did not take — record a Must-fix and do not silently re-apply.
dependency-audit reports a version rollback → do not auto-fix.
Surface it as a Must-fix and wait for user confirmation, because a rollback
can be intentional.
5. Aggregate
- PASS: version check passed or
not-applicable, build succeeded or
build_status=skipped (no documented command for the change type), every
reviewer returned APPROVE or APPROVE WITH CHANGES, and no unaddressed
Must-fix items remain.
- FAIL: anything else.
6. Sentinel
Write pre-pr.ok to the repository's git directory — $(git rev-parse --absolute-git-dir)/pre-pr.ok (never under .claude/). Resolving the git
directory keeps the sentinel correct in linked worktrees, where .git is a file,
not a directory; --absolute-git-dir matches what the hook reads.
The gh pr create hook (.agents/scripts/pre-pr-gate.sh) checks head= and
status=; field names in this block are part of that contract.
head=<full HEAD SHA>
branch=<current branch>
status=PASS|FAIL
timestamp=<ISO-8601 UTC>
build=<command run, or "skipped">
build_status=PASS|FAIL|skipped
reviewers=<comma-separated names invoked>
version=<old->new, introduced:<new>, or "not-applicable">
Output format
On PASS — single line:
Pre-PR: PASS (<branch> vs <base>) — ready to `gh pr create`.
On FAIL — header line, then only the items that need attention, each
prefixed with the source reviewer or check:
Pre-PR: FAIL (<branch> vs <base>)
Must fix:
- [kotlin-engineer] <item>
- [spine-code-review] <item>
- [review-docs] <item>
Should fix:
- [dependency-audit] <item>
Report nothing about checks that passed. If auto-fixes were applied, list
them in one line before the verdict: Auto-fixed: <comma-separated list>.
Notes
- This skill must NOT create the PR itself.
- This skill must NOT create
version.gradle.kts.
- The sentinel lives under
.git/ — per-clone, never committed.
- Each reviewer is the source of truth for its own checks; this skill only
orchestrates and aggregates.
- This skill may auto-fix a missing version bump by running the
bump-version skill;
all other fixes require explicit user confirmation.
