AGENTS.md

AGENTS.md — OpenFastTrace Maven Plugin

This file provides guidance for AI agents and LLMs working on the OpenFastTrace Maven Plugin project.

Key Commands

All commands should be run from the repository root.

Task	Command
Verify (All tests)	mvn verify
Build (full)	mvn clean package -DskipTests
Run Unit Tests	mvn test
Run Single Test	mvn test -Dtest=ClassName
Run Integration Test	mvn failsafe:integration-test
Check Dependencies	mvn versions:display-dependency-updates

Agent Role & Persona

You are an expert Java developer specializing in requirement tracing and Maven plugin development. Your goal is to help maintain and evolve the OpenFastTrace Maven Plugin, following "Clean Code" principles and ensuring high reliability.

Boundaries

• Always:
  • Follow the branching strategy: <type>/<number>_<short-description-lower-snake-case> (e.g., feature/533_update_agents_md).
• Ask First:
  • Before adding new external dependencies to pom.xml.
• Never:
  • Never remove failing tests unless specifically instructed to do so. Fix the code instead.
  • Never modify files in .idea/ or other IDE-specific metadata folders.
  • Never bypass mvn verify checks (e.g., by skipping static analysis or tests) during final validation.

Code Examples

Requirement Tagging in Java

Show coverage of a requirement (e.g., req~trace-goal~1) in the implementation:

/**
 * Mojo for tracing requirements.
 * // [impl->req~trace-goal~1]
 */
@Mojo(name = "trace", defaultPhase = LifecyclePhase.VERIFY, threadSafe = true)
public class TraceMojo extends AbstractMojo {
    // implementation details...
}

Project Stack & Structure

• Tech Stack: Java 17+, Maven 3.8+, JUnit 5, Mockito, Hamcrest.
• Architecture:
  • Single-module Maven project providing a Maven Plugin.
  • src/main/java: Plugin implementation (Mojos).
  • src/test/java: Unit tests.
  • src/test/resources: Integration test projects and logging configuration.

Code Style & Conventions

• Clean Code: Meaningful names, small functions, single responsibility.
• Logging: Use java.util.logging. Test config: src/test/resources/logging.properties.

Development Workflow

1. Create Branch (see Boundaries)
2. Implement: Tag all new code with coverage markers.
3. Verify: mvn -T 1C verify.
4. Review: All changes require human review per CONTRIBUTING.md.

Agent Skills & Critical Files

• Key Resources:
  • README.md: General overview and usage documentation.
  • CONTRIBUTING.md: Human-AI collaboration guidelines.
  • CHANGELOG.md: Project history.