| name | release-check |
| description | Review whether `dev` is healthy and ready to be promoted to `main` (production) — the human release gate from the Release & Deploy process. Surfaces the exact set of changes being promoted (`main..dev`), checks CI/gate health on `dev`, confirms no in-flight `[WIP]` PRs are being left behind, and reports merged-branch cleanup — then gives a READY / NOT READY verdict without promoting or merging anything. Use when the user asks to check, verify, or sign off that `dev` is ready to promote/release to `main`, or before a `dev → main` promotion. |
Release check — dev → main promotion gate
Review whether dev is healthy and ready to be promoted to main, and report,
honestly, whether it is. This is the executable form of the human release gate in
docs/process/06-release-and-deploy.md;
the build-and-rollout mechanics it triggers are authoritative in
docs/architecture/15-deployment.md. It
follows the honesty rule in .agents/rules/03-surfacing-gaps-and-incomplete-work.md.
Read AGENTS.md and the applicable .agents/rules/ first, as always.
Where this sits — not the same as Definition of Done
Two different gates, no overlap:
definition-of-done answers "is this feature done?" — everything before a PR
opens to dev (branch, plan, fmt/lint/check/architecture/tests, security).- This skill answers "is
dev ready to release to main?" — the promotion gate
after work has merged to dev. It reviews the integration branch as a set, not one
feature.
What promoting means here (so the check is grounded)
Deploying is GitOps: promoting dev → main is a merge, and GitHub Actions then builds
and rolls out to PROD SaaS, and cuts the signed self-hosted release bundle
(docs/architecture/15-deployment.md §4, §9).
No one types a deploy command. Consequences the promoter must understand before merging:
- The already-built
dev image digest is promoted — promotion re-tags a digest, it
does not rebuild. What passed on dev is bit-for-bit what serves production (§1).
- Merge to
main also publishes the self-hosted bundle customers install (§9).
dev → main is a deliberate lead/architect act — not automatic, not every engineer.
The full ladder (dev → qa → sandbox → main) is in §1/§6 of the deployment doc; this
skill checks the dev → main gate that doc 06 governs.
Scope of this skill
- Review and report only — never promote, merge, push, tag, or trigger a deploy.
- Surface, don't decide — the promotion authority is human; this skill gives the
evidence and a verdict, it does not stand in for the lead/architect's judgment.
dev is release-ready only when every check is green. "Mostly healthy" is not
ready — report it as not ready.
The checks — run in order
Stop-free: run all of them even if an early one is red, so the report is complete. Use
the gh CLI for GitHub state; if it is unavailable or unauthenticated, mark those checks
manual / not run — never green-by-default.
| # | Check | How |
|---|
| 1 | Repo state is clean | git status clean; git fetch origin; dev and main up to date with origin |
| 2 | There is something to promote | git rev-list --count main..dev > 0; if 0, nothing to release |
| 3 | The promotion set is understood | git log --oneline main..dev and git diff --stat main..dev — a reviewable set, not a surprise batch |
| 4 | No [WIP]/placeholder work in the set | No commit messages that are wip/fix/asdf/placeholder; Conventional-Commit shaped (.agents/rules/02-git-and-branching.md) |
| 5 | CI on dev is green | gh run list --branch dev --limit 5 — latest workflow conclusion is success |
| 6 | Quality gates pass on dev | The root make gates, per-service fallback — see below |
| 7 | No in-flight PR left behind | gh pr list --base dev --state open — nothing [WIP]/mergeable that was meant to be in this release |
| 8 | Merged branches reconciled | git branch --merged dev (and gh for remote) — merged feature branches cleaned up, per .agents/rules/02-git-and-branching.md |
| 9 | Deployed dev env behaves | Manual — the deployed DEV environment must be behaving as expected; the skill cannot observe it, so it flags this for human confirmation |
Check 6 — quality gates on dev
"dev is healthy" means its gates pass. Reuse the exact commands the definition-of-done
skill uses — do not invent targets:
- Discover targets:
make help or read the root Makefile. The root Makefile is the
single interface and is expected to grow the house gates (fmt-check, lint, check,
architecture-check, test, test-full).
- Run each existing root gate:
make <target>.
- Fall back per service when a root target is absent ("No rule to make target"): run
the equivalent inside each service and mark the gate manual / per-service — never
green-by-default. Per-service tooling is listed in the
definition-of-done skill
(Go make, Rust make + cargo, Python uv, web bun).
- If CI on
dev (check 5) already ran the full gate set green on the current dev SHA,
say so and treat the local run as confirmation, not a substitute.
Do not modify code to make a gate pass — this skill reviews. A failing gate on dev means
dev is not release-ready; report it with the failing command and key output.
Step-by-step
- Fetch and orient.
git fetch origin; confirm the working tree is clean and that
local dev/main match origin (check 1).
- Compute the promotion set.
main..dev — count, commit log, and diffstat (checks
2–4). If empty, stop with "nothing to promote".
- Assess
dev health. CI status via gh (check 5) and the quality gates (check 6).
- Check the release is complete and clean. In-flight PRs (7) and branch cleanup (8).
- Flag what only a human can confirm. The deployed DEV environment behaving (9), and
that the promoter understands the set and the deploy consequences above.
- Report (below). Do not promote, merge, push, tag, or deploy.
Output
Emit a single verdict table, one row per check, with an explicit status:
- ✅ pass — ran and green.
- ❌ fail — ran and failed; include the command and the key output.
- ⚠️ manual / not run — could not be run (no
gh, no root target and checked
per-service, or human-only like check 9); say which and why.
Include the promotion set (the main..dev commit list and diffstat) in the report so
the human sees exactly what would ship. Distinguish failed from not run from assumed
(.agents/rules/03-surfacing-gaps-and-incomplete-work.md). End with a one-line verdict:
- READY TO PROMOTE — only if every check is ✅ (check 9 confirmed by the human).
- NOT READY — otherwise, followed by the concise list of what is missing or red and
what must resolve it.
Never soften a ❌ or ⚠️ into a ready-sounding summary. Promotion itself remains a
deliberate lead/architect act — this skill informs it, it does not perform it.
