<!-- Generated by EEIK generate_adapters.py on 2026-08-10 — do not edit by hand -->
# AGENTS.md — this project

OpenAI Codex CLI reads this file to understand the repository context.
Child AGENTS.md files in subdirectories override or extend these instructions.

---

## Project

Enterprise application: this project

- Type: greenfield
- Domain: generic
- Governance profile: standard

## Technology Stack

- (no manifest — generic enterprise defaults apply)

---

## Non-Negotiable Coding Rules

# Golden Rules Standard

**Applies To:** All projects, all languages, all domains  
**Enforced By:** `code-reviewer` agent, CI/CD hooks, `security-auditor` agent  
**Status:** Non-negotiable

---

## The 12 Golden Rules

These rules apply to every line of code committed to any EEIK-managed project. They are not preferences — violation of a BLOCKER rule prevents merge.

---

### Rule 1 — Constructor Injection Only

**No `@Autowired` on fields. All injected fields are `final`.**

```java
// ❌ VIOLATION — field injection
@Service
public class OrderService {
    @Autowired
    private OrderRepository orderRepository;
}

// ✅ CORRECT — constructor injection
@Service
public class OrderService {
    private final OrderRepository orderRepository;

    public OrderService(OrderRepository orderRepository) {
        this.orderRepository = orderRepository;
    }
}
```

**Why:** Fields cannot be `final`. Cannot test without Spring context. Dependencies are invisible.

---

### Rule 2 — No Hardcoded Secrets

**No credentials, API keys, passwords, or AWS account IDs in source code.**

```java
// ❌ VIOLATION
String apiKey = "sk-live-abc123...";
String dbPassword = "SuperSecret123";

// ✅ CORRECT — environment variable or Secrets Manager
String apiKey = System.getenv("API_KEY");
// or via @Value, or SecretsManagerClient
```

**Why:** Source code is version-controlled and shared. Secrets in code become public.

---

### Rule 3 — SLF4J, Not System.out

**Use `log.info(...)` with parameterised messages. Never `System.out.println()`.**

```java
// ❌ VIOLATION
System.out.println("Processing order: " + orderId);

// ✅ CORRECT
log.info("Processing order id={}", orderId);
```

**Why:** `System.out` bypasses the logging framework — no level control, no structured output, no MDC context.

---

### Rule 4 — No SELECT *

**Always specify explicit column lists in SQL.**

```sql
-- ❌ VIOLATION
SELECT * FROM orders WHERE customer_id = :customerId;

-- ✅ CORRECT
SELECT id, customer_id, status, total_amount, created_at
FROM orders
WHERE customer_id = :customerId;
```

**Why:** Schema additions silently increase payload size and break mapping. Query plans are harder to optimise.

---

### Rule 5 — Parameterised Queries Only

**No SQL string concatenation. Use named parameters.**

```java
// ❌ VIOLATION — SQL injection risk
String sql = "SELECT * FROM orders WHERE id = '" + orderId + "'";

// ✅ CORRECT
String sql = "SELECT id, status FROM orders WHERE id = :orderId";
namedJdbcTemplate.queryForObject(sql, Map.of("orderId", orderId), rowMapper);
```

**Why:** String concatenation enables SQL injection. Non-negotiable security rule.

---

### Rule 6 — java.time Only (Java projects)

**No `java.util.Date`, `java.util.Calendar`, or `java.sql.Timestamp`.**

```java
// ❌ VIOLATION
Date now = new Date();
Calendar cal = Calendar.getInstance();

// ✅ CORRECT
Instant now = Instant.now();
LocalDate today = LocalDate.now();
ZonedDateTime zonedNow = ZonedDateTime.now(ZoneId.of("Europe/London"));
```

**Why:** `Date` and `Calendar` are mutable, non-thread-safe, and poorly designed. `java.time` is ISO 8601-correct.

---

### Rule 7 — jakarta.* in Spring Boot 3.x (Java projects)

**No `javax.*` imports in Spring Boot 3.x code.**

```java
// ❌ VIOLATION in Spring Boot 3.x
import javax.persistence.Entity;
import javax.validation.constraints.NotNull;

// ✅ CORRECT
import jakarta.persistence.Entity;
import jakarta.validation.constraints.NotNull;
```

**Why:** Spring Boot 3.x requires Jakarta EE 10. `javax.*` causes `ClassNotFoundException` at runtime.

---

### Rule 8 — Conventional Commits

**All commit messages follow `type(scope): description` format.**

