release-review
Skill152 starsChanged 31 days agoMITView on GitHub
Mandatory pre-release deep review for minor/major releases (X.Y.0 / X.0.0). Runs a multi-agent adversarial audit of the ENTIRE repository, produces a stable-ID findings report with user triage, drives the remediation PR, then runs a post-implementation verification round with fresh lenses. Point releases (X.Y.Z, bug fixes only) are exempt. Invoke when preparing a new minor/major release, or whenever the user asks for a full-repository audit/review.
7 other projects use a version of this.
Adopted by
Most recently taken up by
- arvindand/agent-skillstheir own version, first seen Nov 1, 2026
- pariveo/salesforce-agent-skillstheir own version, first seen Oct 20, 2026
- Shri-Phnx/claude-skillstheir own version, first seen Oct 13, 2026
- SoftBlack42/StarPietheir own version, first seen Oct 9, 2026
- nielsmadan/skillstheir own version, first seen Sep 5, 2026
- indyforge/knowledge-forgetheir own version, first seen Jun 18, 2026
Other versions7 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 7
- SoftBlack42/StarPie★ 1.4ksame name
- arvindand/agent-skills★ 17same name
- pariveo/salesforce-agent-skills★ 2same name
- peterwangze/software-project-governance★ 2same name
- Shri-Phnx/claude-skills★ 2same name
- nielsmadan/skills★ 1same name
- indyforge/knowledge-forge★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository2 other files it gives its agents.
- AGENTS.mdAGENTS.md
- dashboard-previewSkill
The file
We split this skill into the rules it gives an agent
2 rules. 0 are common, 1 is distinctive, and 1 is very specific to this project.
0
Common
Most of the 6 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 24
MANDATORY before tagging any
X.Y.0orX.0.0release: Do not tag without a completed cycle (both rounds) for the release. - Distinctive: line 91
Verify substance by reading the changed code, not commit messages.
“Common” is measured: kept by at least 6 in 10 of the 6 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Release review — full-repository adversarial audit
Automated tests prove the code does what a test author thought to ask. They do not prove that nobody overlooked a way the daemon can drop a healthy host or miss a real outage. Before every minor/major release, the whole repository at HEAD — not just the release diff — goes through this structured audit.
ELI5: every deep clean of a big house finds dirt; that never means the house is filthy. The point is not "zero findings" (unreachable) — it's that new findings stop being scary. Track the severity trend, not the count.
History (why this is mandatory): the v6.0.0 pass found ~100 issues, the
v6.1.6 pass 64, the v6.1.7 pass 65 + 28 more in verification — each round's
Criticals shrank in number and blast radius and migrated from the shutdown
core toward the periphery. See "Pre-release code review" in docs/testing.md.
When
- MANDATORY before tagging any
X.Y.0orX.0.0release. Do not tag without a completed cycle (both rounds) for the release. - NOT required for patch releases (
X.Y.Z) — those are bug-fix only and inherit the minor's review. (If a "patch" has grown feature-sized, that's a sign it should have been a minor — review it.) - Also usable on demand when the user asks for a full-repo audit.
Round 1 — fan-out review (before any fixes)
- Spawn three specialist subagents IN PARALLEL (one message, three
Agent calls — sequential spawning defeats the purpose). These are task
roles, not assumed installed agent types: use
general-purposeagents for the security and test roles. For the first role, useagent-skills:code-reviewerwhen that skill is installed; otherwise give a general-purpose agent the same fresh-context review prompt. In Codex, use ordinary spawned agents with descriptive task names such ascode_review,security_audit, andtest_quality:- Code review — five-axis review (correctness, readability,
architecture, security, performance) of the whole tree. Priority:
production-readiness of the shutdown orchestration, state machine,
signal handling, subprocess/SSH execution, config validation, error
paths. Remind it of the uv-venv rule from
AGENTS.md. - Security audit — threat model + vulnerability pass: OWASP for the dashboard/API, command/argument injection, secrets in logs, YAML safety, dependency CVEs, systemd/packaging hardening. Ask for an explicit list of surfaces examined and found clean.
- Test quality — coverage AND quality: run the unit suite in a uv venv for ground truth; find behavioral gaps (simulated-but-never-exercised paths, races), not just uncovered lines.
- Code review — five-axis review (correctness, readability,
architecture, security, performance) of the whole tree. Priority:
production-readiness of the shutdown orchestration, state machine,
signal handling, subprocess/SSH execution, config validation, error
paths. Remind it of the uv-venv rule from
- Orchestrator direct checks (main session, while agents run): docs freshness, CI/workflow health, dashboard accessibility signals.
- Merge, dedupe, and write the report at the repo root
(
SHIP_REVIEW.mdpattern — a working artifact, do NOT commit it):- Ship decision (GO/NO-GO) + a rollback plan (trigger conditions, per-install-path procedure, RTO).
- Master findings table —
ID | Sev | Axis (source) | file:line | Finding | Suggested remediation | Effort. IDs are stableF-NNN, continuing the existing series across rounds and releases, never reused. - Implementation guidance: findings sharing a root cause become one fix group landed as one unit (the v6.1.7 config schema gate closed seven findings at once); a suggested landing order; per-fix verification.
- The report must be self-contained for a fresh agent session: no references to the review conversation.
- User triage (required before any fix). Present an ELI5 table — one plain-language row per finding, concrete metaphor first, jargon second — so the user can drop or downgrade findings. Record drops in the report with the user's reason (strikethrough row + scope-rule entry). A dropped finding is never implemented; reviewers never return empty, so triage is part of the process, not an insult to it.
Remediation PR
- Track every in-scope finding with
/goalsuntil closed — do not declare done while any non-dropped finding is open (v6.1.7 shipped its PR with one of 62 silently unaddressed; the tracker exists to make that impossible). - One commit per category (fix group / silent-failures / security / perf / CI / tests / docs-tail), all on a single branch, delivered as one PR.
- Then the standard
AGENTS.mdflow: CI green → both upstream AI reviews → address findings (max two rounds) → wait for the user's explicit greenlight. Never self-merge.
Round 2 — verification (after implementation, before merge/tag)
Spawn IN PARALLEL:
- Compliance audit — every in-scope finding vs the actual diff: fixed / fixed-differently (judge the deviation) / partial / missing. Verify substance by reading the changed code, not commit messages. Explicitly re-verify every user-mandated constraint from triage.
- Regression review of the diff itself — bugs the fixes introduced. Crucially: verify each fix works in the exact scenario its finding cites (three v6.1.7 fixes failed their own cited scenario).
- Fresh bug hunts with lenses earlier rounds did NOT use — rotate among: cross-module interactions, real-world data edges (malformed/ extreme NUT variables, odd SSH targets), time & ordering (DST, monotonic-vs-wall, rollover), resource lifecycle (leaks, unbounded growth over weeks of uptime), newest-code-meets-oldest-code.
Rules for round-2 agents: read the round-1 report first — re-reporting a known or user-dropped finding is a task failure; findings need a concrete, traceable failure path (no hardening wishlists); an honest "found little" beats padding.
Output: a separate round-2 report (SHIP_REVIEW_ROUND2.md pattern —
never fold into the round-1 report), continuing the F-ID series, with a
merge/tag gate section, already-fixed markers for anything closed in the
meantime, and a "verified sound — do not re-litigate" list so later passes
don't churn. New findings go through the same user triage, then loop back
into the remediation PR; re-verify only what changed.
Principles (learned over v6.0.0 → v6.1.7)
- Close bug classes, not instances. A declarative gate or a CI tripwire beats N spot fixes; ask "what invariant was missing?" for every cluster.
- Finding count is not a health metric; the severity trend is. Expect a long Minor/Low tail forever; reserve alarm for Criticals recurring in previously-audited core code.
- A fix is not done until verified against its own cited scenario.
- New code carries new bugs at roughly constant density — a review after a feature wave harvests that wave; that's the process working.
- Reports carry stable IDs and
file:lineanchors so any harness (Claude, Codex, a human) can execute them without the originating conversation.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

