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

Capability is not a reason

Building the wrong thing got cheap. Coherent, well-structured, completely misconceived work can be generated in minutes, so a design reading well proves less than it used to, and someone still has to say no to work that would otherwise ship. The default answer to a new capability is no, and the burden of proof is a failure removed, never a preference enabled. The version window needed four dead designs before one passed that bar; the knobs rule is the same principle applied to options.

It prevents the accretion this project was a reaction to (each addition defending itself, nobody removing anything), now accelerated, because writing the unnecessary thing costs nearly nothing while maintaining it costs what it always did.

Prior art is input, never the justification. "Another tool has it" says the idea exists; it says nothing about the failure it would remove here.

Enforced by

Good

A proposal that names the failure it removes and the evidence for it:

Problem: 22 of 203 sessions ran with no guard, and nothing said so.
Change:  the hook template announces each fail-open arm.
Removes: a guard that stopped judging looking like a session with nothing to deny.

Bad

Add `--watch-all`. Nx has it, and it would be nice for large repos.

It names a tool that has the feature and a preference for it, and no failure anyone hit. Nothing in it can be checked, so nothing in it can be refused on evidence either.

See also

designprinciplescope
Last updated (2df714e8)
Glossary

Project

A directory magus recognizes as a unit of work (it has a magusfile); the unit of caching, scheduling, and dependency tracking. Project in full.

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.

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.

Session

An agent host's conversation, by the id the host delivers to its hooks. magus never mints one: a record with no session is unattributed, and the OS user it carries says whose account ran it. Session in full.

Window

The terminal a command runs in. It keys fire-once notices for a caller no host gave a session, and is never recorded as a session. Window in full.

Conventions

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