Headless control of software instruments from Python: the contracts, host and CLI that
patchbay-<instrument> adapters plug into.
This is an experiment, not a product. The distribution name is patchbay-core and the import
name is patchbay. Nothing synth-specific lives here; core grows only when a second adapter needs
the same thing (agent-os/product/mission.md).
-
src/patchbay/: the package, src layout, typed (py.typed).contracts.py: theInstrumentprotocol every adapter implements, and theSubscriberits events reach.models.py: the frozen, strict pydantic models that cross a boundary (Quantity,Parameter,Patch,Pattern,RenderRequest,RenderResultand the rest), all built onPatchbayModel, which takes data in JSON's form (asjson.loads, YAML or TOML give it) throughfrom_json_data.RenderRequest.samplesis the one count of a render's samples.events.py: the events (ParameterChanged,PatchLoaded,RenderCompleted) and the synchronous, in-processEventBus, whosesubscribereturns aSubscriptionthatcancel()ends.errors.py:PatchbayErrorand the errors under it; no built-in exception leaves a public method.testing/: what an adapter's tests use:CONTRACT_TESTS, thirteen contract tests named without atest_prefix, so pytest never collects one an adapter imports; the referenceFakeInstrument; andRecordingSubscriber.
__init__.pyre-exports the first four, and__version__, read from the installed package's metadata sopyproject.tomlis the one place the version is written. The package is imported installed (uv sync): from a baresrc/onsys.paththe import fails rather than invent a version. The runtime dependencies are pydantic, numpy and pydantic-core, which pydantic brings and which is declared sinceerrors.pyimports it, each a range in[project] dependencies. -
tests/: pytest's tree,unit/for now, mirroringsrc/one test module per source module;unit/testing/conftest.pyholds thebusandinstrumentfixtures an adapter's ownconftest.pycopies to run the contract tests. Not a package (no__init__.py), so one basename per test file across it, which mypy holds. -
pyproject.toml: the one configuration file. Every tool the gate runs is configured under[tool.*]there and nowhere else, with nosetup.py,setup.cfg,requirements*.txt,tox.ini,.flake8,mypy.ini,pytest.inior.ruff.toml. The[tool.*]sections (the rule set, and[tool.uv], which pins uv itself) and the dev group's pins of the tools the gate runs (ruff, mypy and pytest), with whatuv.lockresolves for them, are the gate's and change only in the gate's own spec;[project],[build-system]and the dev group's other entries (hypothesis and pre-commit) are the package's.uv.lockis the resolution of the pins. The wheel carriesLICENSE(license-files). -
.pre-commit-config.yaml: hook registration only, the one file pre-commit cannot do without; it configures no tool. -
scripts/:gate.sh(the verification gate),gate-negative-tests.sh(the tests that prove each gate step can fail, not run by the gate) andsync-standards.sh(installed and replaced by the standards sync, never hand-edited). -
agent-os/product/:mission.mdandtech-stack.md, the decisions the specs implement. -
agent-os/standards/:base/, the base standards synced frompatchbay-standardsand pinned to the commit inbase/.version, read-only here;index.yml, whosebase:section is the sync's and whose other sections are this repository's own. -
agent-os/specs/: one folder per spec, with its plan, shaping notes, the standards as they read when it was shaped, andverification/holding the gate transcripts. -
.claude/commands/agent-os/: the Agent OS commands;shape-spec.mdis customized for this repository's gate, the rest are stock. -
.github/workflows/gate.yml: CI, which runs the gate and nothing else. -
CLAUDE.md: the rules for an agent working here, ownership first.
uv syncuv is the one tool this repository assumes, at 0.13.7: pyproject.toml's [tool.uv] required-version pins it, so any other uv refuses every command that reads this project's
settings (uv sync and uv run among them), and CI's setup-uv reads the same key to install it.
uv sync reads .python-version (3.12), fetches that interpreter into uv's cache if it is not
there, creates .venv/ and installs into it the package with its dependencies, pydantic,
pydantic-core and numpy, and the locked dev toolchain: ruff, mypy, pytest, hypothesis and
pre-commit, each pinned exactly in pyproject.toml's [dependency-groups] dev with the date it
was published. uv.lock resolves both. Nothing is installed outside the repository.
Run a tool as uv run --locked <tool>, as the gate does.
scripts/gate.shSix runnable steps, in order, stopping at the first failure (exit 1; exit 2 on usage or when the script cannot enter the repository root):
bash -non every shell script underscripts/as git lists them, tracked or untracked and not ignored, at a work-tree top that is the repository root; a tracked file a step reads that a.gitignoreignores, a file there that is neither.shnor bash-shebanged, a listed path missing from the disk, a symlink to nothing and a listing git cannot make (a corrupt index) each fail the step by name.uv sync --locked, thenuv run --locked ruff format --checkover the.pyand.pyifiles git lists: the locked toolchain syncs, and every file is formatted as ruff format writes it.uv run --locked ruff checkover the same files: no violation of[tool.ruff.lint], which selects every rule and ignores only what this tree proved wrong, each with its reason.uv run --locked mypyover the.pyand.pyifiles git lists undersrc/andtests/: no type error understrict.uv run --locked pytest: every test undertests/passes, once no.pyfile there, and noconftest.pyat the root, is one git ignores.scripts/sync-standards.sh --check:agent-os/standards/base/, thebase:section ofagent-os/standards/index.ymland the sync script itself are byte-identical topatchbay-standardsat the pinned commit.
Step 2 opens with uv sync --locked, which installs exactly what uv.lock names and fails the step
as the sync, before any tool runs, when a pin was edited in pyproject.toml without uv lock (the
lockfile is never rewritten), when uv cannot read either file or build the package from them, or
when the running uv is not the required one; so the gate writes nothing but the ignored .venv/ and
caches. A uv.toml at the root fails the step by name before uv runs, since uv would read it ahead of
[tool.uv]. Steps 2 to 5 then run each tool under --locked, the one uv.lock names, told by flag
to read pyproject.toml alone, so a ruff.toml, mypy.ini or pytest.ini beside it, tracked or
not, cannot replace the rule set, and read only the files git lists: ruff and mypy are given git's list itself, so git alone decides what is
ignored; pytest, which loads the conftest.py of
every directory it collects from, walks tests/ only once nothing it would read is ignored, and
reads no .txt (-p no:doctest). Step 6 reads the sibling checkout at ../patchbay-standards, so
clone patchbay-standards beside this repository first; CI checks it out there at the pinned
commit, installs uv with astral-sh/setup-uv at the version [tool.uv] required-version pins,
runs uv sync --locked and then the script. Three
judgment steps follow the script and are recorded in each spec's shape.md: Docs, Version and the
standards retrospective. The rule is agent-os/standards/base/process/verification-gate.md.
scripts/gate-negative-tests.sh runs each failure case on a scratch copy (all adds the CI
replay); its transcripts live in the spec that last changed a gate file.
uv run --locked pre-commit install # once, to run the hooks on every commit
uv run --locked pre-commit run --all-files # the hooks over the tree, with or without the git hookThe hooks are ruff check --fix and ruff format, run through uv run --locked, so they are the
gate's ruff with the gate's rules; never mypy or pytest, which are the gate's. The hook is a
convenience for the person committing; scripts/gate.sh is the check.
scripts/sync-standards.sh # move the pin to patchbay-standards' origin/main
scripts/sync-standards.sh --check # the drift check, as the gate runs it
scripts/sync-standards.sh --index-only # regenerate the base: section of index.yml aloneThe pin is the commit in agent-os/standards/base/.version. A sync forward is its own change
set, titled chore: sync base standards to <sha>. No file under base/ and no base: entry is
edited here: a change to a base standard is proposed in a spec's retrospective, presented to the
owner, and filed as an issue on patchbay-standards, whose own spec lands it as a pull request.
The rule is agent-os/standards/base/process/standards-sync.md.
Work is shaped with /agent-os:shape-spec in plan mode and ends with the gate. CLAUDE.md
holds the rules an agent follows here, ## Ownership first: a person owns every commit, pull
request and merge.