A lean codebase that agents can ingest instantly, but one missing test file away from being actually verifiable.

17 of 42 checks passed across 6 categories.

• Machine Orientation

  ✓4 checks passed⚠5 problems found

  • mediumAgent instructions file

    AGENTS.md / CLAUDE.md is the direct, machine-read channel for entry points and conventions.

    Fix: Add an AGENTS.md naming the entry points, the build/test commands, and the house conventions.

  • lowllms.txt present

    An llms.txt is the emerging machine-orientation standard — a curated map for LLMs.

    Fix: Add an llms.txt pointing at the key docs and entry points.

  • lowArchitecture doc

    An ARCHITECTURE doc hands an agent the module map instead of making it infer one.

    Fix: Add an ARCHITECTURE.md describing the major components and how they fit.

  • lowExamples directory

    An examples/ directory gives an agent runnable, copyable references for the API.

    Fix: Add an examples/ directory with small, runnable usage samples.

  • lowContribution conventions are written down

    A contributor guide is where an agent learns the branch, commit, and review conventions it must follow.

    Fix: Add a CONTRIBUTING.md stating the branch naming, commit format, and how a change gets reviewed.

  • ✓README present — An agent reconstructs what the repo is and how to work in it from the README first.
  • ✓Repository description set — The one-line description is the fastest orientation signal an agent reads.
  • ✓Topics set — GitHub topics situate the repo's domain and stack for an agent at a glance.
  • ✓README shows usage — A usage/example section tells an agent how the project is actually invoked.

• Reproducible Setup

  ✓3 checks passed⚠4 problems found

  • mediumContainer or dev-container

    A Dockerfile / compose / devcontainer removes 'works on my machine' from setup.

    Fix: Add a Dockerfile, a compose file, or a .devcontainer so the environment is declared, not assumed.

  • lowVersion pins are exact

    A floating pin (a bare major, or a range) still drifts between installs.

    Fix: Pin to an exact or minor version, not a floating range.

  • lowEnv template present

    A .env.example tells an agent which configuration keys it must supply to run.

    Fix: Ship a .env.example listing every required key with placeholder values.

  • lowDev container

    A .devcontainer gives an agent a one-command, fully-declared environment.

    Fix: Add a .devcontainer so the toolchain is declared, not assumed.

  • ✓Lockfile committed — Without a lockfile two clones can resolve different dependency trees — the build isn't reproducible.
  • ✓Runtime / toolchain pinned — An unpinned runtime makes an agent guess the version a clean environment needs.
  • ✓README documents setup — Explicit install/setup steps are what let an agent go from clone to running.

• Code Navigability

  ✓0 checks passed⚠4 problems found

  • mediumConventional source layout

    A recognised src/ · lib/ · app/ layout lets an agent localise code without spelunking.

    Fix: Group source under a conventional top-level directory (src/, lib/, app/, …).

  • low.editorconfig present

    An .editorconfig keeps whitespace and encoding consistent, so diffs stay legible.

    Fix: Add an .editorconfig pinning indentation, charset, and final-newline.

  • lowFormatter configured

    A formatter config (Prettier/Biome/rustfmt/…) keeps style uniform across the tree.

    Fix: Add a formatter (Prettier, Biome, rustfmt, …) and commit its config.

  • lowTyped public API

    A declared `types` entry gives an agent typed signatures to anchor an edit on.

    Fix: Ship type declarations and point package.json `types`/`typings` at them.

• Verification Surface

  ✓2 checks passed⚠5 problems found

  • highTests present

    Runnable tests are the ground truth an agent checks its own edits against.

    Fix: Add a test suite an agent can run to verify a change.

  • lowLint command defined

    A linter an agent can run catches a class of mistakes before they ship.

    Fix: Add a `lint` script and a linter config.

  • lowTask runner present

    A Makefile / Taskfile / justfile gives an agent a single index of the project's commands.

    Fix: Add a Makefile / Taskfile / justfile collecting the common commands.

  • lowTypecheck command

    A typecheck script lets an agent catch type errors before they ship.

    Fix: Add a `typecheck` script (e.g. `tsc --noEmit`).

  • lowBuild command

    A documented build command is the discoverable way for an agent to produce artifacts.

    Fix: Add a `build` script that produces the distributable.

  • ✓Test command defined — A `test` script is the documented, discoverable way to run the suite.
  • ✓CI configured — Readable CI is the feedback loop an agent reads to know what 'green' means here.

