Release Checklist

Release Checklist

Audit whether Bactopia is ready to cut a version release and produce a recommendation report. This is a multi-repo, audit-only skill: it reads bactopia, bactopia-py, nf-bactopia, and the docs-site bactopia.github.io (published at https://bactopia.io), plus GitHub issues, and synthesizes a GO / NO-GO report.

Hard constraints — read first

• Audit-only. Never mutate anything. No git commit/push/tag, no gh issue edit/comment/close, no edits to any tracked source file, no running the config/catalog/schema regenerators against the repo. The only write is the report file under logs/ and scratch files under a mktemp dir.
• Every regeneration check writes to a temp dir and diffs — it never overwrites tracked nextflow.config / nextflow_schema.json / catalog.json / llms.txt.
• Report, don't fix. When a check finds drift, record it and recommend the follow-up skill (e.g. /update-catalog, /merge-schemas, /update-module). Do not apply the fix here.

Version model (why the checks look where they do)

The Bactopia pipeline version and the nf-bactopia plugin pin are declared in versions.yml at the pipeline repo root (keys bactopia: and nf-bactopia:). bactopia-merge-schemas reads them and renders every workflow's nextflow.config from the bactopia-py template, and bactopia-catalog reads them for catalog.json, so the main repo's nextflow.config and catalog.json versions are generated artifacts. versions.yml is the version source of truth; bactopia-lint's repo rules (V001/V002/V003) enforce that every version-bearing file, the CHANGELOG heading, and the plugin pin agree with it. CITATION.cff, bin/bactopia, and data/conda/meta.yaml carry hand-maintained literals that must be bumped to match and are frequent laggards.

Preamble

Resolve paths and a timestamp (from the bash tool):

BP=/home/rpetit3/repos/bactopia/bactopia
PY=$BP/../bactopia-py
NFB=$BP/../nf-bactopia
DOCS=$BP/../bactopia.github.io
TS=$(date +%Y%m%d_%H%M%S)
AUDIT=$(mktemp -d)          # scratch dir for read-only regen diffs

If a sibling repo path does not exist, run its checks in "skipped (repo not found)" mode and note it — never error out.

Run the checks

Present each result; never fix. Numbers below are the report's check IDs.

1. Version consistency (delegated to bactopia-lint)

Version-bearing file consistency is enforced by bactopia-lint's repo rules, not re-implemented in this skill. Run bactopia-lint once — the same run feeds checks 8 and 11 — and read the repo-tier results:

bash .agents/skills/review-groovydoc/scripts/run-bactopia-lint.sh --bactopia-path $BP --json --silent

Parse the repo component's results[] for rule IDs starting with V:

• V001 (FAIL): a version-bearing file disagrees with versions.yml — nextflow.config, catalog.json, bin/bactopia, data/conda/meta.yaml, CITATION.cff, or any *.config bactopia_version / nf-bactopia@ pin. Module/subworkflow test configs inherit both from conf/test_base.config, so that single file is the usual test-side offender (not the ~180 individual test configs). The message groups offenders by value.
• V002 (FAIL): versions.yml: bactopia ≠ the top ## vX.Y.Z CHANGELOG heading (disagreement on what's being released).
• Passing rules are not listed individually (PASS components have empty results[]); absence of a V-FAIL means clean.
• Any V001/V002 FAIL ⇒ check 1 = FAIL. Fixes: regenerate configs (/merge-schemas + /update-catalog), hand-bump CITATION.cff / bin/bactopia / data/conda/meta.yaml, and bump bactopia_version in conf/test_base.config (the single source for every module/subworkflow test config).
• Staleness guard: the lint JSON MUST contain a repo component. If it does not, bactopia-py predates the version rules and the core version gate could not run — this is a FAIL (never a false PASS): report "version rules V001–V003 not loaded; update bactopia-py" and treat the release as NO-GO until re-audited with current tooling.

The deterministic engine is run once and feeds checks 2, 12, 13:

python3 .agents/skills/release-checklist/scripts/release_audit.py --bactopia-path $BP --json

It returns sibling_release_state (check 12), changelog (check 13), module_updates (check 2), and warnings[] — surface any warnings.

2. Module tool versions (offline — reads the /update-module record)

This check does not hit the network. bactopia-update queries the Anaconda API for ~100 modules (~2 min), so the audit never runs it — instead it reads the record that /update-module leaves under logs/module-updates/<TS>.json. The engine's module_updates field carries the result:

• present: false ⇒ FAIL (blocking → NO-GO): no module-version check is on record for this cycle. Recommend: run /update-module (which writes the record) and then re-run /run-tests, before re-auditing. This is a hard release gate — do not hand-wave it.
• present: true:
  • module_config_changed_after: true ⇒ WARN: module.config files changed after the record was written, so it is stale — re-run /update-module.
  • needs_update > 0 ⇒ WARN: that many modules have newer tool versions available — run /update-module to apply them.
  • otherwise ⇒ PASS: module versions were checked at log_timestamp; the needs_user_review count is informational (multi-package modules needing manual review).

Report log_timestamp, needs_update, needs_user_review, and up_to_date from the record. Never edit configs and never call bactopia-update from this skill.

3. Workflow config/schema freshness (read-only diff)

For each of the 4 named workflows — bactopia, teton, staphopia, cleanyerreads (paths from catalog.json.workflows[<wf>].path) — regenerate into the scratch dir and diff against the committed copies:

bash .agents/skills/merge-schemas/scripts/run-bactopia-merge-schemas.sh \
    --bactopia-path $BP --wf <wf> --outdir $AUDIT/<wf>
diff $AUDIT/<wf>/nextflow.config  <committed nextflow.config for wf>
diff $AUDIT/<wf>/nextflow_schema.json <committed nextflow_schema.json for wf>

The scratch dir is empty, so --force is not needed and nothing tracked is touched. Any diff ⇒ the committed file is stale relative to current module schemas/template ⇒ recommend /merge-schemas. The root bactopia config round-trips cleanly, so a root diff usually means a module was added/removed without rewiring, or the template version was bumped without regenerating. Only extend to the ~66 bactopia-tools if the user explicitly asks ("all tools") — tool schemas are otherwise covered by their nf-tests.

4. Catalog & llms.txt freshness (read-only diff)

bash .agents/skills/update-catalog/scripts/run-bactopia-catalog.sh \
    --bactopia-path $BP --output $AUDIT/catalog.json --pretty --llms-output $AUDIT/llms.txt
diff $AUDIT/catalog.json $BP/catalog.json
diff $AUDIT/llms.txt     $BP/llms.txt

Any diff ⇒ stale ⇒ recommend /update-catalog.

5. Docs-site (bactopia.io) version state

In $DOCS (skip with a note if the repo is absent):

• (a) version label — read versions.current.label in docusaurus.config.ts; compare to the release target. A lagging label is a WARN ("bump on release").
• (b) changelog mirror — compare the top ## v<x.y.z> heading of docs/changelog.md to the main repo CHANGELOG.md top heading. A version mismatch is a WARN (mirror out of sync).
• (c) plugin pins — V001 only scans the bactopia repo's *.config files, so the docs site is not covered by the linter. Grep it directly: grep -rn 'nf-bactopia@' "$DOCS" --include='*.md' --include='*.mdx' and flag any pin that lags versions.yml: nf-bactopia (currently developers/nf-bactopia/index.mdx pins 2.0.3). WARN.

6. Docs sync (.agents/docs)

bash .agents/skills/review-docs/scripts/run-bactopia-docs.sh --bactopia-path $BP --validate --json --silent

Record summary.fail. Any FAIL ⇒ recommend /review-docs.

7. Citations integrity

bash .agents/skills/review-citations/scripts/run-bactopia-citations.sh --bactopia-path $BP --validate --json --silent

Record summary.orphans_total and summary.missing_total. Either > 0 ⇒ recommend /review-citations. (expected_orphans are informational, not failures.)

8. GroovyDoc / lint

Reuse the bactopia-lint run from check 1 (do not run it twice). Count component FAIL results — module (M0xx/MC0xx), subworkflow (S0xx), workflow (W0xx) — and exclude the repo-tier V0xx rules, which are reported under checks 1 and 11. Any component FAIL ⇒ recommend /review-groovydoc.

9. Python lint (bactopia-py)

Run the configured ruff linter in $PY (prefer the justfile recipe, fall back to ruff directly):

cd $PY && just lint    # == poetry run ruff check .  ; fallback: ruff check .

Interpret the exit: lint findings (ruff reports violations) ⇒ FAIL recommending a ruff pass in bactopia-py. But distinguish "linter unavailable" from "lint failed": if neither just nor ruff is installed/resolvable in $PY (command-not-found, or just lint errors because the poetry env isn't set up), report SKIP ("ruff not available in this environment"), never FAIL — a missing tool is not a release blocker.

10. Test-run freshness (never launches a run)

Test runs live under logs/run-tests/<timestamp>/ (written by /run-tests); bactopia-review-tests defaults to the newest one. An aborted run leaves a dir with no summary.json and the CLI errors on it, so pick the newest run dir that actually has a summary and review it explicitly:

LATEST_RUN=$(for d in $(ls -1dt "$BP"/logs/run-tests/[0-9]*/ 2>/dev/null); do [ -f "$d/summary.json" ] && basename "$d" && break; done)
bash .agents/skills/review-tests/scripts/run-bactopia-review-tests.sh --bactopia-path $BP --run "$LATEST_RUN" --silent

Also count how many logs/run-tests/[0-9]*/ dirs are newer than $LATEST_RUN but lack a summary.json — those are incomplete/aborted runs worth flagging.

Relay the reviewed run's pass/fail status. Then judge staleness: compare $LATEST_RUN's timestamp to the newest tracked-source commit (git -C $BP log -1 --format=%ct) and the working-tree dirty state (sibling_release_state.bactopia.dirty_files from the engine). Report stale if code changed after the run or the tree is dirty. Severity: a failing reviewed run ⇒ FAIL; a passing-but-stale run, or the presence of newer incomplete run dirs, ⇒ WARN recommending /run-tests; if no run dir has a summary.json at all ⇒ WARN ("no completed test run on record"). Never trigger a run from this skill.