lmnp-organizer/AGENTS.md

## Agent skills

### Issue tracker

Issues and merge requests (MRs) are tracked in this repository's GitLab instance. See [issue-tracker.md](file:///home/nessar/lmnp-organizer/docs/agents/issue-tracker.md).

### Triage labels

Use the default triage labels (`needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`). See [triage-labels.md](file:///home/nessar/lmnp-organizer/docs/agents/triage-labels.md).

### Domain docs

Use the single-context documentation layout. See [domain.md](file:///home/nessar/lmnp-organizer/docs/agents/domain.md).

## General engineering practices

- Make the smallest change that fully solves the issue.
- Follow the existing project structure and conventions before introducing new patterns.
- Prefer simple, explicit code over unnecessary abstraction.
- Keep classes, components, and functions focused on one responsibility.
- Extract reusable logic when it is duplicated or independently testable.
- Avoid unrelated refactoring in feature or bug-fix merge requests.
- Do not introduce a new dependency when the existing stack can reasonably solve the problem.
- The application is not in production. Change development contracts and schemas directly when the domain model changes; update all callers and tests together instead of preserving backward compatibility.
- Add or update tests for changed behavior.
- Do not commit secrets, tokens, credentials, generated artifacts, or local environment files.
- Update relevant domain documentation when behavior, architecture, or business rules change.

## Frontend: Angular

### Components

- Keep components small and focused on a single responsibility.
- Split a component when a section has its own state, behavior, lifecycle, or reusable UI.
- Keep page-level components focused on orchestration, routing, and layout.
- Move reusable presentation elements into shared components.
- Keep feature-specific components inside their feature directory.
- Prefer composition over components with many configuration flags.
- Avoid large component files. Components approaching 250 lines should be reviewed for extraction opportunities.
- Do not place substantial business logic directly in templates or components.

### Angular architecture

- Organize code by feature rather than only by technical type.
- Keep domain and business logic independent from Angular when practical.
- Use services for API access, application coordination, and shared state.
- Use dependency injection instead of manually constructing services.
- Keep services focused; avoid catch-all services with unrelated responsibilities.
- Prefer standalone components where they match the existing project architecture.
- Lazy-load feature routes where appropriate.
- Use route guards only for navigation concerns, not as the sole enforcement of security rules.
- Follow the repository's established state-management approach. Do not introduce another state-management library without justification.

### Templates and state

- Keep templates readable and free of complex expressions.
- Move non-trivial calculations into component methods, computed values, pipes, or domain utilities.
- Do not call expensive or state-changing methods from templates.
- Prefer Angular signals, observables, or local component state according to the existing codebase conventions.
- Do not duplicate derived state. Compute values from their source whenever practical.
- Avoid manual subscriptions when the `async` pipe, signals, or framework lifecycle helpers can manage them.
- Ensure subscriptions are cleaned up when manual subscription is unavoidable.
- Use `trackBy` or Angular's equivalent tracking syntax for dynamic lists.
- Avoid unnecessary change-detection work.

### TypeScript

- Use strict TypeScript types.
- Do not use `any` unless integration constraints make it unavoidable and the reason is documented.
- Define explicit input, output, API, and domain types.
- Prefer unions and enums over loosely related strings or multiple boolean flags.
- Use immutable transformations where practical.
- Do not use regular-expression `.test()` calls unless they are the only valid option and the user has explicitly authorized them; prefer more readable, maintainable validation alternatives.
- Avoid non-null assertions unless the invariant is guaranteed and clear.
- Validate data received from external APIs instead of trusting type assertions.

### Forms

- Prefer reactive forms for complex or business-critical forms.
- Keep validation rules consistent between the frontend and backend.
- Display actionable validation messages.
- Prevent duplicate submissions while a request is pending.
- Do not rely on frontend validation for security or data integrity.

### Styling and user experience

- Use Angular Material components by default whenever they cover the UI need.
- Never use unstyled native buttons or browser-native dialogs; use Angular Material button directives and `MatDialog` instead.
- Reuse the existing design system, shared components, spacing rules, and design tokens.
- Avoid duplicating styles already provided by shared components.
- Keep component styles scoped unless a style is intentionally global.
- Ensure layouts work across supported viewport sizes.
- Provide explicit loading, empty, success, and error states.
- Every user-observable asynchronous frontend operation must expose a truthful loading lifecycle. Prefer content-shaped skeletons for first loads, preserve established content with subtle busy feedback during refreshes, and use operation-local progress for actions so unrelated work remains available; never present pending or failed data as an empty or successful result.
- Avoid unexpected layout shifts and blocking interactions.

### Accessibility

- Use semantic HTML before adding ARIA attributes.
- Use native buttons and links for interactive actions.
- Ensure all interactive elements are keyboard accessible.
- Associate form controls with visible or accessible labels.
- Preserve visible focus indicators.
- Provide alternative text for meaningful images.
- Ensure dialogs and overlays manage focus correctly.
- Do not communicate status or errors through color alone.

### Angular testing

- Test observable behavior rather than implementation details.
- Add unit tests for components, services, pipes, guards, and utilities when their behavior changes.
- Cover important form validation and error states.
- Mock network boundaries rather than internal implementation details.
- Add integration or end-to-end coverage for critical user journeys when appropriate.

## Backend: Java and Spring Boot

### Structure and responsibilities

- Keep controllers thin.
- Controllers should handle HTTP concerns, input validation, authentication context, and response mapping.
- Put application and business logic in dedicated services or use-case classes.
- Keep persistence logic in repositories.
- Do not expose persistence entities directly through public APIs.
- Use dedicated request and response DTOs at API boundaries.
- Keep mapping logic explicit and testable.
- Organize code by domain or feature where possible.
- Avoid utility classes that accumulate unrelated behavior.

### Java practices

- Follow the Java version and conventions already configured in the repository.
- Prefer constructor injection over field injection.
- Make dependencies explicit and immutable where possible.
- Use descriptive names and small methods.
- Avoid deeply nested conditionals; use guard clauses where they improve clarity.
- Prefer domain-specific types over primitive strings and numbers for important concepts.
- Use records for immutable data carriers when supported by the project.
- Use enums for finite domain states.
- Do not use `Optional` for entity fields, method parameters, or collection elements.
- Return empty collections instead of `null`.
- Do not catch broad exceptions unless they are rethrown, translated, or handled meaningfully.
- Do not silently ignore exceptions.

### Spring Boot practices

- Use constructor-based dependency injection.
- Keep configuration externalized through Spring configuration properties.
- Use typed `@ConfigurationProperties` instead of scattering `@Value` annotations.
- Keep environment-specific values outside source code.
- Use profiles only for genuine environment differences.
- Avoid circular dependencies.
- Do not use static access to Spring-managed services.
- Use framework annotations at the application boundary and keep domain code framework-independent where practical.

### API design

- Follow the repository's existing REST conventions.
- Use nouns for resource paths and standard HTTP methods.
- Return appropriate HTTP status codes.
- Keep request and response contracts coherent with the current model; replace obsolete development contracts rather than adding compatibility layers.
- Use explicit DTOs instead of generic maps.
- Validate incoming requests with Jakarta Bean Validation.
- Return consistent, structured error responses.
- Do not expose stack traces, internal class names, database details, or sensitive information.
- Document new or changed endpoints using the project's API documentation approach.
- Consider pagination for endpoints returning potentially large collections.
- Make retry-sensitive write operations idempotent when practical.

### Persistence and transactions

- Keep transaction boundaries in the service layer.
- Use `@Transactional(readOnly = true)` for read-only service operations when appropriate.
- Avoid long-running work, remote calls, or user interaction inside database transactions.
- Prevent N+1 query problems.
- Fetch only the data required for the use case.
- Use explicit database migrations for schema changes.
- Never rely on automatic schema generation in production.
- Add indexes only when supported by an identified query pattern.
- Preserve data integrity with database constraints in addition to application validation.
- Handle concurrent updates explicitly where data consistency requires it.

### Security

- Enforce authorization on the backend for every protected operation.
- Never rely on hidden frontend controls or route guards for authorization.
- Validate and sanitize untrusted input.
- Use parameterized queries or repository abstractions; never concatenate untrusted input into queries.
- Do not log passwords, access tokens, session identifiers, personal data, or sensitive request payloads.
- Store secrets in the configured secret-management or environment mechanism.
- Use least-privilege access for services and database users.
- Review new endpoints for authentication, authorization, data exposure, and abuse cases.

### Logging and observability

- Use structured, meaningful logs.
- Log identifiers needed to investigate a request without exposing sensitive data.
- Use appropriate log levels.
- Do not use `System.out` or print stack traces directly.
- Avoid duplicate logging of the same exception across multiple layers.
- Preserve exception causes when translating errors.
- Add metrics or tracing for important new workflows when the project already supports them.

### Spring Boot testing

- Add unit tests for domain and service logic.
- Use integration tests for persistence, security, serialization, transactions, and framework configuration.
- Prefer focused Spring test slices when the full application context is unnecessary.
- Use the project's established database test strategy.
- Do not depend on test execution order.
- Keep tests deterministic and isolated.
- Test success, validation failure, authorization failure, and important edge cases.
- Add regression tests for bug fixes.

## Development data lifecycle

- The application is not in production; development and test data are disposable and should be deleted or reseeded when the model changes.
- Do not create data migrations, compatibility adapters, dual-read or dual-write paths, or legacy schema support.
- Replace obsolete schemas, reference data, API contracts, and development documents directly, then update every caller and test in the same change.
- Do not plan for rolling upgrades or backward-compatible deployment until an explicit project decision declares production data must be preserved.

## Before finishing

- Review the full diff for unrelated changes.
- Verify that new code follows the existing architecture and naming conventions.
- Check for oversized components, classes, and methods.
- Check for duplicated logic and unnecessary abstractions.
- Run the frontend formatter, linter, type checker, and relevant tests.
- Run the backend formatter or style checks, static analysis, and relevant tests.
- Run the project build when practical.
- Verify API and database changes are reflected in tests and documentation.
- Verify loading, empty, validation, error, and authorization states.
- Confirm that no secrets, debug statements, temporary files, or generated artifacts were added.
- Summarize any command that could not be run and explain why.