Agent workflows · engineering contracts
agent-engineering-rules
Complete engineering, proportionate verification
Install a compact engineering contract while preserving the repository owner's control.
- Public source
- On npm
My role: Rule design, CLI and distribution architecture, release engineering, and research notes.
- @aaarslan/aer on npm
- 45-line kernel
- Node.js >=24
- Claude Code + Codex
- Linux + Windows
At a glance
- Problem
- Coding agents can patch a symptom, miss failure and recovery paths, or spend their implementation budget on repeated checks. Passing a test does not establish that the requested behavior is complete or the design is coherent.
- My contribution
- Rule design, CLI and distribution architecture, release engineering, and research notes: one canonical corpus builds deterministic Claude Code and Codex distributions; a 45-line universal kernel defines engineering responsibilities and completion conditions; profiles adjust verification investment.
- Outcome
- AER v5.0.0 succeeds v3.1.1 directly. The zero-dependency CLI preserves ownership-safe local installation and adds clearer obligations for exact contracts, real recovery, UI draft and focus continuity, and proportionate verification. No general efficacy claim is made.
One canonical source builds both distributions, and the CLI installs one of them into your repository behind ownership checks.
In words
- source/ is canonical: a 45-line kernel/contract.md plus profiles, contexts, and skills.
- The build generates the dist/claude and dist/codex distributions.
- aer init --host claude --target <project> installs one of them into your repository.
- Boundary, collision, and ownership-hash checks guard that install; a collision stops it instead of overwriting your file.
- aer doctor inspects integrity without repair, and aer verify runs one selected diagnostic; neither certifies completion.
Derived from the public repository layout (source/, dist/, tools/) and README.
Engineering decisions
01
Keep universal instructions compact
AER v5 uses a 45-line universal kernel, with selected profiles and task guidance providing additional context. The core contract emphasizes complete behavior and verification proportionate to risk.
Tradeoff
A short kernel cannot enumerate every situation; anything not in the kernel has to earn its place in a profile or a skill that a repository opts into.
02
Make installation ownership explicit
One canonical corpus produces Claude and Codex distributions. Project-local installation and ownership checks protect the distinction between generated files and the repository owner's files.
Tradeoff
Collision refusal means an install can stop on a file the owner has changed instead of overwriting it: slower than a silent overwrite, and the point of the design.
03
Separate diagnostics from efficacy
Repository-only evidence tools freeze a reviewed protocol and validate imported records against artifact hashes. Failed attempts, unavailable costs, missing artifacts, and configuration exceptions remain visible. These checks do not execute models or certify efficacy.
What you can verify
- Read the 45-line universal kernel in the canonical source.
- Public CLI source, generated distributions, and release history; npm 5.0.0 matches the v5.0.0 release.
- A verified walkthrough of installation, collision refusal, drift, saved-edit recovery, and uninstall.
- Protocol and imported-record integrity tests; the planning template cannot pass validation unchanged.
Source and release links checked .
Scope and limits
No general efficacy claim is made. Controlled, model-specific comparisons with recorded budgets and independent grading are still needed to measure the effect of a ruleset.
A short walkthrough
- 01
Read the compact contract and choose the relevant profile.
- 02
Install in a disposable repository and inspect the resulting changes.
- 03
Follow the recovery walkthrough and inspect the evidence format's explicit limits before planning a study.