// Pre-push / pre-release checklist. Runs Rector, Pint, full test suite, PHPStan, and audits README + `.ai/` docs for staleness. Activate before: pushing to remote, tagging a release, writing release notes, or when user mentions: pre-release, pre-push, release checklist, ship, cut release, release notes.
Use when configuring, running, or debugging the laravel-fluent-validation-rector migration. Covers set lists, cross-rector configuration semantics (especially the silent-partial-config pitfall on shared allowlists), and the rule architecture context downstream contributors and AI agents need.
Build Rector PHP rules that transform PHP code via AST. Use when asked to create, modify, or explain Rector rules for PHP code transformations. Rector rules use the PHP-Parser AST and PHPStan type analysis. Triggers on requests like "write a Rector rule to...", "create a Rector rule that...", "add a Rector rule for...", or when working in a rector-src or rector-based project and asked to implement code transformation logic.
| name | pre-release |
| description | Pre-push / pre-release checklist. Runs Rector, Pint, full test suite, PHPStan, and audits README + `.ai/` docs for staleness. Activate before: pushing to remote, tagging a release, writing release notes, or when user mentions: pre-release, pre-push, release checklist, ship, cut release, release notes. |
Run this full gauntlet before pushing commits that may be tagged as a release or before drafting release notes. It catches regressions the two-tier backend-quality skill skips — Rector drift and stale docs shipped to downstream projects.
Activate when:
Do NOT use mid-development — this is a completion-level skill.
The user cuts the tag, not you. The user runs git tag and creates the GitHub release themselves — tagging is irreversible-ish and a release-visibility decision that the user owns. Do NOT suggest, demonstrate, or execute tag/release-create commands. State that the release is ready to tag and leave the tag creation to the user. The skill's job ends only once step 8b (post-tag watch) has confirmed the tag-ref and release-event workflows are green — "tag cut" is not the finish line.
Run the checks in this order. Each must pass before moving to the next. Fix issues as they surface; do not batch.
Always append || true to verification commands so output is captured even on failure (per repo CLAUDE.md rule). Pass/fail is determined from the captured output, not the exit status alone.
The order is 1 → 2 → 3 → 4 → 5a → 5b → 5c → commit → push → 6 → 7 (draft notes) → user cuts tag → 8a (pre-tag gate, just before gh release create) → 8b (post-tag watch). Do not jump from step 5 straight to drafting release notes. The release-notes file is written only after the changes have been committed, pushed, and CI is green on that exact SHA (step 6). Writing notes earlier claims facts ("tests pass on CI matrix", "2,092 tests / 2,941 assertions") that are not yet proven. If you find yourself about to Write a file under RELEASE_NOTES_<version>.md and the last thing you did was a local quality check, stop — you skipped commit/push/CI. And if the tag is cut without step 8a's live-remote + CI re-check, or without waiting on step 8b's tag-ref runs, the release ships on unverified facts even if steps 1-7 all passed.
vendor/bin/rector process || true
Must report 0 files changed. If Rector modifies files, review the diff, commit the changes, and re-run until clean.
vendor/bin/pint --dirty --format agent || true
Must be clean. Re-run after Rector — Rector fixes can introduce style drift.
vendor/bin/pest || true
Must show 0 failures.
Local green ≠ CI green for this step. Pest runs parallel on one OS/PHP/Laravel combo locally. The CI matrix includes Windows + prefer-lowest legs where pest --parallel has historically raced filesystem ops (e.g. PackageManifest::write() → rename()), producing failures invisible on macOS. Do not let a local pass relax step 6 rigor — step 6 is the authoritative test gate across the matrix. See 1.17.1: local green, Windows P8.2 prefer-lowest red, tag cut anyway because step 6 was skipped.
vendor/bin/phpstan analyse --memory-limit=2G || true
Must show 0 errors. Fix real issues — do not pad the baseline. See backend-quality skill for baseline rules.
Release-worthy features change user-visible behavior, so README.md and the .ai/ files we ship to downstream projects (via package-boost:sync) can drift silently. Every release must audit both.
Rule: add or edit docs only where they reflect a real change. Do not bloat the README or skills. Delete stale content aggressively.
Scan README.md against the commits in this release (git log <last-tag>..HEAD). Update these sections when relevant:
If unsure whether a change warrants a README update: check whether a user reading the README after the release would see outdated advice. If yes, update.
The .ai/skills/ and .ai/guidelines/ directories are synced by Laravel Boost (vendor/bin/testbench package-boost:sync) to CLAUDE.md, AGENTS.md, .claude/skills/, and .github/skills/. Those generated files ship with the package and are read by downstream projects' AI tooling.
Check each edited-or-eligible doc:
main.description — if a new workflow exists, make sure someone typing the natural-language ask can discover the skill.If any .ai/ file changed, sync and verify:
vendor/bin/testbench package-boost:sync || true
git status --short .claude/ .github/ CLAUDE.md AGENTS.md
All generated files must be committed together with their .ai/ sources (per the ai-guidelines skill).
PUBLIC_API.md)PUBLIC_API.md enumerates every symbol the package promises to keep stable
under SemVer. Two failure modes silently break consumers:
^N.0 get a fatal class not found or undefined constant on the
bump. Detection: every entry in PUBLIC_API.md must still resolve in
src/ to a class/trait/interface/enum or a documented constant.src/
outside the Internal\ namespace is implicitly public surface. Without
a PUBLIC_API.md entry, the SemVer promise is ambiguous (consumers
import it; future renames break them silently because nothing said it
was off-limits). Detection: every class under src/ not in Internal\
namespace must either appear in PUBLIC_API.md or be in
tests/InternalAuditTest::PUBLIC_CLASSES.The InternalAuditTest test (run in step 3) catches the namespace
boundary — it asserts every src/ class is either explicitly public or
@internal / Internal\. Step 5c catches the documentation boundary
— a class on the public list might still be missing from
PUBLIC_API.md, and PUBLIC_API.md entries might point at symbols that
moved or vanished.
# Cross-check every class in InternalAuditTest::PUBLIC_CLASSES is also
# documented in PUBLIC_API.md. Manual audit; no programmatic check yet
# (would require parsing PUBLIC_API.md sections + reflection over
# PUBLIC_CLASSES).
grep -E "^- |^### " PUBLIC_API.md | head -40
# Cross-check no class under src/ outside Internal\ silently slipped
# in without InternalAuditTest awareness:
vendor/bin/pest tests/InternalAuditTest.php || true
If a symbol moved (e.g. Diagnostics → Internal\Diagnostics),
PUBLIC_API.md must reflect the new location AND the deprecation cycle
for the old location (when shim ships, when removal lands). See
0.20.0 for the canonical example: namespace move + class_alias shim +
removal slated for 1.0, all three documented in the namespace-structure
section of PUBLIC_API.md.
This step has no automated assertion yet — it's a manual audit by the
release author. Open follow-up: bake into a PublicApiSurfaceTest
data-provider that reads PUBLIC_API.md headings and asserts each
named symbol resolves.
Local green ≠ CI green. The matrix job runs against a Testbench-bootstrapped app in a clean env that usually differs from the dev machine — missing APP_KEY, no cached auth user, different PHP/Laravel combos. Local passes frequently, CI fails. A green tag on a red CI is a broken release (see 1.13.1: every Livewire test failed in CI with "No application encryption key has been specified" while 2,081 tests passed locally).
Scope is per-commit, not per-run. This repo has multiple workflows with different triggers — gh run watch follows a single run and will silently skip other workflows that also have opinions about the same SHA. Enumerate by commit SHA and wait for every matching run:
git push
SHA=$(git rev-parse HEAD)
# Settle — GitHub takes several seconds to register runs against the new SHA.
# Querying too early returns an empty list; `running=0` would falsely signal green.
sleep 20
# List every workflow run tied to this SHA, across all workflows/triggers
gh run list --commit "$SHA" --json databaseId,name,event,status,conclusion
# Wait for every run to reach a terminal state, then assert all success.
# `total > 0` guard prevents the empty-list → zero-running false green.
while true; do
total=$(gh run list --commit "$SHA" --json databaseId -q 'length')
running=$(gh run list --commit "$SHA" --json status -q '[.[] | select(.status != "completed")] | length')
[ "$total" -gt 0 ] && [ "$running" -eq 0 ] && break
sleep 15
done
failed=$(gh run list --commit "$SHA" --json conclusion,name -q '[.[] | select(.conclusion != "success" and .conclusion != "skipped")] | length')
[ "$failed" -eq 0 ] || { echo "CI red on $SHA"; gh run list --commit "$SHA"; exit 1; }
Pass criteria: every run for this commit has conclusion in {success, skipped}. Skipped is fine — path-filtered workflows (e.g. on: push: paths: ['**.php']) are expected to skip when the release commit touches docs only.
Don't rely on a "latest run" heuristic. gh run list --branch main --limit 1 may pick a run from a completely different push — the commit-SHA filter is the only reliable anchor.
On failure:
gh run view <id> --log-failed (or via API if --log-failed is empty: gh api /repos/<owner>/<repo>/actions/jobs/<job-id>/logs).Do NOT write release notes until CI is green. Release notes claim "tests pass on X/Y/Z"; CI is the evidence. Skipping this step reduces downstream trust. (The user handles tag creation — once release notes are drafted against a green CI, the skill's job is done.)
Workflows triggered by release (e.g. update-changelog) run AFTER tag creation, not before. They're outside this gate by design — their job is to decorate the release after it ships, not to gate whether it ships.
on: push workflows re-fire on the tag-ref push. Creating a release pushes a tag ref; any workflow that triggers on push (including run-tests) runs again against that tag ref. Those runs are not part of this pre-tag gate — they happen after tag creation. They can surface environment-shape failures (Windows fs races, prefer-lowest combos) that the main-branch run narrowly missed. Step 8 (post-tag watch) handles them.
This is where agents most commonly slip: running the local gauntlet (steps 1-5), then jumping straight to Write RELEASE_NOTES_<version>.md without committing, pushing, or watching CI. Do not do that. Notes claim CI-matrix facts; CI must have produced those facts first.
Release notes are public artefacts — do NOT name or reference peers. The release body is rendered on GitHub, prepended to CHANGELOG.md by CI, and indexed by Packagist. Anything written here is visible to every downstream consumer and shows up in search. Internal peer instances (e0cp6lq3, 2op9yaul, etc.), peer-level adoption reports, and claude-peers channels are process concerns, not product concerns — consumers don't know or care about them, and leaking the IDs exposes internal architecture.
What not to write:
e0cp6lq3"What to write instead:
Scope of the rule: applies to RELEASE_NOTES_<version>.md at the repo root (the file CI promotes into CHANGELOG.md and into the public GitHub release body). Internal planning files in any gitignored location (e.g. internal/roadmap.md, internal/specs/*.md, notes/) CAN reference peer IDs — they stay out of the package's git history and are legitimate session-to-session continuity aids.
Quick scrub checklist before Writeing the notes file: grep your draft for peer, "claude-peers", "claude-code", and any peer-ID-shaped token. Peer IDs mix digits and letters (e0cp6lq3, 2op9yaul), so plain [a-z0-9]{8} matches plain English words like "Highlights" — filter to tokens that have BOTH a digit and a letter:
grep -nE 'peer|claude-peers|claude-code' "$NOTES"
grep -oE '\b[a-z0-9]{8}\b' "$NOTES" | grep -E '[0-9]' | grep -E '[a-z]'
The two-stage grep on the second line extracts 8-char tokens, keeps only those with at least one digit, then keeps only those with at least one letter — exactly the peer-ID shape. Full 40-char git SHAs do NOT match because \b word-boundary requires the whole token be 8 chars; only abbreviated SHAs typed as standalone 8-char tokens (d8c0a3c6 alone) would match — ignore those by eye. If any actual peer-ID-shaped token remains, rewrite or delete the phrase before saving.
Preflight — run these three commands and confirm all three before you create the release-notes file. If any fail, you are not ready to draft notes; go back to whichever earlier step is incomplete.
# 1. Working tree must be clean — the commit landed, nothing is uncommitted
git status --short || true
# 2. HEAD must be pushed — local SHA == origin/main SHA
[ "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)" ] && echo "pushed" || echo "NOT pushed"
# 3. Every CI run for this SHA must be terminal + {success, skipped} — same query as step 6
SHA=$(git rev-parse HEAD)
gh run list --commit "$SHA" --json name,status,conclusion
Only when (1) status is empty, (2) echoes pushed, and (3) every run is completed + {success, skipped} may you Write to RELEASE_NOTES_<version>.md.
Draft into RELEASE_NOTES_<version>.md. The user reads the draft, creates the tag, and publishes the release themselves — do not cut the tag, do not run gh release create, do not push tags. Once the release-notes file exists and CI is green, report "ready to tag" and stop.
Pin the verified SHA in the notes file. The very first line of the notes file must be an HTML comment recording the green SHA. GitHub strips HTML comments when rendering the release body, so this is invisible to readers but greppable by step 8:
<!-- verified-sha: 4387b6845b45def9c6ad80e638990f81b74bfb19 -->
# <version>
...
The SHA in that line is the exact git rev-parse HEAD that step 6 proved green. Step 8's pre-tag gate fails closed if the SHA in the notes file does not match the current HEAD (i.e. someone landed more commits between notes draft and tag).
CI handles CHANGELOG.md automatically — do not edit it manually. .github/workflows/update-changelog.yml prepends the release body on release publish. See the release-automation guideline for details.
Step 7 proves CI green at draft time. Step 8 proves CI is still green at tag time, and catches failures that only show up on the tag-ref push.
8a. Pre-tag gate — run immediately before gh release create / GitHub release publish. This is the one-liner the user runs (not the agent) in the same terminal, seconds before cutting the tag. It re-verifies three things: HEAD hasn't drifted since notes draft, the notes file pins this exact SHA, and CI is still all green.
SHA=$(git rev-parse HEAD)
VERSION="<version>" # e.g. 1.17.2
NOTES="RELEASE_NOTES_${VERSION}.md"
# A. Notes file exists and pins this SHA (anchored regex — tolerant of surrounding blank lines,
# strict about the line itself so a rewrite of the SHA breaks the gate)
grep -qE "^<!-- verified-sha: $SHA -->$" "$NOTES" || { echo "NOTES SHA DRIFT — HEAD=$SHA, notes say $(grep verified-sha "$NOTES")"; exit 1; }
# B. HEAD matches the LIVE remote tip of main — not the cached tracking ref.
# `git rev-parse origin/main` is stale until an explicit fetch and would
# let a concurrent push slip through. `ls-remote` always hits the remote.
LIVE_TIP=$(git ls-remote origin refs/heads/main | awk '{print $1}')
[ "$SHA" = "$LIVE_TIP" ] || { echo "HEAD DRIFT — HEAD=$SHA live origin/main=$LIVE_TIP"; exit 1; }
# C. Every CI run for this SHA still terminal + {success, skipped}
failed=$(gh run list --commit "$SHA" --json conclusion -q '[.[] | select(.conclusion != "success" and .conclusion != "skipped")] | length')
running=$(gh run list --commit "$SHA" --json status -q '[.[] | select(.status != "completed")] | length')
[ "$running" -eq 0 ] && [ "$failed" -eq 0 ] || { echo "CI NOT GREEN — running=$running failed=$failed"; gh run list --commit "$SHA"; exit 1; }
echo "OK to tag $VERSION at $SHA"
The ls-remote call is the key difference from the step 7 preflight, which uses the local tracking ref origin/main. Step 7 runs right after push when the tracking ref is fresh; step 8a can run minutes or hours later, after the user has context-switched, and the only safe way to prove HEAD is still the tip is to ask the remote directly.
If any check fails, do NOT tag. Fix the drift / failure, re-run steps 6-7 for the new SHA, then retry 8a.
8b. Post-tag watch. Creating the release pushes a tag ref, which re-fires on: push workflows (including run-tests) against that ref. Watch those runs — they are not part of the pre-tag gate and can fail even when 8a passed (Windows fs races, prefer-lowest combos that narrowly missed the main-branch run). Also watch release-event decorators (update-changelog).
Do not use gh run list --branch "$TAG". The --branch flag's semantics for tag refs are undocumented — it sometimes works, sometimes returns empty. The reliable selector is the tag's commit SHA plus a jq filter on headBranch == $TAG. Both push-event (tag-ref re-fire) and release-event runs attach to that SHA with headBranch set to the tag name.
Run 8b strictly after gh release create has completed. The tag must already exist on the remote; fetch it locally before resolving the SHA.
TAG="$VERSION"
git fetch --tags origin --quiet
TAG_SHA=$(git rev-list -n 1 "$TAG") # the commit the tag points at
# All runs attached to the tag SHA, then filter to those whose headBranch is the tag ref.
# This cleanly picks up both the `push`-event tag re-fires and the `release`-event decorators,
# and excludes the main-branch runs that step 6 already gated.
gh run list --commit "$TAG_SHA" \
--json databaseId,name,event,headBranch,status,conclusion \
-q "[.[] | select(.headBranch == \"$TAG\")]"
# Wait until every tag-scoped run is terminal, then assert all success.
# `waited` bounds the loop at ~15 min so a hung run doesn't block indefinitely.
# If `total` stays 0 past the first 90s, the tag was likely created without firing
# push/release workflows (rare — e.g. re-using an existing tag) — investigate manually.
waited=0
while [ "$waited" -lt 900 ]; do
running=$(gh run list --commit "$TAG_SHA" --json status,headBranch \
-q "[.[] | select(.headBranch == \"$TAG\") | select(.status != \"completed\")] | length")
total=$(gh run list --commit "$TAG_SHA" --json databaseId,headBranch \
-q "[.[] | select(.headBranch == \"$TAG\")] | length")
[ "$total" -gt 0 ] && [ "$running" -eq 0 ] && break
sleep 15
waited=$((waited + 15))
done
[ "$total" -gt 0 ] || { echo "NO TAG-REF RUNS after ${waited}s — investigate"; exit 1; }
failed=$(gh run list --commit "$TAG_SHA" --json conclusion,headBranch,name \
-q "[.[] | select(.headBranch == \"$TAG\") | select(.conclusion != \"success\" and .conclusion != \"skipped\")] | length")
[ "$failed" -eq 0 ] || { echo "TAG-REF CI RED on $TAG ($TAG_SHA)"; gh run list --commit "$TAG_SHA"; exit 1; }
Wait until terminal. If red:
main, cut a patch release (1.17.2 after 1.17.1). Do not rewrite the tag.update-changelog failed: CHANGELOG.md won't be prepended — re-run the workflow once the underlying cause is fixed, or prepend the entry manually (rare).Rule: the skill is not "done" until 8b goes green. "Tag cut" is not the finish line; "tag-ref CI green + release-event workflows green" is.
| Step | Command | Pass criteria |
|---|---|---|
| 1. Rector | vendor/bin/rector process || true | 0 files changed |
| 2. Pint | vendor/bin/pint --dirty --format agent || true | clean |
| 3. Tests | vendor/bin/pest || true | 0 failures |
| 4. PHPStan | vendor/bin/phpstan analyse --memory-limit=2G || true | 0 errors |
| 5a. README | manual scan vs git log <last-tag>..HEAD | no stale claims; all changed rules listed |
| 5b. Boost docs | vendor/bin/testbench package-boost:sync || true | .ai/ ↔ generated files in sync |
| 5c. PUBLIC_API.md | manual audit: every entry resolves in src/, every public src/ class listed | no stale entries; no undocumented public surface |
| commit + push | user confirms changes + git push | HEAD pushed to origin/main |
| 6. CI green-light | gh run list --commit "$(git rev-parse HEAD)" all complete + no failure | every run for the SHA in {success, skipped} |
| 7. Release notes | preflight (clean tree + pushed via tracking ref origin/main + CI green) → Write RELEASE_NOTES_<version>.md | first line is <!-- verified-sha: $SHA --> |
| 8a. Pre-tag gate | one-liner asserts SHA-drift, push state via live git ls-remote (not tracking ref — may be stale), CI-still-green immediately before gh release create | prints OK to tag |
| 8b. Post-tag watch | gh run list --commit "$TAG_SHA" filtered by headBranch == $TAG | tag-ref + release-event workflows all green |
Write a release-notes file after running local checks, stop: you are about to fabricate facts that the CI matrix has not yet established. Run the step-7 preflight commands first; if any of the three conditions is not satisfied, the draft is premature.git ls-remote, not the cached origin/main) so a concurrent push can't slip a stale commit through. 8b uses --commit "$TAG_SHA" + a jq filter on headBranch == $TAG (not --branch "$TAG", whose tag-ref semantics are undocumented and unreliable) so the tag-ref on: push re-fires and on: release decorators are both caught. Run both every time, even for one-commit patch releases.pest --parallel on Windows prefer-lowest has a known FS race in PackageManifest::write() → rename(). Do not assume local parallel-pest green proves CI-matrix green. Step 6 + 8b are the authoritative test gates.