Start with one feature.
Agree on what the app should do. Keep its behaviour, interfaces, examples and checks together in your repository.
Install the preview
The development preview is available on npm. Requires Node 22 or newer. From your application's directory:
npm install -D mhproto@next
npx mhproto init --agent codex
npx mhproto view
Version 0.8.0-preview.0. Install with @next to follow the preview channel.
init creates a draft feature and installs five repository-local skills. Use
--agent claude or --agent all for the other supported installation
layouts. It refuses to overwrite an existing contract.
Adopt an existing feature
Ask your coding agent to use mhproto-discover to map one feature from its
existing product docs, requests, responses and tests. Reuse the app’s authoritative schema
or generator. Review the draft in the viewer before implementation.
The viewer connects feature pages, endpoints and type definitions. Nested types expand inline. Each named type links back to its consuming endpoints and parent types. Screenshots and design references attach to descriptions and request/response headers.
Agree, review, verify
| Skill | Purpose |
|---|---|
mhproto-discover |
Map an existing feature from its sources. |
mhproto-specify |
Agree on behaviour, interfaces and representative examples. |
mhproto-implement |
Implement the agreed contract. |
mhproto-verify |
Link meaningful app checks to rules and examples. |
mhproto-reconcile |
Resolve drift between the contract and implementation. |
Review an iteration
Open Changes. Choose an earlier snapshot or exported preview, or use the current spec as a baseline before editing. Open an added, changed or removed item for its Before/Now values. Follow its current-page link to inspect highlighted fields in context.
npx mhproto snapshot --label "Before this change" # Edit the source contract. npx mhproto diff npx mhproto check npx mhproto verify --capability daily
Passing, failing, unchecked and stale evidence remain distinct. A passing check records what its linked tests observed; tracked changes require a new run.
Keep the contract in your repo
mhproto.yaml links each feature to its behaviour document, OpenAPI interface,
examples and checks. Authored files and visual references live in mhproto/;
local baselines and verification evidence live in .mhproto/.
The BIVE approach—Behaviour, Interface, Verification and Examples—is the structure inside a spec. MHProto is the tool that makes it readable and actionable for humans and agents.
npx mhproto context --capability daily --operation getToday npx mhproto build --out ./review
Agents fetch a compact index and only the relevant endpoint, rule or type details. The
exported viewer.html contains the human review, diagrams and selected baseline
and works offline. Optional type generation stays with your app’s chosen generator.
Explore the complete Impostor pilot or browse the source on GitHub.