Two files, one repository
doubts-suplab/eeik-bootstrap ships 5 formats across 40 indexed files. The question worth asking is whether the second one says anything the first does not.
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 1 | 29 | 20 | 2% |
| Commands | 1 | 2 | 11 | 7% |
| Section tags | 5 | 2 | 5 | 42% |
What each file covers
Sections
1 shared · 29 only in A · 20 only in B- − AGENTS.md — this project
- − Project
- − Technology Stack
- − Non-Negotiable Coding Rules
- − Golden Rules Standard
- − The 12 Golden Rules
- − Rule 1 — Constructor Injection Only
- − Rule 2 — No Hardcoded Secrets
- − Rule 3 — SLF4J, Not System.out
- − Rule 4 — No SELECT *
- − Rule 5 — Parameterised Queries Only
- − Rule 6 — java.time Only (Java projects)
- − Rule 7 — jakarta.* in Spring Boot 3.x (Java projects)
- − Rule 8 — Conventional Commits
- − ❌ VIOLATION
- − ✅ CORRECT
- − Rule 9 — No Partial Implementations
- − Rule 10 — No Empty Catch Blocks
- − Rule 11 — No Thread.sleep() in Tests
- − Rule 12 — Optional.get() Only with Guard
- − Enforcement
- − Capability packs (engineering intelligence available)
- − Standards enforced
- − Approved patterns
- − Specialist agents
- − Repository Layout
- − Commit Message Format
- − Test Requirements
- − Sub-directory Context
- + CLAUDE.md — Project Brief for Claude Code Sessions
- + What This Repository Is
- + Generation Engine (v1.4) — governed, versioned
- + How to Use Claude Code Agents
- + Supported Technology Stack
- + Legacy Java
- + Modern Java
- + Angular
- + Mainframe
- + Python
- + Go
- + Node.js / TypeScript
- + Data Engineering
- + GraphQL
- + AWS
- + Golden Rules (Non-Negotiable)
- + Estimation Formula
- + Available Slash Commands
- + Memory and Context
- + What NOT To Do
- Before Writing Code
Commands
1 shared · 2 only in A · 11 only in B- − node
- − python
- + pip install -e .
- + python -m eeik
- + python3 -m pytest tests/ -q
- + go-developer
- + go-microservices-engineer
- + node-developer
- + mypy --strict
- + pytest-asyncio
- + pytest-cov
- + go test -race
- + go vet
- python-developer
Section tags
5 shared · 2 only in A · 5 only in B- − architecture
- − security
- + setup
- + types
- + api
- + performance
- + agent-behaviour
- test
- lint-format
- code-style
- git-pr
- do-not
Line diff
doubts-suplab/eeik-bootstrap · AGENTS.md
@@ −1 @@
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
doubts-suplab/eeik-bootstrap · CLAUDE.md
@@ +1 @@
1# CLAUDE.md — Project Brief for Claude Code Sessions
2
3## What This Repository Is
4
5`eeik_bootstrap` is a **bootstrap and seed repository** — it is not a runnable application. Its purpose is to provide a ready-to-fork configuration base for enterprise projects. Drop the relevant files into any new or existing project to immediately establish:
6
7- GitHub Copilot workspace instructions (`.github/` directory — already in this repo)
8- Claude Code agent, command, and standards configuration (`.claude/` directory — this layer)
9- Shared quality gates, coding standards, and memory structure
10
11When adopting this seed into a real project, replace all placeholder values (e.g. service names, environment URLs, team names) with project-specific values.
12
13---
14
15## Generation Engine (v1.4) — governed, versioned
16
17EEIK is evolving from copy-once static config into a **governed generation engine** (posture: an
18engine other tools consume, *not* a product platform competing with APEX). Two things follow from that:
19
20- **The engine is a package.** The executable core lives in the installable **`eeik/`** package
21 (`pip install -e .` → the `eeik` console script, or `python -m eeik`). `scripts/*.py` are thin
22 backward-compatible shims. The repo's *content* layers (`capability-packs/`, `knowledge/`,
23 `templates/`, `generators/`, `bootstrap/`) are data the engine reads — not code.
24- **Three surfaces, one implementation.** The CLI, the MCP server (`eeik mcp`, ADR-006), and the typed
25 Python SDK (`import eeik`, ADR-007) are all adapters over `eeik/api.py`. Add behaviour to the SDK
26 (`eeik/api.py`) and let the CLI/MCP delegate — do NOT duplicate logic per surface. The public API is
27 `eeik.__all__`; the catalog accessor is `eeik.find_packs()` (not `catalog`, to avoid shadowing the
28 submodule).
29- **One canonical manifest schema.** `eeik/schemas/manifest.schema.json` is the single source of truth
30 (`eeik/manifest.py` enforces it). Do NOT reintroduce a second schema copy.
31- **Generators run on HALO.** EEIK's generators are agents; they flow through the `agent-harness`
32 runtime (`eeik/generation.py`). Generation is **SUGGEST authority**, so it can never auto-enforce —
33 drafts are gated, audited, and staged for human review, and it **fails safe** when HALO is absent.
34 Do NOT re-implement a confidence gate inside EEIK — consume HALO's.
35 See [ADR-003](docs/decisions/ADR-003-eeik-generators-run-on-halo.md).
36- **Packs are versioned dependencies.** Every pack declares a `version` in `metadata.yaml`.
37 `eeik lock` pins adopted versions + content digests to `eeik.lock`; `eeik diff` reports drift;
38 `eeik upgrade` re-pins. See [ADR-004](docs/decisions/ADR-004-capability-pack-versioning-and-lockfile.md).
39
40CLI: `eeik demo` (offline governed showcase), `eeik lock|diff|upgrade`, `eeik catalog` (queryable pack
41index), `eeik architectures` (engine-surfaced reference architectures, ADR-010), `eeik verify`
42(conformance gate, ADR-008), `eeik contract` (emit a HALO Agent Contract, ADR-009), `eeik mcp`
43(read-model MCP server, ADR-006), `eeik run <gen> --governed`, `eeik seed` (copy the seed set into an
44adopting project — the explicit dual-purpose boundary, ADR-011), `eeik lessons` (closed-loop knowledge
45capture — HALO/APEX audit logs → staged `LL-NNN` lessons, SUGGEST authority, ADR-012), `eeik doctor`
46(diagnose adoption/health problems — deps, HALO/MCP, manifest, resolution, drift, conformance — each
47with an actionable fix), `eeik lint` (content-quality lint of pack agents + standards — frontmatter,
48name-matches-file, description quality, structure; complements `verify`), `eeik telemetry` (opt-in,
49local-first, non-identifying pack/generator usage counters — off by default, no network; ADR/ROADMAP §8).
50Tests: `python3 -m pytest tests/ -q`. Keep `docs/progress.md`, `ROADMAP.md`, `README.md`, and
51`docs/index.html` in sync when this layer changes.
52
53---
54
55## How to Use Claude Code Agents
56
57Agents live in `.claude/agents/`. Claude Code automatically selects the most relevant agent based on the `description` field in each agent's frontmatter. You can also invoke agents explicitly by mentioning their name.
58
59**Selection rule:** Read the description of each agent file to understand its trigger condition. The description is written as a precise activation trigger — if your task matches it, that agent will be selected.
60
61**To invoke explicitly:** Reference the agent slug in your prompt:
62- "Using the `java-developer` agent, implement the OrderService"
63- "Run a `security-auditor` review on this PR diff"
64- "Activate `estimator` and give me a P80 estimate for this feature"
65
66**Key agents by domain:**
67
68| Domain | Agents |
69|--------|--------|
70| Java / Spring Boot | `java-developer`, `java-tech-lead`, `java-tester`, `jacoco-coverage-tester`, `senior-developer` |
71| Python | `python-developer` |
72| Go | `go-developer`, `go-microservices-engineer` |
73| Node / TypeScript | `node-developer`, `typescript-api-engineer` |
74| Angular | `angular-developer`, `angular-tester`, `angular-coverage-checker` |
75| Architecture | `architect`, `enterprise-architect`, `arb-reviewer` |
76| Cloud / Infra | `aws-architect`, `cdk-terraform-helper`, `aws-deploy-helper`, `ci-engineer`, `containerisation-helper`, `kubernetes-engineer`, `devsecops-engineer`, `local-deploy-helper`, `finops-engineer`, `chaos-engineer`, `platform-engineer` |
77| Data | `data-engineer`, `data-scientist` |
78| Database | `dba-advisor` |
79| Quality | `code-reviewer`, `security-auditor`, `performance-engineer`, `coverage-enforcer`, `test-quality-enforcer`, `tester` |
80| AI / ML | `ai-engineer`, `ml-engineer`, `mlops-engineer`, `ai-governance-officer` |
81| Agentic AI | `langraph-engineer`, `crewai-engineer`, `autogen-engineer`, `mcp-engineer`, `a2a-engineer` |
82| Delivery | `estimator`, `project-tracker`, `business-analyst`, `technical-writer` |
83| Operations | `incident-handler`, `rca-agent`, `ops-engineer`, `sre-engineer` |
84| Modernisation | `modernization-expert`, `ibmi-modernization-expert` |
85
86---
87
88## Supported Technology Stack
89
90### Legacy Java
91- Spring Framework 4.x / 5.x (Spring MVC, Spring Security, Spring Batch)
92- Java 8/11 with `javax.*` APIs
93- JUnit 4, Mockito 2/3, Maven
94
95### Modern Java
96- Spring Boot 3.x with Java 17/21
97- `jakarta.*` exclusively — no `javax.*`
98- Spring Data JPA / Spring Data JDBC, Spring Security 6.x
99- JUnit 5, AssertJ, Mockito 5, Testcontainers, Pact
100
101### Angular
102- Angular 15+ with standalone components
103- Signals API, NgRx, RxJS 7+
104- Jasmine / Karma / Istanbul for tests
105- Strict TypeScript (`"strict": true`)
106
107### Mainframe
108- IBM Enterprise COBOL 6.x, CICS, DB2 z/OS
109- IBM i (AS400): RPG IV, RPGLE (ILE), CL, DDS, DB2 for i
110- JCL, VSAM, QSAM
111
112### Python
113- Python 3.11+ with type annotations (`mypy --strict`)
114- FastAPI with Pydantic v2, SQLAlchemy async, Alembic
115- pytest with `pytest-asyncio`, `pytest-cov`, `testcontainers-python`
116- Ruff for formatting and linting
117
118### Go
119- Go 1.22+, standard-library-first (`net/http`, `database/sql`, `log/slog`)
120- Cloud-native services: gRPC + protobuf (`buf`), context propagation, graceful shutdown
121- Table-driven tests, `go test -race`, Testcontainers-go for integration
122- `gofmt` + `go vet` + `golangci-lint`; idiomatic errors (`%w`, `errors.Is/As`)
123
124### Node.js / TypeScript
125- Node 20+, TypeScript 5.5+ (`"strict": true`, no `any`)
126- NestJS / Fastify services; Zod validation at the boundary; typed, validated env config
127- Vitest / Jest with coverage; Testcontainers for integration; `pino` structured logging
128- ESLint `no-floating-promises`; parameterised queries (Prisma / Drizzle)
129
130### Data Engineering
131- Apache Kafka with Schema Registry (Avro / Protobuf)
132- Apache Spark (PySpark DataFrame API)
133- dbt (staging → intermediate → mart model layers)
134- AWS Glue, Step Functions, Airflow
135
136### GraphQL
137- Schema-first with `.graphql` SDL files
138- Spring for GraphQL (Java) or Strawberry / Ariadne (Python)
139- DataLoader for N+1 prevention
140- Cursor-based (Relay) pagination
141
142### AWS
143- CDK TypeScript (L2/L3 constructs preferred)
144- Terraform HCL with remote state (S3 + DynamoDB lock)
145- ECS Fargate, EKS, Lambda, API Gateway
146- RDS Aurora, ElastiCache, DynamoDB
147- SageMaker, Bedrock, Glue, Athena
148
149---
150
151## Golden Rules (Non-Negotiable)
152
153These rules apply across ALL code in ALL domains. They are enforced by hooks and reviewed by the `code-reviewer` and `java-tech-lead` agents.
154
1551. **Constructor injection only** — no `@Autowired` on fields; all injected fields are `final`
1562. **No hardcoded secrets** — all credentials, API keys, connection strings go to AWS Secrets Manager or environment variables; never committed to source
1573. **SLF4J not System.out** — `log.info(...)` with parameterised messages; never `System.out.println()`
1584. **SOLID principles** — Single Responsibility, Open/Closed, Liskov, Interface Segregation, Dependency Inversion
1595. **Domain-Driven Design** — respect bounded context boundaries; no cross-context direct database joins
1606. **No `SELECT *`** — always specify explicit column lists in SQL
1617. **Parameterised queries only** — never build SQL via string concatenation; use `NamedParameterJdbcTemplate` or named JPQL parameters
1628. **Conventional Commits** — all commit messages follow `type(scope): description` format
1639. **No partial implementations** — every method body is complete; no `// TODO implement this` in committed code
16410. **`jakarta.*` in Boot 3.x** — never `javax.*` in Spring Boot 3.x code
165
166---
167
168## Before Writing Code
169
1701. **Pick the correct agent** — check `.claude/agents/` descriptions and activate the right specialist
1712. **Read the relevant standards file** — check `.claude/standards/` for the technology you are working in
1723. **Read project context** — check `.claude/memory/project-context.md` for environment-specific details
1734. **State what you are building** — before generating code, declare: the bounded context, the layer (domain/application/infrastructure/web), and the acceptance criteria
1745. **Check for existing patterns** — use `Grep` to find similar existing implementations before inventing new abstractions
175
176---
177
178## Estimation Formula
179
180Human Days = **Σ Raw Hours ÷ 6.4**
181
182Where: `6.4 = 8 hours/day × 80% efficiency`
183
184The 80% efficiency factor accounts for: meetings, context-switching, PR review cycles, environment issues, code review iterations, and interruptions.
185
186**Confidence ranges:**
187
188| Scenario | Multiplier | Use For |
189|----------|------------|---------|
190| P50 (Likely) | ×1.0 | Sprint planning baseline |
191| P80 (Conservative) | ×1.3 | Sprint commitment |
192| P90 (Pessimistic) | ×1.6 | Release planning buffer |
193
194**Typical raw hours by task type:**
195
196| Task | Simple | Moderate | Complex |
197|------|--------|----------|---------|
198| REST API endpoint (Spring Boot) | 2–4h | 4–8h | 8–16h |
199| Angular standalone component | 2–4h | 4–8h | 8–12h |
200| Unit test class | 1–2h | 2–4h | 4–6h |
201| Integration test (Testcontainers) | 2–4h | 4–6h | 6–10h |
202| CDK stack (new resource) | 2–4h | 4–8h | 8–20h |
203| Database migration script | 1–2h | 2–4h | 4–8h |
204
205Invoke the `/estimate` command or activate the `estimator` agent for a full breakdown.
206
207---
208
209## Available Slash Commands
210
211| Command | Description |
212|---------|-------------|
213| `/bootstrap` | Interactive project discovery — generates `project-manifest.yaml` |
214| `/setup-memory` | Interactive interview to populate all `.claude/memory/` files with project context |
215| `/validate-manifest` | Validate `project-manifest.yaml` against the schema and governance rules |
216| `/generate-repo` | Generate full repository scaffold from validated manifest |
217| `/generate-agent --blueprint <type> --name <name>` | Generate a project-specific agent from a blueprint |
218| `/adr "decision title"` | Scaffold a new Architecture Decision Record in `docs/decisions/` |
219| `/rca "symptoms"` | Open an RCA workflow with 5-Whys template |
220| `/estimate "feature description"` | Produce a bottom-up P50/P80/P90 effort estimate |
221| `/review` | Run full PR review checklist across security, performance, and quality |
222| `/threat-model "service description"` | STRIDE threat model for a service or bounded context |
223| `/incident "severity: P1\|P2, service: name, symptom: description"` | Declare and coordinate an incident |
224| `/security-scan [file or directory]` | OWASP Top 10 review plus secrets scan |
225| `/deploy-check "env: dev\|staging\|prod, service: name"` | Pre-deployment readiness checklist |
226| `/migrate-db "description"` | Generate Flyway/Liquibase migration with rollback and risk assessment |
227| `/api-contract "resource description"` | Contract-first API design — OpenAPI stub + Pact consumer test |
228| `/tech-debt add "description"` | Register a new tech debt item to `.claude/memory/tech-debt.md` |
229| `/memory-update "what changed"` | Update relevant `.claude/memory/` files with new context |
230| `/coverage-report [module path]` | JaCoCo/Istanbul coverage analysis with targeted test stubs |
231| `/sync-docs` | Sync API documentation against OpenAPI specs |
232
233---
234
235## Memory and Context
236
237Claude Code reads `.claude/memory/` files at the start of sessions to load persistent context. Use these files to avoid re-explaining the project on every session.
238
239| File | Purpose |
240|------|---------|
241| `project-context.md` | Service inventory, environments, auth patterns, key resource names |
242| `domain-glossary.md` | Business terminology — what terms mean in this project's domain |
243| `decisions.md` | Architecture Decision Log — what was decided and why |
244| `constraints.md` | Hard technical and business constraints that must never be violated |
245| `patterns.md` | Approved implementation patterns and anti-patterns to avoid |
246| `tech-debt.md` | Tech debt register with priority and target sprint |
247| `rca-tracker.md` | Incident/RCA status log |
248| `session-log.md` | Auto-updated by the `on-stop.sh` hook with each session's changed files |
249| `rejected-approaches.md` | Things that were tried and rejected — prevents re-trying failed ideas |
250
251Use `/memory-update` to update these files when significant decisions or changes occur.
252
253---
254
255## What NOT To Do
256
257- Do NOT use `javax.*` in Spring Boot 3.x code — use `jakarta.*`
258- Do NOT use `@Autowired` on fields — constructor injection only
259- Do NOT write `SELECT *` in any SQL query
260- Do NOT hardcode credentials, API keys, passwords, or AWS account IDs in source code
261- Do NOT use `Thread.sleep()` in tests — use `Awaitility.await().until()`
262- Do NOT write empty catch blocks — at minimum log the exception at WARN or ERROR level
263- Do NOT use `new Date()` or `java.util.Calendar` — use `java.time` (LocalDate, LocalDateTime, Instant, ZonedDateTime)
264- Do NOT add new Maven/npm dependencies without checking the BOM and flagging version conflicts
265- Do NOT write partial implementations — if a method is not complete, say so explicitly
266- Do NOT commit directly to `main` or `master` — always use a feature branch and PR
267- Do NOT use `System.out.println()` anywhere in production code — use SLF4J
268- Do NOT use `Optional.get()` without a preceding `isPresent()` check or `orElseThrow()`
269
@@ −1 +1 @@
1−<!-- Generated by EEIK generate_adapters.py on 2026-08-10 — do not edit by hand -->
2−# AGENTS.md — this project
1+# CLAUDE.md — Project Brief for Claude Code Sessions
32
4−OpenAI Codex CLI reads this file to understand the repository context.
5−Child AGENTS.md files in subdirectories override or extend these instructions.
3+## What This Repository Is
64
7−---
5+`eeik_bootstrap` is a **bootstrap and seed repository** — it is not a runnable application. Its purpose is to provide a ready-to-fork configuration base for enterprise projects. Drop the relevant files into any new or existing project to immediately establish:
86
9−## Project
7+- GitHub Copilot workspace instructions (`.github/` directory — already in this repo)
8+- Claude Code agent, command, and standards configuration (`.claude/` directory — this layer)
9+- Shared quality gates, coding standards, and memory structure
1010
11−Enterprise application: this project
11+When adopting this seed into a real project, replace all placeholder values (e.g. service names, environment URLs, team names) with project-specific values.
1212
13−- Type: greenfield
14−- Domain: generic
15−- Governance profile: standard
16−
17−## Technology Stack
18−
19−- (no manifest — generic enterprise defaults apply)
20−
2113 ---
2214
23−## Non-Negotiable Coding Rules
15+## Generation Engine (v1.4) — governed, versioned
2416
25−# Golden Rules Standard
17+EEIK is evolving from copy-once static config into a **governed generation engine** (posture: an
18+engine other tools consume, *not* a product platform competing with APEX). Two things follow from that:
2619
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
20+- **The engine is a package.** The executable core lives in the installable **`eeik/`** package
21+ (`pip install -e .` → the `eeik` console script, or `python -m eeik`). `scripts/*.py` are thin
22+ backward-compatible shims. The repo's *content* layers (`capability-packs/`, `knowledge/`,
23+ `templates/`, `generators/`, `bootstrap/`) are data the engine reads — not code.
24+- **Three surfaces, one implementation.** The CLI, the MCP server (`eeik mcp`, ADR-006), and the typed
25+ Python SDK (`import eeik`, ADR-007) are all adapters over `eeik/api.py`. Add behaviour to the SDK
26+ (`eeik/api.py`) and let the CLI/MCP delegate — do NOT duplicate logic per surface. The public API is
27+ `eeik.__all__`; the catalog accessor is `eeik.find_packs()` (not `catalog`, to avoid shadowing the
28+ submodule).
29+- **One canonical manifest schema.** `eeik/schemas/manifest.schema.json` is the single source of truth
30+ (`eeik/manifest.py` enforces it). Do NOT reintroduce a second schema copy.
31+- **Generators run on HALO.** EEIK's generators are agents; they flow through the `agent-harness`
32+ runtime (`eeik/generation.py`). Generation is **SUGGEST authority**, so it can never auto-enforce —
33+ drafts are gated, audited, and staged for human review, and it **fails safe** when HALO is absent.
34+ Do NOT re-implement a confidence gate inside EEIK — consume HALO's.
35+ See [ADR-003](docs/decisions/ADR-003-eeik-generators-run-on-halo.md).
36+- **Packs are versioned dependencies.** Every pack declares a `version` in `metadata.yaml`.
37+ `eeik lock` pins adopted versions + content digests to `eeik.lock`; `eeik diff` reports drift;
38+ `eeik upgrade` re-pins. See [ADR-004](docs/decisions/ADR-004-capability-pack-versioning-and-lockfile.md).
3039
31−---
40+CLI: `eeik demo` (offline governed showcase), `eeik lock|diff|upgrade`, `eeik catalog` (queryable pack
41+index), `eeik architectures` (engine-surfaced reference architectures, ADR-010), `eeik verify`
42+(conformance gate, ADR-008), `eeik contract` (emit a HALO Agent Contract, ADR-009), `eeik mcp`
43+(read-model MCP server, ADR-006), `eeik run <gen> --governed`, `eeik seed` (copy the seed set into an
44+adopting project — the explicit dual-purpose boundary, ADR-011), `eeik lessons` (closed-loop knowledge
45+capture — HALO/APEX audit logs → staged `LL-NNN` lessons, SUGGEST authority, ADR-012), `eeik doctor`
46+(diagnose adoption/health problems — deps, HALO/MCP, manifest, resolution, drift, conformance — each
47+with an actionable fix), `eeik lint` (content-quality lint of pack agents + standards — frontmatter,
48+name-matches-file, description quality, structure; complements `verify`), `eeik telemetry` (opt-in,
49+local-first, non-identifying pack/generator usage counters — off by default, no network; ADR/ROADMAP §8).
50+Tests: `python3 -m pytest tests/ -q`. Keep `docs/progress.md`, `ROADMAP.md`, `README.md`, and
51+`docs/index.html` in sync when this layer changes.
3252
33−## The 12 Golden Rules
34−
35−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.
36−
3753 ---
3854
39−### Rule 1 — Constructor Injection Only
55+## How to Use Claude Code Agents
4056
41−**No `@Autowired` on fields. All injected fields are `final`.**
57+Agents live in `.claude/agents/`. Claude Code automatically selects the most relevant agent based on the `description` field in each agent's frontmatter. You can also invoke agents explicitly by mentioning their name.
4258
43−```java
44−// ❌ VIOLATION — field injection
45−@Service
46−public class OrderService {
47− @Autowired
48− private OrderRepository orderRepository;
49−}
59+**Selection rule:** Read the description of each agent file to understand its trigger condition. The description is written as a precise activation trigger — if your task matches it, that agent will be selected.
5060
51−// ✅ CORRECT — constructor injection
52−@Service
53−public class OrderService {
54− private final OrderRepository orderRepository;
61+**To invoke explicitly:** Reference the agent slug in your prompt:
62+- "Using the `java-developer` agent, implement the OrderService"
63+- "Run a `security-auditor` review on this PR diff"
64+- "Activate `estimator` and give me a P80 estimate for this feature"
5565
56− public OrderService(OrderRepository orderRepository) {
57− this.orderRepository = orderRepository;
58− }
59−}
60−```
66+**Key agents by domain:**
6167
62−**Why:** Fields cannot be `final`. Cannot test without Spring context. Dependencies are invisible.
68+| Domain | Agents |
69+|--------|--------|
70+| Java / Spring Boot | `java-developer`, `java-tech-lead`, `java-tester`, `jacoco-coverage-tester`, `senior-developer` |
71+| Python | `python-developer` |
72+| Go | `go-developer`, `go-microservices-engineer` |
73+| Node / TypeScript | `node-developer`, `typescript-api-engineer` |
74+| Angular | `angular-developer`, `angular-tester`, `angular-coverage-checker` |
75+| Architecture | `architect`, `enterprise-architect`, `arb-reviewer` |
76+| Cloud / Infra | `aws-architect`, `cdk-terraform-helper`, `aws-deploy-helper`, `ci-engineer`, `containerisation-helper`, `kubernetes-engineer`, `devsecops-engineer`, `local-deploy-helper`, `finops-engineer`, `chaos-engineer`, `platform-engineer` |
77+| Data | `data-engineer`, `data-scientist` |
78+| Database | `dba-advisor` |
79+| Quality | `code-reviewer`, `security-auditor`, `performance-engineer`, `coverage-enforcer`, `test-quality-enforcer`, `tester` |
80+| AI / ML | `ai-engineer`, `ml-engineer`, `mlops-engineer`, `ai-governance-officer` |
81+| Agentic AI | `langraph-engineer`, `crewai-engineer`, `autogen-engineer`, `mcp-engineer`, `a2a-engineer` |
82+| Delivery | `estimator`, `project-tracker`, `business-analyst`, `technical-writer` |
83+| Operations | `incident-handler`, `rca-agent`, `ops-engineer`, `sre-engineer` |
84+| Modernisation | `modernization-expert`, `ibmi-modernization-expert` |
6385
6486 ---
6587
66−### Rule 2 — No Hardcoded Secrets
88+## Supported Technology Stack
6789
68−**No credentials, API keys, passwords, or AWS account IDs in source code.**
90+### Legacy Java
91+- Spring Framework 4.x / 5.x (Spring MVC, Spring Security, Spring Batch)
92+- Java 8/11 with `javax.*` APIs
93+- JUnit 4, Mockito 2/3, Maven
6994
70−```java
71−// ❌ VIOLATION
72−String apiKey = "sk-live-abc123...";
73−String dbPassword = "SuperSecret123";
95+### Modern Java
96+- Spring Boot 3.x with Java 17/21
97+- `jakarta.*` exclusively — no `javax.*`
98+- Spring Data JPA / Spring Data JDBC, Spring Security 6.x
99+- JUnit 5, AssertJ, Mockito 5, Testcontainers, Pact
74100
75−// ✅ CORRECT — environment variable or Secrets Manager
76−String apiKey = System.getenv("API_KEY");
77−// or via @Value, or SecretsManagerClient
78−```
101+### Angular
102+- Angular 15+ with standalone components
103+- Signals API, NgRx, RxJS 7+
104+- Jasmine / Karma / Istanbul for tests
105+- Strict TypeScript (`"strict": true`)
79106
80−**Why:** Source code is version-controlled and shared. Secrets in code become public.
107+### Mainframe
108+- IBM Enterprise COBOL 6.x, CICS, DB2 z/OS
109+- IBM i (AS400): RPG IV, RPGLE (ILE), CL, DDS, DB2 for i
110+- JCL, VSAM, QSAM
81111
82−---
112+### Python
113+- Python 3.11+ with type annotations (`mypy --strict`)
114+- FastAPI with Pydantic v2, SQLAlchemy async, Alembic
115+- pytest with `pytest-asyncio`, `pytest-cov`, `testcontainers-python`
116+- Ruff for formatting and linting
83117
84−### Rule 3 — SLF4J, Not System.out
118+### Go
119+- Go 1.22+, standard-library-first (`net/http`, `database/sql`, `log/slog`)
120+- Cloud-native services: gRPC + protobuf (`buf`), context propagation, graceful shutdown
121+- Table-driven tests, `go test -race`, Testcontainers-go for integration
122+- `gofmt` + `go vet` + `golangci-lint`; idiomatic errors (`%w`, `errors.Is/As`)
85123
86−**Use `log.info(...)` with parameterised messages. Never `System.out.println()`.**
124+### Node.js / TypeScript
125+- Node 20+, TypeScript 5.5+ (`"strict": true`, no `any`)
126+- NestJS / Fastify services; Zod validation at the boundary; typed, validated env config
127+- Vitest / Jest with coverage; Testcontainers for integration; `pino` structured logging
128+- ESLint `no-floating-promises`; parameterised queries (Prisma / Drizzle)
87129
88−```java
89−// ❌ VIOLATION
90−System.out.println("Processing order: " + orderId);
130+### Data Engineering
131+- Apache Kafka with Schema Registry (Avro / Protobuf)
132+- Apache Spark (PySpark DataFrame API)
133+- dbt (staging → intermediate → mart model layers)
134+- AWS Glue, Step Functions, Airflow
91135
92−// ✅ CORRECT
93−log.info("Processing order id={}", orderId);
94−```
136+### GraphQL
137+- Schema-first with `.graphql` SDL files
138+- Spring for GraphQL (Java) or Strawberry / Ariadne (Python)
139+- DataLoader for N+1 prevention
140+- Cursor-based (Relay) pagination
95141
96−**Why:** `System.out` bypasses the logging framework — no level control, no structured output, no MDC context.
142+### AWS
143+- CDK TypeScript (L2/L3 constructs preferred)
144+- Terraform HCL with remote state (S3 + DynamoDB lock)
145+- ECS Fargate, EKS, Lambda, API Gateway
146+- RDS Aurora, ElastiCache, DynamoDB
147+- SageMaker, Bedrock, Glue, Athena
97148
98149 ---
99150
100−### Rule 4 — No SELECT *
151+## Golden Rules (Non-Negotiable)
101152
102−**Always specify explicit column lists in SQL.**
153+These rules apply across ALL code in ALL domains. They are enforced by hooks and reviewed by the `code-reviewer` and `java-tech-lead` agents.
103154
104−```sql
105−-- ❌ VIOLATION
106−SELECT * FROM orders WHERE customer_id = :customerId;
155+1. **Constructor injection only** — no `@Autowired` on fields; all injected fields are `final`
156+2. **No hardcoded secrets** — all credentials, API keys, connection strings go to AWS Secrets Manager or environment variables; never committed to source
157+3. **SLF4J not System.out** — `log.info(...)` with parameterised messages; never `System.out.println()`
158+4. **SOLID principles** — Single Responsibility, Open/Closed, Liskov, Interface Segregation, Dependency Inversion
159+5. **Domain-Driven Design** — respect bounded context boundaries; no cross-context direct database joins
160+6. **No `SELECT *`** — always specify explicit column lists in SQL
161+7. **Parameterised queries only** — never build SQL via string concatenation; use `NamedParameterJdbcTemplate` or named JPQL parameters
162+8. **Conventional Commits** — all commit messages follow `type(scope): description` format
163+9. **No partial implementations** — every method body is complete; no `// TODO implement this` in committed code
164+10. **`jakarta.*` in Boot 3.x** — never `javax.*` in Spring Boot 3.x code
107165
108−-- ✅ CORRECT
109−SELECT id, customer_id, status, total_amount, created_at
110−FROM orders
111−WHERE customer_id = :customerId;
112−```
113−
114−**Why:** Schema additions silently increase payload size and break mapping. Query plans are harder to optimise.
115−
116166 ---
117167
118−### Rule 5 — Parameterised Queries Only
168+## Before Writing Code
119169
120−**No SQL string concatenation. Use named parameters.**
170+1. **Pick the correct agent** — check `.claude/agents/` descriptions and activate the right specialist
171+2. **Read the relevant standards file** — check `.claude/standards/` for the technology you are working in
172+3. **Read project context** — check `.claude/memory/project-context.md` for environment-specific details
173+4. **State what you are building** — before generating code, declare: the bounded context, the layer (domain/application/infrastructure/web), and the acceptance criteria
174+5. **Check for existing patterns** — use `Grep` to find similar existing implementations before inventing new abstractions
121175
122−```java
123−// ❌ VIOLATION — SQL injection risk
124−String sql = "SELECT * FROM orders WHERE id = '" + orderId + "'";
125−
126−// ✅ CORRECT
127−String sql = "SELECT id, status FROM orders WHERE id = :orderId";
128−namedJdbcTemplate.queryForObject(sql, Map.of("orderId", orderId), rowMapper);
129−```
130−
131−**Why:** String concatenation enables SQL injection. Non-negotiable security rule.
132−
133176 ---
134177
135−### Rule 6 — java.time Only (Java projects)
178+## Estimation Formula
136179
137−**No `java.util.Date`, `java.util.Calendar`, or `java.sql.Timestamp`.**
180+Human Days = **Σ Raw Hours ÷ 6.4**
138181
139−```java
140−// ❌ VIOLATION
141−Date now = new Date();
142−Calendar cal = Calendar.getInstance();
182+Where: `6.4 = 8 hours/day × 80% efficiency`
143183
144−// ✅ CORRECT
145−Instant now = Instant.now();
146−LocalDate today = LocalDate.now();
147−ZonedDateTime zonedNow = ZonedDateTime.now(ZoneId.of("Europe/London"));
148−```
184+The 80% efficiency factor accounts for: meetings, context-switching, PR review cycles, environment issues, code review iterations, and interruptions.
149185
150−**Why:** `Date` and `Calendar` are mutable, non-thread-safe, and poorly designed. `java.time` is ISO 8601-correct.
186+**Confidence ranges:**
151187
152−---
188+| Scenario | Multiplier | Use For |
189+|----------|------------|---------|
190+| P50 (Likely) | ×1.0 | Sprint planning baseline |
191+| P80 (Conservative) | ×1.3 | Sprint commitment |
192+| P90 (Pessimistic) | ×1.6 | Release planning buffer |
153193
154−### Rule 7 — jakarta.* in Spring Boot 3.x (Java projects)
194+**Typical raw hours by task type:**
155195
156−**No `javax.*` imports in Spring Boot 3.x code.**
196+| Task | Simple | Moderate | Complex |
197+|------|--------|----------|---------|
198+| REST API endpoint (Spring Boot) | 2–4h | 4–8h | 8–16h |
199+| Angular standalone component | 2–4h | 4–8h | 8–12h |
200+| Unit test class | 1–2h | 2–4h | 4–6h |
201+| Integration test (Testcontainers) | 2–4h | 4–6h | 6–10h |
202+| CDK stack (new resource) | 2–4h | 4–8h | 8–20h |
203+| Database migration script | 1–2h | 2–4h | 4–8h |
157204
158−```java
159−// ❌ VIOLATION in Spring Boot 3.x
160−import javax.persistence.Entity;
161−import javax.validation.constraints.NotNull;
205+Invoke the `/estimate` command or activate the `estimator` agent for a full breakdown.
162206
163−// ✅ CORRECT
164−import jakarta.persistence.Entity;
165−import jakarta.validation.constraints.NotNull;
166−```
167−
168−**Why:** Spring Boot 3.x requires Jakarta EE 10. `javax.*` causes `ClassNotFoundException` at runtime.
169−
170207 ---
171208
172−### Rule 8 — Conventional Commits
209+## Available Slash Commands
173210
174−**All commit messages follow `type(scope): description` format.**
211+| Command | Description |
212+|---------|-------------|
213+| `/bootstrap` | Interactive project discovery — generates `project-manifest.yaml` |
214+| `/setup-memory` | Interactive interview to populate all `.claude/memory/` files with project context |
215+| `/validate-manifest` | Validate `project-manifest.yaml` against the schema and governance rules |
216+| `/generate-repo` | Generate full repository scaffold from validated manifest |
217+| `/generate-agent --blueprint <type> --name <name>` | Generate a project-specific agent from a blueprint |
218+| `/adr "decision title"` | Scaffold a new Architecture Decision Record in `docs/decisions/` |
219+| `/rca "symptoms"` | Open an RCA workflow with 5-Whys template |
220+| `/estimate "feature description"` | Produce a bottom-up P50/P80/P90 effort estimate |
221+| `/review` | Run full PR review checklist across security, performance, and quality |
222+| `/threat-model "service description"` | STRIDE threat model for a service or bounded context |
223+| `/incident "severity: P1\|P2, service: name, symptom: description"` | Declare and coordinate an incident |
224+| `/security-scan [file or directory]` | OWASP Top 10 review plus secrets scan |
225+| `/deploy-check "env: dev\|staging\|prod, service: name"` | Pre-deployment readiness checklist |
226+| `/migrate-db "description"` | Generate Flyway/Liquibase migration with rollback and risk assessment |
227+| `/api-contract "resource description"` | Contract-first API design — OpenAPI stub + Pact consumer test |
228+| `/tech-debt add "description"` | Register a new tech debt item to `.claude/memory/tech-debt.md` |
229+| `/memory-update "what changed"` | Update relevant `.claude/memory/` files with new context |
230+| `/coverage-report [module path]` | JaCoCo/Istanbul coverage analysis with targeted test stubs |
231+| `/sync-docs` | Sync API documentation against OpenAPI specs |
175232
176−```
177−# ❌ VIOLATION
178−"fix stuff"
179−"wip"
180−"updated OrderService"
181−
182−# ✅ CORRECT
183−feat(orders): add order cancellation endpoint
184−fix(payments): handle null amount in authorisation
185−chore(deps): upgrade Spring Boot to 3.3.0
186−test(orders): add Testcontainers integration test for cancellation
187−```
188−
189−**Types:** `feat`, `fix`, `refactor`, `test`, `chore`, `docs`, `perf`, `ci`, `build`, `revert`
190−
191233 ---
192234
193−### Rule 9 — No Partial Implementations
235+## Memory and Context
194236
195−**Every committed method body is complete. No `// TODO implement this` in production code.**
237+Claude Code reads `.claude/memory/` files at the start of sessions to load persistent context. Use these files to avoid re-explaining the project on every session.
196238
197−```java
198−// ❌ VIOLATION
199−public BigDecimal calculatePremium(Policy policy) {
200− // TODO: implement premium calculation
201− return null;
202−}
239+| File | Purpose |
240+|------|---------|
241+| `project-context.md` | Service inventory, environments, auth patterns, key resource names |
242+| `domain-glossary.md` | Business terminology — what terms mean in this project's domain |
243+| `decisions.md` | Architecture Decision Log — what was decided and why |
244+| `constraints.md` | Hard technical and business constraints that must never be violated |
245+| `patterns.md` | Approved implementation patterns and anti-patterns to avoid |
246+| `tech-debt.md` | Tech debt register with priority and target sprint |
247+| `rca-tracker.md` | Incident/RCA status log |
248+| `session-log.md` | Auto-updated by the `on-stop.sh` hook with each session's changed files |
249+| `rejected-approaches.md` | Things that were tried and rejected — prevents re-trying failed ideas |
203250
204−// ✅ CORRECT — if not yet implementable, throw explicitly
205−public BigDecimal calculatePremium(Policy policy) {
206− throw new UnsupportedOperationException(
207− "Premium calculation not yet implemented — tracked in TD-042"
208− );
209−}
210−```
251+Use `/memory-update` to update these files when significant decisions or changes occur.
211252
212253 ---
213254
214−### Rule 10 — No Empty Catch Blocks
255+## What NOT To Do
215256
216−**Every catch block at minimum logs the exception.**
217−
218−```java
219−// ❌ VIOLATION
220−try {
221− publishEvent(event);
222−} catch (Exception e) {
223− // swallowed
224−}
225−
226−// ✅ CORRECT
227−try {
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
243−Thread.sleep(2000);
244−assertThat(orderRepository.findById(id)).isPresent();
245−
246−// ✅ CORRECT
247−await().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
260−Order order = orderRepository.findById(id).get(); // NoSuchElementException risk
261−
262−// ✅ CORRECT
263−Order 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−
277−Rules 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−
312−Activate the packs your `project-manifest.yaml` selects with `eeik activate --apply`; each materialises
313−its 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−
319−Standards live in `.claude/standards/` (and `capability-packs/<pack>/standards/`). They define the
320−CORRECT/WRONG patterns the golden rules summarise.
321−
322−## Approved patterns
323−
324−- `agentic-supervisor-pattern`
325−- `java-outbox-pattern`
326−
327−See `knowledge/patterns/` for the full write-ups and `knowledge/anti-patterns/` for what to avoid.
328−
329−---
330−
331−## Specialist agents
332−
333−Route 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)
394−capability-packs/ Intelligence packs — read these for standards
395−knowledge/ Patterns, anti-patterns, ADRs, lessons learned
396−generators/ Project generators
397−eeik/ Engine: validate, activate, generate-adapters, lock
398−templates/ Code templates
399−```
400−
401−## Before Writing Code
402−
403−1. Read `capability-packs/core/standards/golden-rules.md`
404−2. Check `knowledge/patterns/` for existing patterns
405−3. Check `knowledge/anti-patterns/` for what to avoid
406−4. Identify the bounded context (domain, application, infrastructure, web)
407−5. State acceptance criteria before generating
408−
409−## Commit Message Format
410−
411−All commits must follow Conventional Commits:
412−```
413−type(scope): description
414−
415−Types: 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
257+- Do NOT use `javax.*` in Spring Boot 3.x code — use `jakarta.*`
258+- Do NOT use `@Autowired` on fields — constructor injection only
259+- Do NOT write `SELECT *` in any SQL query
260+- Do NOT hardcode credentials, API keys, passwords, or AWS account IDs in source code
261+- Do NOT use `Thread.sleep()` in tests — use `Awaitility.await().until()`
262+- Do NOT write empty catch blocks — at minimum log the exception at WARN or ERROR level
263+- Do NOT use `new Date()` or `java.util.Calendar` — use `java.time` (LocalDate, LocalDateTime, Instant, ZonedDateTime)
264+- Do NOT add new Maven/npm dependencies without checking the BOM and flagging version conflicts
265+- Do NOT write partial implementations — if a method is not complete, say so explicitly
266+- Do NOT commit directly to `main` or `master` — always use a feature branch and PR
267+- Do NOT use `System.out.println()` anywhere in production code — use SLF4J
268+- Do NOT use `Optional.get()` without a preceding `isPresent()` check or `orElseThrow()`
433269
