Agent Rules Pack

Agent instructions: [Project name]

These rules apply to every coding agent that works in this repository, and to the people who review its work. Replace everything in [square brackets]. Delete any line that does not apply. A short, accurate file beats a long, stale one.

Project

• What it is: [One or two sentences. What the project does, who uses it, and what matters most, for example correctness of invoices or uptime of the public API.]
• Language and framework: [e.g. TypeScript with React and Node.js, or Python with FastAPI].
• Runtime versions: [e.g. Node.js 22, Python 3.12]. Use these versions. Do not upgrade them as a side effect of a task.
• Package manager: [npm / pnpm / yarn / uv / poetry / pip]. Use only this one.
• Layout:
• [src/] application code
• [tests/] tests
• [scripts/] maintenance and one-off scripts
• [docs/] documentation and decision records
• Start here: [entry point, main module or architecture document].
• Do not edit: [generated folders, vendored code, lock files by hand, migrations that have already run].

Commands

Use the scripts above. Do not switch package managers, add new tooling or change these commands unless the task is about tooling.

Code conventions

• Follow the formatter and linter configuration in the repository. Do not change their settings to make your code pass.
• Names say what a thing is or does. Avoid abbreviations that a new team member would have to guess.
• Keep functions small and focused. Return early instead of nesting deeply.
• Handle an error where you can do something useful about it. Otherwise let it propagate with context. Never swallow an exception silently.
• Comments explain why, not what. Delete commented-out code instead of leaving it behind.
• Keep public interfaces stable: HTTP APIs, exported functions, database columns, configuration keys, CLI flags and event names. Change them only when the task says so, and call the change out in your summary.
• Match the style of the file you are editing, even where you would have chosen differently.
• [Project-specific rule, for example: all money values are integers in the smallest currency unit.]
• [Project-specific rule, for example: dates are stored in UTC and converted only for display.]

Dependencies

• Do not add, remove or upgrade a dependency without asking first.
• When a new dependency is approved, choose a maintained, widely used package, install it with the project's package manager and commit the updated lock file.
• Prefer the standard library or an existing dependency over a new one for small tasks.

Testing

• New behaviour comes with tests. A bug fix comes with a test that fails before the fix and passes after it.
• Put tests next to the existing tests for that code and reuse their helpers and fixtures.
• Tests must not depend on the network, the real clock, random values without a seed, test order or shared state.
• Never delete, skip or weaken a test to make the suite pass. If you believe a test is wrong, say so and explain why.
• Full testing rules: [link to rules/testing.md or your own document].

Working style

• Read before you write. Look at the code around the change and the tests that cover it.
• Keep each change focused on the task. Do not rename, reformat or refactor unrelated code in the same change.
• Prefer editing existing files to creating new ones. Do not add documentation files unless asked.
• Ask before you start when:
• the request is ambiguous or has more than one reasonable reading
• the change would touch more than [10] files
• the change needs a new dependency, a schema change or a new environment variable
• you would need to change a public interface
• When you make an assumption, write it down in your summary.
• If you get stuck after two honest attempts at the same problem, stop and report what you tried instead of trying random changes.

Security and secrets

• Never commit secrets, tokens, API keys, passwords, private keys, session cookies or real customer data.
• Configuration comes from environment variables or the secret store. Keep .env files out of git. List variable names, without values, in .env.example.
• Never print a secret value in output, logs, tests, fixtures, screenshots or commit messages. Refer to it by name.
• Validate all external input at the boundary: requests, webhooks, uploaded files, queue messages and responses from third-party APIs.
• Use parameterised queries. Never build SQL, shell commands, file paths or HTML from input by string concatenation.
• Check authorisation on the server for every action and every object, not only in the user interface.
• Do not send code or data to outside services unless the task requires it.
• If you find a secret in the code, stop, report its location (not its value) and recommend rotating it.
• Full security rules: [link to rules/security-and-secrets.md or your own document].

Never do without explicit approval in this conversation

• Run destructive commands: rm -rf, git reset --hard, git clean -fdx, git checkout -- . or git restore . over uncommitted work, dropping or truncating tables, deleting cloud resources or storage buckets.
• Force push, rewrite published history, or delete remote branches or tags.
• Push directly to main, master or a release branch, merge a pull request, publish a package or deploy.
• Run migrations or scripts against shared, staging or production databases.
• Change CI/CD pipelines, infrastructure, DNS, authentication, permissions or billing configuration.
• Disable or skip tests, lint rules, type checks or security controls to get a passing build.
• Install global tools, change system settings or edit files outside this repository.
• Read or copy files that hold real credentials, such as .env, key files or cloud credential folders.
• Send email, messages or webhooks to real recipients.

Approval for one of these actions covers that action only. Ask again for the next one.

Git, commits and pull requests

• Branch names: type/short-description, for example fix/login-redirect or feat/csv-export.
• Commit messages follow Conventional Commits: type(scope): summary in the imperative mood, 72 characters or fewer. Types: feat, fix, docs, refactor, test, perf, build, ci, chore, revert. Use the body to explain why. Mark a breaking change with ! after the type and a BREAKING CHANGE: footer.
• One logical change per commit. Keep formatting-only changes in their own commit.
• Create commits only when asked. Never commit build output, local configuration, editor files or logs.
• Pull request descriptions cover:
• what changed and why
• how it was tested, with the commands you ran
• screenshots for user interface changes
• risks and how to roll back
• the linked issue: [issue tracker link format]

Before you say done

1. Run the format check, linter, type checker and tests from the Commands table. If something fails and you cannot fix it, report exactly what fails and why.
2. Run the build if the project has one.
3. Read your own diff from top to bottom. Remove debug output, commented-out code, stray files and anything that looks like a secret.
4. For user-facing changes, check the result in the running app where you can.
5. Summarise:

• what changed and why
• the files you touched
• the commands you ran and their results
• what you could not verify
• assumptions and follow-up work

Never say that something works, passes or is fixed unless you ran it and saw the result. "I could not run this" is a useful answer. A confident guess is not.

Maintaining this file

Owner: [team or person]. Last reviewed: [YYYY-MM-DD]. Keep it under about 200 lines. When a rule stops being true, change it in the same pull request as the code that changed it.

Working rules for [Project name]

You are a coding agent working in this repository. Read this whole file before your first change. It is the only instruction file you need. If the repository also has an AGENTS.md, the two say the same thing, and AGENTS.md wins if they ever disagree.

Replace everything in [square brackets] and delete lines that do not apply.

1. The project in brief

• [One or two sentences: what the project does, who uses it, what matters most.]
• Stack: [language, framework, runtime versions].
• Package manager: [name]. Use only this one.
• Code lives in [src/], tests in [tests/], scripts in [scripts/].
• Start reading at: [entry point or architecture document].
• Never edit by hand: [generated folders, vendored code, lock files, applied migrations].

2. Commands you may run

Do not invent other commands for these jobs, switch package managers or add tooling.

3. Hard stops: ask first, every time

Stop and ask for explicit approval in this conversation before you:

• run a destructive command (rm -rf, git reset --hard, git clean -fdx, discarding uncommitted work, dropping or truncating data, deleting cloud resources)
• force push, rewrite published history or delete remote branches or tags
• push to main, master or a release branch, merge, publish a package or deploy
• run a migration or script against a shared, staging or production database
• change CI/CD, infrastructure, DNS, authentication, permissions or billing
• skip or disable a test, lint rule, type check or security control
• add, remove or upgrade a dependency
• install a global tool, change system settings or edit files outside this repository
• open, print or copy a file that holds real credentials
• send email, messages or webhooks to real recipients

One approval covers one action. Ask again for the next.

4. Secrets and data

• Never write a secret into code, tests, fixtures, logs, output or commit messages. Refer to secrets by variable name only.
• Configuration comes from environment variables. New variables go into .env.example with an empty or obviously fake value.
• Use only fake data in examples and tests: Example Co, [email protected], +1 555 0100.
• If you notice a real secret in the repository, stop. Report the file and line, not the value, and recommend rotating it.
• Validate every external input at the boundary. Use parameterised queries. Never build SQL, shell commands, paths or HTML from input by joining strings.
• Check permissions on the server for every action and every object.

