Copilot instructions

1# GitHub Copilot — Repository Instructions
2 
3> This file is automatically loaded by GitHub Copilot for every interaction in this repository.
4> All rules defined here apply globally unless overridden by a scoped `*.instructions.md` file.
5 
6---
7 
8## Program Context
9 
10This repository supports an enterprise software modernization program spanning three technology domains:
11 
12- **Legacy Java** — Spring 4/5 web applications (XML + annotation config, JdbcTemplate, servlet-based)
13- **Modern Java** — Spring Boot 3.x microservices (Jakarta EE, Java 17/21, REST, JPA)
14- **Angular** — Single-page applications built with Angular 15+ (standalone components, Signals API)
15- **Mainframe** — IBM COBOL, Assembler, JCL, and CICS programs being analyzed and progressively modernized
16 
17Copilot is expected to understand all four domains and produce code that respects the conventions of each stack.
18 
19---
20 
21## Technology Stack Summary
22 
23| Domain | Language / Runtime | Key Frameworks & Libraries |
24|--------|-------------------|---------------------------|
25| Legacy Java | Java 8 / Java 11 | Spring 4.x/5.x, Spring MVC, JdbcTemplate, MapStruct, Maven |
26| Modern Java | Java 17 / Java 21 | Spring Boot 3.x, Spring Data JPA, Spring Security 6.x, springdoc-openapi, MapStruct |
27| Frontend | TypeScript (Angular 15+) | Angular, NgRx (optional), RxJS, Jasmine, Karma |
28| Mainframe | IBM COBOL 6.x, Assembler, JCL | CICS, DB2 (z/OS), VSAM, QSAM |
29| Testing | Java + TypeScript | JUnit 5, AssertJ, Mockito, Testcontainers, Awaitility, Pact |
30| Build | Java | Maven (multi-module), npm |
31 
32---
33 
34## Universal Coding Standards
35 
36### Naming
37- Classes: `PascalCase` — `CustomerService`, `OrderRepository`
38- Methods and variables: `camelCase` — `findActiveOrders()`, `customerId`
39- Constants: `UPPER_SNAKE_CASE` — `MAX_RETRY_COUNT`
40- Packages: lowercase, dot-separated — `com.example.order.service`
41- Test classes: suffix with `Test` (unit) or `IT` (integration) — `OrderServiceTest`, `OrderControllerIT`
42- Angular components: kebab-case file names — `customer-list.component.ts`
43 
44### Design Principles
45- Follow **SOLID** principles: every class has one reason to change
46- Apply **DDD** where applicable: distinguish domain model from DTOs from persistence entities
47- Use **hexagonal architecture** thinking: domain logic must not depend on infrastructure
48- Prefer **composition over inheritance**
49- Keep methods short (≤ 20 lines); extract private methods with descriptive names
50- No magic numbers — use named constants
51 
52### Dependency Injection
53- **Constructor injection only** — never `@Autowired` on fields
54- Mark injected fields `final` (Java)
55- Use `inject()` function in Angular (not constructor injection in modern components)
56 
57---
58 
59## Logging Standards
60 
61- Use **SLF4J** (`org.slf4j.Logger`) exclusively — never `System.out.println`, `System.err.println`, or `java.util.logging`
62- Declare logger as: `private static final Logger log = LoggerFactory.getLogger(MyClass.class);`
63- Log levels:
64  - `DEBUG` — method entry/exit, parameter values (dev/test only)
65  - `INFO` — significant business events (order created, user authenticated)
66  - `WARN` — recoverable errors, unexpected but handled conditions
67  - `ERROR` — exceptions that affect correctness; always include the exception object
68- Never log sensitive data: passwords, tokens, PII, card numbers
69- Use parameterized logging: `log.debug("Processing order {}", orderId)` — never string concatenation in log calls
70 
71---
72 
73## Security Non-Negotiables
74 
75- **No hardcoded secrets** — no passwords, API keys, tokens, or connection strings in code or properties files
76- **No raw SQL with string concatenation** — always use parameterized queries (`PreparedStatement`, JPA `@Query`, named parameters)
77- **Validate all user input** at system boundaries — use Bean Validation (`@Valid`, `@NotNull`, `@Size`)
78- **No `@SuppressWarnings("unchecked")`** without an explanatory comment stating why it is safe
79- All REST endpoints must be explicitly authorized — no anonymous access to business APIs
80- Secrets belong in environment variables or a vault — reference `${ENV_VAR}` in config, never inline values
81 
82---
83 
84## Dependency Policy
85 
86- **Do not add new Maven or npm dependencies** that are not already declared in `pom.xml` / `package.json`
87- If a dependency is genuinely needed, flag it with a comment: `// REQUIRES: add <groupId>:<artifactId>:<version> to pom.xml`
88- Do not upgrade dependency versions without being asked — version changes require controlled review
89 
90---
91 
92## What Copilot Must NOT Generate
93 
94| Forbidden Pattern | Reason |
95|------------------|--------|
96| `System.out.println(...)` | Use SLF4J logger |
97| `@SuppressWarnings` without comment | Masks real issues |
98| Raw generic types (`List`, `Map` without type params) | Type unsafe |
99| `catch (Exception e) { }` (empty catch) | Silently swallows errors |
100| `catch (Exception e) { e.printStackTrace(); }` | Use logger instead |
101| Hardcoded IP addresses, ports, or credentials | Use config/env vars |
102| `new Date()` or `Calendar` | Use `java.time` API |
103| `@SuppressWarnings("deprecation")` on new code | Fix the root cause |
104| `Thread.sleep()` in tests | Use `Awaitility` |
105| `SELECT *` in SQL | List columns explicitly |
106| String concatenation in SQL queries | Use parameterized queries |
107| Deprecated Spring APIs (`WebSecurityConfigurerAdapter`, `javax.*` in Boot 3.x) | Use current replacements |
108 
109---
110 
111## Commit Message Format
112 
113Follow **Conventional Commits** specification:
114 
115```
116<type>(<scope>): <short description>
117 
118[optional body]
119 
120[optional footer]
121```
122 
123Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`, `ci`
124 
125Examples:
126```
127feat(order): add customer credit limit validation
128fix(auth): resolve JWT expiry not checked on refresh
129test(invoice): add missing branch coverage for null line items
130refactor(customer): extract address validation to domain service
131```
132 
133---
134 
135## Pull Request Standards
136 
137- PR title follows Conventional Commits format
138- PR description must include: what changed, why, how to test
139- Every PR touching business logic must include or update tests
140- PRs must not decrease overall test coverage
141- All `[BLOCKER]` review comments must be resolved before merge
142 
143---
144 
145## Code Review Severity Labels
146 
147When reviewing code, use these labels consistently:
148 
149- `[BLOCKER]` — Must fix before merge: correctness bugs, security vulnerabilities, data loss risk
150- `[MAJOR]` — Should fix before merge: missing error handling, architectural violations, no logging on exceptions
151- `[MINOR]` — Fix in follow-up or current PR: naming issues, missing Javadoc, magic numbers
152- `[NIT]` — Optional polish: formatting, unnecessary imports, whitespace
153 
154---
155 
156## Available Agents
157 
158Select an agent from the Copilot Chat **@** dropdown to activate a specialist persona. Full catalogue: see `AGENTS.md` at the repository root.
159 
160### Java Development
161| Agent | Activate With | Use For |
162|-------|--------------|---------|
163| Java Developer | `@java-dev` | Ticket-scoped Spring Boot implementation |
164| Java Tech Lead | `@java-tech-lead` | PR gating, standards enforcement, tech debt |
165| Java Test Engineer | `@java-tester` | JUnit 5 / Testcontainers test suites |
166| JaCoCo Coverage Analyst | `@jacoco-coverage-tester` | Coverage gap analysis and targeted test generation |
167| Senior Java/Angular Developer | `@developer` | Full-stack Java + Angular implementation |
168 
169### Angular Development
170| Agent | Activate With | Use For |
171|-------|--------------|---------|
172| Angular Developer | `@angular-dev` | Standalone components, signals, lazy routes |
173| Angular Test Engineer | `@angular-tester` | Jasmine/TestBed specs |
174| Angular Coverage Analyst | `@angular-coverage-checker` | Istanbul/Karma coverage gap analysis |
175 
176### Architecture & Design
177| Agent | Activate With | Use For |
178|-------|--------------|---------|
179| Solution Architect | `@architect` | ADRs, bounded contexts, API contracts |
180| Enterprise Architect | `@enterprise-architect` | Capability maps, technology lifecycle, TOGAF |
181| AWS Solution Architect | `@aws-architect` | Well-Architected reviews, CDK stacks, cost estimates |
182 
183### Code Quality & Security
184| Agent | Activate With | Use For |
185|-------|--------------|---------|
186| Code Reviewer | `@reviewer` | [BLOCKER]/[MAJOR]/[MINOR]/[NIT] PR reviews |
187| Security Auditor | `@security-auditor` | OWASP Top 10 audit with remediation code |
188| Performance Specialist | `@performance-reviewer` | N+1 queries, resource leaks, rendering |
189| Coverage Guardian | `@coverage-enforcer` | Coverage gap analysis and targeted tests |
190| Test Quality Inspector | `@test-quality-enforcer` | Anti-pattern detection and test regeneration |
191 
192### Infrastructure & Deployment
193| Agent | Activate With | Use For |
194|-------|--------------|---------|
195| CDK / Terraform Helper | `@cdk-terraform-helper` | IaC stacks (CDK TypeScript or Terraform HCL) |
196| AWS Deploy Helper | `@aws-deploy-helper` | Deploy commands, pre-deploy checklist, rollback |
197| Local Deploy Helper | `@local-deploy-helper` | Docker Compose setup, smoke tests |
198| Containerisation Helper | `@containerisation-helper` | Dockerfiles, K8s manifests, Helm |
199| CI Engineer | `@ci-engineer` | GitHub Actions / Jenkins pipelines |
200 
201### Data, ML & AI (AWS)
202| Agent | Activate With | Use For |
203|-------|--------------|---------|
204| AWS Data Scientist | `@data-scientist-aws` | SageMaker notebooks, Glue ETL, Athena |
205| AWS ML Engineer | `@ml-engineer-aws` | SageMaker pipelines, model registry, MLOps |
206| AWS AI Engineer | `@ai-engineer-aws` | Bedrock LLM, RAG pipelines, guardrails |
207 
208### Delivery & Operations
209| Agent | Activate With | Use For |
210|-------|--------------|---------|
211| Estimator | `@estimator` | Bottom-up estimates (8h/day × 80% = 6.4h/day) |
212| Project Tracker | `@project-tracker` | Sprint burndown, story status, velocity |
213| Ops Engineer | `@ops-engineer` | CloudWatch dashboards, alarms, runbooks |
214| Incident Handler | `@incident-handler` | P1/P2 war room coordination |
215| RCA Agent | `@rca-agent` | 5-Whys root cause analysis |
216 
217### Modernisation
218| Agent | Activate With | Use For |
219|-------|--------------|---------|
220| Mainframe Modernization Specialist | `@modernization-expert` | COBOL → Java with semantic risk matrix |
221| Business Analyst | `@analyst` | OpenAPI specs, Gherkin acceptance criteria |
222| QA Automation Engineer | `@tester` | Full test pyramid for any stack |
223 
224---
225 
226## Agent Skills (Auto-Loaded)
227 
228The following skills in `.github/skills/` are loaded automatically by Copilot when relevant:
229 
230- **estimation** — Bottom-up effort estimation with P50/P80/P90 confidence ranges
231- **jacoco-analysis** — JaCoCo report parsing and gap analysis
232- **aws-cdk-deploy** — CDK deploy commands and rollback procedures
233- **incident-response** — ITIL P1/P2 templates and escalation matrix
234- **code-quality-scan** — SonarQube, SpotBugs, Checkstyle, OWASP report triage
235 
236---
237 
238## Hooks
239 
240Lifecycle hooks in `.github/hooks/` log session activity to `.copilot-*.log` files:
241 
242- **session-hooks.json** — logs session start/end and prompt submissions
243- **tool-use-hooks.json** — logs tool invocations and outcomes
244 
245---
246 
247## IntelliJ / JetBrains Usage
248 
249This file is loaded automatically by GitHub Copilot in both VS Code and IntelliJ IDEA. Agents (`.github/agents/`), instruction files (`.github/instructions/`), and prompt files (`.github/prompts/`) are accessible via Copilot Chat `#file:` reference in IntelliJ. See `intellij/` directory for IntelliJ-specific setup guidance.
250