The web framework for content-driven websites.
Opens with four sections on how to approach work, before any repository detail.
This file points the agent at 3 other documents in the repository. Open any of them to read it here, as it was at this commit.
├── .agents │ └── skills │ └── writing-comments │ └── └── reference ├── └──
File measured on main at commit 5be09d6. Analysis written 2026-09-14. Star count is a snapshot from September 2026.
The first third contains no Astro-specific content: it covers stating assumptions, scope, and success criteria. The rest is a tooling guide covering the monorepo layout, test invocation, background dev servers and browser automation.
Quoted lines are verbatim from the file. Open one to see it where it sits.
Behavioral framing
Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution. None reference Astro. They address stating assumptions out loud, building only what was asked, leaving adjacent code alone, and defining what done means before starting.
The Surgical Changes section ends with a test the agent can apply to its own diff line by line, rather than a disposition to hold.
House vocabulary
A comment must state something the reader cannot recover from the code, written for someone reading at HEAD months later with no access to the conversation or the diff. Narrating change history and addressing the reviewer are both listed as prohibited.
Three conversions are given: "fix the bug" becomes "write a test that reproduces it, then make it pass". The stated reason is that criteria the agent can check let it iterate without returning to ask.
The browser automation section covers the case where the tool is missing and no human is available to install it. It directs the agent to fail the job rather than work around the absence.
Dev servers are started through a four-command lifecycle, start, logs, status and stop, with a force flag for replacing a stale one. Backgrounding a server with an ampersand is listed as the thing not to do.
Astro's file tells an agent how the codebase works. It cannot tell it which bug three customers hit this week. Modem keeps that context current and attaches it to the work.