```
# ❌ VIOLATION
"fix stuff"
"wip"
"updated OrderService"

# ✅ CORRECT
feat(orders): add order cancellation endpoint
fix(payments): handle null amount in authorisation
chore(deps): upgrade Spring Boot to 3.3.0
test(orders): add Testcontainers integration test for cancellation
```

**Types:** `feat`, `fix`, `refactor`, `test`, `chore`, `docs`, `perf`, `ci`, `build`, `revert`

---

### Rule 9 — No Partial Implementations

**Every committed method body is complete. No `// TODO implement this` in production code.**

```java
// ❌ VIOLATION
public BigDecimal calculatePremium(Policy policy) {
    // TODO: implement premium calculation
    return null;
}

// ✅ CORRECT — if not yet implementable, throw explicitly
public BigDecimal calculatePremium(Policy policy) {
    throw new UnsupportedOperationException(
        "Premium calculation not yet implemented — tracked in TD-042"
    );
}
```

---

### Rule 10 — No Empty Catch Blocks

**Every catch block at minimum logs the exception.**

```java
// ❌ VIOLATION
try {
    publishEvent(event);
} catch (Exception e) {
    // swallowed
}

// ✅ CORRECT
try {
    publishEvent(event);
} catch (Exception e) {
    log.error("Failed to publish event type={} id={}: {}", 
               event.getType(), event.getId(), e.getMessage(), e);
}
```

---

### Rule 11 — No Thread.sleep() in Tests

**Use Awaitility for async assertions.**

```java
// ❌ VIOLATION
Thread.sleep(2000);
assertThat(orderRepository.findById(id)).isPresent();

// ✅ CORRECT
await().atMost(5, SECONDS).until(() ->
    orderRepository.findById(id).isPresent()
);
```

---

### Rule 12 — Optional.get() Only with Guard

**Never call `Optional.get()` without a preceding `isPresent()` or use `orElseThrow()`.**

```java
// ❌ VIOLATION
Order order = orderRepository.findById(id).get(); // NoSuchElementException risk

// ✅ CORRECT
Order order = orderRepository.findById(id)
    .orElseThrow(() -> new OrderNotFoundException(id));
```

---

## Enforcement

| Severity | Rules | Gate |
|----------|-------|------|
| BLOCKER (pre-merge) | 2 (no secrets), 5 (SQL injection) | CI security scan |
| BLOCKER (code review) | 1, 3, 4, 6, 7, 9, 10, 12 | `code-reviewer` agent |
| MAJOR (code review) | 8, 11 | `code-reviewer` agent |

Rules 1–12 are checked by the `code-reviewer` agent on every PR review.


---

## Capability packs (engineering intelligence available)

