neqsim: Instructions file for Codex

NeqSim — Agent Instructions

Read automatically by VS Code Copilot, OpenAI Codex, Claude Code and other agents. This file is kept short on purpose because it is resent on every model call. It is already in your context — do not read_file it. Detail lives in:

• docs/development/AGENT_REFERENCE.md — full workflow, results.json schema, Automation API, code patterns, key paths, JavaDoc and documentation rules. Search it for the heading you need; never read it whole.
• Skills in .github/skills/ (find them with uv run --project devtools --locked devtools/skill_search.py "<topic>").
• CONTEXT.md — 60-second repo map. docs/development/CODE_PATTERNS.md — starters.

Hard constraints (CI fails otherwise)

• Java 8 everywhere, tests included. Never var, List.of/Set.of/Map.of, String.repeat (use StringUtils.repeat), isBlank/strip/lines (use trim()), text blocks, records, pattern-matching instanceof, Optional.isEmpty().
• Logging: Log4j2 only (private static final Logger logger = LogManager.getLogger(X.class);, parameterized logger.info("{}", v)). Never System.out/err.println, also not in tests or examples.
• Spotless: after creating or editing ANY .java file run .\mvnw.cmd spotless:apply (Linux/Mac ./mvnw), then git add. CI runs spotless:check. Never --no-verify.
• JavaDoc on every class and method, private included: description, @param for each parameter, @return, @throws for every declared exception, class @author/@version. HTML5: <table> needs <caption>, no summary=; @see only with Java references; no </p> after </ul>/</ol>; no -> or raw > in JavaDoc (>). Check with mvnw javadoc:javadoc. Spotless/Checkstyle/JavaDoc failures: neqsim-code-hygiene skill.
• Serializable classes: non-serializable fields (Function, Consumer, Thread, JDBC, interpolators) must be private transient (SpotBugs SE_BAD_FIELD).
• Verify APIs before use: find the class, read constructor/method signatures, never assume convenience overloads, enum locations or getter arguments.
• Discover across all functionality: in a source checkout use uv run --project devtools --locked devtools/capability_search.py "<task or API>" --json. It returns current source types, workflow agents/skills, guides and test references; load only the relevant skill sections. In plugin/MCP-only sessions use runtime discovery. Read the discovery guide before declaring functionality absent. Routing coverage and test references do not establish qualification.
• Agent/MCP coverage: src/main/resources/neqsim/mcp/engineering-coverage.json is a generated snapshot, not a source of truth. After Java formatting or agent/skill mapping changes, regenerate it with uv run --project devtools --locked devtools/build_engineering_coverage.py and stage the output. For merge conflicts, resolve source and registry conflicts first, then regenerate and git add this file. Never hand-merge its JSON or combine branch copies; neither produces a valid inventory of the merged sources. CI rebuilds and validates the snapshot, then commits changed output back to same-repository PR branches and master when permissions and branch protection allow. Fork PRs remain validation-only. Register new engineering operations with routes and evidence; source presence is not validation.
• AI workflow names: GitHub Actions workflows for agent, skill, MCP, task, or research tooling MUST use ai-<purpose>.yml in lowercase kebab-case, directly in .github/workflows/. Categorize by primary responsibility: publishing MCP artifacts still uses publish-. Follow .github/WORKFLOWS.md; update filename references when renaming and preserve required-check names unless their consumers have been reviewed.
• Documentation code must be test-verified: every Java/Python snippet in docs gets a JUnit test (e.g. DocExamplesCompilationTest) that is run and passes before the doc is done.
• Notebooks must be executed end to end (NeqSim Runner by default); unexecuted = incomplete.
• Linux-only engines (FluidMagic, OpenFOAM, OPM Flow) need Docker Desktop/WSL2 on Windows; report a missing runtime as a blocker, never skip silently.
• FluidMagic is Equinor-internal, not on PyPI (enterprise agents/skills only): running it needs the private repo equinor/FluidMagic (own GitHub SSO; gh repo clone equinor/FluidMagic, pip install -e FluidMagic/fluidmagic). Never pip install fluidmagic; if import fluidmagic fails, tell the user how to get it and fall back to the offline hand-off.