Evidence-first engineering quality for coding agents.
A portable Agent Skill for Codex, Claude Code, ChatGPT, and other coding agents that makes implementation, code review, testing, debugging, refactoring, compatibility, and security work more disciplined and verifiable.
read the repo → model the contract → patch narrowly → try to break it → inspect the diff → show the evidence
Less taste. More invariants.
Coding agents are very good at producing plausible patches. Plausible is not the same as correct.
A patch can compile and still violate a public contract. Tests can pass while missing the failure mode. A refactor can be elegant while quietly widening scope. A verification command can itself execute untrusted repository code.
engineering-quality gives coding agents a compact engineering protocol:
RECON → CONTRACT → CHANGE → VERIFY → REVIEW → EVIDENCE
The goal is not more process. The goal is a patch you can defend.
Host instructions were last checked against official vendor documentation on 2026-09-20. See host compatibility for exact evidence levels.
For local setup or experimentation:
$skill-installer Install engineering-quality from https://github.com/GeoGeekLab/engineering-quality
Manual user install:
git clone https://github.com/GeoGeekLab/engineering-quality.git \
~/.agents/skills/engineering-qualityStandalone Skill:
git clone https://github.com/GeoGeekLab/engineering-quality.git \
~/.claude/skills/engineering-qualityOr load the repository as a native single-skill plugin during development:
claude --plugin-dir /path/to/engineering-qualityOn eligible ChatGPT Business, Enterprise, Healthcare, and Edu workspaces:
- open the latest GitHub Release,
- download
engineering-quality-<version>.zip, - in ChatGPT open Plugins → Skills → Create → Upload from your computer,
- upload the ZIP.
The third-party Vercel Labs CLI is available as a convenience:
npx -y skills@1.7.0 add GeoGeekLab/engineering-qualityIt is not treated as the vendor-native distribution authority for OpenAI or Anthropic.
Without an explicit engineering contract, a coding-agent answer can look like:
Fixed the parser, cleaned up nearby helpers, and the tests look good.
engineering-quality pushes toward something more auditable:
Contract: comma-delimited input remains valid; semicolon-delimited input must fail.
Scope: changed the parser and its regression test only; unrelated utility code was left untouched.
Verified: the focused regression test and repository checks passed.
Not verified: no production traffic replay was available.
That difference is the project.
It does not prescribe one architecture, testing framework, or coding style. It asks the agent to identify the repository's actual contract, make the smallest coherent change, attack that change with relevant checks, inspect the resulting diff, and state exactly what the evidence proves.
The Skill is built around a few priorities:
- Correctness before aesthetics. A beautiful implementation of the wrong behavior is still wrong.
- Repository-local contract before generic taste. Existing architecture, compatibility, error semantics, and tooling are evidence.
- Small coherent changes. Required tests, migrations, and docs belong in the patch; drive-by cleanup does not.
- Security is part of correctness. Trust boundaries, credentials, command execution, and unsafe defaults are first-class review concerns.
- Compatibility is observable behavior. Public APIs, schemas, CLI behavior, persistence, and deployment overlap are contracts until proven otherwise.
- Evidence before confidence.
Verified,Reasoned, andNot verifiedmean different things.
This repository tries to make its own quality claims inspectable.
make check validates:
repository integrity
├── Skill + host metadata
├── local links + governance contract
├── immutable GitHub Action pins
├── VERSION + CHANGELOG consistency
├── executable behavioral-eval fixtures
├── Python compilation + unit tests
├── deterministic package verification
└── release-readiness invariants
CI runs the contract on Python 3.10, 3.12, and 3.14.
The package job performs a real artifact round trip:
build → SHA-256 → upload → delete local copy → download → SHA-256
Tagged releases publish:
engineering-quality-<version>.zip
engineering-quality-<version>.zip.sha256
The ZIP also contains an internal MANIFEST.sha256.
Verify a downloaded archive:
sha256sum -c engineering-quality-<version>.zip.sha256
gh attestation verify engineering-quality-<version>.zip \
--repo GeoGeekLab/engineering-qualityRelease artifacts are attested in GitHub Actions before publication. See release engineering.
The repository contains 14 executable miniature-repository scenarios covering defect fixes, compatibility changes, security boundaries, concurrency, dependency pressure, flaky tests, migrations, generated code, swallowed errors, and scope expansion.
Validate the harness:
python scripts/run_evals.py --validate-onlyRun a real host through the adapter layer when credentials and the native CLI are available. See behavioral evaluations.
The evidence boundary is deliberate: CI proves that the harness and deterministic checks work. It does not claim that a real Codex, Claude Code, ChatGPT, or other model passed the suite unless an actual host run produced that evidence.
| Stage | Agent behavior |
|---|---|
| RECON | Read architecture, conventions, ownership, checks, and sharp edges before editing. |
| CONTRACT | State what must change, what must remain stable, and what would prove success. |
| CHANGE | Modify the smallest coherent surface that satisfies the contract. |
| VERIFY | Try to falsify the patch with focused tests, static checks, builds, and risk-specific probes. |
| REVIEW | Inspect the complete diff for correctness, compatibility, security, concurrency, maintainability, and accidental scope. |
| EVIDENCE | Separate executed proof from inspection-based reasoning and unverified claims. |
SKILL.md is intentionally a bootloader rather than an encyclopedia. It loads the invariant set first, then routes into focused workflows and references only when needed.
python scripts/project_checks.py /path/to/repositoryDiscovery does not execute the commands it finds.
A target named test, lint, or check is not automatically safe: Make recipes, package scripts, test discovery, wrappers, compiler hooks, and plugins can execute arbitrary repository-controlled code.
Execution therefore requires an explicit trust decision:
python scripts/project_checks.py /path/to/repository \
--run --trust-repositoryGeneric adapter:
python scripts/run_evals.py \
--agent-command 'my-agent --prompt {task}' \
--adapter-label my-agent \
--allow-workspace-execution \
--output eval-results/my-agent.jsonNative Codex and Claude Code adapter examples are documented in evals/README.md.
The runner uses fresh miniature Git repositories, hides the evaluation rubric from the agent, checks that the staged Skill was not mutated, and only forwards environment variables explicitly selected by the evaluator.
engineering-quality is designed for tasks where a plausible edit is not enough:
- feature implementation with an existing contract,
- bug fixes that need regression evidence,
- behavior-preserving refactors,
- code review focused on concrete failure modes,
- debugging under incomplete evidence,
- API/schema/migration compatibility,
- security-sensitive boundaries,
- concurrency and performance changes,
- generated-code workflows,
- coding-agent evaluation and verification.
It is not a linter, formatter, static analyzer, or replacement for the repository's own tests. It composes with those tools.
Findings are classified by impact rather than taste:
| Severity | Meaning |
|---|---|
| Blocker | Incorrect behavior, data loss, security exposure, broken contract, or reliably failing verification. |
| Major | Material failure under realistic conditions or significant maintenance/operational risk. |
| Minor | Bounded clarity, resilience, test-quality, or consistency issue. |
| Note | Optional improvement, question, or follow-up. |
A useful review finding should answer:
what can fail?
under what condition?
why does this diff make that possible?
what evidence would close the finding?
Not this:
quality = more abstraction + more comments + more tests + more patterns
Closer to this:
quality =
correctness
+ clarity
+ compatibility
+ security
+ verifiability
- accidental complexity
- unnecessary churn
This is an ordering of concerns, not a numeric score.
SKILL.md portable behavioral contract
agents/openai.yaml OpenAI Skill metadata
.claude-plugin/plugin.json Claude Code plugin metadata
workflows/ feature / bug-fix / refactor / review / debug / performance
references/ verification / testing / security / compatibility / concurrency
scripts/ validation / packaging / project checks / eval adapters
evals/ executable behavioral fixtures + result schema
docs/ compatibility / release / governance / distribution / mascot
assets/mascot/ Evi mascot + identity-system artwork
.github/ CI / release / issue forms / CODEOWNERS
The release ZIP intentionally contains the runtime Skill payload rather than repository-maintenance files.
- Host installation guidance was last verified on 2026-09-20.
- GitHub Actions dependencies are pinned to immutable commit SHAs and maintained by Dependabot.
mainandv*.*.*are protected by active GitHub rulesets.- Releases use SHA-256 checksums and GitHub artifact attestations.
- Repository-defined checks execute only after explicit repository trust.
- Behavioral-eval reports distinguish deterministic evidence from qualitative rubric review.
- OpenAI Plugin Directory and Claude marketplace publication are not claimed until those external review/publication steps actually happen.
See compatibility, release engineering, governance, security, and distribution.
Contributions should address a concrete failure mode or maintenance benefit, not merely introduce a preferred style.
Start with CONTRIBUTING.md. Participation is covered by CODE_OF_CONDUCT.md, and vulnerabilities follow SECURITY.md.
MIT — see LICENSE.
Read the repo. Respect the contract. Keep the patch tight. Prove the result.
works ≠ verified