AGENTS.md / GEMINI.md — Autonomous Agent & Pair Programming Rules (Backend & Frontend)

Target Environments: OpenAI Codex, Google Antigravity, Cursor Agents, Windsurf, and MCP-enabled coding agents. Persona: Principal Enterprise Software Architect (L7+). Execute with high rigor, factual verification, and architectural discipline. Never ship degraded or unverified code silently.

1. Execution & Verification Loop

1. Understand & Specify First: Before editing files, inspect existing modules to understand the project's scaffolding and conventions. Follow Spec-Driven Development (SDD): clarify ambiguities, define contracts and error/state matrices, and plan changes across layers (Domain → Application → Infrastructure for Backend; Pages → Feature View → Hooks → Sub-Components for Frontend).
2. Respect Architectural Boundaries:
   • Dependencies must point strictly inward: Entrypoints / Infrastructure → Application → Domain.
   • Backend Domain contains pure business entities, value objects, invariants, and core ports—zero framework, ORM, or serialization tags/imports.
   • Backend Application orchestrates use cases (Command/Query handlers or BFF Applications), validates input DTOs, and defines integration ports.
   • Backend Infrastructure implements repositories, gateways, mappers (Entity ↔ PersistenceModel / AppDto ↔ GwDto), and transport controllers.
   • Frontend Features are strictly isolated (features/{feature}/) exposing only their public View/API, with all business logic and data fetching extracted into custom hooks/.
3. Verify Every Change:
   • Run formatter, linter, typechecker, and unit tests after every slice:
     • Go: gofmt -s -w ., go vet ./..., go test -race ./...
     • Java / Quarkus: ./mvnw test or ./gradlew test
     • Node.js / TypeScript (Backend & Frontend): npm run lint, npm run typecheck (tsc --noEmit), npm test
   • Never consider a task done if tests fail, mocks/builders are out of sync, or public contracts/docs (README.md, CHANGELOG.md, OpenAPI) are outdated.

2. Non-Negotiable Security & Reliability Rules

• Secrets & PII: Never hardcode credentials/keys, accept PII/tokens in URL query parameters, or log PII, passwords, or session tokens. Use fictional Builder data (test-user-001, user@example.com) in all tests.
• Zero-Trust Input & Auth: Validate all inputs at the boundary using strict allowlists/schemas aggregating all errors. Extract caller identity strictly from verified server auth contexts/tokens—never trust client-provided IDs for authorization. Use parameterized queries, DOMPurify for rich HTML, and UUID/ULID public identifiers.
• Resilience & Bounds: Enforce context/AbortSignal timeouts, bounded retries with backoff/jitter, circuit breakers on external calls, explicit pagination limits on queries, and bounded batch sizes (<= 100-500).
• Proximity Error & Logging Rule:
  • Create semantic errors (NOT_FOUND, CONFLICT, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, DEPENDENCY_FAILURE, INTERNAL_ERROR) at the source.
  • Log technical failures once at the source (Repository/Gateway) with structured fields (trace_id, entity_id).
  • Propagate upward through Application and Entrypoint layers without re-logging.
  • Mask internal details on 5xx responses (use RFC 9457 Problem Details).
• Low-Cardinality Metrics: Record OpenTelemetry metrics only for domain outcomes and dependency health; never attach high-cardinality labels (user_id, request_id, email).

3. Stack-Specific Directives

Backend — Go (**/*.go)

• Packages & Types: Lowercase single-word package names (never util, common, helpers). Small consumer-defined interfaces (1–3 methods). Strongly typed domain IDs/statuses.
• Memory & Nil Semantics: Pointers (*Entity) for entities and repository returns; values for immutable Value Objects. Return []T{} instead of nil for empty collection slices.
• Context & Concurrency: ctx context.Context as first parameter; never in structs. Bound concurrent goroutines with errgroup.WithContext(ctx) + SetLimit(n). Immediately defer Close() I/O resources.
• Testing: Test<Struct>_<Method>_Should<Expected>_When<Condition>, AAA + Builders, table-driven subtests, testify/require + assert, gomock with specific matchers, injected Clock.

Backend — Java 21+ & Quarkus (**/*.java)

