micaelcf/ef-harness / skills/ef-readiness
ef-readiness
VerifiedMake a repository's agent rulebook (AGENTS.md / CLAUDE.md) verifiable: vendor a deterministic checker, audit every rule and citation against the code, bootstrap a lean rulebook from what the code cannot say, and grow it from audit findings. Use when setting a repo up for agents, when asked to audit or slim AGENTS.md or CLAUDE.md, before the first EF feature in a repo, or after an audit proposes rulebook lines. Do NOT use to generate a codebase overview or documentation tour.
EF Readiness: once per repository, then whenever audits find rot
Runs once per target repo · before the first feature, and again whenever audits find rot · /ef:ready
Make the repo's rulebook small, true and checked. True means every path, command and rule it states has been checked against the code. Small means it holds only what the code can't say. Checked means a deterministic gate fails when either of those stops being so.
The premise
The evidence on context files is unflattering. Across agents and models, AGENTS.md-style files
did not generally raise task success and raised cost by about 20%. Developer-written files beat
generated ones. Repository overviews didn't help agents find the right files, and instructions
were followed, so every line costs something
(Gloaguen et al. 2026). Teams running agents at scale settled
on a short map pointing to deeper docs, with mechanical checks that the docs are still true
(OpenAI, Harness engineering).
So this skill never writes an overview and never generates a rulebook in one pass. It writes only what can't be derived, places each line at the cheapest level that works, and installs a gate so the result can't quietly rot.
The parts
| Part | Where | Role |
|---|---|---|
| The checker | scripts/ef-check.mjs, relative to this skill | Deterministic gates: anchors, commands, budget, routing, checks, single-source, bindings — and feature, over every .ef/<feature>/ checklist |
| The format | references/rulebook-format.md | What the checker enforces, and the root skeleton. Load it before writing any rulebook |
| The levels | references/levels.md | Where each line belongs, and the day-one test. Load it in audit and grow |
| The interview | references/interview.md | The questions only a human can answer. Load it in bootstrap |
Vendor the checker (every mode, first)
Copy scripts/ef-check.mjs from this skill to .ef/bin/ef-check.mjs in the repository,
byte for byte, and make sure the repo's .gitattributes holds .ef/bin/*.mjs text eol=lf, so a
CRLF checkout never makes one copy differ from another. If a copy exists, compare its VERSION with
this skill's. If they differ, replace it and say so. Never patch the vendored copy: every repo runs
the same gates the harness documents.
Vendoring is also the opt-in. The plugin's edit hook runs only in a repo that has the vendored checker. From then on, every markdown edit the agent makes is checked against that copy, the same one CI runs.
Then run node .ef/bin/ef-check.mjs and keep the output. Every mode starts from it.
Modes
Three modes: audit (default), bootstrap, grow. An empty or very thin rulebook goes to bootstrap. A rulebook that exists goes to audit.
Audit: report, fix nothing
-
The checker's findings are facts. Report them as they are, grouped by gate. Don't re-derive what a gate already proved.
-
Then the judgement the checker can't make. Walk the root rulebook line by line, then each scoped one. Place each line with
references/levels.mdand give it one verdict:Verdict Meaning keepthe right line at the right level enforcea deterministic check could own it; name the lint, type or test cutderivable from code, README or manifests scopetrue but tied to a subtree; belongs in a scoped rulebook, with a routing line skilla procedure recordhistory, rationale or a date; belongs in an ADR or the changelog falsecontradicted by the code; give path:linestale-gapCheck: none, but a check now exists or is cheap; name it -
Claims the checker can't parse, such as "X is the only caller of Y" or "every handler does Z", are verified against the code and graded with the
ef-sharedskill'sreferences/evidence-grades.md. A claim graded C or D is reported as a question, never asfalse.
Report: the checker summary, the verdict table (file:line · verdict · reason · proposed home),
the budget before and after the proposed moves, and the honest gaps ranked by how cheap their
check would be. Edit nothing in this mode. The owner approves; the changes are then applied as
in grow.
Bootstrap: write the rulebook from what the code can't say
- Derive everything the code answers: the task runner's commands, the CI workflows, generated code, test layout and existing scoped docs. Run each gate candidate once. A command that doesn't run doesn't go in. Never invent a command.
- Interview with
references/interview.md, one question at a time, under theef-grillingskill's protocol. Don't ask what step 1 answered. - Write the root rulebook from the skeleton in
references/rulebook-format.md: scoped rulebooks only where the interview found rules, aCLAUDE.mdcontaining@AGENTS.mdbeside eachAGENTS.md, and the## ef-harnessblock withnode .ef/bin/ef-check.mjsamong the gates. Where the repo keeps immutable records (ADRs, closed feature docs), add adoc <dir>/ # <reason>line to.ef/anchors.allow, but only for directories the user confirms are records. A live design doc that cites a moved path is a finding, not history. - Gate: run the checker until it passes. Each error is fixed in the rulebook, never in the checker.
- CI: propose a step that runs
node .ef/bin/ef-check.mjs. Add it with the user's go-ahead. It's the step that makes the rulebook a gate rather than a document.
Grow: turn findings into rules
Input: a ## Rulebook proposals section from a Stage 5 audit, or findings the user hands over.
For each proposal, in order of preference:
- Build the check (level 0): the lint rule, type or structural test that would have caught it, with a failure message that names the fix. Then the rulebook needs at most a pointer.
- Add an invariant with its
Check:at the levelreferences/levels.mdgives it. - Add an honest gap (
Check: none — <reason>) when no check is possible yet, and say what would make one possible.
Every proposal is also checked against what's already there: a new line that duplicates an existing one is a merge, not an addition. Run the checker after each change. The budget is a limit, not a target. Every line grow adds has to pay for itself, and growing past the warning is the signal to move something down a level.
Rules
- Never invent a command. Every command written down was run once, or already runs in CI.
- Never write an overview. A directory the agent can list is a directory it will list.
- One rulebook per directory.
CLAUDE.mdbesideAGENTS.mdholds@AGENTS.mdand nothing that competes with it. - A rule without a check is a wish. Write the check, or say honestly that there is none.
- The checker's verdict is not negotiable in a rulebook edit. Changing a limit goes through
rulebook-budget:with a reason, in the diff where a reviewer sees it.
Common failures
- Generating the rulebook from the code. That gives you the overview the evidence says doesn't help, written down where it costs tokens every session.
- Keeping a rule at level 1 that a check already enforces, so the agent pays for it twice.
- A scoped rulebook with no routing line. omp never loads it, and Claude Code loads it only once the agent is already in that directory.
- A pointer
CLAUDE.mdthat says "read AGENTS.md" in prose. Both tools load onlyCLAUDE.mdwhen both exist, so the real rulebook is left to the agent's discretion. - Allowlisting a path that moved. The allowlist is for citations of things deleted on purpose.
- Editing the vendored checker to get a pass.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |