▶ Start here: agent-contracts — the canonical, CI-ready front door: a 30-second GitHub Action scan, a browser playground, and the Agent Governance Index scoring 27 of the most-used agent frameworks. NLAH is the underlying harness; new users should begin at agent-contracts.

---

NLAH — Natural Language Agent Harness

A framework for making LLM agents behave consistently over time, across sessions, and under real operational pressure.

Not a framework in the "install the package" sense. This is a harness: a set of contracts, a failure taxonomy, and a runtime that you wire into your CLAUDE.md and Python codebase. The agent runs inside it.

---

The problem this solves

LLM agents fail in patterned, repeating ways. The same mistakes recur across sessions because:

1. The model's default behavior keeps winning against prose instructions
2. You can't correct what you can't name
3. Soft rules don't hold under pressure — they need code enforcement

NLAH solves this with three components:

• Named failure modes — a taxonomy of how agents fail, built from real incidents
• Contracts — pre/post conditions that run at execution time, not just at prompt time
• Runtime rules — a structured CLAUDE.md that governs session lifecycle and defaults

---

Structure

harness/
├── _runtime.md              # Session lifecycle, git workflow, default-to-action
├── contracts/               # Per-contract docs (trigger, precondition, enforcement, recovery)
│   ├── loop_prevention.md
│   ├── pre_denial_gate.md
│   ├── behavioral_haiku_guard.md
│   └── ...
└── failure_modes/
    └── taxonomy.md          # 35 named failure modes with code guards and recovery paths

core/
└── contracts.py             # Python Contract base class + enforcement pipeline

---

How it works

CLAUDE.md is the loader. It tells the agent which harness modules govern its behavior, where to find the failure taxonomy, and what the session startup sequence is.

Contracts are Python classes with check_pre() and check_post() methods:

class VerifyBeforePush(Contract):
    name = "verify-before-push"
    failure_mode = "FM-002"

    def check_pre(self, ctx: ContractContext) -> Optional[Violation]:
        if ctx.action == "git_push" and not ctx.verification_output:
            return Violation(
                contract=self.name,
                failure_mode=self.failure_mode,
                message="No verification output found. Run tests before pushing.",
                severity="block",
                recovery="Run tests. Paste output. Then push."
            )
        return None

The enforcement pipeline runs contracts before and after each action:

from core.contracts import check_all_pre, check_all_post, ContractContext

ctx = ContractContext(action="git_push", verification_output="")
violations = check_all_pre(ctx)
# → [Violation(contract="verify-before-push", severity="block", ...)]

Violations block the action, warn, or trigger auto-recovery depending on severity.

---

The failure taxonomy

35 named failure modes, each with:

• Pattern (what it looks like)
• Root cause (why it happens)
• Contract (what catches it)
• Code guard (what enforces it)
• Recovery (how to fix it)
• Frequency (how often it fires)

The most common ones (FM-001 through FM-004) account for the majority of real incidents. Start there.

See harness/failure_modes/taxonomy.md for the full list.

---

Getting started

1. Copy harness/ into your project root
2. Copy core/contracts.py and wire check_all_pre / check_all_post into your execution loop
3. Adapt CLAUDE.md to reference your harness directory
4. Pick 3 failure modes from the taxonomy that match how your agent currently breaks. Write a contract for each.
5. Add the contract to _ALL_CONTRACTS in contracts.py

Add new contracts as you find new failure modes. The taxonomy grows with real incidents.

---

Questions / adapting this to your stack

Follow along: Echo From Shadow — the newsletter where Shadow documents what it's building, what breaks, and what works.

Consulting inquiries: impartshadow@gmail.com — if you're adapting this to a different agent framework, hitting specific failure modes, or want to talk through the architecture.