Groundworkers Plugin Catalogue

The Groundworkers Plugin Catalogue is the release and compatibility index for the Groundworkers ecosystem. It describes the Groundworkers host, installable runtime plugins, prompt-pack distributions, and site-owned filesystem packs.

The canonical source is catalogue/plugins.yaml. The validation tool generates filtered indexes under dist/, and the refresh workflow maintains the status table in this README. This repository must remain private while its canonical source contains private plugin metadata.

Find a component

The table below is generated from the canonical catalogue. The status symbol is the latest recorded catalogue verification state. A GitHub Actions badge is included when the component declares a compatibility.yml workflow; badges are live and may change without this README being regenerated.

Component	Visibility	Kind	Target version	Groundworkers compatibility	CI status
Groundworkers	public	host	0.8.0	host	—
Groundskeeping	public	host	0.9.1	host	—
Groundstore	public	host	0.5.0	host	—
OHDSI Prompt Registry	public	runtime-plugin	0.5.0	>=0.7.1,<1.0
Phenotype Validate	private	runtime-plugin	0.1.0	>=0.7,<1	—
OMOP Concept Grounding	private	prompt-pack	0.1.0	>=0.7.1,<1.0
OMOP Phenotype Design	private	prompt-pack	0.1.0	>=0.7,<1	—
Comparator Recommender	private	runtime-plugin	0.1.0	>=0.7.1,<1.0
CQI Workers	private	runtime-plugin	0.1.0	>=0.7.1,<1.0
PBS Mapper	private	runtime-plugin	0.1.0	>=0.7.1,<1.0
eviQ Mapper	private	runtime-plugin	0.1.0	>=0.7.1,<1.0	—
Groundcrew Prompt Packs	private	filesystem-pack	Git revision	>=0.7.1,<1.0
OHDSI Onto-Bridge	private	runtime-plugin	0.1.0	>=0.7.1,<1.0
OHDSI UMLS Bridge	private	runtime-plugin	0.1.0	>=0.7.1,<1.0

The catalogue uses these component kinds:

Kind	Meaning	User action
host	The Groundworkers MCP host itself.	Install and configure Groundworkers.
runtime-plugin	An installed Python package discovered through the groundworkers.plugins entry-point group.	Install the package into the Groundworkers environment and configure it if required.
prompt-pack	A versioned Python distribution that contributes workflows to the OHDSI Prompt Registry.	Install the distribution alongside the registry.
filesystem-pack	A directory of prompt-pack content loaded from a configured filesystem path.	Obtain repository access, configure the pack root, and restart Groundworkers.

Install a public component

Use the installation command shown in the component's catalogue record. Public components install from PyPI:

uv add groundworkers==0.7.1
uv add ohdsi-prompt-registry==0.3.0

Install a private component

Private components are not on PyPI. Each v* tag publishes a GitHub Release, and the record's install field installs from that tag over SSH, so you need access to the component repository:

uv add "pbs-mapper @ git+ssh://git@github.com/AustralianCancerDataNetwork/pbs-mapper.git@v0.1.0"

Install the host and any desired components into the same environment. After installation, configure the component according to its own README, start Groundworkers, and use groundworkers --describe to confirm that the package was discovered and whether it is active.

Private components are not part of the public installation path. Their catalogue records are visible only to people with access to this repository and the corresponding source repository.

Understand compatibility status

The declared Groundworkers range describes what the component claims to support. The status symbol and workflow badge provide evidence about what has actually been tested. unverified means that no release-compatible result has been recorded; it does not mean that the component is known to be broken. Check the linked workflow for the exact component version, Groundworkers version, Python version, commit, and test result before adopting a planned or private component.

The catalogue describes what can be installed. Groundworkers entry-point discovery describes what is installed in one environment, and groundworkers --describe describes what is active and configured in that environment. The catalogue never downloads or executes a package automatically.

Publish or maintain a component

Add one record to catalogue/plugins.yaml for each published component. Keep the record focused on information a user or compatibility job needs:

• Use a stable, lower-case id that will not change when the display title changes.
• Set visibility to public only when the source and installation path can be disclosed to public users; use private for internal components.
• Classify the component as runtime-plugin, prompt-pack, or filesystem-pack. Use host only for Groundworkers itself.
• Record the source repository, distribution channel, released version, install command, capabilities, dependencies, and declared Groundworkers/Python ranges.
• Use distribution.channel: pypi for public components only. Private components use channel: git: each v* tag builds the wheel and sdist, publishes them as a GitHub Release (via the reusable private-release.yml in this repo), and installs with uv add "<name> @ git+ssh://git@github.com/<org>/<repo>.git@v<version>". The validator rejects pypi for private records.
• Set status: released only when users can obtain the stated version. Keep future work as planned.
• Leave verification.status as unverified until the required compatibility matrix has passed.

Every released runtime plugin or prompt-pack distribution should provide a compatibility.yml workflow that accepts the groundworkers-compatibility repository-dispatch event. The workflow contract and release gates are documented in docs/compatibility.md.

The catalogue's compatibility workflow dispatches requests to released components. The component repository owns the detailed test matrix and publishes the result through its normal GitHub Actions checks. First-party release automation should not publish a component until its required matrix is green.

For a public component, add the repository and package metadata to the canonical catalogue, add its compatibility workflow, enable its matrix, and regenerate the projections and README. For a private component, keep the source URL, installation details, and status in this private repository; the generated public index will exclude the record.

Current release set

The records target Groundworkers 0.7.1 and Python 3.12/3.13. Components marked planned have no release recorded yet: their ranges are declared, and their compatibility is shown by the live workflow badge.

Planned phenotype components

phenotype-validate is a private runtime plugin for Circe validation, rendering, SQL text generation, and structural shape classification. omop-phenotype-design is a content-only distribution providing the phenotype-design prompt pack through the OHDSI Prompt Registry.

The design pack requires registry 0.5.0 or newer. Its design/review workflow also needs the validator's phenotype_validate_validate, phenotype_validate_render, and phenotype_validate_shape tools, alongside Groundworkers concept and knowledge tools. The validator is a workflow requirement, not a Python dependency of the content pack.

Both entries target an initial 0.1.0 release; their tag-based installation commands are future release targets. The design repository is provisionally listed as private at AustralianCancerDataNetwork/omop-phenotype-design, pending creation or confirmation. Compatibility dispatch remains disabled for both until their repositories provide the required workflow.

Repository layout

catalogue/
  plugins.yaml              # canonical records, including private records
  schema/plugin.schema.json # versioned record contract
docs/
  compatibility.md          # developer and CI contract
scripts/
  validate_catalogue.py     # validate and generate filtered indexes
dist/
  public-index.json         # generated public projection
  private-index.json        # generated internal projection
  compatibility-matrix.json # generated CI dispatch matrix
.github/workflows/
  validate.yml              # validate source and generated files
  refresh-readme.yml        # regenerate and commit README/index changes
  compatibility-dispatch.yml# request component compatibility runs

Local development

uv sync --dev
uv run python scripts/validate_catalogue.py
uv run python scripts/validate_catalogue.py --write-readme
uv run python scripts/validate_catalogue.py --check-generated
uv run python scripts/validate_catalogue.py --check-readme
uv run python -m pytest -q -p no:cacheprovider

The generated files are deterministic. The validation workflow fails when a change leaves README.md or dist/ out of date, while the refresh workflow can regenerate and commit those views on main.