accuweather-mcp: Instructions file for Codex

Agents and Project Guidance

This file defines how agents should work in this repository and where to find reusable skills.

• Rules file: Describe project-specific expectations, conventions, and constraints for agents. Examples:

  • Coding style, frameworks, and libraries to prefer.
  • Files or areas of the codebase that need extra care.
  • Any constraints (e.g. no external network calls, no schema changes without approval).

• Skills directory: Custom skills live in the .agents/skills/ directory.

Java

• Use final: Prefer prefixing parameters and local variables with final where they are not reassigned, to make immutability explicit and avoid accidental reassignment.
• String formatting: Prefer String.format(...) over string concatenation.

Spring Boot

• Dependency versions: When using Spring Boot with the io.spring.dependency-management plugin, do not specify versions on individual dependencies in the dependencies {} block. Rely on BOMs (for example, spring-boot-dependencies and technology-specific BOMs like spring-ai-bom) to control versions centrally, as recommended in the Spring Boot dependency management documentation.

Build tooling

• Gradle, not Maven: This project uses Gradle as its build tool. Prefer Gradle commands (for example, ./gradlew test) instead of Maven commands.

Null handling

• Package defaults: Each Java package in this project should declare a package-info.java file that applies @NullMarked:

  @NullMarked
  package com.jonjam.accuweathermcp;
  
  import org.jspecify.annotations.NullMarked;
  

• Nullable values: Anywhere a value can legitimately be null (fields, parameters, return types, type arguments), it must be explicitly annotated with @Nullable from JSpecify:

  import org.jspecify.annotations.Nullable;
  
  public String greet(@Nullable String name) { ... }
  

• Non-null by default: Under @NullMarked, all unannotated types are treated as non-null, so @Nullable is the only marker needed to indicate possible absence.
• Prefer Optional for absence in APIs: For public APIs and reusable utilities, prefer returning Optional<T> over returning nullable values. Reserve @Nullable primarily for interoperability or where Optional would be impractical, while keeping null usage explicit and rare.