Simple AI Harness Blueprint

A reusable scaffold for repositories where AI agents (Cursor, Claude Code, Windsurf, Codex CLI, Antigravity) and humans collaborate — without drift, amnesia, or contradictory rules accreting in every config file.

Three sizes — S, M, L — each strictly additive over the previous, plus an opt-in L+ autonomy profile on top of L (not a fourth size). Start at the smallest size that fits your project. Grow by adding files, never by renaming them.

Two ways to use this repo

1. As a Claude or Codex Desktop skill

Claude:

git clone https://github.com/GuiomeB/simple-ai-harness-blueprint.git ~/.claude/skills/simple-ai-harness-blueprint

Codex Desktop:

mkdir -p ~/.codex/skills
git clone https://github.com/GuiomeB/simple-ai-harness-blueprint.git ~/.codex/skills/simple-ai-harness-blueprint

Local development with Codex Desktop:

mkdir -p ~/.codex/skills
ln -s /path/to/simple-ai-harness-blueprint ~/.codex/skills/simple-ai-harness-blueprint

Then in any Claude or Codex session:

"Audit my repo against the AI harness blueprint and tell me what's missing for size M."

"Bootstrap an AI harness at size S on this repo."

The same SKILL.md works for both Claude and Codex Desktop. The generated harness remains agent-agnostic: AGENTS.md is canonical, and adapter files such as CLAUDE.md only restate load order for tools that need them.

The skill detects what's already present, asks for the target size, and generates only the delta — never overwriting existing files silently.

2. As a template repo

git clone https://github.com/GuiomeB/simple-ai-harness-blueprint.git
cp -R simple-ai-harness-blueprint/references/templates/S/. my-new-project/

Edit the templates to match your stack, commit, push, done.

What's inside

simple-ai-harness-blueprint/
├── README.md                          (this file: install + usage)
├── Explanations.md                    (why this exists, design notes, lessons learned)
├── SKILL.md                           (Claude / Codex skill — opens with YAML frontmatter)
├── agents/openai.yaml                 (optional Codex Desktop UI metadata)
├── LICENSE                            (MIT)
└── references/
    ├── templates/
    │   ├── S/                         (4–5 files — all 3 mechanisms present in their simplest form,
    │   │                               including a /learn workflow from day one)
    │   ├── M/                         (additive: STATUS_APP, ROUTER, context capsules, retro workflow,
    │   │                               formalized PR template)
    │   ├── L/                         (additive: patterns, rules, project skills, ADRs, meta-validator,
    │   │                               CI signal, CODEOWNERS, reviewer subagent)
    │   └── L+/                        (opt-in autonomy profile: /loop, .claude/ hooks, headless runner,
    │                                    ADR-0002 — not a fourth size)
    └── health-metrics.md              (diagnostic checklist for an existing harness)

Explanations.md is not part of the skill — it's pedagogical material for someone reading this repo on GitHub. The skill itself never loads it.

This repository also dogfoods its own blueprint: it runs the L+ profile for its own development (AGENTS.md, .agents/, .claude/ hooks + /loop, scripts/validate_agent_context.py, etc.), with the headless runner kept at manual dispatch.

Choosing your size

S — minimum with all key mechanisms present. Four or five files, including a /learn workflow that lets the system improve itself. Right for any solo / hobby / one-agent project that should still learn over time.

M — public/production codebase, 1–3 AI agents, recurring "the agent forgot rule X". Adds routing, status log, and formal PR risk rails. The 80% sweet spot.

L — established project, multiple rotating agents, painful past frictions, real release discipline. Adds patterns, project-specific skills, ADRs, meta-validator, CI signals, a read-only reviewer subagent.

L+ — not a fourth size; an opt-in autonomy profile on top of L. Add it only when you actually run bounded loops unattended (headless CI, parallel subagents/worktrees, real budgets and stop-conditions) — and record the decision in an ADR. It adds /loop (with three mandatory hard brakes), .claude/ hooks, and a headless runner. A loop without its brakes is forbidden; the default stays conservative.

The intro line (top of this file), the full signal matrix, and the L+ gate are in SKILL.md. Match signals — not codebase lines — to a level.

The five Karpathy rules + M0

Every blueprint generated by this skill opens its AGENTS.md with the same five behavioural rules (posture) plus the M0 verification mechanism:

1. Ask, don't assume.
2. Simplest solution for simple problems, stronger solutions for hard ones.
3. Don't touch unrelated code — but surface what you find.
4. Flag uncertainty explicitly.
5. Suggest better ways.

M0 — Verification: state a verifiable success criterion, then loop until it holds (trigger · stop criterion · validation · budget · stop/no-progress). The rules are posture; M0 is the mechanism the validation matrix, the DoD, and the loops all inherit from.

The rationale and field experience behind each rule lives in Explanations.md.

Contributing

This is v1. Opinionated, not finished. If you adopt the blueprint on your repo and find a rule that breaks, a capsule that should exist, or a file that's pure overhead — open an issue.

License

MIT — see LICENSE.