Agent Harness Pattern

How to make coding-agent delivery evidence-backed instead of trust-based.

TL;DR

Use @agentskit/harness (ak-harness) to freeze a human-approved task contract, resolve ambiguities before implementation, run every applicable check, record structured evidence, and refuse COMPLETE without human approval.

The harness is agent-agnostic. An agent only needs to read the contract, run the CLI, and emit the common evidence format. Doc Bridge and the Playbook can enrich context, but the core protocol remains usable without either integration.

Lifecycle

CLARIFYING → PLANNED → IMPLEMENTING → VERIFYING
                                      ↓
                         AWAITING_HUMAN_APPROVAL
                                      ↓
              AWAITING_AUTHORIZATION → COMPLETE

BLOCKED means a required check failed or evidence was incomplete. STALE means the contract or source changed after evidence was produced. CANCELLED and SUPERSEDED preserve the history without pretending the task completed.

Contract rules

Every repository task contract declares:

• intent, in-scope and out-of-scope surfaces, and unresolved ambiguities;
• outcome statements mapped to required checks;
• applicability for logic, CLI, MCP, UI, endpoint, database, and docs;
• real execution for UI, endpoint, database, CLI, and MCP checks;
• a structured evidence result for every required check;
• conditional external tracking, budget, and cleanup policy.

An agent may propose the contract, but a human must approve it before PLANNED. Once a run starts, changing the contract invalidates the run and requires a new approval.

Evidence format

Every required check prints one final JSON line:

{"status":"passed","criteria":["responsive-layout"],"artifacts":[]}

The harness captures stdout, stderr, exit code, duration, source revision, contract hash, and run ID. UI evidence additionally declares real-browser and screenshot, then supplies project-relative screenshot paths, SHA-256 hashes, and viewport dimensions.

Evidence proves that the declared command ran and produced the declared artifact. It does not replace good acceptance criteria; a weak check is still a weak check.

Local-first workflow

ak-harness doctor --json
ak-harness plan approved --by human
ak-harness start
ak-harness verify --json
ak-harness approve approved --by human

If tracking is declared by the contract, the final step is:

ak-harness authorize approved --by human

After a failure, fix the code and run ak-harness retry. The new run preserves the blocked run as history and receives a new run ID.

Dogfood

The harness should validate itself in the Playbook and then run a separate, task-scoped contract at the root of agentskit-os. Do not reuse an unrelated repository contract or turn the entire monorepo into a mandatory check for every small change.

See also

• quality-gates-pattern.md
• ../../phases/04-test/
• ../../pillars/ai-collaboration/human-in-the-loop-pattern.md