GEMINI.md

1<!-- Generated by EEIK generate_adapters.py on 2026-08-10 — do not edit by hand -->
2# GEMINI.md — this project
3 
4Google Gemini CLI reads this file as persistent project context.
5 
6---
7 
8## Project Overview
9 
10Enterprise application: this project
11 
12**Type**: greenfield | **Domain**: generic | **Profile**: standard
13 
14## Technology
15 
16- (no manifest — generic enterprise defaults apply)
17 
18---
19 
20## Coding Standards
21 
22# Golden Rules Standard
23 
24**Applies To:** All projects, all languages, all domains  
25**Enforced By:** `code-reviewer` agent, CI/CD hooks, `security-auditor` agent  
26**Status:** Non-negotiable
27 
28---
29 
30## The 12 Golden Rules
31 
32These rules apply to every line of code committed to any EEIK-managed project. They are not preferences — violation of a BLOCKER rule prevents merge.
33 
34---
35 
36### Rule 1 — Constructor Injection Only
37 
38**No `@Autowired` on fields. All injected fields are `final`.**
39 
40```java
41// ❌ VIOLATION — field injection
42@Service
43public class OrderService {
44    @Autowired
45    private OrderRepository orderRepository;
46}
47 
48// ✅ CORRECT — constructor injection
49@Service
50public class OrderService {
51    private final OrderRepository orderRepository;
52 
53    public OrderService(OrderRepository orderRepository) {
54        this.orderRepository = orderRepository;
55    }
56}
57```
58 
59**Why:** Fields cannot be `final`. Cannot test without Spring context. Dependencies are invisible.
60 
61---
62 
63### Rule 2 — No Hardcoded Secrets
64 
65**No credentials, API keys, passwords, or AWS account IDs in source code.**
66 
67```java
68// ❌ VIOLATION
69String apiKey = "sk-live-abc123...";
70String dbPassword = "SuperSecret123";
71 
72// ✅ CORRECT — environment variable or Secrets Manager
73String apiKey = System.getenv("API_KEY");
74// or via @Value, or SecretsManagerClient
75```
76 
77**Why:** Source code is version-controlled and shared. Secrets in code become public.
78 
79---
80 
81### Rule 3 — SLF4J, Not System.out
82 
83**Use `log.info(...)` with parameterised messages. Never `System.out.println()`.**
84 
85```java
86// ❌ VIOLATION
87System.out.println("Processing order: " + orderId);
88 
89// ✅ CORRECT
90log.info("Processing order id={}", orderId);
91```
92 
93**Why:** `System.out` bypasses the logging framework — no level control, no structured output, no MDC context.
94 
95---
96 
97### Rule 4 — No SELECT *
98 
99**Always specify explicit column lists in SQL.**
100 
101```sql
102-- ❌ VIOLATION
103SELECT * FROM orders WHERE customer_id = :customerId;
104 
105-- ✅ CORRECT
106SELECT id, customer_id, status, total_amount, created_at
107FROM orders
108WHERE customer_id = :customerId;
109```
110 
111**Why:** Schema additions silently increase payload size and break mapping. Query plans are harder to optimise.
112 
113---
114 
115### Rule 5 — Parameterised Queries Only
116 
117**No SQL string concatenation. Use named parameters.**
118 
119```java
120// ❌ VIOLATION — SQL injection risk
121String sql = "SELECT * FROM orders WHERE id = '" + orderId + "'";
122 
123// ✅ CORRECT
124String sql = "SELECT id, status FROM orders WHERE id = :orderId";
125namedJdbcTemplate.queryForObject(sql, Map.of("orderId", orderId), rowMapper);
126```
127 
128**Why:** String concatenation enables SQL injection. Non-negotiable security rule.
129 
130---
131 
132### Rule 6 — java.time Only (Java projects)
133 
134**No `java.util.Date`, `java.util.Calendar`, or `java.sql.Timestamp`.**
135 
136```java
137// ❌ VIOLATION
138Date now = new Date();
139Calendar cal = Calendar.getInstance();
140 
141// ✅ CORRECT
142Instant now = Instant.now();
143LocalDate today = LocalDate.now();
144ZonedDateTime zonedNow = ZonedDateTime.now(ZoneId.of("Europe/London"));
145```
146 
147**Why:** `Date` and `Calendar` are mutable, non-thread-safe, and poorly designed. `java.time` is ISO 8601-correct.
148 
149---
150 
151### Rule 7 — jakarta.* in Spring Boot 3.x (Java projects)
152 
153**No `javax.*` imports in Spring Boot 3.x code.**
154 
155```java
156// ❌ VIOLATION in Spring Boot 3.x
157import javax.persistence.Entity;
158import javax.validation.constraints.NotNull;
159 
160// ✅ CORRECT
161import jakarta.persistence.Entity;
162import jakarta.validation.constraints.NotNull;
163```
164 
165**Why:** Spring Boot 3.x requires Jakarta EE 10. `javax.*` causes `ClassNotFoundException` at runtime.
166 
167---
168 
169### Rule 8 — Conventional Commits
170 
171**All commit messages follow `type(scope): description` format.**
172 
173```
174# ❌ VIOLATION
175"fix stuff"
176"wip"
177"updated OrderService"
178 
179# ✅ CORRECT
180feat(orders): add order cancellation endpoint
181fix(payments): handle null amount in authorisation
182chore(deps): upgrade Spring Boot to 3.3.0
183test(orders): add Testcontainers integration test for cancellation
184```
185 
186**Types:** `feat`, `fix`, `refactor`, `test`, `chore`, `docs`, `perf`, `ci`, `build`, `revert`
187 
188---
189 
190### Rule 9 — No Partial Implementations
191 
192**Every committed method body is complete. No `// TODO implement this` in production code.**
193 
194```java
195// ❌ VIOLATION
196public BigDecimal calculatePremium(Policy policy) {
197    // TODO: implement premium calculation
198    return null;
199}
200 
201// ✅ CORRECT — if not yet implementable, throw explicitly
202public BigDecimal calculatePremium(Policy policy) {
203    throw new UnsupportedOperationException(
204        "Premium calculation not yet implemented — tracked in TD-042"
205    );
206}
207```
208 
209---
210 
211### Rule 10 — No Empty Catch Blocks
212 
213**Every catch block at minimum logs the exception.**
214 
215```java
216// ❌ VIOLATION
217try {
218    publishEvent(event);
219} catch (Exception e) {
220    // swallowed
221}
222 
223// ✅ CORRECT
224try {
225    publishEvent(event);
226} catch (Exception e) {
227    log.error("Failed to publish event type={} id={}: {}", 
228               event.getType(), event.getId(), e.getMessage(), e);
229}
230```
231 
232---
233 
234### Rule 11 — No Thread.sleep() in Tests
235 
236**Use Awaitility for async assertions.**
237 
238```java
239// ❌ VIOLATION
240Thread.sleep(2000);
241assertThat(orderRepository.findById(id)).isPresent();
242 
243// ✅ CORRECT
244await().atMost(5, SECONDS).until(() ->
245    orderRepository.findById(id).isPresent()
246);
247```
248 
249---
250 
251### Rule 12 — Optional.get() Only with Guard
252 
253**Never call `Optional.get()` without a preceding `isPresent()` or use `orElseThrow()`.**
254 
255```java
256// ❌ VIOLATION
257Order order = orderRepository.findById(id).get(); // NoSuchElementException risk
258 
259// ✅ CORRECT
260Order order = orderRepository.findById(id)
261    .orElseThrow(() -> new OrderNotFoundException(id));
262```
263 
264---
265 
266## Enforcement
267 
268| Severity | Rules | Gate |
269|----------|-------|------|
270| BLOCKER (pre-merge) | 2 (no secrets), 5 (SQL injection) | CI security scan |
271| BLOCKER (code review) | 1, 3, 4, 6, 7, 9, 10, 12 | `code-reviewer` agent |
272| MAJOR (code review) | 8, 11 | `code-reviewer` agent |
273 
274Rules 1–12 are checked by the `code-reviewer` agent on every PR review.
275 
276 
277---
278 
279## Repository Intelligence
280 
281This repository uses **EEIK (Enterprise Engineering Intelligence Kit)**.
282Context is structured across:
283 
284| Location | Contents |
285|----------|----------|
286| `capability-packs/` | Standards, agents, workflows per technology |
287| `knowledge/patterns/` | Approved implementation patterns with code examples |
288| `knowledge/anti-patterns/` | What NOT to do and why |
289| `knowledge/adr-repository/` | Architecture Decision Records |
290| `.claude/memory/` | Project-specific context, constraints, decisions |
291 
292## Capability packs (engineering intelligence available)
293 
294| Pack | Focus |
295|---|---|
296| `agent-harness` | Generic, enterprise-grade agent runtime conformance |
297| `ai-engineering` | Agentic AI engineering — agent design, LangGraph, RAG, prompt engineering, evaluation |
298| `angular` | Angular engineering capability pack — Angular 17+ standalone components, Signals API, OnPu… |
299| `architecture` | Enterprise architecture capability pack providing solution design, ADR authoring, NFR anal… |
300| `aws` | AWS cloud engineering capability pack — CDK, security, tagging, cost, deployment |
301| `banking` | Banking domain — payments, risk, and PSD2 / Basel III / PCI-DSS compliance |
302| `belgium-insurance` | Belgium insurance domain capability pack — Branch 21/23/26 product rules, FSMA/NBB regulat… |
303| `chaos-engineering` | Chaos & resilience engineering — hypothesis-driven fault-injection experiments, blast-radi… |
304| `containers` | Containerisation — Dockerfiles, ECS Fargate, and container runtime standards |
305| `core` | Foundational capability pack — cross-cutting agents, standards, and workflows for all proj… |
306| `data-engineering` | Data pipeline engineering capability pack |
307| `delivery` | Delivery — sprint planning, release management, and branching / CI-CD standards |
308| `finops` | Cloud FinOps — cost visibility, allocation/tagging, rightsizing, commitment discounts (RI/… |
309| `go` | Go engineering — cloud-native services, standard-library HTTP, table-driven tests, and idi… |
310| `governance` | Enterprise governance — architecture reviews, security reviews, PRR, AI governance, compli… |
311| `healthcare` | Healthcare domain — FHIR / HL7, HIPAA / GDPR health-data compliance, clinical data |
312| `insurance` | Insurance domain — claims, underwriting, and Solvency II / GDPR compliance |
313| `java` | Enterprise Java engineering capability pack for Spring Boot 3.x / Java 21 |
314| `modernization` | Legacy modernization — COBOL / RPG / IBM i analysis and strangler-fig migration |
315| `node` | Node.js / TypeScript backend — NestJS & Fastify services, strict TypeScript, Zod validatio… |
316| `openshift` | Red Hat OpenShift and Kubernetes engineering capability pack |
317| `platform-engineering` | Platform engineering — internal developer platforms (IDP), golden paths / paved roads, sel… |
318| `python` | Python engineering — FastAPI, Pydantic, pytest, and type-annotated services |
319| `react` | React engineering capability pack — Next.js 14 App Router, Server Components, TanStack Que… |
320| `retail` | Retail & e-commerce domain — catalog, cart/checkout, order management, inventory, pricing/… |
321 
322Activate the packs your `project-manifest.yaml` selects with `eeik activate --apply`; each materialises
323its agents and standards into `.claude/`.
324 
325## Standards enforced
326 
327`ai-governance`, `angular`, `api-standard`, `architecture-principles`, `aws`, `branching-standard`, `cicd`, `containers`, `data-engineering`, `estimation-standard`, `event-driven`, `fastapi`, `golden-rules`, `graphql`, `integration-standard`, `java`, `java-standard`, `mainframe`, `modernization-patterns`, `nfr-standard`, `observability-baseline`, `python`, `react-standard`, `security-baseline`, `spring-standard`, `sql`, `testing`
328 
329Standards live in `.claude/standards/` (and `capability-packs/<pack>/standards/`). They define the
330CORRECT/WRONG patterns the golden rules summarise.
331 
332## Approved patterns
333 
334- `agentic-supervisor-pattern`
335- `java-outbox-pattern`
336 
337See `knowledge/patterns/` for the full write-ups and `knowledge/anti-patterns/` for what to avoid.
338 
339## Specialist agents
340 
341| Agent | Use for |
342|---|---|
343| `a2a-engineer` | Use for designing and implementing Agent-to-Agent (A2A) communication protocols, multi-agent orchestration sys… |
344| `ai-engineer` | Use for designing and implementing generative AI applications: RAG pipelines, LLM integrations, Bedrock agents… |
345| `ai-governance-officer` | Use for AI governance reviews, model risk assessments, ethical AI audits, and producing model cards, AI risk r… |
346| `angular-coverage-checker` | Use for analysing Angular Istanbul/Karma coverage reports, identifying uncovered branches in components and se… |
347| `angular-developer` | Use for ticket-scoped Angular feature delivery: standalone components, services, reactive forms, lazy routes, … |
348| `angular-tester` | Use for generating Jasmine/TestBed spec files for Angular standalone components and services |
349| `arb-reviewer` | Use for Architecture Review Board (ARB) gate reviews: validating designs against enterprise standards, assessi… |
350| `architect` | Use for system design, architectural pattern validation, ADR authoring, bounded context reviews, API contract … |
351| `autogen-engineer` | Use for designing and implementing multi-agent systems with Microsoft AutoGen: conversation patterns, GroupCha… |
352| `aws-architect` | Use for AWS cloud architecture design, Well-Architected reviews, CDK stack skeletons, cost estimates, and scal… |
353| `aws-deploy-helper` | Use for AWS deployment tasks: ECS Fargate service deployments, Lambda updates, CDK deploy commands, deployment… |
354| `business-analyst` | Use for translating requirements into OpenAPI contracts, Gherkin acceptance criteria, data models, and event s… |
355| `cdk-terraform-helper` | Use for producing AWS CDK TypeScript constructs and Terraform HCL modules |
356| `ci-engineer` | Use for CI/CD pipeline design, GitHub Actions workflow authoring, build optimisation, test parallelisation, an… |
357| `code-reviewer` | Use for structured pull request reviews with severity labels [BLOCKER]/[MAJOR]/ [MINOR]/[NIT] |
358| `containerisation-helper` | Use for Docker and container-related tasks: writing Dockerfiles, docker-compose files, multi-stage builds, con… |
359| `coverage-enforcer` | Use for multi-stack coverage gap analysis (Java + Angular) and generating targeted tests to close gaps |
360| `crewai-engineer` | Use for designing and implementing multi-agent systems with CrewAI: crew composition, agent role definition, t… |
361| `data-engineer` | Use for data pipeline implementation: Kafka producer/consumer setup, Apache Spark jobs, dbt model authoring, A… |
362| `data-scientist` | Use for data science tasks: exploratory data analysis, feature engineering, model training and evaluation, sta… |
363| `dba-advisor` | Use for database design and operational guidance: Flyway/Liquibase migration authoring, query plan analysis, i… |
364| `devsecops-engineer` | Use for DevSecOps pipeline integration: SAST/DAST tooling, secrets scanning, container vulnerability scanning,… |
365| `enterprise-architect` | Use for TOGAF-aligned enterprise architecture artifacts: capability maps, value streams, technology lifecycle … |
366| `estimator` | Use for bottom-up effort estimation: producing P50/P80/P90 estimates for features, epics, and technical tasks |
367| `ibmi-modernization-expert` | Use for IBM i (AS/400) modernisation tasks: analysing RPG IV / RPGLE / CL programs, mapping IBM i business log… |
368| `incident-handler` | Use for incident management: declaring incidents, coordinating response, producing live status updates, and dr… |
369| `jacoco-coverage-tester` | Use for JaCoCo XML/HTML report analysis, identifying uncovered lines and branches in business logic, and gener… |
370| `java-developer` | Use for ticket-scoped Java Spring Boot implementation work: services, controllers, repositories, DTOs, and Map… |
371| `java-tech-lead` | Use for Java PR gating, standards enforcement, tech debt classification, and framework-level decisions on Spri… |
372| `java-tester` | Use for generating complete Java test suites: JUnit 5 unit tests, Spring Boot slice tests (@WebMvcTest, @DataJ… |
373| `kubernetes-engineer` | Use for Kubernetes and Helm workloads: Helm chart authoring, RBAC configuration, NetworkPolicy design, Horizon… |
374| `langraph-engineer` | Use for designing and implementing stateful multi-agent workflows with LangGraph: graph-based agent orchestrat… |
375| `local-deploy-helper` | Use for local development environment setup and troubleshooting: starting services with docker-compose, config… |
376| `mcp-engineer` | Use for designing and implementing Model Context Protocol (MCP) servers and clients: tool definitions, resourc… |
377| `ml-engineer` | Use for ML engineering tasks: building and optimising ML training pipelines, feature stores, model serving inf… |
378| `mlops-engineer` | Use for MLOps platform design and implementation: model registry management, drift monitoring, automated retra… |
379| `modernization-expert` | Use for mainframe and legacy application modernisation: COBOL-to-Java migration strategy, legacy Spring 4/5 to… |
380| `ops-engineer` | Use for operational tasks: CloudWatch dashboard design, runbook authoring, alert configuration, capacity plann… |
381| `performance-engineer` | Use for detecting N+1 queries, unbounded result sets, resource leaks, Angular rendering bottlenecks, and scala… |
382| `project-tracker` | Use for project status tracking, sprint planning support, dependency mapping, and delivery health reporting |
383| `python-developer` | Use for ticket-scoped Python implementation work: FastAPI services, Django applications, data scripts, CLI too… |
384| `rca-agent` | Use for post-incident Root Cause Analysis: conducting 5-Whys analysis, producing RCA reports, identifying syst… |
385| `react-developer` | Activate for React tasks: functional components, hooks, React Query, Zustand/Redux Toolkit state, Next.js App … |
386| `security-auditor` | Use for OWASP Top 10 security reviews, vulnerability analysis, and producing severity-rated findings with reme… |
387| `senior-developer` | Use for full-stack Java and Angular implementation spanning both backend and frontend layers |
388| `spring-security-engineer` | Activate for Spring Security tasks: OAuth2/OIDC configuration, JWT validation, method security (@PreAuthorize)… |
389| `sre-engineer` | Use for SRE practice implementation: SLI/SLO definition, error budget management, toil identification, reliabi… |
390| `technical-writer` | Use for technical documentation tasks: API documentation, architecture guides, onboarding docs, runbooks, ADRs… |
391| `test-quality-enforcer` | Use for auditing test suites for anti-patterns (empty assertions, mocking SUT, Thread.sleep, flaky patterns) a… |
392| `tester` | Use for comprehensive test strategy and generating full test pyramid coverage for any stack |
393 
394## Architecture
395 
396Hexagonal Architecture + DDD:
397- `domain/` — pure business logic, no framework dependencies
398- `application/` — use cases and orchestration
399- `infrastructure/` — adapters for DB, messaging, external services
400- `web/` — HTTP layer, DTOs
401 
402## Key Commands
403 
404```bash
405# Validate manifest
406eeik validate
407 
408# Check active packs and adapter status
409eeik status
410 
411# Regenerate adapters after manifest change
412eeik generate-adapters --apply
413```
414