Lean, navigable, and fully tested, but missing a lockfile and agent guardrails.

69 of 137 checks passed across 6 categories.

• Machine Orientation

  ✓12 checks passed⚠13 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.

  • mediumProject layout is explained

    A map of the tree lets an agent localise a change without reading every folder.

    Nothing in the snapshot shows this.

    Fix: Add a 'Project layout' section listing the top-level directories and their responsibilities.

  • mediumAgent-specific guidance exists

    General docs are written for humans; an agent benefits from its own orientation file.

    Nothing in the snapshot shows this.

    Fix: Add an AGENTS.md covering the rules, off-limits paths, and how to verify changes.

  • mediumRuntime versions are pinned precisely

    An agent running the wrong runtime version hits failures it cannot diagnose.

    Checked file tree: package.json; it does not show this.

    Fix: Pin the exact runtime/language version in a .nvmrc, .python-version, or engines field.

  • mediumAn example shows the expected result

    An example with its expected output is the cheapest way for an agent to confirm it understood the project.

    Checked README § Usage; it does not show this.

    Fix: Add one small end-to-end example to the README with the output or result it should produce.

  • 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.

  • lowTopics set

    GitHub topics situate the repo's domain and stack for an agent at a glance.

    Fix: Add a few GitHub topics describing the domain and stack.

  • 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.

  • lowKey technical decisions are explained

    An agent that doesn't know the reasoning behind a choice will cheerfully undo it.

    Nothing in the snapshot shows this.

    Fix: Note the reasoning behind major technical decisions in the docs or an ADR directory.

  • lowA change history is accessible

    An agent reading a project cold can't tell what is fresh versus legacy without a change trail.

    Nothing in the snapshot shows this.

    Fix: Keep a CHANGELOG.md noting what changed in each version or at each notable milestone.

  • lowProject maturity is stated

    Maturity tells an agent how conservative its changes must be and whether breaking an API is acceptable.

    Nothing in the snapshot shows this.

    Fix: Add a one-line status to the README: experimental, stable, maintenance-only or archived.

  • ✓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.
  • ✓README shows usage — A usage/example section tells an agent how the project is actually invoked.
  • ✓README states the purpose, not just the name — An agent that can't tell what a repo is for will optimise the wrong thing. Evidence: README introduction.
  • ✓Entry points are named — Knowing where execution begins saves an agent from guessing across the tree. Evidence: README § pLimit(concurrency) ^{default export}.
  • ✓Domain terms are defined — Undefined jargon forces an agent to infer meaning, and it infers wrong. Evidence: README § API.
  • ✓Documentation looks current — Stale docs are worse than none — an agent trusts them and acts on fiction. Evidence: file tree: readme.md.
  • ✓Scope and non-goals are clear — Knowing the boundary stops an agent from building features that were deliberately excluded. Evidence: README § How is this different from the [p-queue](https://github.com/sindresorhus/p-queue.
  • ✓The intended audience is clear — Knowing the intended use frames every decision an agent makes about the repo. Evidence: README introduction.
  • ✓Documentation links resolve — A dead link is a dead end an agent follows before discovering it leads nowhere. Evidence: README § How is this different from the [p-queue](https://github.com/sindresorhus/p-queue.
  • ✓The stack is identifiable — An agent must know the stack before it can reason about how to change the code. Evidence: manifest: package.json.
  • ✓Supported platforms are stated — An agent that doesn't know the supported targets can't tell a real bug from an unsupported setup. Evidence: README introduction.

• Reproducible Setup

  ✓7 checks passed⚠13 problems found

  • highLockfile committed

    Without a lockfile two clones can resolve different dependency trees — the build isn't reproducible.

    Fix: Commit your lockfile (package-lock.json / pnpm-lock.yaml / Cargo.lock / …).

  • highSetup works from a clean clone

    Hidden setup steps are where an autonomous run silently stalls.

    Checked README § Install; it does not show this.

    Fix: Walk the setup yourself on a clean machine and document every prerequisite and command you actually needed.

  • 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.

  • mediumCommands are exact and copyable

    An agent runs commands verbatim — a described command is a command it has to reconstruct.

    Checked README § Install; it does not show this.

    Fix: Put the real commands in fenced code blocks, exactly as they should be typed.

  • mediumExternal prerequisites are listed

    An agent can't install what the docs never mention it needs.

    Checked manifest: package.json; it does not show this.

    Fix: List every external dependency (runtimes, databases, system packages) and how to obtain it.

  • mediumA dependency lockfile is committed

    Without a lockfile the same install command resolves to different versions on different runs.

    Nothing in the snapshot shows this.

    Fix: Commit the lockfile your package manager generates so dependency resolution is frozen.

  • 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.

  • lowThe build looks deterministic

    A build that drifts means an agent's green run today is a red run tomorrow.

    Checked file tree: package.json; it does not show this.

    Fix: Pin versions and vendor or checksum external downloads so the build is reproducible.

  • lowSetup includes a validation step

    A setup that ends with no verification leaves an agent unsure whether to proceed.

    Checked README § Install; it does not show this.

    Fix: Add a validation command after setup so the agent can confirm the environment is ready.

  • lowNon-idempotent steps are flagged

    An agent that reruns a non-idempotent step can silently corrupt state it relied on.

    Nothing in the snapshot shows this.

    Fix: Mark setup steps that aren't safe to rerun, or make them idempotent and say so.

  • lowTest fixtures are committed

    Tests that need data they can't get from the repo can't run in a network-isolated agent environment.

    Nothing in the snapshot shows this.

    Fix: Commit test fixtures and seed data so the suite runs without external data sources.

  • ✓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.
  • ✓Setup avoids manual GUI steps — A click-only step is a wall an autonomous agent simply cannot get past. Evidence: README § Install.
  • ✓It runs on sensible defaults — If nothing works until everything is configured, an agent can't get a first foothold. Evidence: README § Usage.
  • ✓The build is self-contained — A build that reaches out to something mutable isn't reproducible across runs. Evidence: file tree: .github/workflows/main.yml.
  • ✓Setup is reasonably bounded — A sprawling setup multiplies the places an agent's run can stall. Evidence: README § Install.
  • ✓The package manager is unambiguous — Competing lockfiles make an agent pick a tool at random and produce a dependency tree nobody else has. Evidence: README § Install.

• Code Navigability

  ✓13 checks passed⚠9 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/, …).

  • mediumModules have clear boundaries

    Clear seams let an agent change one thing without reading everything.

    Checked Repository description; it does not show this.

    Fix: Split grab-bag modules so each has one clear responsibility reflected in its name.

  • mediumThe data model is documented or inferrable

    An agent editing a system whose data shapes are opaque will make changes that contradict the model.

    Checked README § API; it does not show this.

    Fix: Document the core data model or make it inferrable from schemas or types committed to the repo.

  • 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.

  • lowComments explain the non-obvious

    An agent can read what code does; it can't recover the reasoning that isn't written down.

    Checked file tree: index.js; it does not show this.

    Fix: Comment the non-obvious decisions and constraints — the context that isn't in the code itself.

  • lowError handling is consistent

    Predictable error handling lets an agent reason about failure paths without surprises.

    Checked README § rejectOnClear; it does not show this.

    Fix: Adopt one error-handling pattern and apply it consistently.

  • lowFew unexplained magic values

    A magic value with no name is intent an agent has to infer and may get wrong.

    Checked file tree: index.js; it does not show this.

    Fix: Name magic values as named constants with a brief explanation.

  • lowCross-cutting concerns are isolated

    Scattered cross-cutting logic is expensive for an agent to refactor without unintended side effects.

    Nothing in the snapshot shows this.

    Fix: Centralize cross-cutting concerns in dedicated modules rather than sprinkling them everywhere.

  • ✓.editorconfig present — An .editorconfig keeps whitespace and encoding consistent, so diffs stay legible.
  • ✓Naming is consistent — Consistent naming lets an agent guess where things are instead of searching. Judged from the snapshot as a whole; no single section settles it.
  • ✓Little obvious dead or commented-out code — Dead code is a trap an agent wastes context understanding before discarding. Evidence: file tree: index.js.
  • ✓Structure isn't pathologically nested — Deeply nested trees make an agent traverse more to find less. Evidence: file tree: .github/.
  • ✓Files have a single responsibility — A focused file is one an agent can change confidently without unrelated fallout. Judged from the snapshot as a whole; no single section settles it.
  • ✓Public boundaries are typed — Typed boundaries give an agent ground truth instead of guesses about shapes. Evidence: file tree: index.d.ts.
  • ✓The dependency structure is legible — A tangled dependency graph makes an agent's change ripple unpredictably. Evidence: file tree: package.json.
  • ✓The public API surface is explicit — Without a clear public surface an agent can't tell what it's safe to change versus what others depend on. Evidence: README § API.
  • ✓Formatting is automated and enforced — Manual formatting is noise an agent generates and a human has to clean up. Evidence: file tree: .github/workflows/main.yml.
  • ✓Tests are near the code they cover — Tests an agent has to hunt for are tests it won't update when it changes the source. Evidence: file tree: test.js.
  • ✓Code for a feature lives together — When a feature lives in one place, an agent's change touches one area instead of a dozen folders. Judged from the snapshot as a whole; no single section settles it.
  • ✓Each language keeps to its own area — Interleaved languages make an agent apply the wrong toolchain and conventions to a file. Judged from the snapshot as a whole; no single section settles it.
  • ✓Helper scripts have a home — Findable, well-named scripts are the tools an agent reaches for first; loose ones get missed or misused. Evidence: file tree: scripts/.

• Verification Surface

  ✓7 checks passed⚠18 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.

  • mediumHow to run the tests is documented

    An agent can't check its own work if the way to verify is undocumented.

    Nothing in the snapshot shows this.

    Fix: Document the exact command to run the test suite (and any setup it needs).

  • mediumTests assert behaviour

    A test that asserts nothing turns green no matter how broken the code is.

    Checked file tree: test.js; it does not show this.

    Fix: Make tests assert expected outcomes, not just that code runs without throwing.

  • mediumKinds of tests are separated

    Separated suites let an agent get fast feedback before paying for the slow ones.

    Checked manifest: package.json; it does not show this.

    Fix: Split tests by kind into directories or scripts.

  • 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.

  • lowThe feedback loop is reasonable

    If the only check takes forever, an agent's iteration loop grinds to a halt.

    Checked manifest: package.json; it does not show this.

    Fix: Expose a way to run a focused subset of tests/checks for quick iteration.

  • lowNo obviously broken tests committed

    A baseline that's already red gives an agent no trustworthy signal to check against.

    Checked file tree: .github/workflows/main.yml; it does not show this.

    Fix: Fix or remove broken/skipped tests so a green suite is meaningful.

  • lowEdge cases get some coverage

    Untested edge cases are where an agent's change silently breaks something.

    Checked file tree: test.js; it does not show this.

    Fix: Add tests for error paths and boundary conditions, not just the success case.

  • lowCI status is visible from the README

    An agent targeting a red codebase should know it's red before it starts.

    Nothing in the snapshot shows this.

    Fix: Add a CI status badge to the README linked to the latest pipeline run.

  • lowCoverage goes beyond example-driven tests

    An agent's generated code passes exactly the examples it was written to; property tests probe the edges it missed.

    Nothing in the snapshot shows this.

    Fix: Add property-based or mutation tests to at least the most critical subsystems.

  • lowTest names describe what they test

    A test named 'test_1' forces an agent to read the implementation to understand what failed.

    Nothing in the snapshot shows this.

    Fix: Name tests to describe what they assert — 'given X, when Y, then Z' is a reliable pattern.

  • lowTest coverage is measured

    Measured coverage shows an agent which code has no safety net before it changes it.

    Checked manifest: package.json; it does not show this.

    Fix: Add a coverage script or coverage configuration.

  • lowExamples are exercised

    Untested examples rot, and an agent that copies them copies the rot.

    Checked file tree: .github/workflows/main.yml; it does not show this.

    Fix: Run the examples in CI or turn them into doc tests.

  • lowChecks run before a commit leaves

    Local hooks catch an agent's mistakes before they cost a CI run.

    Nothing in the snapshot shows this.

    Fix: Add pre-commit or git-hook configuration.

  • lowCI tests what the project supports

    Supported-but-untested platforms are where an agent's change breaks without any signal.

    Checked file tree: .github/workflows/main.yml; it does not show this.

    Fix: Add a CI matrix covering each supported runtime or platform.

  • ✓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.
  • ✓Tests look like they cover the core — An agent trusts a green suite — a green suite that tests nothing real is a false signal. Evidence: file tree: test.js.
  • ✓Verification feedback is legible — A noisy or flaky signal is one an agent can't tell apart from a real failure. Evidence: file tree: .github/workflows/main.yml.
  • ✓Static checks are meaningful — A linter set to pass everything gives an agent false confidence. Evidence: manifest: package.json.
  • ✓Tests run without elaborate setup — Tests an agent can't actually run are no feedback loop at all. Evidence: manifest: package.json.
  • ✓CI mirrors the local checks — If CI checks differ from local ones, an agent's local green is a false signal. Evidence: file tree: .github/workflows/main.yml.

• Agent Safety

  ✓12 checks passed⚠14 problems found

  • highDestructive operations are flagged

    An agent will run an unmarked destructive command the same as any other.

    Nothing in the snapshot shows this.

    Fix: Clearly label destructive/irreversible commands and gate them behind an explicit confirmation.

  • 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.

  • mediumSecurity policy

    A SECURITY.md is where an autonomous security agent reads this repo's rules before acting on it.

    Fix: Add a SECURITY.md stating the disclosure channel and the repo's security rules.

  • medium"Don't touch" zones are stated

    Without a no-go list an agent will happily edit the one file it shouldn't.

    Checked file tree: .gitignore; it does not show this.

    Fix: Document the off-limits paths (generated, vendored, security-sensitive) in an AGENTS.md or CODEOWNERS.

  • mediumSecret handling is explained

    If the safe path for secrets is unstated, an agent invents an unsafe one.

    Nothing in the snapshot shows this.

    Fix: Document how secrets are provided (env/secret store) and state that none belong in the repo.

  • mediumThe security policy describes this system

    A scanning agent inherits its threat model from this file; boilerplate aims it at nothing in particular.

    Checked file tree: .github/security.md; it does not show this.

    Fix: Rewrite SECURITY.md around this system's real assets, entry points and trust boundaries.

  • mediumUntrusted input is identified

    An agent that cannot tell trusted data from untrusted input will either miss real paths or invent them.

    Nothing in the snapshot shows this.

    Fix: Name the untrusted inputs (user uploads, webhooks, fetched content) and the boundary each one crosses.

  • mediumReleasing is restricted

    If any checkout can publish, an agent with credentials in its environment can ship a broken release.

    Checked file tree: .github/workflows/main.yml; it does not show this.

    Fix: Publish only from CI on tags or through a documented maintainer-only process.

  • 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.

  • lowCode ownership is marked

    An agent proposing changes to an owned area needs to know who to route the review to.

    Nothing in the snapshot shows this.

    Fix: Add a CODEOWNERS file mapping paths to responsible maintainers.

  • lowThe merge gate is documented

    Without a stated gate an agent doesn't know what its change must clear to be safe to land.

    Checked file tree: .github/workflows/main.yml; it does not show this.

    Fix: Document the required checks and reviewer rules that gate a merge, in CONTRIBUTING or the README.

  • lowDependency auditing is practiced

    An agent adding a dependency needs to know audit failures will be caught before they ship.

    Checked file tree: .github/workflows/main.yml; it does not show this.

    Fix: Add automated dependency auditing to CI and document the command to run it locally.

  • lowCI actions are pinned to a version

    A floating action tag means a supply-chain change can silently alter what runs in CI.

    Checked file tree: .github/workflows/main.yml; it does not show this.

    Fix: Pin CI actions to a specific version or digest — not a floating tag like `@main` or `@latest`.

  • ✓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.
  • ✓License makes the code reusable — Without a license an agent cannot safely copy, redistribute, or vendor any of this code.
  • ✓No prompt-injection in repo text — Repo text is untrusted input; injected instructions are an attack surface, not guidance. No repository text (README, docs, description, file names) addresses automated reviewers or tries to steer a verdict.
  • ✓Side effects are bounded — A command that reaches outside the repo can do damage an agent never anticipated. Evidence: README § Install.
  • ✓No untrusted code executed at build — Build-time execution of remote code is a supply-chain hole an agent would walk straight into. Evidence: file tree: package.json.
  • ✓It can run sandboxed — An agent operating safely runs sandboxed; broad host access defeats that. Evidence: README § Usage.
  • ✓Secrets aren't printed or logged — A secret echoed into logs is a leak an agent will faithfully propagate. Judged from the snapshot as a whole; no single section settles it.
  • ✓Findings can be validated by running the code — A security agent that cannot exercise the code has to speculate, which is how false positives get filed. Evidence: manifest: package.json.
  • ✓No hardcoded credentials in the code — Hardcoded credentials in the tree are a breach waiting for an agent to widen the exposure. Judged from the snapshot as a whole; no single section settles it.
  • ✓Dependencies come from standard registries — Unregistered sources bypass the review and yanking that registries provide, and an agent installs them without a second look. Evidence: file tree: package.json.

• Context Economy

  ✓18 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.
  • ✓Documentation is signal-dense — Every token of filler is context an agent spends without getting closer to the task. Evidence: file tree: readme.md.
  • ✓The tree isn't drowning in noise — A tree full of noise makes an agent work to find the few files that matter. Judged from the snapshot as a whole; no single section settles it.
  • ✓The repository is focused — A grab-bag repo forces an agent to hold far more context than the task needs. Evidence: Repository description.
  • ✓The files that matter are easy to find — If the important files are buried, an agent spends its budget locating them instead of editing them. Evidence: manifest: package.json.
  • ✓The README is appropriately sized — An overlong README spends an agent's context before it reaches the task. Evidence: file tree: readme.md.
  • ✓Docs aren't duplicated or contradictory — Conflicting docs force an agent to guess which version is true. Evidence: file tree: readme.md.
  • ✓Old versions aren't kept in the tree — Stale duplicates in the tree are noise an agent reads and must rule out. Evidence: file tree: .gitignore.
  • ✓The dependency list is lean — Every dependency is more surface an agent must account for when reasoning about the repo. Evidence: file tree: package.json.
  • ✓Large assets don't bloat the repo — Bulky assets inflate what an agent has to clone and scan for no signal gain. Judged from the snapshot as a whole; no single section settles it.
  • ✓There is one canonical home for the docs — Multiple doc homes force an agent to reconcile conflicting versions of the truth. Evidence: file tree: readme.md.
  • ✓CI configuration is readable — An unreadable CI config is one an agent can't reliably reason about or safely update. Evidence: file tree: .github/workflows/main.yml.
  • ✓Code comments don't double as an issue tracker — Inline design debates are noise an agent reads through to find the actual code logic. Judged from the snapshot as a whole; no single section settles it.
  • ✓Reference docs live outside the code — Docs embedded only in code require an agent to read the source to answer questions that belong in a doc. Evidence: file tree: readme.md.
  • ✓Each tool is configured once — Overlapping configs make an agent guess which one wins. Evidence: file tree: package.json.
  • ✓The root is concise — A crowded root is the first thing an agent reads and the least useful. Evidence: file tree: scripts/.

74 of 148 checks passed across 6 categories.

• First Impression

  ✓21 checks passed⚠6 problems found

  • mediumThe intended audience is named

    A newcomer who can't tell whether they are the intended user wastes time finding out the hard way.

    Checked README introduction; it does not show this.

    Fix: Add one sentence near the top naming who the project is built for.

  • lowTopics set

    Topics situate the project's domain at a glance and help a newcomer find it.

    Fix: Add a few GitHub topics describing the domain and stack.

  • lowStatus badges

    Build/version badges signal at a glance that the project is alive and healthy.

    Fix: Add a few status badges (CI, version, license) near the top of the README.

  • 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.

  • lowThe project's maturity is honest

    A newcomer who mistakes a prototype for a stable tool leaves frustrated.

    Nothing in the snapshot shows this.

    Fix: State the project's status (e.g. alpha/beta/stable) near the top of the README.

  • lowProject status is labeled

    A newcomer discovering a project mid-pivot or post-deprecation deserves to know before they invest time.

    Nothing in the snapshot shows this.

    Fix: Add a status badge or one-line statement to the README.

  • ✓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.
  • ✓README shows what it does — A usage/example section lets a newcomer see the tool in action before committing.
  • ✓The README earns a newcomer's attention — A newcomer decides in seconds whether a project is worth their time. Evidence: README introduction.
  • ✓The intro avoids unexplained jargon — Jargon in the first paragraph tells a newcomer this wasn't written for them. Evidence: README introduction.
  • ✓It shows the project in action — Seeing it work is far more convincing to a newcomer than being told it works. Evidence: README § Usage.
  • ✓The tone is welcoming — Tone signals whether questions and contributions are welcome — or merely tolerated. Evidence: README introduction.
  • ✓The value proposition is clear — A newcomer weighing their time wants to know what makes this worth it. Evidence: README § How is this different from the [p-queue](https://github.com/sindresorhus/p-queue.
  • ✓The opening renders cleanly — A broken first screen tells a newcomer no one's minding the shop. Evidence: README introduction.
  • ✓The README is scannable — A newcomer scans before they read; an unbroken wall makes them bounce. Evidence: file tree: readme.md.
  • ✓There are credibility signals — A newcomer is deciding whether to trust strangers' code with their time. Evidence: file tree: package.json.
  • ✓Claims are realistic — A newcomer who feels oversold leaves and doesn't come back. Evidence: README introduction.
  • ✓The project has a recognizable identity — A project without a visual identity is harder to remember, recommend, or find again. Evidence: README introduction.
  • ✓Key information is above the fold — A newcomer who scrolls past badges and boilerplate looking for the point often doesn't find it. Evidence: README introduction.
  • ✓Benefits are framed, not just features — Features describe what a product has; benefits tell a newcomer why they should care. Evidence: README introduction.
  • ✓When to choose it is clear — A newcomer comparing options needs the differentiation spelled out, not implied. Evidence: README § How is this different from the [p-queue](https://github.com/sindresorhus/p-queue.
  • ✓What it deliberately doesn't do is stated — Knowing the edges early saves a newcomer from adopting it for a job it was never meant to do. Evidence: README § How is this different from the [p-queue](https://github.com/sindresorhus/p-queue.
  • ✓What kind of thing it is is clear — A newcomer can't judge fit or find the right instructions until they know whether to import it, run it, or deploy it. Evidence: README § Install.
  • ✓The repo description and the README agree — The description is what a newcomer sees in search results; a mismatch with the README reads as a stale or confused project. Evidence: Repository description.
  • ✓Forks and mirrors point to the real home — A newcomer who lands on an unmarked fork or mirror files issues and pull requests where nobody is listening. Judged from the snapshot as a whole; no single section settles it.
  • ✓The README is sized to its job — A stub leaves a newcomer guessing and a sprawling manual buries the first steps; both cost the first visit. Evidence: file tree: readme.md.

• Getting Running

  ✓13 checks passed⚠11 problems found

  • highLockfile committed

    Without a lockfile a newcomer's install resolves differently and hits errors the docs don't mention.

    Fix: Commit your lockfile so a fresh clone installs the same dependency tree.

  • 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.

  • mediumPrerequisites are spelled out

    A newcomer can't be expected to already have the tools the maintainer takes for granted.

    Checked README § Install; it does not show this.

    Fix: List the prerequisites up front with links or commands to install each.

  • mediumA newcomer can confirm it worked

    Without a success signal, a newcomer can't tell 'done' from 'silently broken'.

    Checked README § Usage; it does not show this.

    Fix: Tell the reader what success looks like after setup (the expected output or URL).

  • 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.

  • lowThere's something to try it on

    A newcomer with nothing to run it on can't experience the project at all.

    Checked README § Usage; it does not show this.

    Fix: Provide sample/seed data or a demo mode so a newcomer can try it immediately.

  • lowThere's a way to start over

    Stuck with a half-broken setup and no reset, a newcomer gives up.

    Checked README § limit.clearQueue(); it does not show this.

    Fix: Document how to reset/clean up a botched setup so a newcomer can retry.

  • lowOne command bootstraps the environment

    Multi-step setup multiplies the places a newcomer stalls before their first run.

    Checked file tree: package.json; it does not show this.

    Fix: Write a setup.sh (or equivalent) that performs all setup in one command.

  • lowExpected setup time is stated

    A newcomer who expects minutes but waits an hour assumes something is broken.

    Nothing in the snapshot shows this.

    Fix: Add a note on expected setup time so a newcomer knows whether to wait or investigate.

  • ✓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.
  • ✓There's a real quickstart — A quick first win is what turns a curious visitor into a user. Evidence: README § Usage.
  • ✓Setup steps are in order — Out-of-order instructions strand a newcomer who can't tell what comes first. Evidence: README § Install.
  • ✓Common pitfalls are covered — The first error a newcomer hits is where they quietly give up. Evidence: README § FAQ.
  • ✓Commands are copy-pasteable — Reconstructing a command from prose is where a newcomer makes their first mistake. Evidence: README § Install.
  • ✓The first run needs little config — Front-loading configuration stalls a newcomer before their first win. Evidence: README § Usage.
  • ✓The minimum viable run is fast — Every additional step before the first success is a place to lose the newcomer. Evidence: README § Usage.
  • ✓Dependencies install in one command — Manual dependency hunting is where a newcomer's first-run experience falls apart. Evidence: README § Install.
  • ✓It can be installed without building from source — A packaged release lets a newcomer try the project in one step before committing to a full toolchain. Evidence: README § Install.
  • ✓Setup commands match the project's tooling — A newcomer copying a command that names the wrong package manager or a missing script is stuck on step one. Evidence: README § Install.
  • ✓Setup doesn't take over the machine — Newcomers are rightly wary of running unexplained root commands for a project they are only evaluating. Evidence: README § Install.
  • ✓Using it and building it are separate paths — A newcomer who just wants to use it shouldn't have to wade through the contributor toolchain, and vice versa. Evidence: file tree: readme.md.

• Finding Your Way

  ✓13 checks passed⚠12 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.

  • mediumA newcomer can orient in the codebase

    Dropped into an unmapped codebase, a newcomer doesn't know which thread to pull.

    Checked file tree: readme.md; it does not show this.

    Fix: Add a short 'Project layout' or 'Where things live' guide pointing at the key directories.

  • mediumAn architecture overview exists

    A newcomer can't navigate a system they have no map of.

    Nothing in the snapshot shows this.

    Fix: Write an architecture overview — even a short diagram and description — covering major components and their connections.

  • mediumModule boundaries show in the tree

    Visible boundaries let a newcomer ignore most of the code and focus on the part their change touches.

    Checked file tree: scripts/; it does not show this.

    Fix: Group source files into folders by feature or responsibility, each with a name that says what it owns.

  • mediumDocs and code use the same words

    When the docs say one word and the code another, a newcomer can't connect what they read to where it lives.

    Checked file tree: index.js; it does not show this.

    Fix: Rename folders or doc terms so each core concept carries one name in both the README and the source tree.

  • lowFormatter configured

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

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

  • lowTerms are explained for newcomers

    Unexplained terms quietly lock a newcomer out of understanding the rest.

    Checked README § FAQ; it does not show this.

    Fix: Add a short glossary or define terms inline the first time they appear.

  • lowComments help a human read the code

    A newcomer learns the project by reading it; absent context, they stall.

    Checked file tree: index.js; it does not show this.

    Fix: Comment the non-obvious parts with the intent a newcomer would otherwise miss.

  • lowThe data flow is described

    Understanding the data path is often the key to understanding how the code works.

    Checked README § Usage; it does not show this.

    Fix: Add a data-flow explanation or diagram to the docs.

  • lowThe testing strategy is described

    A newcomer who can't figure out the testing strategy will contribute without tests.

    Nothing in the snapshot shows this.

    Fix: Add a section explaining the testing approach: types of tests, how to run them, and what coverage is expected.

  • lowCommon tasks are documented

    A newcomer asked to do a routine task needs the pattern, not just the tools.

    Checked README § Recipes; it does not show this.

    Fix: Document common task patterns as named recipes in a runbook or CONTRIBUTING guide.

  • ✓No oversized source file — A single thousand-line file is a wall a newcomer bounces off.
  • ✓.editorconfig present — Consistent indentation/encoding keeps the code readable and diffs clean for newcomers.
  • ✓Key concepts are explained — A newcomer can't navigate a system whose central ideas are never named. Evidence: README introduction.
  • ✓Deeper docs are discoverable — Docs a newcomer can't find might as well not exist. Evidence: README § Recipes.
  • ✓The code is approachable — A newcomer learns the project by reading its code; cryptic code shuts that door. Evidence: file tree: readme.md.
  • ✓There's something to learn from — Worked examples are the fastest way a newcomer goes from reading to doing. Evidence: README § Usage.
  • ✓There's a suggested place to start — Dropped in with no starting point, a newcomer doesn't know which thread to pull. Evidence: README introduction.
  • ✓The documentation is organised — Information a newcomer can't locate might as well not be written. Evidence: file tree: readme.md.
  • ✓The style is predictable — Inconsistent style makes every new file a fresh puzzle for a newcomer. Evidence: file tree: .editorconfig.
  • ✓The codebase is search-friendly — Cryptic abbreviations break the simplest navigation a newcomer has. Evidence: README § API.
  • ✓The repository root is tidy — The root is the first thing a newcomer navigates; clutter there hides the few files that matter. Evidence: file tree: test.js.
  • ✓The entry point is easy to spot — Knowing where the program starts gives a newcomer a thread to pull when reading the rest. Evidence: file tree: package.json.
  • ✓Tests map clearly to the code they cover — When tests sit beside or mirror their code, a newcomer finds usage examples and a safety net for each file. Evidence: file tree: test.js.

• Path to Contribute

  ✓6 checks passed⚠19 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.

  • mediumHow to contribute is explained

    Goodwill to contribute dies when the how is left as a guessing game.

    Nothing in the snapshot shows this.

    Fix: Add a CONTRIBUTING guide covering the dev setup, the change workflow, and how to open a PR.

  • mediumThe dev setup is documented

    Contributing requires a working dev setup, which is often different from just using it.

    Nothing in the snapshot shows this.

    Fix: Document the development setup distinctly from the end-user install.

  • mediumThe path to a first PR is clear

    A clear path is what converts a willing newcomer into an actual contributor.

    Nothing in the snapshot shows this.

    Fix: Document the end-to-end flow from change to opened PR in CONTRIBUTING.

  • mediumThe local dev loop is documented

    Without a known edit-run-test loop, a contributor can't iterate with confidence.

    Nothing in the snapshot shows this.

    Fix: Document the local loop: how to run the code and tests while developing.

  • 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.

  • lowThere's an obvious place to start

    A newcomer who wants to help needs a small, safe task to start on.

    Nothing in the snapshot shows this.

    Fix: Label a few approachable issues as good-first-issue, or list starter tasks in CONTRIBUTING.

  • lowContribution expectations are clear

    Unstated expectations turn a first PR into a frustrating round of surprises.

    Nothing in the snapshot shows this.

    Fix: State the expectations for a PR — tests, formatting, and any commit/PR conventions.

  • lowMaintainers look responsive

    A newcomer won't invest effort where contributions seem to vanish unanswered.

    Nothing in the snapshot shows this.

    Fix: Triage and respond to issues and PRs; even a quick acknowledgement keeps contributors engaged.

  • lowThe review process is explained

    Not knowing what comes next makes a newcomer hesitant to submit at all.

    Nothing in the snapshot shows this.

    Fix: Describe the review and merge process so contributors know what to expect.

  • lowContributors are recognised

    Recognition is much of what a newcomer gets back for contributing.

    Nothing in the snapshot shows this.

    Fix: Acknowledge contributors — a contributors list or credit in releases.

  • lowA PR template exists

    An unguided first PR is often missing context; a template makes the right information easy to provide.

    Nothing in the snapshot shows this.

    Fix: Add a .github/PULL_REQUEST_TEMPLATE.md guiding contributors on what to include.

  • lowThe commit convention is documented

    Undocumented commit conventions generate review churn for a contributor who guessed wrong.

    Nothing in the snapshot shows this.

    Fix: Document the expected commit format in CONTRIBUTING — even a few examples is enough.

  • lowFork-or-branch policy is stated

    A newcomer who forks when they should branch (or vice versa) starts wrong and needs correction.

    Nothing in the snapshot shows this.

    Fix: State in CONTRIBUTING whether to fork or branch and name the target branch for PRs.

  • lowCI runs on fork contributions

    A contributor who can't run CI has no feedback signal before they are reviewed.

    Checked file tree: .github/workflows/main.yml; it does not show this.

    Fix: Ensure CI runs on external fork PRs (safe read-only jobs) so contributors see a signal before review.

  • lowContribution scope guidance exists

    A newcomer who submits a sprawling first PR learns the hard way what the project expects.

    Nothing in the snapshot shows this.

    Fix: State in CONTRIBUTING that contributions should be focused — one concern per PR.

  • ✓Test command defined — A documented test command lets a contributor check their change before opening a PR.
  • ✓Contributor setup isn't onerous — A heavy contributor setup filters out exactly the casual first-timers you want. Evidence: file tree: package.json.
  • ✓Contributors can run CI's checks locally — A contributor who can reproduce CI locally fixes failures in minutes instead of round-tripping through pushes. Evidence: file tree: package.json.
  • ✓Project scripts say what they do — Clear script names are the contributor's menu; cryptic ones force reading build plumbing before writing a line. Evidence: file tree: package.json.
  • ✓Tests run without private credentials — An outside contributor who can't run the tests can't tell whether their change broke anything. Evidence: file tree: package.json.
  • ✓No heavyweight legal gate on contributions — A CLA to sign before a typo fix turns away casual contributors and anyone who needs employer sign-off. Evidence: License: MIT License.

• Signs of Life

  ✓10 checks passed⚠15 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.

  • mediumReleases or versions are tracked

    Without a release trail a newcomer can't tell what they're getting or whether it's current.

    Nothing in the snapshot shows this.

    Fix: Cut tagged releases and keep a CHANGELOG so versions and changes are legible.

  • mediumMore than one person keeps it going

    A project that rests on one person stalls when they step away, and a newcomer investing time should know that.

    Nothing in the snapshot shows this.

    Fix: List the maintainers or maintaining team in the README or a maintainers file.

  • 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.

  • lowIssues are tended, not piled up

    A neglected tracker tells a newcomer their bug report would go nowhere.

    Nothing in the snapshot shows this.

    Fix: Triage incoming issues regularly — label, respond, and close stale ones.

  • lowThere's somewhere to get help

    A newcomer who gets stuck needs somewhere to turn that isn't a dead end.

    Nothing in the snapshot shows this.

    Fix: Point to a support channel — Discussions, a chat link, or where to ask questions.

  • lowThe project's direction is visible

    A newcomer invests more readily in a project that's clearly going somewhere.

    Nothing in the snapshot shows this.

    Fix: Share a roadmap or near-term plans so newcomers see the direction.

  • lowIssues get responses

    A newcomer won't report or rely on something where problems vanish unheard.

    Nothing in the snapshot shows this.

    Fix: Respond to incoming issues, even briefly, so the tracker looks alive.

  • lowThere is a CI status badge

    A newcomer's first proxy for project quality is whether the build is green — a badge surfaces that immediately.

    Checked README introduction; it does not show this.

    Fix: Add a CI status badge to the README linked to the current pipeline.

  • lowKnown adopters are mentioned

    Knowing others depend on it tells a newcomer the project is worth building on.

    Nothing in the snapshot shows this.

    Fix: Add an 'Used by' or 'Adopters' section to the README, even if small.

  • lowCommunity engagement is visible

    A newcomer's first read of a project's health is how many others are invested.

    Nothing in the snapshot shows this.

    Fix: Surface community signals (badges, stats, or a brief note) in the README.

  • lowMaintenance commitment is stated

    A newcomer choosing between projects needs to know whether this one will still be maintained next year.

    Nothing in the snapshot shows this.

    Fix: State the project's maintenance commitment — actively developed, LTS, or feature-complete.

  • lowReleasing looks like a routine, not an event

    A routine release process means fixes actually ship; without one they tend to pile up on the main branch.

    Checked file tree: .github/workflows/main.yml; it does not show this.

    Fix: Add a release workflow or tool, or document the release steps in the repo.

  • ✓CI configured — Green CI on every change tells a newcomer the project is actively kept working.
  • ✓The project looks maintained — A newcomer hesitates to build on something that looks dead. Evidence: file tree: .github/workflows/main.yml.
  • ✓Docs keep pace with the project — Docs that lag the code erode a newcomer's trust in everything else they read. Evidence: file tree: readme.md.
  • ✓There's recent activity — A long-silent repo tells a newcomer they'd be building on abandoned ground. Judged from the snapshot as a whole; no single section settles it.
  • ✓A newcomer can pin a version — Without a pinnable release a newcomer can't build on stable ground. Evidence: file tree: package.json.
  • ✓No unaddressed neglect warnings — An unaddressed neglect notice tells a newcomer to look elsewhere. Evidence: file tree: readme.md.
  • ✓A security policy is visible — Without a stated security policy a newcomer who finds a vulnerability doesn't know what to do with it. Evidence: file tree: .github/security.md.
  • ✓Declared dependencies look current — Dependencies frozen years back are a quiet sign nobody has touched the project, and they rarely install cleanly today. Evidence: manifest: package.json.
  • ✓Build and CI tooling is current — Config for a CI service or build tool retired years ago tells a newcomer the plumbing hasn't been touched since. Evidence: file tree: .github/workflows/main.yml.
  • ✓Tests reach the main areas of the code — Broad tests mean a newcomer's change is caught if it breaks something, and show the project is cared for. Evidence: file tree: test.js.

• Open Door

  ✓11 checks passed⚠11 problems 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).

  • lowSecurity policy

    A SECURITY.md tells a newcomer how to report a problem responsibly.

    Fix: Add a SECURITY.md describing how to report a vulnerability.

  • lowThe project feels inclusive

    Subtle exclusion in the framing quietly narrows who feels they belong.

    Nothing in the snapshot shows this.

    Fix: Use inclusive language and a code of conduct that signals everyone is welcome.

  • lowCommunity expectations are set

    Stated ground rules are what make a newcomer feel safe to step in and ask.

    Checked file tree: .github/security.md; it does not show this.

    Fix: Add a CODE_OF_CONDUCT.md stating the expectations for interaction.

  • lowQuestions are explicitly welcomed

    A newcomer who isn't sure questions are welcome stays stuck in silence.

    Nothing in the snapshot shows this.

    Fix: Explicitly invite questions and name where to ask (Discussions, chat, issues).

  • lowIssue templates are provided

    An unguided first issue report is often incomplete; a template makes the right information easy to provide.

    Nothing in the snapshot shows this.

    Fix: Add .github/ISSUE_TEMPLATE/ with templates for bug reports and feature requests.

  • lowNon-code contributions are welcomed

    Many potential contributors don't feel confident coding but could meaningfully help in other ways.

    Nothing in the snapshot shows this.

    Fix: Mention in CONTRIBUTING that non-code contributions (docs, design, triage) are valued.

  • lowDecision-making is transparent

    Opaque decision-making signals to a newcomer that their input won't matter even if they engage.

    Nothing in the snapshot shows this.

    Fix: Make significant decisions public — RFCs, GitHub Discussions, or published meeting notes.

  • lowThe roadmap is public

    A newcomer who wants to contribute strategically needs to know where the project is going.

    Nothing in the snapshot shows this.

    Fix: Publish a roadmap in ROADMAP.md or as GitHub milestones so newcomers can align their contributions.

  • lowThe language barrier is considered

    A project that silently assumes native fluency excludes a large group of potential contributors.

    Nothing in the snapshot shows this.

    Fix: State that non-native language contributions are welcome and that imperfect prose is fine.

  • lowResponse expectations are set honestly

    Clear expectations keep a newcomer from reading slow replies as rejection, or from waiting on help that isn't coming.

    Nothing in the snapshot shows this.

    Fix: Add a line to the README or support docs describing how and how quickly issues and questions are handled.

  • ✓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.
  • ✓The terms of use are clear — Without clear terms a newcomer can't safely adopt the project at all. Evidence: License: MIT License.
  • ✓It doesn't assume an insider's background — Assumed background is an invisible wall a newcomer keeps walking into. Evidence: README § Install.
  • ✓The entry barrier is low — Every hoop before the first win is a place a newcomer drops off. Evidence: README § Install.
  • ✓Contribution terms are clear — Unclear contribution terms are a legal question a cautious newcomer won't resolve alone. Evidence: License: MIT License.
  • ✓It accommodates different skill levels — Material pitched only at experts shuts the door on most newcomers. Evidence: README § Recipes.
  • ✓No surprise gating of core use — A bait-and-switch on core functionality burns a newcomer's goodwill instantly. Evidence: License: MIT License.
  • ✓There are clear next steps — A newcomer who succeeds once and then hits a void quietly drifts away. Evidence: README § Recipes.
  • ✓The license is stated the same way everywhere — Conflicting license statements leave a newcomer unsure which terms actually apply to them. Evidence: License: MIT License.
  • ✓An 'open source' claim matches the license — A newcomer who reads 'open source' and later finds non-commercial or source-available terms has been misled. Evidence: License: MIT License.