# AGENTS.md

<!-- Replace every placeholder. Delete anything that does not apply. A short accurate file beats a long aspirational one. -->

One line: what this project is and who uses it.

## Project

Stack: <languages, framework, database, hosting>.

Where things live:

- `src/` application code
- `src/lib/` shared helpers
- `tests/` tests, mirroring the source tree
- `scripts/` one off and maintenance scripts
- `docs/` documentation

Entry points: <the two or three files that explain how the app starts and how requests flow>.

Anything unusual a newcomer would trip over: <describe it here, or delete this line>.

## Commands

```bash
<install>            # install dependencies
<dev>                # run locally
<build>              # production build
<test>               # run the test suite
<test one file>      # run a single test while iterating
<lint>               # lint
<typecheck>          # type check, if the language has one
```

Use <package manager> only. The lockfile is <lockfile name>.

Run <lint> and <test> before returning work.

## Code style

Keep this list short and specific. Add a rule the second time you have to correct the same thing.

- Formatting is handled by <formatter>. Do not hand format.
- <a naming convention that is actually enforced here>
- <where business logic belongs, and where it does not>
- <how errors are handled: exceptions, result types, logging>
- <how configuration is read: never inline, always through one module>
- No commented out code and no TODO without an owner.

## Boundaries

Do not touch without explicit instruction:

- `.env` and any file containing a credential. New variables go in `.env.example` with an empty value.
- The lockfile. Add dependencies through the package manager so the diff stays minimal.
- Generated code and build output: <list the directories>.
- Database migrations that have already been applied.
- `.github/workflows/` and deployment configuration.

Needs human review before merge: <auth, payments, anything that deletes data, anything that talks to a customer>.

If a task appears to require one of these, describe the change and stop.

## Testing

- Run the suite with <test command>. Run one file with <single test command>.
- Must have tests: <the layer where bugs actually hurt, for example business logic and API handlers>.
- Does not need tests: <the layer where tests are not worth it here>.
- A bug fix ships with a test that fails without the fix.
- Do not weaken a test to make it pass. If the expected behavior changed, say so in the PR.

## Git workflow

- Branch from `<default branch>`: `feat/short-description`, `fix/short-description`, `chore/short-description`.
- Conventional commits: `feat(scope): add thing`, `fix(scope): correct thing`. Imperative mood, lowercase subject, no trailing period.
- One logical change per commit. Do not mix a refactor with a behavior change.
- Never commit directly to `<default branch>` and never force push a shared branch.
- PR description: what changed, why, and how it was verified. Note any migration, environment variable, or manual step.