Rhiza Glossary¶

A comprehensive glossary of terms used in the Rhiza template system.

Core Concepts¶

rhiza (template repository)¶

The GitHub repository (jebel-quant/rhiza) that contains the curated set of configuration files, CI/CD workflow stubs, and other tooling files that downstream projects sync from. This is the content — the files you receive. See also: rhiza-claude, rhiza-task.

rhiza-claude¶

The Claude Code plugin marketplace providing the rhiza plugin — the slash commands that drive a managed repo: /rhiza:init, /rhiza:update, /rhiza:status, /rhiza:quality, /rhiza:docs, /rhiza:release, /rhiza:detach. It is the engine: it reads .rhiza/template.yml, fetches the selected bundles and three-way merges them into the working tree, recording what arrived in .rhiza/template.lock. Its scripts are stdlib-only Python, so nothing is installed beyond the plugin itself. Versioned independently from the template repository. See also: rhiza (template repository), Template Sync.

rhiza-cli (retired)¶

The former PyPI package that provided a rhiza command — init, sync, bump, release — invoked as uvx rhiza .... The package is unpublished and its repository is archived; the sync it performed now ships inside rhiza-claude. The separation of content from engine that ADR-0005 chose is unchanged — only the engine moved. Listed here because the name still appears in older documents and changelog entries.

Living Templates¶

A template approach where configuration files remain synchronized with an upstream source over time, as opposed to traditional "one-shot" template generators (like cookiecutter or copier) that generate files once and then disconnect from the source.

Template Sync¶

The process of pulling updates from the upstream Rhiza repository into a downstream project. Executed via the rhiza-claude /rhiza:update command. Allows projects to receive ongoing improvements without manual copying.

Downstream Project¶

A project that has adopted Rhiza templates. It receives updates from the upstream Rhiza repository through template sync.

Upstream Repository¶

The source Rhiza repository (jebel-quant/rhiza) that contains the canonical template configurations. Changes here propagate to downstream projects via sync.

Bundle Model¶

Bundle¶

The atomic unit of Rhiza adoption. A bundle owns a coherent set of synced files and may declare hard dependencies via requires and optional relationships via recommends. Any bundle can be selected on its own — its declared dependencies are resolved and installed automatically, including transitive ones. For example, selecting github-tests automatically installs tests, github, and core. Bundles are either feature bundles (local-first, no CI/CD workflows) or platform overlay bundles (prefixed github- or gitlab-, adding hosted workflow stubs). See also: Profile.

Profile¶

A named preset in .rhiza/template-bundles.yml that expands to a curated set of bundles for a common use case such as local, github-project, or gitlab-project. Declaring a profile is equivalent to selecting all its constituent bundles. Profiles are the recommended starting point; bundles give full manual control. See also: Bundle.

Overlay Bundle¶

A platform-specific bundle such as github-tests or gitlab-book that layers hosted CI/CD files on top of a feature bundle. Overlay bundles depend on both the feature they extend and the platform base bundle.

Stub Workflow¶

A thin injected workflow file that delegates to a reusable workflow in jebel-quant/rhiza. These stubs live in overlay bundles rather than in local-first feature bundles.

Bundle Dependency Map¶

Solid arrows show requires dependencies; dotted arrows show recommends relationships.

