What a Harness Actually Is

A harness doesn't make the model smarter. It wraps the model in a loop instead: you hand it a goal, it works, something checks the result, and round it goes again.

Six stages, one loop

Strip a reliable agent setup to its bones and you always find the same six stages:

• Objective, explicit rules and a checkable definition of done (AGENTS.md, a feature list).
• Initialize, build the environment from scratch, every run (init.sh).
• Run, the agent edits and executes inside a persistent terminal.
• Feedback, runtime output and logs flow back so errors become the next task.
• Verify, a full-pipeline gate decides done vs. not-done.
• Handoff, commit, tidy, and leave a note so the next pass starts from clarity.

Verification failing routes back to feedback. Verification passing routes to handoff, then the next unit of work. That cycle is the harness.

flowchart LR
  O["Objective, AGENTS.md + feature_list.json"] --> I["Init, init.sh"]
  I --> R["Run, agent in tmux"]
  R --> F["Feedback, logs"]
  F --> V{"Verify, verify.sh"}
  V -->|red| R
  V -->|green| H["Hand off, handoff.md"]
  H --> O
  linkStyle 4 stroke:#e0493f,stroke-width:2.5px,color:#e0493f
  linkStyle 5 stroke:#2ea043,stroke-width:2.5px,color:#2ea043

Why a prompt is not enough

A great prompt improves a single turn. A harness improves the hundredth turn, because it owns the things a prompt cannot: durable state, a real environment, evidence from the runtime, and a gate that refuses to accept unverified work. Prompts are inside the loop; the harness is the loop.

Agentum is the loop, packaged

In Agentum these six stages are the Harness Engine. They map onto real files in an .agentum-harness/ directory: the objective is AGENTS.md plus feature_list.json, init is init.sh, the run is a real agent spawned in tmux, and the gate is verify.sh. The engine runs init.sh once, then for each pending feature it spawns one agent scoped to that feature, waits for it to settle, and runs verify.sh keyed by $HARNESS_FEATURE_ID. Green marks the feature done, writes handoff.md, and advances. Red re-prompts the agent with the failing output and retries up to max_retries before halting. There is no completion promise to fake, because the gate is a shell script, and the run ends only when every feature is green.

The bigger loop: roles around the work

That feature loop is only the middle of a larger one. Agentum wraps it in an autonomous SDD role lifecycle, a phase machine that runs above the backlog: authoring → architecture → decompose → executing → review → done. Each phase before and after the work is played by a role agent. A PM clarifies the spec, an Architect validates the design, the feature loop you just saw is the Developer phase, and a Reviewer signs it off.

The whole thing advances on its own. A gate passes when the role agent produces its artifact and a machine readable verdict, never on a human tap. You open a spec and walk away: the PM refines it, the architect checks it, the harness builds and verifies each feature, the reviewer approves, and you come back to a finished, verified change. A human stop is opt in, never the default, including at QA.

Exercises

Further reading