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

A harness is not an agent thing

The word harness spread with agents, and most people now read it as agent machinery: hooks, permission prompts, tool wrappers. I think that reading is too literal, and it misses the point. A harness is the deterministic part of the work around a change, whoever is making it. A compiler error, a formatter, a linter, a spell checker, a type check, a test suite and the gate a branch has to pass before it merges were a harness long before any model ran in a terminal. They guide a person to the green path and refuse the change that leaves it.

Seen that way, there is no separate agent harness to design. The guard that denies an agent's raw go test and hands back magus run test is the same idea as the lint that fails a person's push: one set of checks, built once, held to the same evidence, reaching whoever is at the keyboard. An agent needs the harness more often and more strictly, because advice that only prints is routed around (ADR 0013), but the harness itself is not about agents. That is why magus builds it as developer tooling first, and why nearly every rule the guard enforces is a rule a person would want too.

Enforced by

Good

One gate, whoever runs it:

magus affected ci

Bad

.agent/rules.md:  Always run the linter before committing.
.github/workflows/ci.yml:  (no lint step)

The rule exists only as advice to a model. A person is never held to it, an agent reads it and skips it, and nothing checks either of them.

See also

PrinciplesPages in this section. Where this is strainedWhere the principles cost more than they claim, and the rules that live only in prose so far. magus documentationThe magus documentation hub covering install, targets, spells, charms, operations, engines, remote caching, MCP, telemetry, and the interactive playground. SpellsA spell is a library of tool-native ops (go-build, cargo-clippy, eslint) plus cache metadata that your magusfile composes into runnable targets.
designprincipleharnessagents
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.

Spell

A language/runtime adapter (e.g. go, md) that maps generic targets onto a toolchain's real commands. Spell in full.

Affected

The set of projects touched by a change; magus affected <target> runs a target only over them. Affected 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.

Agent

A model working through an agent host such as Claude Code, Codex, Cursor or OpenCode. magus treats an agent as one more caller of its CLI, MCP tools and console, held to the same checks as a person. Agent 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.

Harness

The deterministic scaffolding around the work on a change, for a person or an agent: compiler errors, formatters, linters, checks, gates, leases and hooks, placed at points a person chose. Around an agent's loop, magus supplies one and keeps it outside. Harness in full.

Job

The unit of delegated work, and one row of the job store: what an orchestrating agent handed out, with its goal, the checkpoint it was cut against, the paths it may write or must not touch, and the one check it runs. A job's holder is either a session, for work an orchestrator handed out, or the daemon, for its own maintenance. The store records; the agent guard is what reads those facts back when grading a write. Job 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.