Agents

Agents in this repository are expected to work from local instructions, not memory alone. The goal is to make agent work predictable, reviewable, and aligned with the architecture of this product.

The main entry point is AGENTS.md. It tells agents which rules are always active and which skill files to read for specialized work.

Rules

Rules are strict project expectations. They protect the codebase from common mistakes and keep agent changes consistent with how the app is built.

The required rule sources are:

Important rules from AGENTS.md include:

• Read skills/behavioral-guidelines.md and skills/project-rules.md before making changes.
• Ask before adding, modifying, or expanding tests.
• Put feature owned tests under src/features/<feature>/tests/.
• Use App Router patterns only. Do not use Pages Router APIs.
• Read the relevant Next.js docs from node_modules/next/dist/docs/ before writing Next.js code.
• Read skills/SEO.md before changing metadata, robots, sitemap, structured data, indexing behavior, or SEO copy.
• Read skills/i18n.md before changing locale routing, translation keys, shared strings, or interpolation.
• Read skills/audit.md when the user asks for a review, audit, investigation, or thorough check.
• Log failures in server side async work with enough context to identify the affected job, route, provider, user, chat, or event.
• Avoid ternary component branches in JSX. Prefer explicit readable branches.
• Keep shared state selectors readable and stable.
• Be careful with inline callbacks and freshly allocated objects in expensive render surfaces.

These rules exist because agents can otherwise make changes that look reasonable in isolation but violate local patterns. The rules keep edits small, feature owned, typed, and easier for a human maintainer to review.

Skills

Skills are focused instruction files for work that needs extra context. They give an agent a narrower playbook for a specific domain instead of making every task depend on one huge rule file.

The repository currently has these skills:

Why Skills Exist

Skills make agent behavior modular.

For example, a normal UI change needs the behavioral and project rules. A metadata change also needs the SEO skill. A translation change also needs the i18n skill. A review request needs the audit skill and a different response style from a build request.

This keeps the agent from loading every detail for every task, while still making domain specific work precise when it matters.

How Agents Should Use Them

Agents should start with AGENTS.md, then read the required skill files for the task.

For implementation work, the usual flow is:

1. Read the relevant rules and skill files.
2. Inspect the existing feature structure.
3. Make the smallest change that solves the request.
4. Ask before changing tests.
5. Run the relevant verification command.
6. Report what changed and what was verified.

For review work, the agent should follow skills/audit.md: clarify scope, inspect the code, lead with findings, and avoid making fixes unless the user asks.

Updating Agent Guidance

Use AGENTS.md for rules that must apply broadly across the repository.

Use a skill file when the guidance is domain specific, long enough to distract from the root rules, or only relevant for certain kinds of tasks.

Keep skill files practical. A good skill tells the agent when it applies, what to inspect, what patterns to follow, and what mistakes to avoid.