Agenda

1. The Repo Zoo Problem — what goes wrong at scale and why it's structural
2. Why existing tools fall short — the Day 0 / Day 365 gap
3. How Rhiza works — config, bundles, the sync loop, and Renovate
4. Getting started — setup and the two bootstrap PRs
5. Living with Rhiza — sync PRs, customisation, and conflict resolution
6. The ecosystem — rhiza-claude, rhiza-hooks, and companion projects
7. Adoption — migrating existing repos and rolling out across a team

How every team starts

A new project? Run the generator.

cookiecutter gh:my-org/python-template

✓ CI workflow — wired up
✓ Makefile — ready
✓ Linting config — configured
✓ Test harness — set

Day 0 is great. Everything is consistent.

Then time passes.

The backtesting repo got a pre-commit hook the risk model never received.

The data pipeline still pins Python 3.9 — EOL since October 2024.

Three repos use Black. Two use Ruff. One uses both.

The reporting dashboard references a GitHub Actions runner deprecated eight months ago.

Nobody did this on purpose. It just happens.

Each repo drifted into a different breed — incompatible with the others, living in its own enclosure, expensive to maintain on its own terms.

The real cost

Every change made to one repo is a change not made to the others.

CVE in a GitHub Actions runner
You need to update 17 repos. You do 12, get distracted. Five months later, five are still vulnerable.

Python 3.9 reaches end-of-life
You update the active repos. The legacy repos drift on, unpatched.

Team decides to standardise on Ruff
Active repos updated. Legacy repos still run Black. "Our standard" is now a fiction.

The hidden tax

The problem is not just drift — it is the ongoing cost of managing inconsistency.

Every shared infrastructure decision multiplies by your repo count.

At 20 repos, a 15-minute task becomes an afternoon. At 50, it becomes a week.

The coordination problem

Who owns shared infrastructure?

• DevOps pushes a new CI standard → who updates the 30 repos?
• Security mandates a new linting rule → how does it reach everyone?
• A CVE appears in a GitHub Actions dependency → who's responsible?

There is no clean answer without a system. Everyone assumes someone else is handling it.

The classic response — write a runbook, send a team email — doesn't scale.
Documentation tells people what to do. Rhiza opens a pull request.

The tools we reach for

The Day 0 / Day 365 gap

All of these tools were designed to solve the Day 0 problem:

Getting a new project off the ground with sensible defaults.

None were designed for the Day 365 problem:

Keeping twenty existing projects aligned as shared infrastructure evolves.

Template systems treat configuration as something you set up once.
But configuration is not a one-time decision — it is ongoing infrastructure.

The insight

Born from experience at a large sovereign wealth fund: dozens of Python repos, multiple teams, no mechanism to stay aligned. The problem was not carelessness — it was structural. One-shot scaffolding produces drift by design.

Treat the update as a pull request, not a push.

Instead of forcing changes into downstream repos, Rhiza opens a PR in each one:

• Clean diff of what changed in the template
• Owner reviews, adapts if necessary, merges
• Opt-in per repo — systematic across the organisation

The sync is not a bulldozer. It is a proposal.

Three actors

The config file: .rhiza/template.yml

repository: Jebel-Quant/rhiza   # Which template repo to sync from
ref: v1.7.1                      # Which version (pinned tag — recommended)
language: python                 # Which language layer (python / rust / go)

profiles:                         # Curated bundle preset (recommended)
  - github-project

exclude: |                        # Files you own locally — never overwritten
  SECURITY.md
  .github/CONFIG.md

One file, under version control. That's all Rhiza needs.

Your org's fork

The canonical template is Jebel-Quant/rhiza. For most teams the right setup is:

1. Fork Jebel-Quant/rhiza into your organisation
2. Customise — add your org's runners, secrets, standards
3. Point all projects at your-org/rhiza in template.yml
4. Pull upstream when you're ready — nothing flows through without your review

Bundles — named groups of files

Feature bundles (local tooling, no CI/CD):

core defines no install and no all — a language layer (python-core, rust-core, go-core) supplies them. Pick exactly one.

