CLAUDE.md

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