flowchart LR
    subgraph Foundation["Foundation"]
        core["core"]
        python_core["python-core"]
        rust_core["rust-core"]
        go_core["go-core"]
    end

    subgraph Local["Local-first bundles"]
        renovate["renovate"]
        legal["legal"]
        devcontainer["devcontainer"]
        vscode["vscode"]
        docker["docker"]
        lfs["lfs"]
        presentation["presentation"]
        paper["paper"]
        book["book"]
        tests["tests"]
        benchmarks["benchmarks"]
        marimo["marimo"]
    end

    subgraph GitHub["GitHub base and overlays"]
        github["github"]
        github_devcontainer["github-devcontainer"]
        github_docker["github-docker"]
        github_paper["github-paper"]
        github_tests["github-tests"]
        github_marimo["github-marimo"]
        github_book["github-book"]
        github_quality_review["github-quality-review"]
    end

    subgraph GitLab["GitLab base and overlays"]
        gitlab["gitlab"]
        gitlab_tests["gitlab-tests"]
        gitlab_marimo["gitlab-marimo"]
        gitlab_book["gitlab-book"]
        gitlab_quality_review["gitlab-quality-review"]
    end

    python_core --> core
    rust_core --> core
    go_core --> core
    github --> core
    gitlab --> core
    book --> core
    tests --> book
    tests --> core
    tests --> python_core
    benchmarks --> tests
    marimo --> book
    marimo --> core
    marimo --> python_core
    github_devcontainer --> devcontainer
    github_devcontainer --> github
    github_docker --> docker
    github_docker --> github
    github_paper --> paper
    github_paper --> github
    github_tests --> tests
    github_tests --> github
    github_marimo --> marimo
    github_marimo --> github
    github_book --> book
    github_book --> github
    github_quality_review --> core
    github_quality_review --> github
    gitlab_tests --> tests
    gitlab_tests --> gitlab
    gitlab_marimo --> marimo
    gitlab_marimo --> gitlab
    gitlab_book --> book
    gitlab_book --> gitlab
    gitlab_quality_review --> core
    gitlab_quality_review --> gitlab
    presentation -.-> marimo
    book -.-> tests
    book -.-> marimo

Directory Structure¶

.rhiza/¶

The core directory containing Rhiza's template system files. Synced from upstream, so its contents are overwritten by the next sync and should not be edited — with one exception: .rhiza/.env is repo-owned, read by rhiza-task as layer 2 of its settings order, and gitignored, so it holds developer-local values only.

rhiza-task¶

The pinned CLI that provides Rhiza's developer tasks — install, test, typecheck, book, view-prs and the rest. Provisioned per invocation by uvx, never synced. It replaced .rhiza/rhiza.mk and the sixteen fragments in .rhiza/make.d/, both of which are gone.

Makefile (the shim)¶

A template-owned file, shipped by the core bundle. It pins RHIZA_TASK, bootstraps uv on a runner that has none, and forwards every unmatched target to the CLI with a %: catch-all. Because it is synced, the pin travels with the template — a repo synced at a tag runs that tag's gates — and anything appended to the file is overwritten by the next update. Project-specific targets go in local.mk, which the shim -includes. It was repo-owned for one release, printed by uvx rhiza-task shim; that subcommand was removed in rhiza-task 1.0.0.

.rhiza/template.yml¶

The pointer: which template repository this project follows, at which ref, and which bundles or profiles it selects (plus any include/exclude patterns). Written by /rhiza:init, and the file Renovate bumps.

.rhiza/template.lock¶

The record: what a sync actually delivered — repository, ref, commit SHA, timestamp, strategy, and every managed file. The pointer and the record answer different questions and can disagree, which is why /rhiza:status reports both, and why /rhiza:update stages precisely the recorded file list rather than everything that changed.

local.mk¶

The project's own make targets, -included by the shim and never synced. Deliberately not gitignored: anything CI invokes has to be committed. This is where a repo's targets live now that the Makefile is template-owned.

Makefile System¶

Make Target¶

A named command reached through make (e.g., make test, make fmt). Rhiza provides 40+ of them out of the box, and nearly all are tasks of rhiza-task rather than rules in a file: the shim forwards every unmatched target to the pinned CLI.

Hook Targets (retired)¶

The synced make layer anchored pre-install:: / post-install:: and similar double-colon no-ops, so a project could chain work onto a template target without overriding it. The CLI knows nothing about make targets, so those hooks are gone. The replacement is to shadow the target: an explicit rule in local.mk beats the shim's %: catch-all, so an install: rule there can call uvx $(RHIZA_TASK) install and then the extra step.

make doctor¶

A diagnostic target that validates required tools, checks versions, and reports environment issues. Run this first when something is wrong with your setup.

Version Management¶

Version Bump¶

Incrementing the version number in pyproject.toml. Types: - major: Breaking changes (1.0.0 → 2.0.0) - minor: New features (1.0.0 → 1.1.0) - patch: Bug fixes (1.0.0 → 1.0.1)