26 bundles in v1.7.1. tests, marimo and paper are not among them any more — their config folded into python-core, book and github-paper.

Platform overlay bundles layer CI/CD on top: github-tests, github-book, gitlab-tests, etc.

Profiles (github-project, gitlab-project, local, rust-local, go-local) expand to a sensible combination. Start here.

What's in the github + github-tests bundles

The github overlay provides the base platform wiring:

The github-tests overlay adds testing CI on top:

Other bundles layer in more workflows — benchmarks, a weekly dependency/link check, a LaTeX paper build, and an advisory quality review. Mutation testing and fuzzing were retired in v1.5.0. There is no sync workflow: template changes are applied by running /rhiza:update.

The sync loop

1. Fetch — reads template.yml, pulls matching files from the template repo at ref
2. Diff — compares what was fetched against what's currently in your project
3. Review — if anything changed, opens a pull request with the diff (scoring is /rhiza:quality)
4. Commit — you review the PR and merge it (or close it if not relevant)

Run it on demand with /rhiza:update in Claude Code — it bumps the ref, syncs the files, resolves conflicts, runs the quality gates, and opens the PR.

Renovate — closing the loop

Without Renovate, the ref: pin is frozen. Projects drift behind the template silently.

Two separate steps: should we upgrade? (the ref-bump PR) then here's what changed (the /rhiza:update PR).

The ref: pin in depth

ref: v1.7.1   # pinned tag — recommended for all production repos
ref: main     # tracks latest commit — useful during template development only

Pinning to a tag gives you:

• A known, auditable version — you can see exactly what each project is running
• Safe upgrades — Renovate proposes the bump, you review before it lands
• Easy rollback — if v1.7.1 breaks something, the cause is unambiguous

Tracking main delivers template changes immediately with no review step. Use only when actively developing the template. Never in repos others depend on.

Four commands

# 1. Install uv (skip if already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Make the repo rhiza-managed — writes .rhiza/template.yml, opens PR #1
/rhiza:init

# 3. After #1 merges: sync the template — this is where the files arrive (PR #2)
/rhiza:update

# 4. Install dev environment
uv run rhiza-task install     # or: make install

The /rhiza:* commands come from the rhiza Claude Code plugin — install it once with
/plugin marketplace add Jebel-Quant/rhiza-claude then /plugin install rhiza@rhiza-claude.

That's it. Your project is now Rhiza-managed.

What /rhiza:init asks

Running /rhiza:init walks you through a few questions:

? Host and repo (GitHub or GitLab, owner/name):  Jebel-Quant/rhiza
? Language (python / rust / go):                  python
? Template repo:                                  Jebel-Quant/rhiza
? Template ref (tag, branch, or commit):          v1.7.1

The template defaults to Jebel-Quant/rhiza for all three languages — it is multi-language, layering python-core, rust-core or go-core on a neutral core. Name any other owner/repo — a fork, or your own house template — and it is checked for reachability, and for whether it actually defines the profile, before being pinned.

The profile follows from the platform and language, so it is not asked. The result is .rhiza/template.yml — one file, under version control, that describes everything Rhiza will manage in this project.

/rhiza:init opens a PR on a rhiza_init_<date> branch. It syncs nothing: no CI, no Makefile, no gates. Merge it, then run /rhiza:update for the content.

What you get on day one

After syncing with the github-project profile (core + python-core + github + book and their GitHub overlays):

.github/workflows/rhiza_ci.yml          ← CI: test matrix on push and PRs
.github/workflows/rhiza_release.yml     ← Build + publish to PyPI on a tag
.pre-commit-config.yaml                 ← Local commit hooks (rhiza-hooks, run by prek)
ruff.toml                               ← Linting config
Makefile                                ← 71-line shim: pins RHIZA_TASK, forwards to it
.python-version                         ← Pinned Python version
.editorconfig                           ← Editor consistency

Config files, all of them — no .rhiza/rhiza.mk, no make.d/, no .rhiza/tests/.
The tasks come from rhiza-task, the checks from pytest-rhiza, both via uvx at the pinned version.

