AGENTS.md

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