Conversation
…ledge base
Build reusable AI-assistant tooling for developing, maintaining, submitting, and
reviewing Bioconductor R packages, distilled from the official contributions guide.
- knowledge/: 20 task-oriented summaries covering all 33 chapters + appendices A-H,
plus an end-to-end submission runbook (workflow.md) and topic router (index.md).
Single source of truth; each summary links its canonical chapter and stamps the
fetch date. SOURCES.md pins the upstream pkgrevdocs commit for drift detection.
- Cross-tool adapters: AGENTS.md (Codex/Cursor/Gemini/Copilot), with GEMINI.md and
CLAUDE.md importing it.
- Claude Code plugin: skills/bioconductor-package-dev/SKILL.md and
agents/bioc-package-review.md, packaged via .claude-plugin/{plugin,marketplace}.json.
- templates/: lean package skeletons; scripts/check-submission.R runs the gate.
- context/: plan, session state, TODO, and REFRESH.md maintenance runbook.
context/ holds local working docs (session state, plan, TODO, refresh runbook) that should not ship with the shared repo.
REFRESH.md moves out of gitignored context/ and covers all five tracked upstreams, not just pkgrevdocs. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Delete scripts/check-submission.R and templates/ - both reimplement Bioconductor tooling that already does more, the reuse violation ch5 warns about. All three router files now carry an identical block pointing at BiocCheck and biocthis instead. Content fixes: - 01-submissions.md: eligibility is upstream "should", not "must"; CI files on a non-default branch is a recommendation, not a rule - workflow.md: add a "Converting an existing package" entry point - SOURCES.md: pin all five tracked upstreams; add the .Rmd column, so a GitHub compare can be joined to the affected summaries - SKILL.md: description retuned for conversion; router now lives only in AGENTS.md - README: layout tree, How this is verified, Built on Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…tion verify.py runs 12 static checks (Python 3 stdlib, no network): manifests, frontmatter, path references that must exist and must not be gitignored, the README tree, Source/Fetched stamps, the SOURCES map against the per-file footers, references to removed tooling, the BiocCheck/biocthis block being identical in all three router files, gate values, emoji, rule text duplicated between AGENTS.md and SKILL.md, and the stamp contract. Run against the pre-fix tree it reports the known defects; clean here except for two files Layer 3 and Layer 5 still have to create. Building the fidelity table surfaced a sixth defect: four of the five gate numbers were stated as requirements when upstream says "should" or "it is recommended that". Only the 5 MB file limit is a "must", and the tracker's own minimum is check plus BiocCheck with no ERROR or WARNING. The gate is now two tiers everywhere it appears, and the review agent reports a tier-2 miss as a warning rather than a blocker. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Six checks against the five tracked upstreams: pkgrevdocs commit drift mapped through the .Rmd column to the affected summaries, chapter URL liveness, the quotation table, the Contributions issue template, chapter coverage against the guide TOC, and tool version pins. The quotation table is how modality is kept honest. Where a knowledge file states a load-bearing rule it must quote upstream verbatim, and the check asserts the quote is present both upstream and here. Upstream rewording fails the check; paraphrasing a "should" into a "must" fails it too, because the paraphrase no longer matches. Nine rows seeded: the four size and timing numbers, the version rule, the default-branch rule, the CRAN exclusivity rule, and the eligibility list. urllib first, curl second: a TLS-intercepting proxy makes urllib reject certificates curl accepts, and that must not read as upstream drift. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
scripts/golden-path.R runs the biocthis chain from the documented block against a throwaway package, then asserts the chain produced what the gate asks for - DESCRIPTION with biocViews and Version 0.99.0, NAMESPACE, NEWS.md, inst/CITATION, a vignette and a man page. A biocthis rename fails here with a clear message rather than deep inside BiocCheck output. .github/workflows/verify.yml runs the layers on four different triggers: static on every push, golden-path on pull requests and weekly, fidelity weekly only (it opens or updates a single upstream-drift issue instead of gating anyone's pull request), evals on manual dispatch. New static check: the workflow must pin bioc-actions to the tag recorded in SOURCES.md, and no action may be pinned to a branch. Not yet executed anywhere: golden-path.R needs R 4.6 and Bioconductor devel, and this machine has R 4.4 with none of usethis, biocthis or BiocCheck installed. It parses, and it fails cleanly with an install message when a dependency is missing. Its first real run will be in CI. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Ten cases under evals/, one per prompt documented in the README. Three guard the skill description, which is the single point of failure that can make the whole plugin inert while every static check passes green: conversion, implicit (never says "Bioconductor"), and a negative case that must stay quiet on a plain CRAN question. Two agent cases audit a fixture package with exactly three planted defects - Version 0.1.0, no biocViews, no vignette - built by shell only, so they need neither R nor biocthis. Their LLM graders name both the findings that count and the false positives that do not. New static check: every quoted prompt in the README's Example prompts section must appear verbatim as some case's execution.prompt, so the documented examples cannot drift away from the tested ones. Not yet executed: `claude plugin eval` is early access and unavailable in the local CLI. The cases are written against the schema the CLI validates, but have never been run, and the evals job is dispatch-only so a broken case cannot break anything else. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The load test asked for a DESCRIPTION version and got a confident but invented "R (>= 4.5.0)" floor. The cycle was recorded only in SOURCES.md, which the skill never opens. It is now one line in all three router files, and a network check compares all four against config.yaml. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A local smoke test showed correct behaviour is to say "not Bioconductor, skipping that guidance" and then answer the CRAN question. The grader banned the bare word, so it would have scored the right answer as a failure. It now bans substantive Bioconductor guidance instead. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The job has never executed. Reverting in the next commit. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
First CI run of golden-path died in "Set up job" before any step ran. GitHub auto-fails workflows reaching actions/cache v2, and bioc-actions/use-bioc-caches pins it - at v1.0.16 and on the action main branch, so a tag bump does not help. Replaced with actions/cache@v4 on the R library, which is the thing worth caching here anyway; the action caches hub data the golden-path package never downloads. Recorded in SOURCES.md and REFRESH.md so a future refresh does not helpfully re-add it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
usethis refuses to create a project nested inside an existing one. Also echo the tail of the failure as a ::error:: annotation so a red run is diagnosable without opening the log. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The first successful golden-path run failed on use_bioc_vignette(): usethis::use_package() calls check_installed() for every Suggests it adds, so BiocStyle, knitr, RefManageR, sessioninfo and testthat must be present, not merely declared. Anyone following the documented "install BiocCheck and biocthis" line hit the same error. Install line fixed in all three router files, and golden-path.R now preflights the full list. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Golden path found it: use_bioc_description() goes through usethis::write_over(), which will not replace an existing file without approval and declines silently when it cannot ask. The scaffolded package ended up with no biocViews and no error. This matters most for the audience this plugin targets. Someone with an existing package runs the documented command, sees nothing go wrong, and still has no biocViews - or approves and loses the DESCRIPTION they had. Documented in the three router files and in the conversion checklist: add biocViews by hand on an existing package. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
setup-bioc does not provide pandoc, and the vignette biocthis writes is R Markdown, so R CMD build died at "creating vignettes". Dropped the separate R CMD INSTALL step and the comment claiming build does not install - the build log shows it installs the package itself to build vignettes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
biocthis 1.23.0: the CITATION template substitutes {{Title}} but
use_bioc_citation() never passes a Title, so inst/CITATION lands with an
empty title. utils::citation() errors on that, the generated vignette
calls citation(), and R CMD build dies at "creating vignettes".
Following the documented chain therefore produced a package that could
not be built. Documented in the three router files; golden-path.R fills
the title in, which is what a user has to do anyway - the DOI in that
file is the literal string 10.1101/TODO - and warns if biocthis fixes it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The template substitutes {{github_owner}}, which is empty on any package
with no GitHub remote configured - so a new package always gets
as.person(""), and citation() errors on that the same way.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
BiocCheck ERRORs when the maintainer email is not registered on the support site, which a throwaway fixture with a usethis placeholder maintainer can never satisfy - so --no-check-bioc-help. Nothing else is disabled. Also added real testthat tests to the fixture. BiocCheck asked for them, the guide asks for them, and a fixture without them is not the package we tell people to submit. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
BiocCheck handleError: "Add biocViews other than Software" - the four top-level terms do not count on their own. The documented command said exactly that, so following it produced a package that fails BiocCheck. The block now asks for specific terms, and notes two more things a fresh scaffold trips: a Description that is "too concise", and the warning a Software package gets when it has no Bioconductor dependencies. The fixture now answers all three rather than suppressing them - real biocViews, a real Description, and a genuine SummarizedExperiment dependency, which is also the reuse rule this repo teaches. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Full chain now passes on Bioconductor devel: documented scaffolding, R CMD build, R CMD check, BiocCheck. Back to pull requests and the weekly cron rather than every push. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
"Crufty analysis code, make it submittable" is one step earlier than the conversion path assumed, and the advice diverges: for a package, scaffolding overwrites metadata you have; for scripts, scaffolding is the whole first move. workflow.md said "Do not scaffold from scratch" unconditionally, which was wrong for that half. - workflow.md: split the entry point on whether a DESCRIPTION exists, and give the scripts branch its own sequence - settle Software vs Workflow first, then scaffold, then kill load-time side effects, decide exports, relocate data - agent: with no DESCRIPTION anywhere, report a gap list rather than running every gate item against a non-package and calling it blockers - SKILL.md: description now covers scripts and messy analysis code - README + evals/trigger-scripts: one case, fixture is a ten-line script with setwd, rm(list=ls()), install.packages and 1:ncol Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.