| name | release |
| description | Orchestrate an Open Notebook release — changelog audit, risk-based A/B/C test matrix, Docker image gate (fresh + upgrade), fix loop via PRs, cut, publication with credits, retro. Use when preparing, testing, cutting or publishing a release. |
Open Notebook Release Orchestrator
You are conducting a release of Open Notebook, reproducing the process
established in v1.11.0. The source of truth for the process is
.github/RELEASE_PROCESS.md — read it first. This skill adds the
orchestration order, the exact commands, and the human gates.
Ground rules for the whole run:
- The release happens in a single session. Track phases with the task
tools (TaskCreate/TaskUpdate) so the owner sees progress.
- Every repo change goes through a PR (branch → PR → CI + cubic → merge).
Never push to main. Confirm the owner authorizes you to merge your own PRs
when clean; otherwise hand merges to them.
- Interact in the owner's language; write code, commits and docs in English.
- Read
${CLAUDE_SKILL_DIR}/gates.md NOW — it defines what you may do
autonomously and what requires an explicit GO.
Phase 0 — Scope and changelog audit
git fetch --tags · find the last release tag and gh release list.- List everything merged since:
git log <last-tag>..origin/main --oneline.
- Audit the CHANGELOG
[Unreleased] section against that list. Convention:
entries reference the issue number when one exists, the PR number
otherwise. Close every gap via PR.
- Check open Dependabot alerts (
gh api repos/{owner}/{repo}/dependabot/alerts?state=open)
— a security-themed release with open highs is incoherent. Triage them
into the fix loop or document acceptance.
Phase 1 — Risk-based test matrix
Read ${CLAUDE_SKILL_DIR}/test-matrix.md and instantiate it against the
actual release diff. Classify each change: what can it break, for whom,
which bucket (A/B/C) verifies it. Refine the matrix with the owner before
executing — they decide bucket-B investments and own bucket C.
Phase 2 — Execute bucket A
Run in parallel where possible:
uv run pytest tests/ · ruff check . · uv run python -m mypy . (all three
are required CI gates since the July 2026 cleanup; mypy must exit 0)- Frontend:
npm run lint, npm run test, npm run build (production build;
a stale node_modules produces false build failures — npm ci first if so)
- The smoke-e2e agent against the local dev stack (start it: database →
api → worker → frontend; check ports are free first — another project may
hold 3000/8000: identify the owner via
lsof + process cwd, never kill
blind; the frontend runs fine on PORT=3001 npm run dev — pass the URL to
the smoke agent. Also note the dev .env may point at a standalone
SurrealDB, not the repo-compose one)
- Dev-DB leak check: snapshot per-table record counts (at least
credentials) before and after the backend suite — a diff means a test is
writing to the live database (caught 48 leaked credentials in v1.12.0)
- The targeted probes from the matrix (legitimate-use regression checks
for security changes)
Phase 3 — Image gate + bucket C kickoff
make docker-build-local, then make release-test TAG=<ver> OLD_TAG=<prev>
(pull the genuine previous tag first — see gotchas in RELEASE_PROCESS.md).- Hand the owner their bucket-C checklist (from the matrix) so they test in
parallel — do not leave them as the bottleneck at the end.
Phase 4 — Fix loop
For each finding: reproduce → root-cause → focused PR with regression tests →
CI + cubic → merge (per gates.md). Apply the re-test policy from
RELEASE_PROCESS.md after each merge. Pre-existing bugs that are not release
regressions become backlog issues (ask the owner before creating issues).
Verify UI fixes in the real browser (Playwright) before opening the PR.
Phase 5 — Cut
- Cut PR off updated main: bump
pyproject.toml, date the changelog section.
- After merge:
make tag.
- Rebuild the image from final main and re-run the image gate against it.
- Push version images via CI:
gh workflow run build-and-release.yml --ref main -f push_latest=false
and watch the run. (Local make docker-push needs docker login.)
- Verify the pushed manifests (see
${CLAUDE_SKILL_DIR}/runbook.md).
Phase 6 — Pushed-image verification (human gate)
Offer the owner a browsable RC stack on this machine:
make release-stack TAG=<ver> [DUMP=<dump>] — with a copy of their dev data
for realism (export command in the runbook). Support them through it; findings
go back to Phase 4. Do not proceed without their GO.
Phase 7 — Publish (human gate)
- Draft release notes per
${CLAUDE_SKILL_DIR}/comms-templates.md — the
Thanks section is mandatory; collect every contributor with the
commands in the template. Show the owner for review.
- With their explicit GO:
gh release create v<ver> --title ... --notes-file ... --latest.
Publication triggers CI to push v1-latest — watch it, then verify the
latest manifests (runbook).
- Mark shipped issues with the
released label (ask before mass-labeling).
- Deliver the Discord post text (the owner posts it).
Phase 8 — Cleanup
make release-stack-down, remove temp dumps/data dirs, stop watchers, ensure
git status is clean on main and no test containers remain.
Phase 9 — Retro (always runs)
Ask the owner: "what should improve in this process?" — and apply the
accepted improvements now: edit .github/RELEASE_PROCESS.md,
scripts/release-test/*, and this skill's files while context is fresh.
New gotchas discovered during the run go into RELEASE_PROCESS.md's Known
Gotchas via the same PR flow.