• Agent Safety

  ✓5 checks passed⚠6 problems found

  • medium.gitignore covers env files

    An ignore rule for .env is what keeps the next careless commit from leaking secrets.

    Fix: Add `.env` (and `.env.*`) to .gitignore.

  • mediumPolicy names the threat model

    A scanning agent aims at what the repo says it is defending, and where untrusted input crosses in.

    Fix: Describe the threat model and trust boundaries in SECURITY.md — what is attacker-controlled, and where it reaches trusted code.

  • mediumPolicy scopes what counts as a finding

    With no reportable-finding bar and no out-of-scope list, an automated scan returns noise nobody triages.

    Fix: State in SECURITY.md what counts as a reportable finding, and what is out of scope or accepted risk.

  • lowCODEOWNERS present

    CODEOWNERS marks the 'don't touch without review' zones an agent should respect.

    Fix: Add a CODEOWNERS file marking the sensitive paths.

  • lowAutomated dependency updates

    Dependabot / Renovate keeps dependencies patched without a human in the loop.

    Fix: Enable Dependabot or Renovate.

  • lowPolicy gives severity context

    Severity judged against this system beats a generic rating an agent had to guess at.

    Fix: Say in SECURITY.md how severity is judged here — what makes a finding critical for this system.

  • ✓No committed .env — A tracked real .env hands secrets to anything — including an agent — that reads the repo.
  • ✓No exposed secrets — Secret-shaped literals in tracked files are a live credential leak.
  • ✓.gitignore present — A .gitignore is the first guard against an agent committing secrets or build junk.
  • ✓Security policy — A SECURITY.md is where an autonomous security agent reads this repo's rules before acting on it.
  • ✓License makes the code reusable — Without a license an agent cannot safely copy, redistribute, or vendor any of this code.

• Context Economy

  ✓3 checks passed⚠1 problem found

  • lowGenerated / vendored files marked

    A .gitattributes linguist marker tells tools (and agents) what to skip.

    Fix: Mark generated/vendored paths in .gitattributes (linguist-generated / linguist-vendored).

  • ✓Dependencies not vendored in — A committed node_modules / vendor tree drowns the real signal an agent needs.
  • ✓Build output not committed — Generated dist/ · build/ output is noise an agent has to read past.
  • ✓No oversized source file — A single file in the hundreds of KB blows past an agent's effective context window.

14 of 33 checks passed across 6 categories.

• First Impression

  ✓5 checks passed⚠1 problem found

  • lowExamples to learn from

    An examples/ directory gives a newcomer something concrete to run and adapt.

    Fix: Add an examples/ directory with small, runnable samples.

  • ✓README present — The README is the first screen — with none, a newcomer has nothing to land on.
  • ✓Repository description set — The one-line description sets expectations before a newcomer even opens the README.
  • ✓Topics set — Topics situate the project's domain at a glance and help a newcomer find it.
  • ✓Status badges — Build/version badges signal at a glance that the project is alive and healthy.
  • ✓README shows what it does — A usage/example section lets a newcomer see the tool in action before committing.

