assay

README

Assay

Assay is a methodology for running software delivery across a fleet of AI agents, with machine-checkable gates so you can tell what actually happened.

assay.guide · Video walkthroughs

Run engineering as a system

A governed operating model for agent-led engineering — an agent-operated delivery pipeline with a human-governance layer.

Read the Assay vision report for the direction from governed delivery to cells, continuing operations, quality, assurance and bounded machine judgment. The report distinguishes current foundations from unfinished integration and future work, and includes an evidence appendix and a designed PDF.

Overview

When agents do the work, generating code is the easy part; knowing whether it was done correctly is not. Assay makes each unit of work a self-contained, checkable artifact, and derives the project's status board from those artifacts rather than from a human's assertion.

It has four parts:

• Briefs. A self-contained unit of scope and definition-of-done, with typed dependencies, a risk-derived review gate, and a Verify table that can actually be run. One brief is one reviewable piece of work. See docs/brief-template.md and docs/brief-rules.md.
• Registers. Append-only FINDINGS, INTAKE, and RETRO logs. Entry IDs are slugs, not a counter, so they carry no contiguity guarantee — there is no sequence to have a gap in. What keeps nothing going missing quietly is what statusgen actually enforces: an entry that has ever existed on main but is absent from the working tree is a lint failure (a tombstone check against history), and duplicate IDs are rejected. Entries are tombstoned rather than deleted.
• Streams and the board. Briefs live in streams and move through a defined lifecycle. The board, STATUS.md, is generated, never hand-edited.
• Tools that enforce the above. statusgen lints the tree and generates the board. A separate reviewer identity, which the author cannot post as, keeps reviews attributable to someone other than the author. A trust gate names who the tooling will obey.

The board is derived from agent-authored artifacts, checked by the linter and re-verified independently. It is not measured from ground truth, and Assay does not claim it is. The aim is not a green dashboard but a set of gates that make a passing state hard to fake and easy to catch when the artifacts and the checks disagree.

Contents

Path	What it is
docs/vision/	The public strategic vision, GitHub-rendered diagrams and matching PDF.
docs/	The methodology: the adoption runbook, the brief schema (rules, template), the lifecycle, the registers, the evidence bundle, and the telemetry posture (opt-in, off by default).
statusgen/	The generator and linter. Run cd statusgen && go run . --root ../examples/adopter-scaffold --lint.
plugins/assay/	The Assay plugin for Claude Code: methodology skills for adopting Assay, shaping specifications and authoring briefs (adopt, author-spec, author-brief).
examples/adopter-scaffold/	A populated streams and registers tree to copy from.
tools/freshness/	Freshness checks for tracked artifacts.
tools/desk/	The desk tooling, a Go submodule (github.com/medici-finance/assay/tools/desk). Importing one of its packages from another module? See how to pin it — a bare repo tag does not resolve.
Dockerfile	Builds one combined Linux image with the desk-tools suite + statusgen on PATH, published to GHCR. See docs/docker.md.

Building and generated Cursor files

make build-all compiles every tracked Go module and emits every desk executable under tools/desk/dist/. On Windows, use pwsh -File scripts/build-windows.ps1 build-all; the target discovers the same tracked go.mod files. Neither target installs tools.

This repository consumes its canonical plugins/assay through generated .cursor skills, references, rules, and the bounded AGENTS.md bindings. After changing the canonical bundle, run from tools/desk:

go run ./cmd/deskinstall --harness cursor --bundle ../../plugins/assay --repo ../.. --forge github
go run ./cmd/deskinstall --harness cursor --bundle ../../plugins/assay --repo ../.. --forge github --check

Run the relevant tools/harnessgen generator first when changing its canonical inputs. CI checks the committed Cursor tree without regenerating it, and runs harnessgen tests on a fresh Windows checkout with explicit LF attributes. Release stamping refreshes the derived placement after canonical version stamps. Canonical component.yaml declarations are excluded from runtime skill copies; they retain one component owner in the source tree. See the Cursor install/upgrade contract.

Container image

The desk-tools suite and statusgen are published together as a combined Linux image at ghcr.io/medici-finance/assay/desk-tools (linux/amd64). Native macOS/Windows binaries are a separate artifact. See docs/docker.md for how to pull, run, and what's inside.

Adopting Assay

The install guide is docs/adopting-assay.md. It reads as a runbook for a coding agent to follow step by step, and covers three cases: a green-field repo, an existing suite of repos, and carving a unit out of a larger project.

Some steps are deliberately human-gated and never run autonomously: creating the reviewer GitHub App, choosing the trust-roster values, granting repo admin, and merging to main. Agents open draft PRs; a human reviews and merges.

Links

• Site and guide: assay.guide
• Video walkthroughs: YouTube playlist

License

Apache 2.0; see LICENSE and NOTICE. Before contributing, read CONTRIBUTING.md and CODE_OF_CONDUCT.md; report security issues per SECURITY.md.