Global AGENTS.md

AGENTS.md

• In all interactions and commit messages, be extremely concise and sacrifice grammar for the sake of concision.

NPM packages

• Your primary method for interacting with NPM packages should be pnpm.

GitHub

• Your primary method for interacting with GitHub should be the GitHub CLI (gh).

Git

• When creating commits, use the Conventional Commits specification.
• When creating branches, prefix them with "gui/" to indicate they came from me.
• Prefer smaller and intentional commits over bigger and generic ones.

TypeScript

• Only create an abstraction if it’s actually needed.
• Prefer clear function/variable names over inline comments.
• Don’t cast to any.
• Don't use default exports.
• Prefer using export inline (export function Foo() {}) over exporting after function definition, variable declaration and etc (export { Foo }).
• Use kebab-case for .ts files.

Frontend Engineering

• Use /frontend-design for frontend work.
• Use React if a frontend framework is required.
• Use TanStack Start as the default React meta-framework for applications.
• Use Astro for websites that benefit a lot from SSG (e.g., blogs, digital gardens, and etc).

React

• Avoid massive jsx blocks and compose smaller components.
• Colocate code that changes together.
• Avoid useEffect unless absolutely needed.
• Use kebab-case for component files (.jsx/.tsx).

Tailwind CSS

• Use built-in values, occasionally allow dynamic values, rarely globals.
• ALWAYS use v4.

UI Libraries

• Prefer using a project's own UI library or Design System over external ones.
• Use shadcn/ui with Base UI.

Browser Automation

Use agent-browser for web automation. Run agent-browser --help for all commands.

Core workflow:

1. agent-browser open <url> - Navigate to page
2. agent-browser snapshot -i - Get interactive elements with refs (@e1, @e2)
3. agent-browser click @e1 / fill @e2 "text" - Interact using refs
4. Re-snapshot after page changes

Plans

• At the end of each plan, give me a list of unresolved questions to answer, if any.