• Getting Running

  ✓3 checks passed⚠4 problems found

  • mediumOne-command environment

    A Dockerfile / compose / devcontainer turns a fiddly setup into one command.

    Fix: Add a Dockerfile, a compose file, or a .devcontainer for a one-command setup.

  • lowEnv template present

    A .env.example shows a newcomer exactly which settings they must fill in to run it.

    Fix: Ship a .env.example listing every required key with placeholder values.

  • lowOne-click dev container

    A .devcontainer lets a newcomer start in a cloud IDE with zero local setup.

    Fix: Add a .devcontainer for a one-click, batteries-included environment.

  • lowVersions pinned exactly

    A floating version still drifts — a newcomer can hit a break the maintainer never saw.

    Fix: Pin prerequisites to an exact or minor version, not a floating range.

  • ✓Lockfile committed — Without a lockfile a newcomer's install resolves differently and hits errors the docs don't mention.
  • ✓Prerequisite versions pinned — Unpinned prerequisites are the classic 'works on my machine' first-run failure.
  • ✓README documents setup — Explicit install steps are the difference between a 5-minute start and giving up.

• Finding Your Way

  ✓1 check passed⚠4 problems found

  • mediumConventional source layout

    A familiar src/ · lib/ · app/ layout lets a newcomer guess where things live.

    Fix: Group source under a conventional top-level directory (src/, lib/, app/, …).

  • mediumArchitecture / overview doc

    An overview hands a newcomer the map instead of making them reconstruct it.

    Fix: Add an ARCHITECTURE.md (or a 'Project layout' README section) naming the key directories.

  • low.editorconfig present

    Consistent indentation/encoding keeps the code readable and diffs clean for newcomers.

    Fix: Add an .editorconfig pinning indentation, charset, and final-newline.

  • lowFormatter configured

    An auto-formatter means a newcomer never guesses the house style.

    Fix: Add a formatter (Prettier, Biome, rustfmt, …) and commit its config.

  • ✓No oversized source file — A single thousand-line file is a wall a newcomer bounces off.

• Path to Contribute

  ✓1 check passed⚠5 problems found

  • mediumCONTRIBUTING guide

    A CONTRIBUTING guide is the difference between a guessed and a guided first PR.

    Fix: Add a CONTRIBUTING.md covering dev setup, the test command, and how to submit a change.

  • lowIssue templates

    Issue templates show a newcomer how to file something useful — and that contributions are welcome.

    Fix: Add issue templates under .github/ISSUE_TEMPLATE.

  • lowPull-request template

    A PR template tells a first-time contributor what a good change includes.

    Fix: Add a PULL_REQUEST_TEMPLATE.md.

  • lowLint command

    A linter lets a first-time contributor catch style issues before review.

    Fix: Add a `lint` script and a linter config.

  • lowTask runner

    A Makefile / Taskfile gives a contributor a single index of the project's commands.

    Fix: Add a Makefile / Taskfile collecting the common dev commands.

  • ✓Test command defined — A documented test command lets a contributor check their change before opening a PR.

• Signs of Life

  ✓1 check passed⚠4 problems found

  • mediumTests present

    A test suite signals a project that's cared for, not abandoned.

    Fix: Add a test suite — it's the clearest sign the project is maintained.

  • lowAutomated dependency updates

    Dependabot / Renovate activity is a visible heartbeat of ongoing maintenance.

    Fix: Enable Dependabot or Renovate.

  • lowChangelog

    A maintained CHANGELOG shows a newcomer the project ships and records its changes.

    Fix: Keep a CHANGELOG.md (e.g. the Keep a Changelog format).

  • lowFunding configured

    A FUNDING config signals an invested, sponsored project — not a one-off dump.

    Fix: Add a .github/FUNDING.yml if the project accepts sponsorship.

  • ✓CI configured — Green CI on every change tells a newcomer the project is actively kept working.

• Open Door

  ✓3 checks passed⚠1 problem found

  • lowCode of conduct

    A code of conduct states the social ground rules that make it safe to step in.

    Fix: Add a CODE_OF_CONDUCT.md (the Contributor Covenant is the de-facto standard).

  • ✓License present — With no license the project isn't legally reusable — the door is shut however friendly the README.
  • ✓License is a standard one — A non-standard or custom license is a legal question mark a newcomer won't resolve.
  • ✓Security policy — A SECURITY.md tells a newcomer how to report a problem responsibly.