The web framework for content-driven websites.
Opens with four sections on how to approach work, before any repository detail.
├── .agents │ └── skills │ └── writing-comments │ └── └── reference ├── └──
The file, explained
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 passages are verbatim. Open one to see it in the source.
01 / 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.
Source excerpt starting at line 3.**Don't assume. Don't hide confusion. Surface tradeoffs.**
02 / From this file
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.
Source excerpt starting at line 40.The test: Every changed line should trace directly to the user's request.
03 / 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.
Source excerpt starting at line 75.- Deletion test: a comment must state something the reader cannot recover from the code. If names or types already carry it, don't write it.
04 / From this file
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.
Source excerpt starting at line 60.Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
05 / From this file
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.
Source excerpt starting at line 153.Note: `agent-browser` should be installed globally, and is not a dependency of this monorepo. If `agent-browser` isn't available on this machine, ask the user to run `npm install -g agent-browser && agent-browser install`. If you are running in headless mode with no human operator and need this tool to complete your job, it is best to fail the job vs. trying to work around not having the tool.
06 / From this file
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.
Put it to work
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.
Try Modem