# AGENTS.md

## Core Principles
- At the beginning of each development session, read all Markdown (.md) files in agent_instructions/ to establish project standards and constraints.
- During implementation, consult relevant instruction files as needed.
- All applicable instructions remain binding.
- Work autonomously using approved technologies, libraries, components, and established patterns.
- Do not implement custom functionality when an approved solution already meets the requirement.
- Before introducing a new dependency, architectural pattern, or design-system component, evaluate existing alternatives and request user approval. 
- Prioritize long-term maintainability. 
- Favor clear, modular, reusable implementations and established patterns. 
- Avoid unnecessary complexity, duplication, and technical debt.
- Changes to approved technologies or architecture must include corresponding documentation updates.
- Maintain comprehensive, logically organized current-state specifications for all implemented functionality, including changes requested through prompts or conversations. Follow SHAPE.md.


## Libraries & Frameworks
- **Do not reinvent the wheel.**
- Prefer existing approved libraries, frameworks, and reusable components over custom implementations.
- Before implementing non-trivial functionality, evaluate whether an existing approved solution meets the requirement.
- If an approved solution is suitable, use it.
- If no approved solution is suitable, the agent may implement straightforward functionality using the existing stack.
- Introducing a new dependency requires explicit human approval.
- Avoid unnecessary dependencies for functionality that can be implemented simply with existing project capabilities.

## Code Structure & File Size
- **DRY** - Don't Repeat Yourself
- **Modularize aggressively.** Build reusable components and extract shared logic into separate files whenever possible.
- **File size rules:**
  - Target: **≤ 200 lines per file**
  - Hard limit: **350 lines maximum**
  - Exceeding 200 lines requires explicit justification through unavoidable constraints.
  (Exception are seed data files, i18n files, static HTML  and *.md files.)

## Styling and UX
- Use token-driven styling (CSS variables) for colors, spacing, and typography.
- Ensure responsive layouts for mobile and desktop.
- Accessibility is required:
  - semantic structure
  - keyboard support
  - visible focus states
  - sufficient color contrast

## SEO and Content
- Define metadata per page.
- Keep heading hierarchy and link text meaningful.
- Tone must stay technical, credible, and business-focused.

## Preserve URLs and SEO Redirects
- Preserve existing public URLs when renaming, moving, or removing pages. Where necessary, implement permanent redirects (301 or 308) using mechanisms supported by the approved hosting and deployment architecture.
- Do not introduce unsupported runtime dependencies to implement redirects.
- Update internal links, canonical URLs, language alternates, and sitemap entries. Preserve query parameters where applicable. Never redirect unrelated or missing pages to the homepage.
- Before merging, audit route and slug changes against available Git history and existing redirects. Verify HTTP status codes, redirect destinations, and query parameter preservation. Prevent redirect loops and chains.
- If the approved architecture cannot support a required redirect, explain the limitation and request a human decision rather than silently breaking the existing URL.
- If no relevant replacement exists, obtain approval for an intentional page retirement (404 or 410). Never silently break an existing public URL.

## Architecture & Separation of Concerns
- Enforce **clear separation of concerns** between:
  - Domain logic
  - Application logic
  - Infrastructure
  - UI
- Cross-layer coupling is discouraged and must be explicitly justified.

## Front-End & Back-End Components
- Components must be canonical and reusable.
- Variants must be explicitly named, finite, and justified by a genuine functional or design requirement. 
- Do not introduce new variants when an existing one meets the need.

### UI Components (Critical)
- UI components (e.g. buttons, cards, headlines) must be **singular, reusable, and canonical**.
- Prefer existing, named component variants and design tokens.
- Reuse established components and styles wherever possible.
- Specifications may introduce local layout variations or component-specific styling without requiring prior approval.
- When a variation is likely to be reused, extend the existing component or propose an addition to the design system.
- Example (button):
  - Sizes: `small | medium | large`
  - Styles: `default | positive | warning`
- Inline styles are **forbidden**.
- Styles must be applied **only via named CSS classes, design tokens, or a theme system**.
- Request approval before introducing material changes to the shared design system, not for routine local styling decisions.

## Theming & Style Swappability
- All styling **must be theme-driven and fully swappable**.
- The application must support changing the entire visual appearance (e.g. green theme → red theme) **by swapping stylesheets, themes, or token definitions only**.
- No component may depend on hard-coded colors, fonts, spacing, or visual values.
- All visual properties must be derived from **design tokens or a centralized theming system**.

## Accessibility (a11y)
- Accessibility is **mandatory**, not optional.
- UI components must support:
  - Keyboard navigation
  - Focus management
  - Screen-reader compatibility
  - Sufficient color contrast
- Accessibility requirements apply to all variants of a component.

## Testing
+- Follow SHAPE.md for specification-driven test creation, maintenance, regression protection, and human-controlled execution.

## Internationalization (i18n)

- **Required languages:** All user-facing content must support English (`en`), German (`de`), and Spanish (`es`) from the start.
- **No hardcoded content:** All user-facing text, including headings, paragraphs, navigation, buttons, metadata, accessibility labels, alt text, validation messages, and errors, must be stored in localized YAML files.
- **Markdown support:** Long-form content may use Markdown within designated YAML fields. Do not embed JSX, executable application code, CSS, or presentation logic in content files.
- **Complete translations:** All three languages must be provided for every implemented feature or page. Missing translations are not acceptable; never silently fall back to another language.
- **Consistent structure:** Maintain matching keys, section identifiers, data structures, and placeholders across all supported languages.
- **Shared components:** Reuse the same components and layouts across languages. Do not create language-specific component implementations or embed translation objects and language-dependent text conditions in UI code.
- **Translation maintenance:** Update all supported languages whenever user-facing content changes. Validate translation completeness and consistency before considering the work complete.
- **Architecture compliance:** Follow `ARCHITECTURE.md` for YAML content organization, Markdown rendering, translation loading, and localized routing.


## Security
- **Never store sensitive information in files.**
- This includes (but is not limited to):
  - Passwords
  - API keys
  - Tokens
  - Secrets
  - License keys

## Documentation Discipline
- Project documentation must remain **synchronized with implementation**.
- Outdated documentation is considered a defect.

## AGENTS.md Governance (Strict)
- **The agent is forbidden from editing `AGENTS.md` autonomously.**
- `AGENTS.md` may only be modified **upon explicit user instruction**.
- If the agent wishes to propose changes:
  - They must write them to **`agents.extensions.md`**
  - No automatic merging or implicit updates are allowed.

  ## Quality Gate
- Before merge:
  - lint passes
  - type-check passes
  - build passes
  - dictionary checks pass (`pnpm run test:i18n`)
- Keep files modular and readable; split large components early.