A polished, well-documented mega-project that's ready for newcomers on the surface—but the monorepo complexity and hefty prerequisites quietly raise the bar for meaningful contribution.
last scored 2026-06-15
Readiness lenses
The same repo, two ways: how ready it is for an AI coding agent, and for a human newcomer. Switch lenses to see each one's score and checks.
How ready the repo is for an AI coding agent to read, build, and operate it.
24 of 35 checks passed across 6 categories.
Machine Orientation
7 checks passed1 problem found
- 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.
- README present — An agent reconstructs what the repo is and how to work in it from the README first.
- Agent instructions file — AGENTS.md / CLAUDE.md is the direct, machine-read channel for entry points and conventions.
- Agent instructions stay lean — A bloated instructions file burns context and measurably hurts more than it helps.
- 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.
- Architecture doc — An ARCHITECTURE doc hands an agent the module map instead of making it infer one.
- Contribution conventions are written down — A contributor guide is where an agent learns the branch, commit, and review conventions it must follow.
Reproducible Setup
5 checks passed1 problem found
- 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.
- 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.
- Version pins are exact — A floating pin (a bare major, or a range) still drifts between installs.
- Container or dev-container — A Dockerfile / compose / devcontainer removes 'works on my machine' from setup.
- Dev container — A .devcontainer gives an agent a one-command, fully-declared environment.
Code Navigability
1 check passed1 problem found
- lowTypeScript strict mode on
Strict typing gives an agent typed signatures to anchor an edit on, not guesses.
Fix: Turn on `strict` in tsconfig.json.
- Conventional source layout — A recognised src/ · lib/ · app/ layout lets an agent localise code without spelunking.
Verification Surface
6 checks passed1 problem found
- 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.
- Tests present — Runnable tests are the ground truth an agent checks its own edits against.
- Test command defined — A `test` script is the documented, discoverable way to run the suite.
- Lint command defined — A linter an agent can run catches a class of mistakes before they ship.
- CI configured — Readable CI is the feedback loop an agent reads to know what 'green' means here.
- Typecheck command — A typecheck script lets an agent catch type errors before they ship.
- Build command — A documented build command is the discoverable way for an agent to produce artifacts.
Agent Safety
4 checks passed4 problems found
- highNo committed .env
A tracked real .env hands secrets to anything — including an agent — that reads the repo.
Fix: Remove the .env from history, gitignore it, and ship a .env.example instead.
- 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.
- 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.
- 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
1 check passed3 problems found
- mediumDependencies not vendored in
A committed node_modules / vendor tree drowns the real signal an agent needs.
Fix: Remove the vendored dependency directory and gitignore it.
- 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).
- lowNo oversized source file
A single file in the hundreds of KB blows past an agent's effective context window.
Fix: Split the largest files along their natural seams.
- Build output not committed — Generated dist/ · build/ output is noise an agent has to read past.
How ready the repo is for a human newcomer to understand, set up, and contribute.
78 / 10019 of 25 checks passed across 6 categories.
First Impression
88Clear, welcoming README with purpose, live demos, and a professional homepage.
The README immediately communicates what Astro is ('website build tool for the modern web'), includes CI badges, install instructions, and links to official docs and Discord. The project has 60k+ stars and an active sponsor roster, signaling maturity. However, the snapshot doesn't show a high-level architecture diagram or quick technical overview for deeper understanding.
Getting Running
72Explicit prerequisites and clear setup steps, but monorepo complexity and pnpm workspaces add friction for beginners.
CONTRIBUTING.md lists Node >=22.12.0 and pnpm ^10.28.0 with Corepack guidance; build, dev, and test commands are documented. However, the setup requires understanding pnpm workspaces, top-level install discipline, and running `pnpm run build` before you can do anything—that's four steps before testing changes. The snapshot shows 6000+ files and dozens of packages; a newcomer won't know which example to run first to verify their setup works.
Finding Your Way
68Directory table helps, but the 6000-file monorepo and lack of visible architecture docs make navigation daunting.
The README includes a package directory table with links, and the file tree shows sensible structure (packages/integrations, packages/language-tools). However, there is no architecture.md, codebase tour, or mental-model guide in the root; the project mentions `.agents/skills/astro-developer/architecture.md` but that's internal tooling docs, not newcomer-facing. A human will struggle to find where to make a first fix without reading 10+ package.json files.
Path to Contribute
80CONTRIBUTING.md exists and covers local setup, testing methods, and links to issue labels—but workflow and PR conventions need more detail.
The guide covers prerequisites, workspace setup, dev/build/test commands, and references examples and local linking. It mentions writing tests and offers multiple testing strategies. However, it lacks explicit beginner-labeled issues, issue/PR templates (beyond a PR template stub visible in the file tree), coding conventions (STYLE_GUIDE.md exists but not shown here), and clear guidance on what constitutes a ready-to-review PR in a 6000-file project.
Signs of Life
85Active, recent commits (last pushed 2 days ago) and heavy CI/automation infrastructure signal a healthy, well-staffed project.
The repo was pushed 2026-06-15, has 157 open issues (not stale), 60k stars, active sponsorships, and the file tree shows extensive GitHub Actions workflows (check.yml, ci.yml, release.yml, etc.) and changeset automation. The agent infrastructure (.agents/, .flue/) suggests sophisticated automation and ongoing active maintenance. This is clearly not a one-person effort.
Open Door
82MIT license, Code of Conduct, and community governance are clear—but governance docs are in an external org folder, not the main repo.
The README links to LICENSE (MIT), Code of Conduct, and Governance in withastro/.github/; SECURITY.md exists. However, the CoC and governance live outside the repo root, which could confuse newcomers (they may not know to look in the org-level .github folder). The snapshot shows no explicit 'where to ask for help' besides Discord in the README; a dedicated help or support doc would lower friction.
First Impression
3 checks passed0 problems found
- 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.
Getting Running
5 checks passed1 problem found
- 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.
- 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.
- One-command environment — A Dockerfile / compose / devcontainer turns a fiddly setup into one command.
- One-click dev container — A .devcontainer lets a newcomer start in a cloud IDE with zero local setup.
- Versions pinned exactly — A floating version still drifts — a newcomer can hit a break the maintainer never saw.
Finding Your Way
2 checks passed1 problem found
- lowNo oversized source file
A single thousand-line file is a wall a newcomer bounces off.
Fix: Split the largest files along their natural seams.
- Conventional source layout — A familiar src/ · lib/ · app/ layout lets a newcomer guess where things live.
- Architecture / overview doc — An overview hands a newcomer the map instead of making them reconstruct it.
Path to Contribute
5 checks passed1 problem found
- 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.
- CONTRIBUTING guide — A CONTRIBUTING guide is the difference between a guessed and a guided first PR.
- Issue templates — Issue templates show a newcomer how to file something useful — and that contributions are welcome.
- Pull-request template — A PR template tells a first-time contributor what a good change includes.
- Test command defined — A documented test command lets a contributor check their change before opening a PR.
- Lint command — A linter lets a first-time contributor catch style issues before review.
Signs of Life
2 checks passed1 problem found
- lowAutomated dependency updates
Dependabot / Renovate activity is a visible heartbeat of ongoing maintenance.
Fix: Enable Dependabot or Renovate.
- Tests present — A test suite signals a project that's cared for, not abandoned.
- CI configured — Green CI on every change tells a newcomer the project is actively kept working.
Open Door
2 checks passed2 problems found
- lowLicense is a standard one
A non-standard or custom license is a legal question mark a newcomer won't resolve.
Fix: Use a recognised OSI license so reuse terms are unambiguous.
- 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.
- Security policy — A SECURITY.md tells a newcomer how to report a problem responsibly.
Where the grip slips
- highFinding Your Way+14 pts if fixed
Monorepo size and lack of codebase tour make navigation overwhelming
The file tree shows 6000+ files across dozens of packages. CONTRIBUTING.md tells you how to run tests but not where the core compiler lives, how modules relate, or which package to edit for a specific feature. A newcomer will spend an hour just trying to locate the right file.
Fix: Create or surface a codebase-tour.md in the root (or link to .agents/skills/astro-developer/architecture.md if it's suitable). Include: (1) diagram or ASCII chart of core packages and their relationships, (2) which file to touch for common fixes (e.g., 'SSR behavior' → packages/astro/src/vite-plugin-ssr.ts), (3) quick pointer to the compiler repo.
- highPath To Contribute+12 pts if fixed
Missing beginner-labeled issues and no explicit 'first good issue' guide
A newcomer viewing the repo sees 157 open issues but has no way to find 'good-first-issue' or 'help-wanted' labels, and no guide on which issue sizes are appropriate for a first contribution. This leaves new contributors uncertain where to start and increases the risk they'll abandon the project.
Fix: Add a 'For New Contributors' section to CONTRIBUTING.md linking to GitHub's issue label filter (e.g., 'good-first-issue' and 'help-wanted') and list 3–5 recent, small, well-scoped examples. Create or label 5–10 issues as 'good-first-issue' explicitly.
- mediumGetting Running+8 pts if fixed
Setup requires build before running examples; unclear which example to test first
CONTRIBUTING.md says to run `pnpm install && pnpm run build` before testing, but doesn't tell a newcomer which of the 30+ examples in /examples to run first to validate their setup. A newcomer will try `pnpm --filter @example/minimal run dev` blindly and may hit unexpected errors if the build missed something.
Fix: Add a 'Verify Your Setup' subsection after the build command in CONTRIBUTING.md: 'Run `pnpm --filter @example/minimal run dev` to start a dev server. You should see a page at http://localhost:3000. If it fails, check [Troubleshooting](#troubleshooting).' Also add a Troubleshooting section with common errors (e.g., 'pnpm install must run from repo root').
- lowOpen Door+5 pts if fixed
Code of Conduct and governance live in external org repo, not visible here
The README links to CODE_OF_CONDUCT.md and GOVERNANCE.md in 'withastro/.github', not this repo. A newcomer reading the main repo will not see these files and may not discover them, reducing the sense of psychological safety and clarity on decision-making.
Fix: Add a CONDUCT.md or CoC section to the root README that either copies or embeds the key points of the org's CoC, with a link to the full version. Alternatively, add a brief 'Community & Governance' link section to the main CONTRIBUTING.md.
- lowGetting Running+4 pts if fixed
pnpm version pinned but no error message if version is wrong
The package.json specifies 'pnpm@11.5.0' and engines 'node@>=22.12.0', but there's a preinstall script that says 'only-allow pnpm'. If a newcomer uses npm or yarn, they'll see a terse error. If they use an old pnpm, they'll get cryptic lockfile errors.
Fix: Add a .npmrc or .pnpmrc file with clear comments, and improve the error message in the preinstall script to say 'This repo uses pnpm >=11.5.0. Please upgrade: pnpm add -g pnpm' or reference a docs section on this.
- lowPath To Contribute+4 pts if fixed
STYLE_GUIDE.md exists but is not linked or referenced in CONTRIBUTING.md
The file tree shows STYLE_GUIDE.md exists, but CONTRIBUTING.md doesn't mention it or link to coding conventions. A newcomer won't know if they should follow it, what it covers, or if PRs will be rejected for style violations.
Fix: Add a 'Code Style & Conventions' section to CONTRIBUTING.md with a direct link to STYLE_GUIDE.md and a one-sentence summary of what it covers (e.g., 'We use Biome for linting and Prettier for formatting; see STYLE_GUIDE.md for conventions').
Show your score
[](https://latch.fyi/withastro/astro)Share this analysis
https://latch.fyi/withastro/astroFixed some issues? Re-analyze to measure your progress →
Copy the whole report
Grab the entire verdict in one go — a Markdown block for a README or an issue, plain text, or a prompt you can paste straight into an LLM.