agents.md

Applies to the whole repository unless a deeper AGENTS.md overrides it.

Goal

Leave the system clearer, more correct, and easier to trust. Answer in the user's language. Verify uncertain claims against code, tests, or runtime output — do not assert what you have not checked.

Invariants

• Never print or commit secrets, tokens, credentials, or raw .env values — anywhere, including fixtures, logs, and screenshots.
• Never stage, commit, amend, rebase, reset, stash, push, or delete files unless explicitly asked.
• Never stop or kill processes to free ports; use isolated ports or config overrides.
• Never hand-edit generated files (including Prisma migration.sql); change the declarative source (schema.prisma, codegen inputs) and run the generator.
• Never weaken auth, permissions, validation, encryption, rate limits, or auditability to make a task easier.
• Never revert, reformat, or clean up user changes you did not create.
• Do not add CI/CD, deployment pipelines, hosted automation, or release ceremony unless explicitly asked.
• Do not add new production dependencies without explicit approval; prefer existing utilities and the standard library.

Autonomy

• Answer / explain / review / diagnose / plan: inspect the relevant materials and report. Do not implement unless also asked.
• Change / build / fix: make the requested in-scope changes and run non-destructive validation without asking.
• Ask first only for destructive, irreversible, security- or privacy-sensitive actions, external writes, or a material expansion of scope.
• If a safe assumption unblocks work, proceed and state it in the final report.
• When material product or architecture tradeoffs exist, present up to two viable options and recommend one.

How to work

• Ground in the repository: current code, schemas, tests, and runtime output outrank docs and assumptions. Use the repo's existing package manager, scripts, test runner, formatter, and build tools.
• For changes to behavior, logic, contracts, auth, permissions, persistence, validation, routing, or state transitions, work test-first: highest-value failing case → minimal implementation → green → next case. Start from user-visible or contract-level behavior. If adding a test is disproportionate, say so and use the fastest reliable validation instead.
• Fix the owning layer, not the nearest visible symptom. A bug surfacing in a child component, hook, or helper usually belongs to a parent decision; child-side fallbacks, defensive guards, and duplicated decision logic that hide an upstream mistake are not fixes. A one-file fix for cross-layer behavior is suspicious until proven otherwise.
• When touching a shared boundary (contract, schema, route, guard, query, auth, async workflow), keep both sides consistent: producer and consumer, read and write paths, and the user-visible states they drive (loading, empty, error, success, optimistic, stale).
• If two attempts fail to move the primary signal, stop and reframe instead of patching harder.

Change quality

• Aim for the smallest coherent change that fully solves the real problem at the owning layer — minimal surface area and abstraction count, not smallest diff at any cost.
• Prefer flat, local, boring code over new layers, helpers, wrappers, and patterns. Small intentional duplication beats the wrong shared abstraction.
• A change is not minimal if it makes the code harder to understand tomorrow.
• If re-architecture or migration is required, state scope, risks, backward compatibility, and rollout order before proceeding.

Validation and done

• Validate the changed surface with the cheapest sufficient signal first: targeted tests → typecheck / lint → build → wider suites only when needed. If contracts changed, validate both producer and consumer.
• The primary signal is user-visible or contract-level behavior. Green tests, lint, or typecheck alone do not equal success; if only secondary signals were checked, the task is partially validated and must be reported as such.
• Any non-zero exit, runtime error, unhandled rejection, failed assertion, type error, or build failure is failed validation. Report what failed, what it means, and the next useful experiment — never hide it.
• The task is not done if the visible symptom is gone but the same mechanic remains structurally inconsistent across directly coupled layers.

UI

• Follow the existing design system, primitives, and visual language; no redesigns unless explicitly asked.
• Shared visual components are closed units (surface, padding, radius, typography belong to the component). Adapt consumers through existing semantic props, then the smallest new semantic prop, then a local wrapper — never visual overrides or ad hoc surfaces.
• Keep layout rhythm on the shared spacing scale via parent padding and container gap, not ad hoc margins.

Docs and hygiene

• Code is the source of truth. Update README.md / docs/ only when a change materially affects architecture, setup, contracts, operations, or important decisions. Call out doc drift you leave out of scope.
• Keep temporary artifacts under ./.scratch/; keep diffs free of unrelated formatting churn.

Final report

State concisely:

• what changed and why; root cause when identified;
• primary signal status — met, not met, or partially validated — with the exact checks run;
• remaining risks, missing coverage, or follow-ups when relevant;
• a suggested commit message when the change is ready.