5. How to write code here

• Read the surrounding code and its tests first. Follow the patterns already in use.
• Keep the change focused. No unrelated renames, reformatting or refactors.
• Prefer editing existing files to creating new ones.
• Small functions, clear names, early returns. Handle errors where you can act on them; never swallow them.
• Comments explain why. Delete commented-out code.
• Keep public interfaces stable unless the task says otherwise: APIs, exported functions, database columns, configuration keys, CLI flags.
• Respect the formatter and linter settings. Never change them to make your code pass.
• [Project-specific rule.]
• [Project-specific rule.]

6. Tests

• New behaviour needs tests. A bug fix needs a test that fails without the fix.
• Tests do not touch the network or the real clock, do not rely on order and do not share state.
• Never delete, skip or loosen a test to get green. If a test looks wrong, explain why and ask.

7. When to ask instead of guessing

• The request has more than one reasonable reading.
• The change would touch more than [10] files.
• The change needs a schema change, a new environment variable or a public interface change.
• You have tried the same fix twice and it still fails.

Otherwise, proceed, and write down any assumption you made.

8. Git

• Branches: type/short-description.
• Commits: Conventional Commits, type(scope): summary, imperative mood, 72 characters or fewer. Explain why in the body.
• One logical change per commit. Commit only when asked.
• Never commit build output, local configuration, editor files or logs.

9. Before you report back

1. Run format check, lint, type check and tests. Fix what you can. Report exactly what still fails.
2. Run the build if there is one.
3. Read your whole diff. Remove debug output, stray files and anything that looks like a secret.
4. Check user-facing changes in the running app where you can.
5. Report: what changed and why, files touched, commands run with results, what you could not verify, assumptions and follow-ups.

Only say something works if you ran it and saw it work.

Changelog

• 1.0.0, 22 October 2026: first release

Agent Rules Pack

Version 1.0.0

A set of rules files that teach a coding agent how your team works: the commands to run, the conventions to follow, what it must never do without asking and how to report its work honestly. The same rules come in the formats that different agents and editors read, so you write them once and every tool on the team follows them. It also includes a checklist for reviewing what the agent produces.

Who it's for

• Teams that use one or more coding agents on a shared repository
• Solo developers who want an agent to stop guessing at commands and conventions
• Tech leads who review agent-made pull requests and want a consistent standard

How to use it in 5 minutes

1. Copy AGENTS.md to the root of your repository and fill in the Project and Commands sections. Delete lines that do not apply.
2. Copy rules/ into the repository as well, or move its contents into your own docs folder and update the two links in AGENTS.md.
3. Check which file names your agents read (see "The formats" below) and copy only the matching files across.
4. Paste prompts/start-of-task.md into your agent at the start of the next task.
5. When the change comes back, review it with review-checklist.md.

The formats

Different tools look for rules in different places. The content is the same; only the location and the header change.

