Skip to content

Rhiza Quick Reference Card

A concise reference for common Rhiza operations.

Essential Commands

Command Description
make install Install dependencies and set up environment
make test Run pytest with coverage
make fmt Format and lint code with ruff
make doctor Validate required tools and versions (start here when something is wrong)
make help Show all available targets

Version & Release

Command Description
make workflow-status Show recent runs for the release workflow

Releasing is driven by the rhiza-claude /release command, which derives the next version, bumps pyproject.toml, regenerates CHANGELOG.md, and creates the git tag locally. Pushing that tag triggers the release workflow.

Code Quality

Command Description
make fmt Format + lint with auto-fix
make deps Check for unused/missing dependencies
make fmt Run all pre-commit hooks

Template Sync

Command Description
/rhiza:update Sync templates from upstream Rhiza (a rhiza-claude command, not a make target)
make rhiza-test Run the conformance checks over this repository 
repository: Jebel-Quant/rhiza
ref: v0.14.0

profiles:
  - github-project   # or: local, gitlab-project

.rhiza/template.yml — bundle-based (advanced)

repository: Jebel-Quant/rhiza
ref: v0.14.0

templates:
  - core
  - tests
  - github
  - github-tests

Running Tests

# All tests
make test

# Specific file
uv run pytest tests/path/to/test.py -v

# Specific test function
uv run pytest tests/path/to/test.py::test_name -v

# With output
uv run pytest -v -s

Directory Structure

Makefile              # synced from `core`: a shim forwarding to the pinned CLI
local.mk              # optional, committed: this repo's own make targets
pyproject.toml        # [tool.rhiza-task] settings live here
.rhiza/
├── template.yml      # Sync configuration
├── semgrep.yml       # Static-analysis rules
└── .env              # optional, gitignored: developer-local settings

Extending a Task

There are no hook targets. pre-install::/post-install:: belonged to the synced make layer; the CLI knows nothing about make targets. Shadow the task instead — an explicit rule beats the shim's %: catch-all:

install:
    @$(UVX) $(RHIZA_TASK) install
    @./scripts/fetch-fixtures.sh

That works for any task, runs in a defined order, and needs no anchor to have been declared in advance.

Key Files

File Purpose
pyproject.toml Project metadata, dependencies, version — must have [project] (name, version, description, readme, requires-python) and [dependency-groups]
uv.lock Locked dependency versions
.python-version Default Python version — single line, e.g. 3.13
.rhiza/template.yml Sync configuration (repository, ref, profiles/bundles)
ruff.toml Linter/formatter configuration
local.mk This repo's own make targets — -included by the Makefile, never synced, and committed (not gitignored)

Python Execution

Always use uv for Python operations:

uv run python script.py    # Run Python script
uv run pytest              # Run tests
uv build                   # Build distribution packages

Version Format

  • Source of truth: version field in pyproject.toml
  • Git tags: v prefix (e.g., v1.2.3)
  • Semantic versioning: MAJOR.MINOR.PATCH

CI Workflows

Workflow Trigger
CI Push, Pull Request
Release Tag v*
Security Schedule, Push
Weekly maintenance Schedule

Common Patterns

Add a custom make target

Add it to local.mk — the Makefile is template-owned, so anything appended there is overwritten by the next sync: 

my-target: ## My custom task
    @echo "Custom target"
The ## comment is what puts it in make help, under Repo-owned targets.

Extend a template task

Shadow it in local.mk (see Extending a Task above) — there are no hook targets: 

install: $(UVX)
    @$(UVX) $(RHIZA_TASK) install
    @echo "Additional setup after install"

Change a setting

# pyproject.toml
[tool.rhiza-task]
coverage-fail-under = 80
Or RHIZA_COVERAGE_FAIL_UNDER=80 make test for one run; uvx rhiza-task print coverage-fail-under shows what currently resolves.

Skip CI on commit

git commit -m "docs: update readme [skip ci]"