Agent Harness: Repository Governance for Agent-First Engineering

This repository is a practical, docs-first harness for running coding agents with clear guardrails, validation loops, and progressive-disclosure knowledge maps.

It distills the working patterns described in OpenAI's harness engineering guidance into reusable repository artifacts: principles, checklists, prompts, and invariants.

What This Repo Is

• A lightweight governance layer for agent-assisted development
• A source-of-truth documentation set for how humans and agents collaborate
• A reusable template for keeping agent output legible, reviewable, and maintainable

Who This Is For

• Engineering teams adopting AI coding agents in production workflows
• Operators running multi-agent systems (including OpenClaw-style setups)
• Maintainers who need enforceable standards instead of ad hoc instructions

Quick Start

1. Read the core operating model in principles.md.
2. Classify risk with autonomy-levels.md (L0-L3).
3. Run change planning from checklists/change-preflight.md.
4. Use architecture constraints from invariants-and-guardrails.md.
5. Use feedback-loop guidance from legibility-and-feedback-loops.md.
6. For OpenClaw operations, continue in openclaw/README.md.

Usage Examples

Example 1: Prepare a docs-only governance update

Use this when adding or refining harness guidance:

1. Define scope with checklists/change-preflight.md.
2. Apply documentation hygiene from checklists/doc-gardening.md.
3. Keep changes focused to the affected source-of-truth files (for example principles.md + one checklist).
4. Review against checklists/pr-review.md before opening a PR.

Example 2: Audit OpenClaw config/documentation drift

Use this when OpenClaw config changes and you need docs to stay accurate:

1. Start with openclaw/checklists/config-change-preflight.md.
2. Verify invariant expectations in openclaw/invariants.md.
3. Run the validation order in openclaw/validation-loops.md.
4. Reconcile agent workspace quality with openclaw/checklists/workspace-health.md.
5. If needed, run the maintenance prompts in openclaw/prompts/.

Repository Structure Map

.
├── README.md
├── principles.md
├── autonomy-levels.md
├── repository-knowledge.md
├── legibility-and-feedback-loops.md
├── invariants-and-guardrails.md
├── merge-and-throughput.md
├── entropy-and-gc.md
├── checklists/
│   ├── change-preflight.md
│   ├── pr-review.md
│   └── doc-gardening.md
├── prompts/
│   ├── doc-gardener.md
│   └── harness-enforcer.md
├── openclaw/
│   ├── README.md
│   ├── invariants.md
│   ├── validation-loops.md
│   ├── checklists/
│   └── prompts/
└── sources/
    └── openai-harness-engineering.md

GitHub SEO

Suggested repository description:

Agent harness docs for AI coding workflows: principles, checklists, invariants, and OpenClaw operations governance.

Searchable keywords:

• agent harness
• harness engineering
• codex workflow
• ai coding governance
• progressive disclosure docs
• multi-agent operations
• OpenClaw
• repository invariants
• doc gardening

Suggested GitHub topics:

• ai-agents
• developer-tools
• documentation
• governance
• llmops
• openai
• operations
• prompt-engineering
• software-engineering

References

• OpenAI: Harness engineering article
  • https://openai.com/index/harness-engineering/
• OpenAI Cookbook (examples and patterns)
  • https://github.com/openai/openai-cookbook
• OpenAI Agents SDK for Python
  • https://github.com/openai/openai-agents-python
• OpenAI API developer docs
  • https://platform.openai.com/docs