The one manual step — PAT_TOKEN

Rhiza's automation (Renovate, releases) opens pull requests. GitHub requires a Personal Access Token for PRs that touch .github/workflows/ files.

Create a fine-grained token:

GitHub → Settings → Developer settings → Personal access tokens (fine-grained)

Required permissions: contents: write, pull-requests: write, workflows: write

Add it as PAT_TOKEN in your repository secrets — or as an org secret to cover all repos at once.

Without PAT_TOKEN, automation falls back to GITHUB_TOKEN, which cannot write workflow files. PRs that touch workflow files will silently fail to open.

PyPI publishing — OIDC Trusted Publishing

The release workflow publishes to PyPI without a stored token, using OpenID Connect:

permissions:
  id-token: write   # required for OIDC — no PYPI_TOKEN needed

On PyPI: Publishing → Trusted Publishers → Add
Specify the repo name, workflow filename, and environment name. PyPI issues a short-lived credential at publish time.

Benefits:

• No token to rotate or accidentally expose
• Publish permission is tied to the specific workflow, not a person
• Revocation is instant — remove the trusted publisher on PyPI

Reading a sync PR

A sync PR is a standard git diff of template files that changed.

Green (added) — new template content your project doesn't have yet.
Usually safe to accept.

Red (removed) — content removed from the template.
Check whether anything you depend on is being removed.

Changed — read carefully. Could be a workflow version bump, a lint rule adjustment, or a security fix.

The PR description explains what changed at a high level. If Renovate bumped the ref, check the template repo's release notes for the version you're upgrading to.

Accept, modify, or reject?

Accept as-is — CI workflow updates, runner version bumps, linting adjustments that apply cleanly and tests pass.

Modify before merging — the change applies but needs a small tweak for your project. Or: add a file to exclude: in template.yml before merging.

Close without merging — the change isn't relevant (e.g. Docker support in a project that won't use containers).

Closing is fine. The next sync will re-open the PR
if the template still differs from your project.

Customising safely

Never edit template-managed files directly. Since v1.5.0 check-managed-files
refuses the commit — so you find out now, not in the next sync PR.

(custom-task.mk and custom-env.mk retired with the make layer in v1.4.0.)

Handling conflicts

A sync PR conflicts when you have edited a template-managed file locally.

Option 1 — Accept the template version
Discard your local change. Clean, but you lose your customisation.

Option 2 — Keep your version and exclude
Add the file to exclude: in template.yml, resolve the conflict in your favour. You now own that file permanently.

Option 3 — Merge both changes manually
Take what's useful from the template update and your local edit. Most effort, cleanest long-term result.

If you find yourself regularly in option 2 or 3 for the same file, that file belongs in exclude:.

The exclude list in practice

exclude: |
  SECURITY.md                          # claims about THIS repo's posture — ours to make
  .github/workflows/rhiza_ci.yml       # we use a custom test matrix
  .github/rulesets/tag-protection.json # our required checks, not the template's

Excluding a file does not delete it: an excluded path is never treated as an orphan, so your version stays and simply stops being overwritten.

Exclude deliberately, not defensively.

Every excluded file is a file you are now responsible for — including applying security fixes the template would otherwise deliver automatically.

Audit your exclude list when bumping the template version. Ask: "Does the new template version of this file contain anything I should merge in manually?"

rhiza-task — the tasks left the template

Up to v1.3.x, core synced .rhiza/rhiza.mk + a make.d/ fragment per bundle — ~1,500 lines of make, copied into every consumer.

Because make cannot include a remote file:

• "You are on v1.3.3" meant "copied at v1.3.3, and nobody checked since"
• A bug in a gate was found, fixed, released and re-synced per repo
• The recipes were shell — make -n proves the text of a command, never its flags

v1.4.0: the tasks are a pinned package, rhiza-task, fetched by uvx per invocation.

uv run rhiza-task test        # the documented interface
make test                     # the shim core still ships — same code

RHIZA_TASK lives in the synced Makefile, so the version travels with the sync.
Same move for the checks: .rhiza/tests/ → pytest-rhiza (v1.3.4).

