Beryl

An installable set of repository files and scripts that tell coding agents how to work in a project and check that some of those rules were actually followed.

Status: active · developer tooling
Role: Author and maintainer. I designed and wrote Beryl; this site's repository uses it.
Stack: agentic-coding, developer-tools, testing, code-review
Repository: Source code
Dates: Updated 2026-09-30

Write-up

Problem

Instruction files such as AGENTS.md can guide an agent, but they give no evidence that the rules were followed, and different tools read different files.

What I built

Beryl installs one canonical instruction set with task routing and project context, plus deterministic shell checks (Markdown sanity, secret scanning, test-manifest immutability, project tests) that run locally and in optional Git hooks.

Evidence

Output

$ printf '\n// weakened\n' >> tests/update-topic-subtitle.test.js
$ ./.beryl/scripts/check-tests-unchanged.sh
ERROR: check-tests: configured test scope differs from tests/.manifest.sha256. If intentional, run .beryl/scripts/update-test-manifest.sh and commit the updated manifest.

Real check output from this site's repository: a test file was edited without updating the test manifest, and the Beryl gate refused it.

One hard decision

Checks are plain shell scripts over files in the repository rather than a hosted service or agent plugin, so any agent, CI runner, or reviewer can run the same gate and read its output.

Where it stands

Used in this repository, where the check gate runs before every change; a benchmark of whether machine-readable policies improve agent outcomes is in progress as CP3106 independent research and has no results yet.

Limits

The checks detect changes; they do not prove an agent's change is correct, and anyone with write access can update the manifest. Beryl still depends on human review and branch protection.