agentic-harness

🦎 Agent Harness

Enforce. Enforce. Enforce.

Stop the slop. AI agents aren't sloppy — the human toolchains they inherited are.

44 rules · 5 stacks · <500ms · Zero config

Quick Start · The Problem · Stacks · For AI Agents · Contributing

PyPI: Install as agentic-harness — the agent-harness name is reserved by an unrelated abandoned package (transfer pending). CLI command is agent-harness.

---

Agent: writes Dockerfile, commits
  ↓
agent-harness lint → FAIL: no USER directive, no HEALTHCHECK, COPY . . before pip install
  ↓
Agent: reads errors, fixes all three, re-lints
  ↓
agent-harness lint → 10 passed, 0 failed (476ms)
  ↓
Agent: commits clean code. No human involved.

Dockerfiles without USER directives. Compose files without healthchecks. Secrets hardcoded in ENV. Dependency caches busted on every build. Coverage gates that don't exist. Formatters that never run.

This isn't the AI's fault. These are human-built toolchains with decades of accumulated slop — implicit defaults, silent failures, missing guardrails. Humans learned to work around them through tribal knowledge. AI agents don't have tribal knowledge. They just hit the wall.

Agent Harness is the wall that talks back. One CLI, deterministic feedback, actionable error messages. Every rule exists because an AI agent made that exact mistake — and will keep making it until something stops it.

$ agent-harness lint

  PASS  conftest-gitignore (39ms)
  PASS  conftest-json (0ms)
  PASS  yamllint (117ms)
  PASS  file-length (0ms)
  PASS  ruff:format (50ms)
  PASS  ruff:check (118ms)
  PASS  ty (109ms)
  PASS  conftest-python (43ms)

8 passed, 0 failed (476ms)

The Problem

AI agents are as good as the feedback they get. Human toolchains give terrible feedback — or none at all.

An agent can't act on "consider using healthchecks." It can act on "FAIL: services.api missing healthcheck — add healthcheck: block."

That's the difference between documentation and a harness. Documentation hopes. A harness enforces.

We'll build AI-first frameworks eventually. Until then, agents have to work with what humans built. Agent Harness makes that survivable.

Quick Start

# Install
uv tool install agentic-harness   # or: pip install agentic-harness

# Detect stacks + subprojects
agent-harness detect

# Set up configs and Makefile
agent-harness init

# Run all checks
agent-harness lint

# Auto-fix what's fixable, then lint
agent-harness fix

Stacks

Agent Harness auto-detects your project and activates the right checks. Zero config required.

Python

Detected by pyproject.toml, setup.py, requirements.txt

JavaScript / TypeScript

Detected by package.json, tsconfig.json

Docker

Detected by Dockerfile, docker-compose*.yml

Dokploy

Detected by dokploy-network reference in compose files

Universal

Always active on every project.

Configuration

Zero config by default — stacks are auto-detected. Override with .agent-harness.yml:

stacks:
  - python
  - docker
  - javascript

exclude:
  - _archive/
  - vendor/

python:
  coverage_threshold: 95
  line_length: 140
  max_file_lines: 500

javascript:
  coverage_threshold: 80

docker:
  own_image_prefix: "ghcr.io/myorg/"

Conftest Exceptions

Skip individual policies per file when legitimate:

docker:
  conftest_skip:
    scripts/autonomy/Dockerfile:
      - dockerfile.user        # runs as root intentionally
      - dockerfile.healthcheck # not a service

See SKILL.md for the full list of exception IDs.

Commands

For AI Agents

The feedback loop

Agent writes code
       ↓
agent-harness lint
       ↓
  ┌─ PASS → commit
  └─ FAIL → agent reads error → agent fixes → re-lint

Every error message is actionable. Every Rego policy has a structured comment:

# WHAT: What this rule checks
# WHY: Why it matters for AI agents
# WITHOUT IT: What breaks in practice
# FIX: How to resolve the violation

When a user challenges a rule

1. Read the WHY block from the .rego file
2. Explain the risk to the user
3. If they still want to suppress — that's their call

The WHY exists because agents make these specific mistakes. It's the agent's argument.

Claude Code plugin

Agent Harness ships as a Claude Code plugin with guidance docs:

# Load as plugin
claude --plugin-dir /path/to/agent-harness

# Or add to your shell alias
alias c="claude --plugin-dir ~/path/to/agent-harness"

The plugin includes:

• Skill — when to use, workflow, stack reference
• Docker guidance — healthcheck recipes, migration patterns, config strategies
• Python guidance — why each pyproject.toml knob matters

Architecture

┌─────────────────────────────────────┐
│  Framework (Django, FastAPI, Next.js)│  ← future
├─────────────────────────────────────┤
│  Stack (Python, JS/TS, Go)          │
├─────────────────────────────────────┤
│  Infrastructure (Docker, Dokploy)   │
├─────────────────────────────────────┤
│  Universal                          │  ← always active
└─────────────────────────────────────┘

Each layer composes on top of the previous. Adding a new stack = creating a new directory. Each check is a self-contained file with its own docstring, test, and single responsibility.

Tool Stack

Agent Harness orchestrates external tools — it doesn't embed them:

Requirements

• Python 3.12+
• conftest (required)
• hadolint (for Docker projects)
• Other tools auto-fallback via uv run or npx

Status

Actively developed. See PLANS.md for roadmap.

Current: 44 Rego deny rules, 5 stacks (Python, JavaScript, Docker, Dokploy, Universal), 201 Python tests, 109 Rego tests.

Contributing

See CONTRIBUTING.md.

Every Rego policy follows the WHAT/WHY/WITHOUT IT/FIX pattern. Every Python check has a self-documenting docstring. Adding a rule? Write the WHY first — if you can't articulate why an AI agent needs this specific check, it doesn't belong here.

License

Apache 2.0 — see LICENSE.

---

_{🦎 Cold-blooded enforcement since mid 2025.}

_{Built by Denis Tomilin at Yose Labs}