• AGENTS.md is an open, shared format. Many coding agents read it automatically from the repository root, and some also read one in a subfolder for rules that apply only there. This is your source of truth.
• ASSISTANT-RULES.md holds the same rules laid out for agents that expect a single file under their own name. Check your agent's documentation for the file name it reads, then copy or rename this file to that name. It stands alone, so it works even where AGENTS.md is not read.
• .cursor/rules/*.mdc are project rules for editors that read that folder. Each file starts with a small frontmatter block: description says what the rule covers, globs lists the file patterns it applies to, and alwaysApply: true loads it for every request. The house rules and security rules always apply; the testing and front-end rules load only for matching files.
• .github/instructions/.instructions.md are path-scoped instructions for tools that read that folder. The applyTo glob in the frontmatter decides which files each one applies to. "*" means every file.

Keep one source of truth

Edit AGENTS.md and the files in rules/. Treat everything else as a copy. When you change a rule:

1. Change it in AGENTS.md or in rules/.
2. Update ASSISTANT-RULES.md and any agent-specific copy of it.
3. Check the short versions in .cursor/rules/ and .github/instructions/ and adjust the matching lines.
4. Commit all of them in the same pull request.

If your agent only needs its own file name and you do not want a second document to maintain, copy AGENTS.md itself to that name instead of using ASSISTANT-RULES.md. Replace [AGENT-FILE.md] below with the name your agent reads.

macOS, Linux or Git Bash:

cp AGENTS.md [AGENT-FILE.md]

Windows PowerShell:

Copy-Item AGENTS.md [AGENT-FILE.md]

Run it again whenever AGENTS.md changes, or add it to your project's setup script. Some agents also accept a one-line file that points to AGENTS.md; check your agent's documentation.

Combining the files

• Use AGENTS.md alone if every agent your team uses reads it.
• Add ASSISTANT-RULES.md (renamed) for any agent that reads only its own file.
• Add the .cursor/rules/ or .github/instructions/ files only if your team uses tools that read those folders. Delete the folders you do not need.
• Keep project-wide rules short. Put rules for one area (tests, front end, security) in the scoped files, so the agent loads them only when it is working on those files.

File map

A note on limits

Rules files guide an agent. They do not enforce anything. An agent can still ignore or misread an instruction, so keep branch protection, required CI checks and human review in place, and treat the approval list as a backstop to those controls, not a replacement. File names and folders that each tool reads change over time; check your tool's current documentation when you set it up.

Licence

MIT License. See LICENSE.txt.

Review checklist for agent-made changes

Use this when you review a change written by a coding agent, whether it arrives as a pull request, a branch or a diff in your editor. Agents write plausible code quickly. The risks are different from a human change: scope creep, confident claims that were never checked, invented APIs and quiet weakening of tests or checks. Work through the sections in order. Most reviews take ten to twenty minutes.

1. Before you read the code

• You know what the task was. Reread the issue or the prompt.
• The summary says what changed and why, which files were touched, and which commands were run.
• The summary lists assumptions and anything that was not verified.
• CI has finished. You are not reviewing on top of a red or pending build.

2. Scope

• Every changed file is needed for the task.
• No unrelated renames, reformatting, refactors or "while I was here" fixes.
• No new files that duplicate something that already exists (a second date helper, a second API client).
• No changes to configuration, CI, lint rules, formatter settings or test thresholds unless the task asked for them.
• The diff size makes sense for the task. A small bug fix that touches twenty files needs an explanation.

3. Correctness

• The change does what the task asked, not a nearby easier version of it.
• Edge cases are handled: empty input, zero, negative numbers, very large values, unicode, duplicates, missing fields, timezones.
• Error paths behave sensibly. Errors are not swallowed. Messages help the person who will read them.
• Every function, method, option and import that the code uses actually exists in the version the project uses. Check anything unfamiliar against the library's documentation.
• Concurrency and ordering are safe: awaited promises, transactions where needed, no race between check and update.
• Public interfaces are unchanged, or the change is deliberate, documented and versioned.
• Data changes are reversible, or there is a written plan for the case where they are not.

4. Tests

• New behaviour has tests. A bug fix has a test that would fail without the fix.
• The tests assert real outcomes, not just that code ran without throwing.
• No test was deleted, skipped, commented out or loosened. If one was, the reason is convincing.
• Snapshot or golden file updates were read and explained.
• Tests do not use the network, the real clock or shared state.
• You ran the relevant tests yourself, or CI ran them on this exact commit.

5. Security

• No secrets, tokens, keys or real personal data in code, tests, fixtures, logs or the summary.
• New environment variables are in .env.example without values.
• External input is validated at the boundary.
• Queries are parameterised. No shell commands, paths or HTML built from input by joining strings.
• Every new route or action checks authorisation on the server, per object.
• No security control was disabled: CSRF, CORS, TLS verification, rate limits, security headers.
• Error responses do not leak internals.

6. Dependencies

• No new dependency, or the new one was approved.
• The package name is spelled correctly and is the maintained original, not a look-alike.
• The lock file changed only as expected. No surprise major upgrades.
• The licence of any new dependency or copied code is compatible with the project.

7. Performance

• No queries inside loops where one query would do. No missing index on a new filter or join column.
• Lists and endpoints that can grow are paginated or bounded.
• No large dependency added for a small job, and no large import added to a client bundle.
• Expensive work is not repeated on every request or render without need.

8. Documentation and user-facing text

• README, setup steps, environment variables and API docs are updated if behaviour changed.
• User-facing copy is accurate, consistent with the product's wording and free of placeholder text.
• Code comments explain why, and none of them describe what the code used to do.
• The changelog or release notes are updated if the project keeps them.

9. The diff itself

• No debug output, stray logging or leftover print statements.
• No commented-out code.
• No placeholder values, dummy URLs or unfinished branches that return early.
• No generated files, build output, editor files or local configuration.
• Commit messages follow the project's convention and describe the change accurately.
• Names and structure match the rest of the codebase.

10. Claims vs evidence

Agents sometimes report work they did not do. Check each claim against something you can see.

• Every claim in the summary has evidence.
• Anything marked "could not verify" has been verified by you or is accepted as a known risk.

11. Decision

• Approve when every section is clear or the remaining risks are understood and written down.
• Request changes with specific, actionable comments. When you hand the comments back to the agent, quote the file and line and say what outcome you want, not only what is wrong.
• Close the change and start again when the scope is badly off. A fresh, narrower task is often faster than repairing a sprawling diff.

--- applyTo: "**" ---

Security instructions

These apply to every file in the repository. The full version is in rules/security-and-secrets.md.

Secrets

• Never write a secret value into code, tests, fixtures, documentation, logs or commit messages. Refer to it by its environment variable name.
• Read configuration from environment variables or the secret store. Add new variable names to .env.example without values.
• Do not open, print or copy .env files, private keys or cloud credential files unless the user asks.
• If you find a real secret in the repository, stop and report the file and line. Do not repeat the value. Recommend rotating it.

Code

• Validate every external input at the boundary: requests, webhooks, uploads, queue messages, third-party responses.
• Use parameterised queries and safe APIs. Never build SQL, shell commands, file paths or HTML by joining strings with input.
• Check authentication and authorisation on the server for every action and every object.
• Return generic errors to clients. Log details on the server, without secrets or personal data.
• Use the platform's vetted libraries for cryptography, password hashing and session handling. Do not write your own.

Changes that need approval

• Adding, removing or upgrading a dependency.
• Changing authentication, permissions, CI/CD, infrastructure or security headers.
• Disabling a security control, lint rule or test.

--- applyTo: "**/.test.,**/.spec.,/__tests__/,/tests/,**/test_*.py,**/*_test.py" ---

Test instructions

These apply when you create or change test files. The full version is in rules/testing.md.

• For a bug, write the failing test first, then the fix.
• Follow the naming, structure and helpers of the tests already in the same folder.
• One behaviour per test, named for the expected outcome, for example returns 404 when the order does not exist.
• Cover the main path, the edges (empty, zero, maximum, unicode, duplicates) and the error paths.
• No real network, no real clock, no unseeded randomness, no order dependence, no shared mutable state.
• Mock at the system boundary, not the unit under test.
• Use fake data only: Example Co, [email protected].
• Never delete, skip or weaken a test to make the suite pass. Never update snapshots without explaining why the new output is right.
• Report the exact command you ran and the pass, fail and skip counts. If you did not run the tests, say so.

Prompt: review my diff

Paste this after the agent has finished a change, or when you want it to review a diff you wrote. It asks for a critical review with evidence, not a summary of what the code does.

Review the current diff against the base branch ([main]) as a strict senior reviewer. Do not change any files yet.

Check, in this order:
1. Scope: any change not needed for the task "[task in one sentence]".
2. Correctness: bugs, missed edge cases, swallowed errors, functions or options that do not exist in the versions this project uses.
3. Tests: missing tests, weakened or skipped tests, assertions that do not check real outcomes.
4. Security: secrets, unvalidated input, string-built queries or commands, missing server-side authorisation checks.
5. Dependencies: anything added or upgraded.
6. Leftovers: debug output, commented-out code, placeholders, stray files.

For each finding give the file and line, what is wrong, why it matters and a suggested fix. Mark each as "must fix", "should fix" or "nit".

Then run [lint command] and [test command] and report the exact results with counts.

Finish with a list of every claim in the original change summary and whether the diff and the command output support it.

Prompt: start of task

Paste this at the start of a task, then replace the parts in [square brackets]. It makes the agent read the rules, plan before it edits and report in a form you can check.

Task: [Describe the outcome you want in one to three sentences.]

Context: [Links to the issue, relevant files, error messages or screenshots.]

Done means: [The observable result, for example "the CSV export includes the order date column and the existing export tests still pass".]

Out of scope: [Things not to touch, for example "do not change the export file name or the API response".]

Before you edit anything:
1. Read AGENTS.md (or ASSISTANT-RULES.md) and follow it.
2. Read the code and tests around the change.
3. Reply with a short plan: the files you expect to change, the tests you will add or update, and any question or assumption. Wait for my go-ahead if the plan touches more than [10] files, needs a new dependency, or changes a public interface.

While you work:
- Keep the change focused on this task.
- For a bug, write a failing test first.
- Do not run destructive commands, push, deploy or change CI without asking.

When you finish, report:
- what changed and why
- the files you touched
- the commands you ran and their results, with test counts
- what you could not verify
- assumptions and follow-up work

Security and secrets rules

These rules tell a coding agent how to handle credentials, input, access control and dependencies in this repository. They also tell it when to stop and ask. Link to this file from AGENTS.md and keep the short versions in the other rule files in step with it.

1. What counts as a secret

Treat all of these as secrets, whatever the file or format:

• API keys, access tokens, refresh tokens and personal access tokens
• passwords, passphrases and database connection strings that contain a password
• private keys (SSH, TLS, signing, JWT signing keys, wallet keys and seed phrases)
• webhook signing secrets and OAuth client secrets
• session cookies and bearer tokens copied from a browser or a log
• cloud credential files and service account JSON files
• real personal data: names with contact details, addresses, payment details, health data, government identifiers

A value is still a secret if it is "only for testing", "only for staging" or "already expired". You cannot tell from the outside, so treat it as live.

2. Where secrets live

• Application code reads secrets from environment variables or the project's secret store: [your secret store, e.g. the hosting platform's environment settings or a vault].
• Local development uses a .env file that is listed in .gitignore and never committed.
• The repository contains .env.example with every variable name and an empty or obviously fake value, plus a one-line description in the setup documentation.
• Values meant for the browser use the framework's public prefix, for example [NEXT_PUBLIC_] or [VITE_]. Anything with that prefix is public. Never give a server secret a public prefix.
• CI reads secrets from the CI platform's encrypted secret settings, scoped to the jobs that need them.

3. Rules for the agent

• Never write a secret value into code, tests, fixtures, documentation, examples, logs, terminal output, screenshots, commit messages or pull request text.
• Refer to secrets by variable name only, for example "set STRIPE_SECRET_KEY in your environment".
• Do not open, print, copy or summarise .env files, key files, credential folders or password manager exports unless the user asks you to in this conversation. If you must check that a variable exists, check for its name, not its value.
• When you add a new variable, add the name to .env.example, read it in one configuration module, and fail at start-up with a clear message if it is missing.
• Use fake values in tests: test_key_not_real, [email protected], Example Co. Never use a real-looking key format that a scanner would flag.
• Never add a secret to a client bundle, a URL, local storage, a cookie readable by scripts, or an error message.

4. Logging

• Log events and identifiers, not payloads. Prefer "payment failed for order 1042" over dumping the request.
• Never log passwords, tokens, cookies, authorisation headers, full card numbers or full request bodies from authentication or payment routes.
• Redact known sensitive fields centrally in the logger configuration rather than at each call site.
• Error responses to clients are generic. Stack traces and internal details stay in server logs.
• Keep personal data in logs to the minimum needed, and follow the project's retention period: [retention period].

5. Input validation

• Validate every input that crosses a trust boundary: HTTP requests, query strings, headers, cookies, webhooks, uploaded files, queue messages, environment variables and responses from third-party APIs.
• Validate with a schema at the boundary: [validation library, e.g. zod, pydantic]. Check type, length, range, format and allowed values. Reject unknown fields where the framework allows it.
• Use parameterised queries or the ORM's query builder. Never build SQL by joining strings with input.
• Never pass input to a shell. If you must run a process, pass arguments as a list and use an allow-list of values.
• Resolve file paths against a fixed base directory, then check that the result is still inside it.
• Encode output for its context (HTML, attribute, URL, JavaScript). Do not render user HTML without a vetted sanitiser.
• For uploads, check size and type on the server, store files outside the web root or in object storage, and generate your own file names.
• Verify webhook signatures with the provider's library and reject old timestamps.
• When fetching URLs supplied by users, block private and link-local addresses to prevent server-side request forgery.

6. Authentication and authorisation

• Use the project's existing authentication system: [auth library or provider]. Do not write a new one.
• Check authentication and authorisation on the server for every request, every action and every object. Hiding a button is not access control.
• Look up the object and confirm the current user may act on it, every time. Never trust a user ID, role, price or tenant ID sent by the client.
• Default to deny. New routes and database tables are private until a rule opens them.
• Hash passwords with the platform's recommended algorithm (Argon2id, scrypt or bcrypt) through a maintained library.
• Session cookies are HttpOnly, Secure and SameSite=Lax or stricter. Rotate the session ID on login.
• Rate-limit login, sign-up, password reset and any endpoint that sends email or costs money.
• Use the platform's vetted libraries for cryptography. Never write your own.

7. Dependencies

• Ask before adding, removing or upgrading any dependency.
• Before suggesting a package, check that the name is spelled correctly, that it is the maintained original and not a look-alike, and that it is widely used. Lookalike names are a common supply-chain attack.
• Install with the project's package manager and commit the lock file. Use the lock file in CI (npm ci, pip install with hashes or a locked resolver).
• Do not copy code from unknown sources without saying where it came from and what licence it has.
• Never pipe a remote script into a shell. Never add install scripts that download and run code.
• When an audit tool reports a vulnerability, report it with the package, the affected version and the fixed version. Do not upgrade major versions without approval.

8. Refuse, or stop and ask

Refuse, and explain why, if asked to:

• commit a secret, or move a secret into client-side code
• disable authentication, authorisation, CSRF protection, TLS verification or input validation in code that will run outside a local test
• weaken password hashing, remove rate limits or log credentials
• add code that collects data or sends it to a third party without the user's knowledge

Stop and ask before you:

• change authentication, permissions, CORS, security headers or the Content Security Policy
• change CI/CD secrets, deployment configuration or infrastructure
• touch payment, billing or data deletion code
• run anything against shared, staging or production data
• read any file that holds real credentials

9. If you find a secret

1. Stop the current task.
2. Do not repeat the value anywhere, including in your reply.
3. Report the file, line number and type of secret, for example "an API key in config/payments.ts line 12".
4. Recommend that the owner rotates it at the provider now. Deleting it from the code does not make it safe, because it stays in git history and may already be copied.
5. Offer to move the code to read the value from an environment variable and to add the name to .env.example.
6. Mention that removing it from history needs a history rewrite and a force push, which needs explicit approval and coordination with everyone who has a clone.
7. Wait for instructions before continuing the original task.

10. Before you say done

• No secret values in the diff, in test data or in your summary
• New environment variables are listed in .env.example
• All new inputs are validated at the boundary
• Every new route or action checks authorisation on the server
• Logs added in this change contain no secrets or unnecessary personal data
• No new dependency was added without approval
• Any security-relevant change is called out in the summary

Testing rules

These rules tell a coding agent how to write, change, run and report on tests in this repository. Link to this file from AGENTS.md.

1. Commands

2. When tests are required

• New behaviour: tests for the main path, the edge cases and the error cases.
• Bug fix: a test that reproduces the bug. It must fail before the fix and pass after it.
• Refactor with no behaviour change: the existing tests stay as they are and keep passing. If coverage around the code is thin, add tests first, then refactor.
• Configuration, documentation or copy changes: tests only where the change can break behaviour.

3. Test-first for bugs

1. Read the bug report and find the smallest input that shows the problem.
2. Write a test with that input and the expected result.
3. Run it and confirm that it fails for the reason you expect. A test that fails for a different reason proves nothing.
4. Fix the code with the smallest change that makes the test pass.
5. Run the whole suite.
6. In your summary, quote the test name and say that it failed before the fix.

4. Structure

• Put tests where the existing tests for that code live: [e.g. next to the source as *.test.ts, or in tests/ mirroring src/].
• Reuse existing fixtures, factories and helpers before writing new ones.
• One behaviour per test. Name the test for the outcome: rejects an expired token, rounds totals to two decimal places.
• Arrange, act, assert, in that order, with a blank line between them where it helps.
• Keep setup short and visible. Move repeated setup into a fixture or builder, but keep the values that matter to the test inside the test.
• Assert on behaviour and outputs, not on private details. A test that breaks on every refactor is a maintenance cost, not a safety net.
• Prefer a few precise assertions to one large snapshot.

5. Isolation: no network, no clock

• No real network calls. Stub HTTP at the client boundary or use the project's mock server: [mock library].
• No real clock. Inject the clock or use fake timers, and set an explicit date in each test that depends on time.
• No unseeded randomness. Seed random generators or inject fixed values.
• No dependence on test order. Every test sets up what it needs and cleans up after itself.
• No shared mutable state between tests: global variables, singletons, module caches or a shared database row.
• Use a temporary directory for file system tests and remove it afterwards.
• Database tests use a dedicated test database or transactions rolled back after each test. Never point tests at shared, staging or production data.
• Mock at the boundary of the system (HTTP, database driver, clock, file system, message queue), not the code under test.
• Use fake data only: Example Co, [email protected], +1 555 0100.

6. Flaky tests

A flaky test passes and fails without a code change. Treat it as a bug.

• Do not add retries, longer sleeps or larger timeouts as a fix.
• Look for the usual causes: real time, timezone or locale, unawaited promises, shared state, order dependence, race conditions, network calls, unseeded randomness, or reliance on the order of a set or map.
• Replace sleeps with waits on a specific condition.
• If you cannot fix it within the task, report it with the test name, how often it fails and what you found. Quarantine it only with approval and a linked issue.

7. Coverage

• Coverage is a tool for finding untested code, not a target to hit.
• Every changed line of logic should be exercised by at least one test, including the error branches.
• Prefer testing a few real scenarios well to touching every line with weak assertions.
• Do not add tests that only execute code without asserting anything.
• Do not lower coverage thresholds in configuration to make CI pass.

8. What the agent must never do

• Delete, skip, comment out or mark as expected failure a test to make the suite pass.
• Loosen an assertion (for example from an exact value to "is defined") without explaining why the old assertion was wrong.
• Update snapshots or golden files without reading the diff and explaining why the new output is correct.
• Change production code only to make a test pass when the test reveals a real problem with the requirement. Ask instead.
• Edit test configuration, timeouts or thresholds as a side effect of another task.

If you believe a test is wrong, say so, explain why, and ask before you change it.

9. Reporting results honestly

• Report the exact command you ran.
• Report what you saw: the number of tests passed, failed and skipped, and the names of any failures.
• If a failure is unrelated to your change, say so and show why you think so, for example that it also fails on the main branch.
• If you could not run the tests (missing service, missing credentials, slow suite), say so plainly and list what you ran instead.
• Never write "all tests pass" unless you ran the whole suite in this session and saw it pass.
• Never describe tests you planned as tests you ran.

Example summary:

Ran [test command]: 412 passed, 0 failed, 3 skipped (the 3 skips were already skipped on main). Added rejects an expired token in tests/auth/session.test.ts; it failed before the fix with "expected 401, received 200". Did not run the end-to-end suite because it needs the staging database.