Design principles

Scope records what belongs in magus. This section records how it is allowed to behave, and it is opinionated on purpose. Bad developer experience gets under my skin, and most of what is here started as a tool that made me dig through layers of configuration, guess which default won, or read a keymap to see my own build output. Each page says what I believe, why, and what in the tree holds the line.

This is the project's north star. Features, flags and whole subsystems come and go; these are what stay. When a change and a page disagree, one of them is wrong, and the page wins unless the change brings new evidence, in which case the page changes in the same commit.

Every page has the same shape, so a person or an agent finds the same thing in the same place:

• The page opens with the argument: why the rule exists and the failure it prevents.
• Enforced by names the test, lint, guard rule or review step that holds it. A rule with no mechanism yet is a debt in Where this is strained, because a rule that lives only in prose holds about half the time.
• Good and Bad each show a real example, and a sentence after the bad one says why it is bad.
• See also links the pages and the code the rule touches.

Checking a new feature against this section is a graph query, not a reread:

magus query "kind=docsection id=~design/ <terms>"

Before reversing one of these, read A record of refusals and the decisions; reopen a settled question only with new evidence.

Pages

Principles say how the tool is built. Judgment pages say when magus automates a decision and when it hands the decision to you.

Principles

• Unix survives at the verb, not the binary: Each verb answers one question, deterministically, from declared sources, and stops; the binary is as big as the monorepo problem.
• Capability is not a reason: The default answer to a new capability is no; the burden of proof is a failure removed, never a preference enabled.
• Optimize the loop that verifies, never the loop that generates: Every mechanism makes knowing and trusting a change cheaper; nothing in magus exists to make producing code faster.
• A cache is an accelerator, never a dependency: A cache may shorten a derivation, never be the only copy of one; switching it off changes a duration, never an answer.
• Everything is a file: Local state is JSON Lines a person reads with cat, grep and diff; one entry per line, the last line per key wins, every rewrite a rename.
• Behavior is code, facts are data: A target is a Buzz function you can read top to bottom; configuration holds only facts with no algorithm in them.
• Human-first is the AI integration: Nothing is designed for an agent first; an interface legible to a person is legible to anything.
• Verdicts are provenance-blind; disposition is not: No gate conditions on who or what wrote a change; accepting, sending and landing one carries a true name.
• Human in the loop: An agent proposes and does bounded work; a person decides at named points, each explicit, reasoned and recorded.
• Built for the expensive era: Move what a model would have to work out into deterministic, checked answers, so a smaller model can do the work.
• The orchestrator plans, workers work, the integrator lands: Delegated work has three roles; the orchestrator plans and coordinates, workers read, edit and check, and the integrator builds, regenerates and commits.
• A copy can be the right answer: Merge duplicates only when they share semantics, knobs and bugs; otherwise keep the copy, with one line saying why.
• Friction that carries meaning: Keep resistance where the resistance is the information; friction that tells every caller the same sentence is a toll, and a toll is removed.
• Worth cloning: Assume magus can be reproduced; build what is better when copied, and publish the judgment a clone cannot recover.
• Clear is better than clever: Write to the need in front of you, one way, the obvious way; clever earns its place only where a measurement says it must, and then it says why.
• Built for the largest monorepos: magus is aimed at the largest monorepos that exist; at that scale performance is the feature, and every hot path is measured.
• The Go proverbs, beyond Go: Rob Pike's Go proverbs hold in every language here; where one has an enforcement point the page names it, and where it has none that is a debt.
• Delete before you add: The best code is still no code; before adding code to keep something working, check whether removing the old path reaches the goal.
• Break now, hold still later: Before 1.0 a wrong name or format is fixed without a migration path; after it, the tool that works the way it worked last year is the product.
• Sit next to the tools, never in front of them: A build tool runs other tools; it stays thin enough that you can always see which command ran and reach the tool directly.
• No generated code in the build path: Scaffolding hands you a file and leaves; a generator that must run for the tool to work never leaves, so magus has none.
• Inform people, contain the engine: Guardrails live in the engine (the sandbox and the cache), not in a schema that predicts you; magus is strict about what it tells a person and permissive about what it lets them do.
• One source, every door: A capability lives once, in the layer every caller reaches; the CLI, a magusfile, a script and the MCP tools are doors onto it, never copies of it.
• Measured, not asserted: A claim that something is better, or that a rule holds, needs an artifact someone else can check; a measurement that kills an idea is kept.
• Abstract at the right layer, or not at all: A package, module or layer earns its boundary by what it hides; a thin one that renames a function makes every reader open five files to follow one call.
• What we do not build is the product: When anyone can generate any feature, the tool is defined by what it refuses; the least code is the most secure code, and some capabilities must not be possible at all.
• A harness is not an agent thing: The checks, formatters, linters, compiler errors and gates around a change are one harness, and they hold a person to the green path the same way they hold an agent.
• Every answer has an address: A run's output ref is derived from the hash of everything it declared, the way a Nix store path is; the same inputs name the same run on any machine.
• No news is good news: A passing run says almost nothing; output is spent on what failed, what changed and what to do next, because every line costs a reader's attention and an agent's context.
• Enforcement, not pinky promises: A rule written only as prose in an agent's context is a pinky promise; each rule lives at the lowest layer that can enforce it, and skills teach rather than guard.

Judgment

• Agents propose, humans dispose: An agent integration can suggest work but never accept it; authorship comes from the transport, never the writer's claim.
• The host wiring is yours: magus owns the guard rules and the verdict; the part that knows your agent host is a template you copy and edit.
• The outer harness stays outside: magus judges and informs, and never transforms what reaches the model; the host owns the loop.
• Determinism at chosen points: magus fixes a step where it can prove the answer and leaves the rest to the model; a person chooses which steps are fixed.
• A refusal carries its reason: A refusal names the mechanism and a next step; an error that leaves you with no next step is a design bug.
• No silent defaults: A default that changes what happens without saying so is a bug; misconfiguration is an error, never a warning.
• Told, never guessed: magus never sniffs where it runs to change what it does; a caller that needs different behavior asks for it.
• Provider I/O is Buzz: A CI or VCS provider is reached only by a Buzz op that names the act; Go opens no provider socket of its own.
• Automation you can interrogate: Each automated verdict ships with a lens that shows its inputs, and each step magus runs is expressible as the tool call it made.
• Manual on purpose: Automate a repetition, never a rep; each act that forms judgment stays a person's keystroke.
• The loop keeps you able to notice: What reaches a person is the deviation, the batch and the absence, never a confirmation of a pattern they already trust.
• Corrective competence: The skill this section protects is your ability to fix the thing yourself when the agent is wrong, or gone.

Also in this section

• The standard: Wendell Berry's nine standards for a new tool, held against magus in both directions.
• Where this is strained: where the principles cost more than they claim, and the rules that live only in prose so far.
• A record of refusals: what magus could have had and does not, with what decided each.