magus v0.4.3 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
2 min read

The standard

Adapted from Wendell Berry's nine standards for adopting a new tool ("Why I Am Not Going to Buy a Computer", 1987). His subject was a farm; the criteria survive the distance because they are about what a tool owes the person who takes it up. Held against magus in both directions: what magus asks of itself before adding anything, and what you should ask of magus before adopting it:

  1. Cheaper than what it replaces. Total cost: install, learning, upkeep. One binary, no account, nothing to upsell, no toolchain underneath it to break. The honest half: the learning cost is charged up front, and the claim is cheaper over a year, not cheaper in week one.
  2. At least as small in scale. The tool may not outgrow what one person can hold. Enforced today by judgment alone; the ledger that would measure it is a debt, in Where this is strained.
  3. Clearly and demonstrably better. A claim of better needs an artifact someone else can check: the benchmark results, committed with the hardware, the date, and the exact competing tool versions they were taken on; terminal recordings that are captured bytes rather than mockups; the drift gate. The claim that querying the graph beats grepping is argued from mechanism and not yet measured; weigh it accordingly.
  4. Uses less energy. affected and the cache are this criterion implemented: run only what a change reaches, never do the same work twice. The savings are real and currently invisible; a debt, in Where this is strained.
  5. Powered by what the work already produces. Berry said the body's own energy. Here it is the scope test verbatim: every capability reads the model that correctness already forced the build to hold, and the one exception, the release registry, is named there.
  6. Repairable by its user. Refusals carry a next step, every diagnostic code has a page, the host wiring is a template you own, no generated code sits between you and a running build, and the guard fails open with a notice rather than failing silent. The systematic version is missing; a debt, in Where this is strained.
  7. Repairable near home. The cache is a plain store on your disk, the console is loopback-locked, no capability requires a hosted service, the daemon accelerates and never gates. The exceptions run on infrastructure we operate; Scope names them.
  8. From a shop that will take it back. One maintainer, said plainly, and the mitigations are structural rather than social: a sealed engine kept small, documentation written before announcement, GPLv3 so the tool stays repairable in common if the shop ever closes. Choosing Buzz for its maintainers was this criterion applied to a dependency before we had read it stated.
  9. Disrupts nothing good that already exists. The terminal's decades of contract stay intact: scrollback, selection, the working directory, plain text, your toolchain visible and yours. The console is where this is under active tension, and it ships under a rule: what does not give genuine value over the good thing that already exists should not ship.
designstandard
Last updated (2df714e8)
Glossary

Op

A single tool-native command a target composes (long form: operation); the middle of the work hierarchy (Spell to Op to Target). Op in full.

Buzz

The language magusfiles are written in (the .buzz engine). Buzz in full.

Engine

The interpreter a magusfile runs on; magus embeds the Buzz engine. Engine in full.

Cache

The content-addressed store magus consults before running a target, so unchanged work is skipped. Cache in full.

Affected

The set of projects touched by a change; magus affected <target> runs a target only over them. Affected in full.

Service

A long-running or shared process magus manages across runs, distinct from a one-shot target. Service in full.

Daemon

The background process a person starts with magus server start. It serves MCP, the console, background jobs and the warm knowledge graph, and adopts nested magus calls into one pool. Daemon in full.

CI

An ordinary target you compose yourself with ctx.needs; magus does not hardcode its stages. It is the anchor magus affected ci keys off, and ci strips the rw charm. CI in full.

Scope test

The question every proposed capability has to answer: does it read the model magus already had to build, or does it make magus learn something new about the world? Reads stay small; acquisitions are where a tool loses its shape. Scope test in full.

Tool

An action a model can call through its host: a name, a description, a typed input and a result. magus serves its tools over MCP, each a read of the workspace model or a run of the CLI it already has. Tool in full.

Run

One target executing under one magus invocation, such as magus run test web or magus affected ci. A run keeps its captured output behind an output reference. Every magus run is a run whether or not any job asked for it; see Job for how the two relate. Run in full.

Lease

The grant a holder takes on a job: the write and read paths that job declared, enforced in the checkout that took it with magus job exec. A job is the piece of work; a lease is permission over it. Lease in full.

Conventions

This page uses none of the site's convention markers. The full set is on the conventions page.