Set up or update the agent-first engineering harness for any repository. Implements the complete scaffolding that makes AI coding agents effective: knowledge maps (AGENTS.md as a concise TOC), structured documentation, architecture boundaries, enforcement rules (.harness/*.yml specs), quality scoring, and process patterns for agent-driven development. Use this skill whenever someone wants to make a repo agent-ready, set up AGENTS.md or docs/ structure, define domain boundaries or golden principles, generate .harness/ configuration, audit agent readiness, or update an existing harness. Also trigger when a user reports problems with agent effectiveness, context management, or architectural drift — these are symptoms of a missing or stale harness. Trigger on: "harness this repo", "set up harness", "agent-first setup", "make this agent-ready", "update the harness", "assess agent readiness", "set up AGENTS.md", "organize for agents", or any discussion about structuring a codebase for AI agent workflows.
The harness is the scaffolding that makes coding agents effective in a repository. It encodes the knowledge, boundaries, and rules that an agent needs to reason about the full business domain directly from the repo itself.
The philosophy: agents execute, humans steer. The engineer's job is not to write code but to design environments, specify intent, and build feedback loops. The harness is what makes this possible.
From the agent's point of view, anything it can't access in-context while running effectively doesn't exist. Slack discussions, Google Docs, tacit team knowledge — all invisible. The harness makes this knowledge legible by encoding it as repository-local, versioned artifacts.
A well-harnessed repo gives agents:
Without this scaffolding, agents replicate whatever patterns they find — including bad ones. The harness is what prevents entropy from compounding.
The harness is built incrementally. Each level builds on the previous — don't try to jump from Level 0 to Level 4 in one pass. Assess the current level and build toward the next.
| Level | Name | What it enables | Key artifacts |
|---|---|---|---|
| 0 | Unharnessed | Agents guess everything — no map, no rules | Nothing |
| 1 | Map | Agents know where to look and what the codebase does | AGENTS.md, ARCHITECTURE.md, docs/ |
| 2 | Rules | Agents know what's allowed and what isn't | .harness/principles.yml, enforcement.yml, domains.yml |
| 3 | Feedback | Agents self-correct via quality signals and process patterns | .harness/quality.yml, doc-gardening, GC sweeps |
| 4 | Autonomy | Agents operate independently with defined escalation boundaries | Worktree isolation, escalation rules, agent-to-agent review |
Each level compounds. A repo at Level 2 without Level 1 has rules nobody can find. A repo at Level 3 without Level 2 has quality grades but no way to enforce improvement. Build the foundation first.
During assessment (Phase 1), determine the current maturity level. During planning (Phase 2), target the next level — not all levels at once. Repeat the harness workflow to climb.
Critical exception: for repos where agents are actively writing code (agent-first or agent-assisted), architecture boundaries (domain definitions and the forward-only dependency rule) should be co-created alongside the knowledge layer, not deferred to a separate Level 2 pass. The article is