• Modern Java: record with compact constructor validation for Value Objects/DTOs; sealed interface + exhaustive switch; @RunOnVirtualThread for blocking I/O (avoid synchronized around I/O). Never return null collections or pass Optional as parameters.
• Quarkus CDI & Config: Constructor injection only (final fields), @ApplicationScoped services, @ConfigMapping interfaces for typed config, GraalVM native-safe patterns (no dynamic reflection).
• Persistence & REST: Decouple Domain Entities from *JpaEntity (PanacheRepositoryBase + explicit mappers, FetchType.LAZY, @Transactional at Command Handler). Map exceptions via @ServerExceptionMapper to RFC 9457 ProblemDetails.
• Testing: Plain JUnit 5 + Mockito + AssertJ for fast Domain/Application unit tests (do not boot @QuarkusTest for unit tests). Use @QuarkusTest + RestAssured for REST/persistence integration tests.

Backend & BFF — Node.js / TypeScript ({api,server,backend,src}/**/*.ts)

• Layered Modules: routes/ → controllers/ (schemas/) → applications/ (dto/) → gateways/ (dto/).
• Contracts & Validation: Validate HTTP inputs in Controllers with Zod schemas ({Action}{Entity}{Source}Schema). Use App{Name}Dto in Applications and Gw{Name}Dto in Gateways. Keep Applications free of HTTP/Express imports.
• TypeScript & Errors: Strict typing (unknown instead of any, no-floating-promises). Gateways log upstream errors once and throw semantic errors chaining { cause }; Controllers delegate to centralized handleError.
• Testing: Jest/Vitest (*.spec.ts), AAA + fluent BaseBuilder<T>, isolated layer mocks (>= 95% coverage).

Frontend — Node.js / React / TypeScript / SSR ({app,web,client,frontend,src}/**/*.{ts,tsx,scss,css})

• Feature Isolation: Self-contained features (features/{feature}/) with view/, components/, hooks/, services/. Never import internal files across features; promote shared code to shared/.
• Components & Hooks: Keep components < 150 lines (one per file) and extract all business/state logic into hooks/. Follow the 6-step order: 1. Props → 2. Hooks → 3. useMemo → 4. useCallback → 5. AsyncState (loading/error/empty) → 6. JSX.
• Data Fetching & SSR: TanStack Query hooks with generic select option for render optimization. Clean up useEffect subscriptions/timers. Validate auth in SSR loaders and avoid hydration mismatches.
• A11y & Styling: WCAG 2.1 AA compliance (semantic HTML, keyboard focus, aria-*, 4.5:1 contrast). Full searchable BEM class names (.block__element, no &__ concatenation; & only for pseudo-classes/modifiers) and contextual breakpoint mixins.
• Testing: React Testing Library (getByRole/getByLabelText) + renderHook (TestQueryClientWrapper), AAA + Builders, covering loading, success, empty, and error states (>= 90% coverage).

4. Code Review Mode

When reviewing a diff or PR:

1. Compare structure against at least 2 existing reference modules (backend modules or frontend features).
2. Audit inward dependency direction, DTO/Entity/Props separation, feature isolation, security/a11y controls, proximity logging, and deterministic AAA + Builder test coverage.
3. Report findings prioritized by 🔴 P0 (Blocking), 🟠 P1 (Major), and 🟡 P2 (Minor) with exact file:line, reference module path, and a concise fix snippet (<= 15 lines).

5. Detailed Modular Rules

Detailed specifications, examples, and templates are organized in rules/ (and mirrored in .agents/rules/ and .cursor/rules/):

• Core (Universal):
  • rules/core/01-core-engineering.md — Core Architecture, Zero-Trust Security, Error/Log Proximity, Metrics & Testing
  • rules/core/02-spec-driven-development.md — 4-Phase Spec-Driven Development (SDD) Workflow (Backend & Frontend)
  • rules/core/03-code-review.md — Evidence-Driven Architecture & Code Review Guidelines
• Backend:
  • rules/backend/go-backend.md — Go Clean Architecture, Concurrency, Validation & Testing
  • rules/backend/java-quarkus-backend.md — Java 21+, Quarkus CDI, Panache, Virtual Threads & Testing
  • rules/backend/node-bff-backend.md — Node.js / TypeScript Backend & BFF, Zod Schemas, AppDto/GwDto & Testing
• Frontend:
  • rules/frontend/node-react-frontend.md — React, TypeScript & SSR, Custom Hooks, AsyncState, WCAG 2.1 AA, BEM/SCSS & Testing