neqsim AGENTS.md

NeqSim — Agent Instructions

This file is read automatically by OpenAI Codex, Claude Code, and other AI coding agents. For VS Code Copilot, see .github/copilot-instructions.md.

Quick Orientation

Read CONTEXT.md for a 60-second overview of the codebase (repo map, build commands, code patterns).

Critical Constraint: Java 8

All code MUST compile with Java 8. Never use:

• var, List.of(), Map.of(), Set.of(), String.repeat(), str.isBlank(), str.strip(), text blocks ("""), records, pattern matching instanceof, Optional.isEmpty().
• Use explicit types, Arrays.asList(), StringUtils.repeat(), str.trim().isEmpty().

Critical Constraint: Logging

All Java logging/output MUST use Log4j2 logger. Never use System.out.println or System.err.println in production code, tests, examples, or generated snippets.

Use class logger fields and parameterized logging calls:

• private static final Logger logger = LogManager.getLogger(YourClass.class);
• logger.info("Message {}", value);
• logger.warn("Message {}", value);
• logger.error("Message {}", ex.getMessage(), ex);

Critical Constraint: Code Formatting (Spotless)

AI-generated Java is NOT auto-formatted. After creating or editing ANY .java file you MUST run Spotless before committing — do not rely on local pre-commit hooks being installed:

./mvnw spotless:apply    # reformats all Java to the project style
./mvnw spotless:check    # verifies formatting (this is what CI runs)

• Formatter profile: Eclipse .config/neqsim_formatter.xml (configured in pom.xml), applied to src/main/java and src/test/java.
• CI runs ./mvnw spotless:check and fails the build on any unformatted file.
• NEVER bypass the gate with git commit --no-verify.
• Run spotless:apply, then git add the reformatted files, then commit.

Continuous Improvement of Agents & Skills (always-on default)

Improving the agents and skills you use — and their cooperation — is part of every task, not an optional extra. Default behaviour, no need to ask: when a task reveals that a SKILL.md or *.agent.md is missing a pattern, naming convention, API signature, gotcha, or a needed agent↔skill hand-off, fix it in the same session. Improve cooperation too: add cross-references in both directions between related skills, keep hand-off shapes consistent along the chain, and update agent "Loaded skills" lists and router/composition guidance when a useful multi-skill/multi-agent pipeline is found. Keep site-specific detail in the enterprise repos and community content plant-agnostic; follow each repo's front-matter/validation conventions; note the improvements in the task summary; do not over-engineer.