| Pack | Focus |
|---|---|
| `agent-harness` | Generic, enterprise-grade agent runtime conformance |
| `ai-engineering` | Agentic AI engineering — agent design, LangGraph, RAG, prompt engineering, evaluation |
| `angular` | Angular engineering capability pack — Angular 17+ standalone components, Signals API, OnPu… |
| `architecture` | Enterprise architecture capability pack providing solution design, ADR authoring, NFR anal… |
| `aws` | AWS cloud engineering capability pack — CDK, security, tagging, cost, deployment |
| `banking` | Banking domain — payments, risk, and PSD2 / Basel III / PCI-DSS compliance |
| `belgium-insurance` | Belgium insurance domain capability pack — Branch 21/23/26 product rules, FSMA/NBB regulat… |
| `chaos-engineering` | Chaos & resilience engineering — hypothesis-driven fault-injection experiments, blast-radi… |
| `containers` | Containerisation — Dockerfiles, ECS Fargate, and container runtime standards |
| `core` | Foundational capability pack — cross-cutting agents, standards, and workflows for all proj… |
| `data-engineering` | Data pipeline engineering capability pack |
| `delivery` | Delivery — sprint planning, release management, and branching / CI-CD standards |
| `finops` | Cloud FinOps — cost visibility, allocation/tagging, rightsizing, commitment discounts (RI/… |
| `go` | Go engineering — cloud-native services, standard-library HTTP, table-driven tests, and idi… |
| `governance` | Enterprise governance — architecture reviews, security reviews, PRR, AI governance, compli… |
| `healthcare` | Healthcare domain — FHIR / HL7, HIPAA / GDPR health-data compliance, clinical data |
| `insurance` | Insurance domain — claims, underwriting, and Solvency II / GDPR compliance |
| `java` | Enterprise Java engineering capability pack for Spring Boot 3.x / Java 21 |
| `modernization` | Legacy modernization — COBOL / RPG / IBM i analysis and strangler-fig migration |
| `node` | Node.js / TypeScript backend — NestJS & Fastify services, strict TypeScript, Zod validatio… |
| `openshift` | Red Hat OpenShift and Kubernetes engineering capability pack |
| `platform-engineering` | Platform engineering — internal developer platforms (IDP), golden paths / paved roads, sel… |
| `python` | Python engineering — FastAPI, Pydantic, pytest, and type-annotated services |
| `react` | React engineering capability pack — Next.js 14 App Router, Server Components, TanStack Que… |
| `retail` | Retail & e-commerce domain — catalog, cart/checkout, order management, inventory, pricing/… |

Activate the packs your `project-manifest.yaml` selects with `eeik activate --apply`; each materialises
its agents and standards into `.claude/`.

## Standards enforced

`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`

Standards live in `.claude/standards/` (and `capability-packs/<pack>/standards/`). They define the
CORRECT/WRONG patterns the golden rules summarise.

## Approved patterns

- `agentic-supervisor-pattern`
- `java-outbox-pattern`

See `knowledge/patterns/` for the full write-ups and `knowledge/anti-patterns/` for what to avoid.

---

## Specialist agents

Route work to the right specialist (guidance lives in `.claude/agents/`):

| Agent | Use for |
|---|---|
| `a2a-engineer` | Use for designing and implementing Agent-to-Agent (A2A) communication protocols, multi-agent orchestration sys… |
| `ai-engineer` | Use for designing and implementing generative AI applications: RAG pipelines, LLM integrations, Bedrock agents… |
| `ai-governance-officer` | Use for AI governance reviews, model risk assessments, ethical AI audits, and producing model cards, AI risk r… |
| `angular-coverage-checker` | Use for analysing Angular Istanbul/Karma coverage reports, identifying uncovered branches in components and se… |
| `angular-developer` | Use for ticket-scoped Angular feature delivery: standalone components, services, reactive forms, lazy routes, … |
| `angular-tester` | Use for generating Jasmine/TestBed spec files for Angular standalone components and services |
| `arb-reviewer` | Use for Architecture Review Board (ARB) gate reviews: validating designs against enterprise standards, assessi… |
| `architect` | Use for system design, architectural pattern validation, ADR authoring, bounded context reviews, API contract … |
| `autogen-engineer` | Use for designing and implementing multi-agent systems with Microsoft AutoGen: conversation patterns, GroupCha… |
| `aws-architect` | Use for AWS cloud architecture design, Well-Architected reviews, CDK stack skeletons, cost estimates, and scal… |
| `aws-deploy-helper` | Use for AWS deployment tasks: ECS Fargate service deployments, Lambda updates, CDK deploy commands, deployment… |
| `business-analyst` | Use for translating requirements into OpenAPI contracts, Gherkin acceptance criteria, data models, and event s… |
| `cdk-terraform-helper` | Use for producing AWS CDK TypeScript constructs and Terraform HCL modules |
| `ci-engineer` | Use for CI/CD pipeline design, GitHub Actions workflow authoring, build optimisation, test parallelisation, an… |
| `code-reviewer` | Use for structured pull request reviews with severity labels [BLOCKER]/[MAJOR]/ [MINOR]/[NIT] |
| `containerisation-helper` | Use for Docker and container-related tasks: writing Dockerfiles, docker-compose files, multi-stage builds, con… |
| `coverage-enforcer` | Use for multi-stack coverage gap analysis (Java + Angular) and generating targeted tests to close gaps |
| `crewai-engineer` | Use for designing and implementing multi-agent systems with CrewAI: crew composition, agent role definition, t… |
| `data-engineer` | Use for data pipeline implementation: Kafka producer/consumer setup, Apache Spark jobs, dbt model authoring, A… |
| `data-scientist` | Use for data science tasks: exploratory data analysis, feature engineering, model training and evaluation, sta… |
| `dba-advisor` | Use for database design and operational guidance: Flyway/Liquibase migration authoring, query plan analysis, i… |
| `devsecops-engineer` | Use for DevSecOps pipeline integration: SAST/DAST tooling, secrets scanning, container vulnerability scanning,… |
| `enterprise-architect` | Use for TOGAF-aligned enterprise architecture artifacts: capability maps, value streams, technology lifecycle … |
| `estimator` | Use for bottom-up effort estimation: producing P50/P80/P90 estimates for features, epics, and technical tasks |
| `ibmi-modernization-expert` | Use for IBM i (AS/400) modernisation tasks: analysing RPG IV / RPGLE / CL programs, mapping IBM i business log… |
| `incident-handler` | Use for incident management: declaring incidents, coordinating response, producing live status updates, and dr… |
| `jacoco-coverage-tester` | Use for JaCoCo XML/HTML report analysis, identifying uncovered lines and branches in business logic, and gener… |
| `java-developer` | Use for ticket-scoped Java Spring Boot implementation work: services, controllers, repositories, DTOs, and Map… |
| `java-tech-lead` | Use for Java PR gating, standards enforcement, tech debt classification, and framework-level decisions on Spri… |
| `java-tester` | Use for generating complete Java test suites: JUnit 5 unit tests, Spring Boot slice tests (@WebMvcTest, @DataJ… |
| `kubernetes-engineer` | Use for Kubernetes and Helm workloads: Helm chart authoring, RBAC configuration, NetworkPolicy design, Horizon… |
| `langraph-engineer` | Use for designing and implementing stateful multi-agent workflows with LangGraph: graph-based agent orchestrat… |
| `local-deploy-helper` | Use for local development environment setup and troubleshooting: starting services with docker-compose, config… |
| `mcp-engineer` | Use for designing and implementing Model Context Protocol (MCP) servers and clients: tool definitions, resourc… |
| `ml-engineer` | Use for ML engineering tasks: building and optimising ML training pipelines, feature stores, model serving inf… |
| `mlops-engineer` | Use for MLOps platform design and implementation: model registry management, drift monitoring, automated retra… |
| `modernization-expert` | Use for mainframe and legacy application modernisation: COBOL-to-Java migration strategy, legacy Spring 4/5 to… |
| `ops-engineer` | Use for operational tasks: CloudWatch dashboard design, runbook authoring, alert configuration, capacity plann… |
| `performance-engineer` | Use for detecting N+1 queries, unbounded result sets, resource leaks, Angular rendering bottlenecks, and scala… |
| `project-tracker` | Use for project status tracking, sprint planning support, dependency mapping, and delivery health reporting |
| `python-developer` | Use for ticket-scoped Python implementation work: FastAPI services, Django applications, data scripts, CLI too… |
| `rca-agent` | Use for post-incident Root Cause Analysis: conducting 5-Whys analysis, producing RCA reports, identifying syst… |
| `react-developer` | Activate for React tasks: functional components, hooks, React Query, Zustand/Redux Toolkit state, Next.js App … |
| `security-auditor` | Use for OWASP Top 10 security reviews, vulnerability analysis, and producing severity-rated findings with reme… |
| `senior-developer` | Use for full-stack Java and Angular implementation spanning both backend and frontend layers |
| `spring-security-engineer` | Activate for Spring Security tasks: OAuth2/OIDC configuration, JWT validation, method security (@PreAuthorize)… |
| `sre-engineer` | Use for SRE practice implementation: SLI/SLO definition, error budget management, toil identification, reliabi… |
| `technical-writer` | Use for technical documentation tasks: API documentation, architecture guides, onboarding docs, runbooks, ADRs… |
| `test-quality-enforcer` | Use for auditing test suites for anti-patterns (empty assertions, mocking SUT, Thread.sleep, flaky patterns) a… |
| `tester` | Use for comprehensive test strategy and generating full test pyramid coverage for any stack |

---

## Repository Layout

```
.claude/          Claude Code configuration (agents, commands, hooks)
capability-packs/ Intelligence packs — read these for standards
knowledge/        Patterns, anti-patterns, ADRs, lessons learned
generators/       Project generators
eeik/            Engine: validate, activate, generate-adapters, lock
templates/        Code templates
```

## Before Writing Code

1. Read `capability-packs/core/standards/golden-rules.md`
2. Check `knowledge/patterns/` for existing patterns
3. Check `knowledge/anti-patterns/` for what to avoid
4. Identify the bounded context (domain, application, infrastructure, web)
5. State acceptance criteria before generating

## Commit Message Format

All commits must follow Conventional Commits:
```
type(scope): description

Types: feat | fix | refactor | test | docs | chore | ci | perf | security
```

## Test Requirements

- Unit tests for all domain logic
- Integration tests for all repository/adapter classes
- No `Thread.sleep()` — use Awaitility
- No `Optional.get()` without guard — use `orElseThrow()`

---

## Sub-directory Context

- `src/main/java/` → Java/Spring Boot source. See `capability-packs/java/`
- `src/test/`      → Tests. See `capability-packs/java/standards/`
- `infrastructure/`→ CDK/Terraform IaC. See `capability-packs/aws/`
- `frontend/`      → Angular/React. See relevant capability pack