Astro Agent Rules

The web framework for content-driven websites.

Overview

The first third is not Astro-specific. It covers assumptions, scope, and success criteria. The rest maps the monorepo and explains tests, background development servers, and browser automation.

Documents

├── 
├── .agents
│   └── skills
│       └── writing-comments
│           └── 
└── reference
    ├── 
    └──

Patterns in this file

Behavioral framing Router files Hard prohibitions House vocabulary

01 / Behavioral framing

Four framing sections before any repository detail

Four general sections come first: Think Before Coding, Simplicity First, Surgical Changes, and Goal-Driven Execution. They cover assumptions, scope, adjacent code, and completion criteria.

Source excerpt starting at line 3.
3**Don't assume. Don't hide confusion. Surface tradeoffs.**

A one-line test for scope

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.
40The test: Every changed line should trace directly to the user's request.

03 / House vocabulary

A deletion test for comments

Keep comments only when the code cannot recover the information. Write for someone reading HEAD months later, without the conversation or diff; never narrate change history or address a reviewer.

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.

Tasks rewritten as verifiable loops

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.

60Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

An instruction to fail rather than substitute

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.

153Note: `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.

A managed lifecycle for long-running servers

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.

Ideas for your repo

Open with general working rules that transfer across repositories before adding project-specific guidance.
Give scope creep a one-line test the agent can run against its own diff.
Adopt the deletion test for comments. It addresses the "this now correctly handles" habit in one rule.
Document the full lifecycle for long-running processes: start, logs, status, and stop.