A template distributes configuration. A package manager distributes code. — ADR-0011

rhiza-hooks — the commit checks

rhiza-hooks ships hooks that catch config errors before they reach CI:

Runs on every git commit, through prek — a faster drop-in for pre-commit reading the same config.

Releasing — /rhiza:release

/rhiza:release prepares a release straight from your conventional-commit history — in two phases:

Why two phases? A squash-merge replaces the branch's commits, so a tag cut before the merge names a SHA that never lands. The pushed tag triggers rhiza_release.yml, which builds and publishes.

The old version-matrix and coverage-badge helpers are no longer user commands — that logic now lives inside the reusable CI workflows (rhiza_ci.yml derives the test matrix from requires-python; the coverage badge is generated during CI).

The Rhiza ecosystem

Who's using it

The Rhiza tools themselves — rhiza and rhiza-hooks sync from the template; rhiza-claude and rhiza-task run its gates through the pinned CLI without being synced by it. The system eats its own cooking.

External projects:

Three of the four have converged on profile + a short list of extras.

GitLab support

Rhiza works on GitLab with the gitlab bundle replacing github:

templates:
  - core
  - python-core
  - gitlab     # instead of github
  - tests
  - renovate

What changes: CI workflows become .gitlab-ci.yml pipeline files. Renovate opens merge requests. PAT_TOKEN → GitLab Personal Access Token with api scope.

What doesn't change: template.yml, renovate.json, the tooling (rhiza-claude, rhiza-hooks), and how you sync — you still run /rhiza:update in Claude Code.

Starting fresh vs. migrating

New project — the easy case:

/rhiza:init      # config + skeleton, PR #1
/rhiza:update    # after #1 merges: the template content, PR #2
make install     # → uvx rhiza-task install

Done. Rhiza-managed from day one.

Existing project:

/rhiza:init      # detects the existing repo from its origin and asks
                 # nothing; opens PR #1 on rhiza_init_<date>
/rhiza:update    # the first sync — this is the PR that needs review

PR #1 is nearly empty on an existing repo. The sync in PR #2 is where the diff appears: some files may already match, others may have local customisations — preserve those via exclude: in template.yml before merging.

The migration path

1. Audit your current setup — list your CI files, linting configs, and Makefiles
2. Start conservative — begin with core plus a language layer; add github once you've reviewed the workflow files
3. Move your own targets to local.mk — the root Makefile is template-owned and gets overwritten
4. Exclude what you own — add locally-maintained files to exclude: before syncing
5. Review the first sync PR carefully — that is PR #2, from /rhiza:update; treat it as a code review, not a forced update
6. Add Renovate — add the renovate bundle and install the GitHub App
7. Expand bundles gradually — add book, docker, benchmarks as your team gains confidence

Don't try to adopt everything at once. The goal of the first PR is to get Rhiza in place with minimal disruption.

Rolling out across a team

Week 1 — Pick one low-risk repo as your pilot. Adopt Rhiza, run a sync cycle, review the process with the team.

Weeks 2–3 — Add Rhiza to active projects. Fork the template into your org if you need custom standards.

Month 2 — Add Renovate org-wide. Enable the Dependency Dashboard. Review the first round of version-bump PRs together.

Ongoing — New projects start with /rhiza:init. Legacy repos migrate at their next maintenance window.

Governance — One person or platform team owns the org's template fork. Changes go through PRs on the fork — reviewed before they propagate to all subscriber repos.

Key takeaways

1. Drift is structural — it is the default outcome of one-shot scaffolding, not a failure of discipline.

2. Existing template tools solve Day 0. Rhiza solves Day 365.

3. The PR model is the key insight. Systematic coverage, opt-in per repo, auditable history.

4. Setup is four commands. Ongoing maintenance is reviewing a weekly PR.

5. You stay in control. exclude:, local.mk, [tool.rhiza-task] and org forks give full flexibility.

6. Renovate closes the loop. Without it, the ref: pin is frozen and drift returns.

7. Adoption is gradual. One repo at a time, one bundle at a time.