Controlled-Variable State Machine Protocol (CVSM)

A state machine protocol for running controlled ML experiments with coding agents. You write the study spec: which variables differ between arms, which are held fixed, and which may adapt. Agents implement and run the study through GitHub issues and pull requests, one state at a time. Every run records its resolved config, and a script checks it against the spec and reports any difference the spec does not allow. You decide at four points: publish, merge, budget and conclude.

CVSM is a set of files you copy into a research repo, not a service. GitHub issues hold the state, and one rules file (AGENTS.md) plus four skills hold the procedure, for Claude Code and Codex alike.

中文 · Docs · Quick start

Every run is checked against the study spec

The spec states the arms, the settings held fixed (each with a reason), and what may adapt. It is the one layer you can truly read. Agents do the work below it, and CVSM checks every run against it from the run's own record, right after launch and in every results comment.

You adopt CVSM by copying its files into your repo

1. Copy the files into your repo:

   git -C <cvsm clone> archive HEAD \
     AGENTS.md .agents .claude .codex .github scripts tests \
     ':!.github/workflows/pages.yml' | tar -x -C <your repo>
   

2. Fill in the Project section of AGENTS.md, one line per field: layout, test command, language, protected paths, Run command and run records.

3. Push to main and run bash scripts/setup.sh as a repo admin. It sets the labels, squash-only merges and branch protection.

Then open Claude Code or Codex in the repo and say "let's plan this study". The adoption guide covers guard.toml, run.toml, CI and an optional machine account.

The docs cover each part in detail

• Start: Overview · Quick start · Talk, don't click
• Concepts: State · Gates and blockers · Review · Merging · Run records · Study spec · Principles
• Guides: Adopt · Plan a study · Run experiments · Adapt your environment · Claude Code and Codex
• Reference: AGENTS.md · Skills · Issue forms · guard · merge.py · run.py · results.py · Interfaces
• Project: Status · Built with CVSM · License
• Design notes (Chinese): docs/design/2026-10-16-harness-v1.md

CVSM v0.1.0 is a pre-release, and its interfaces may still change before 1.0.

License

Apache-2.0.