harness-engineering

Harness Engineering

A harness is the combined set of deterministic tooling and LLM-based agents that keeps AI code generation trustworthy and maintainable at scale. The concept originates from Birgitta Boeckeler's article "Harness Engineering" (2026), which identifies three components that together form a complete harness.

For the full article summary and four hypotheses, consult references/boeckeler-summary.md.

The Three Components

Context Engineering

The knowledge an LLM needs to work effectively in a codebase. This includes explicit documentation (conventions, constraints, stack declarations) and implicit context (the code design itself). A well-structured codebase is easier to harness than a sprawling one because the structure communicates intent.

In this plugin, context engineering lives in HARNESS.md's Context section — stack declaration, convention documentation, and any project-specific knowledge that shapes how code should be written.

Architectural Constraints

Rules that must be enforced — not suggestions, but hard boundaries. Each constraint is backed by a verification slot that can be filled by either a deterministic tool (linter, formatter, structural test) or an agent-based review. The rest of the system does not care which backs the slot — only whether the constraint passed.

In this plugin, constraints live in HARNESS.md's Constraints section and are enforced at three timescales: advisory at edit time (hooks), strict at merge time (CI), and investigative on schedule (audit).

Garbage Collection

Periodic checks that fight entropy — the slow drift that neither real-time hooks nor PR gates catch. Documentation goes stale, conventions erode, dead code accumulates, dependencies fall behind. Garbage collection agents run on a schedule to find and fix (or flag) these issues.

In this plugin, GC rules live in HARNESS.md's Garbage Collection section and are run by the harness-gc agent.

The Living Harness

The central design principle of this plugin is that the harness is a living document — HARNESS.md — that generates its own enforcement. The document declares what should be true; the plugin's agents, hooks, and CI check whether it is true; the auditor updates the document's Status section to reflect reality.

This creates a self-referential feedback loop: the harness is harnessed by its own document. When the Status section shows drift between declared and actual enforcement, the team knows where to invest next.

Progressive Hardening

Constraints follow a promotion ladder:

1. Unverified — declared intent, no automation yet
2. Agent — LLM-based review against the constraint's prose rule
3. Deterministic — tool-backed enforcement (linter, formatter, test)

Start by declaring what should be true. Automate when ready. The harness improves over time without restructuring.

Testing the Harness Itself

The harness teaches TDD for code. But the harness's own artifacts — skills, conventions, CLAUDE.md directives — are specifications that produce agent behaviour. A skill without behavioural tests is an unverified claim.

Test-Driven Agentic Behaviours (TDAB, after Antony Marcano, 2026) applies TDD to guidance files: write a test describing desired agent behaviour, run the agent, observe the gap, modify the guidance, verify the behaviour. Red-green-refactor for skills.

On the promotion ladder, a skill without behavioural tests is unverified. A skill with passing tests is agent-verified. If you would not ship code without tests, do not ship skills without them either.

Implementation Patterns

Beneath the three components lies a layer of mechanical patterns that make the harness work in practice. Six patterns from production agent systems:

• Tiered Memory — always-loaded index, on-demand topic files, searchable archive
• Dream Consolidation — periodic pruning and reorganisation of compound learning memory
• Progressive Context Compaction — compression intensity increases with conversation age
• Progressive Tool Expansion — start agents with minimal tools, expand on demand
• Command Risk Classification — allow/ask/deny per tool, gated by reversibility and blast radius
• Single-Purpose Tool Design — typed inputs, constrained scope, individual permission surfaces

These are documented in detail in the framework (Theme 10, Appendices H, I, J).

Enforcement Timing

Three concentric feedback loops:

Loop	Trigger	Strictness	Purpose
Inner	PreToolUse hook	Advisory	Catch issues while context is fresh
Middle	CI on PR	Strict	Prevent violations reaching main
Outer	Scheduled GC + audit	Investigative	Fight slow entropy

Plugin Components

Component	Count	Purpose
Commands	5	User-facing harness lifecycle
Agents	4	Workers with bounded trust
Skills	5	Knowledge for agents and users
Hooks	2	Real-time enforcement wiring
Templates	3	Opinionated defaults

For detailed guidance on each component, consult the relevant skill: context-engineering, constraint-design, garbage-collection, verification-slots.

Additional Resources

Reference Files

• references/boeckeler-summary.md — Full summary of the article, the three components, the four hypotheses, and related work