spotregen

Regenerative Software tooling, version 0.11.0

Chad Fowler’s Regenerative Software treats code as disposable and the system’s knowledge as the asset. A module is safely replaceable when it can be deleted and rebuilt from knowledge that lives outside its implementation, and when the rebuilt module is judged by an oracle that outlives the code. spotregen reads that knowledge from a tracked regen/ tree and checks it against the source tree.

What you get

A static check, spotregen check, that fails when the knowledge and the code disagree. It is deterministic and belongs in make guard.
Reports: status, deletion-test, context (the regeneration bundle), compact and new-unit.
Measures: measures (intent coverage and specification size) and mutate (mutation score: the evaluations run against planted mutants; slow, never part of make guard). See the tutorial.
Two drivers, spotregen claude and spotregen local, that regenerate a unit with an LLM. They are non-deterministic and never belong in make guard (see the drivers).
Zero runtime dependencies. The tool uses the standard library only and never imports the modules it describes; it reads source files with ast.

Install

uv add --dev spotregen          # a development dependency, pinned in uv.lock
uv run spotregen --help

Python 3.13 or later is required. python -m spotregen works as well.

A first check

make_sample_repo writes a minimal, consistent repository: a package samplepkg with two subpackages, one regenerable unit, one decision, one evaluation file and one documentation page. The same repository drives the test suite, the docstring examples and the tutorials.

import subprocess
import sys
import tempfile
from pathlib import Path

from spotregen import make_sample_repo

tmp = tempfile.TemporaryDirectory()
root = make_sample_repo(Path(tmp.name) / "demo")
print(sorted(str(p.relative_to(root)) for p in root.rglob("*") if p.is_file()))

['docs/guide.qmd', 'regen/architecture.toml', 'regen/decisions/why-add.toml', 'regen/units/core.calc.toml', 'src/samplepkg/__init__.py', 'src/samplepkg/app/__init__.py', 'src/samplepkg/app/main.py', 'src/samplepkg/core/__init__.py', 'src/samplepkg/core/calc.py', 'tests/test_regen_eval_calc.py']

Run the check in that repository, as you would on the command line:

def spotregen(*args):
    """Run `spotregen` in the sample repository and show the call and its output."""
    done = subprocess.run(
        [sys.executable, "-m", "spotregen", *args],
        cwd=root,
        capture_output=True,
        text=True,
        check=False,
    )
    print("$ spotregen", *args)
    print(done.stdout + done.stderr, end="")
    print(f"[exit {done.returncode}]")


spotregen("check")

$ spotregen check
regen check: 1 units, 0 errors, 0 warnings
[exit 0]

The summary line regen check: N units, E errors, W warnings is stable, and the exit code is 0 when no error was found (with --strict, when no warning was found either). Break something and the check says what and where:

(root / "scripts").mkdir()
(root / "scripts" / "use_it.py").write_text("from samplepkg.core import calc\n")
spotregen("check")

$ spotregen check
ERROR   DEL01   samplepkg.core.calc: scripts/use_it.py depends on the unit but is not a declared consumer
regen check: 1 units, 1 errors, 0 warnings
[exit 1]

A file outside the declared consumers depends on the unit (DEL01). The check tutorial walks through this; the schema page describes the regen/ files and lists every finding code.

Where to go next

you want to	read
write the `regen/` files	Schema and finding codes
learn the commands on a live repository	the tutorials
regenerate a unit with an LLM	Regeneration drivers
use the functions from Python	the API reference

Design

The package and its command line are recorded in ADR 0001. spotregen checks itself with its own static check: its regen/ tree is part of the repository.