Release Tag¶

A git tag prefixed with v (e.g., v1.2.3) that triggers the release workflow.

Version Matrix¶

A JSON array of Python versions to test against, generated from the Programming Language :: Python :: 3.x classifiers in pyproject.toml. In rhiza_ci.yml, adding or removing one of these classifiers automatically changes CI Python version coverage.

CI/CD¶

OIDC Publishing¶

OpenID Connect-based authentication for PyPI publishing. Uses GitHub's identity provider instead of stored API tokens. More secure than traditional token-based auth.

Trusted Publisher¶

A PyPI configuration that allows a specific GitHub repository/workflow to publish packages without API tokens, using OIDC authentication.

Matrix Testing¶

Running CI tests across multiple Python versions simultaneously. Rhiza supports Python 3.11, 3.12, 3.13, and 3.14.

SLSA Provenance¶

Supply-chain Levels for Software Artifacts. Cryptographic attestations proving that build artifacts were produced by a specific CI workflow. Enables supply chain verification.

SBOM (Software Bill of Materials)¶

A formal record of components used to build software. Generated in SPDX or CycloneDX formats for supply chain transparency.

Tools¶

uv¶

A fast Python package installer and resolver from Astral. Rhiza uses uv for all Python operations: - uv sync - Install dependencies - uv run - Execute Python code - uvx - Run external tools

Ruff¶

A fast Python linter and formatter from Astral. Replaces flake8, isort, black, and many other tools. Configured in ruff.toml.

Hatch¶

A Python build backend used to create distribution packages (wheels and sdists). Invoked via uv build.

Deptry¶

A tool that checks for unused and missing dependencies in Python projects. Integrated in CI via make deps.

Bandit¶

A security linter for Python code. Finds common security issues. Integrated in pre-commit and CI.

CodeQL¶

GitHub's semantic code analysis engine. Scans for security vulnerabilities in Python code and GitHub Actions workflows.

Marimo¶

A reactive Python notebook format. Rhiza includes support for marimo notebooks; the marimo bundle keeps them in docs/notebooks (the marimo-folder setting), inside the docs tree so the book can publish them.

Configuration Files¶

pyproject.toml¶

The central Python project configuration file (PEP 518/621). Contains project metadata, dependencies, and tool configurations. No bundle ships a pyproject.toml — the project owns it outright, and /rhiza:init creates it as part of the skeleton rather than a sync delivering it. What the python-core layer ships is a validator: pytest-rhiza's test_pyproject check, which the layer names in RHIZA_CHECKS and make rhiza-test runs. It requires a minimum structure — among other things: - [project] table with name, version, description, readme, and requires-python (all non-empty strings) - [dependency-groups] table with a test group that lists pytest

uv.lock¶

Lock file containing exact versions of all dependencies. Ensures reproducible builds across environments.

.python-version¶

Single-line file specifying the default Python version for the project. Used by uv and other tools.

ruff.toml¶

Configuration for the Ruff linter/formatter. Defines enabled rules, line length, and per-file exceptions.

pytest.ini¶

Configuration for pytest test runner. Sets logging levels and output options.

.pre-commit-config.yaml¶

Configuration for pre-commit hooks. Defines checks that run before each git commit.

.editorconfig¶

Cross-editor configuration for consistent coding style (indentation, line endings, etc.).

renovate.json¶

Configuration for Renovate, an automated dependency update bot.

Workflows¶

CI Workflow¶

Continuous Integration workflow that runs tests on every push and pull request.

Release Workflow¶

Multi-phase workflow triggered by version tags. Builds packages, creates GitHub releases, publishes to PyPI, optionally generates a conda recipe with grayskull, and can publish devcontainer images.

Sync Workflow (retired)¶

Syncing is no longer a CI job in either platform's bundle: /rhiza:update runs it from a developer's machine and opens the pull request, so nothing needs a write-scoped token on a schedule.

Security Workflow¶

Workflow running security scans (bandit, semgrep, CodeQL) on the codebase.

Commands Reference¶