AGENTS.md

AGENTS.md — OpenFastTrace

This file provides guidance for AI agents and LLMs working on the OpenFastTrace (OFT) project.

Key Commands

All commands should be run from the repository root.

Task	Command
Verify (All tests)	mvn -T 1C verify
Self-Trace	./oft-self-trace.sh
Build (full)	mvn -T 1C clean package -DskipTests
Run Unit Tests	mvn -T 1C test
Run Single Test	mvn test -Dtest=ClassName
Run Integration Test	mvn -Dit.test=CliStarterIT failsafe:integration-test -projects product
Check Dependencies	mvn versions:display-dependency-updates

Agent Role & Persona

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

Boundaries

• Always:
  • Review all changes with ./oft-self-trace.sh to ensure tracing completeness.
  • Follow the branching strategy: <type>/<number>_<short-description-lower-snake-case> (e.g., feature/533_update_agents_md).
  • Place coverage markers at the narrowest possible scope (method or class).
  • Follow the quality requirements in doc/spec/design/quality_requirements.md.
• Ask First:
  • Before adding new external dependencies to pom.xml.
  • Before changing existing architectural patterns in openfasttrace-core.
• 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~help-command~1) in the implementation:

/**
 * Handles the help command.
 * // [impl->req~help-command~1]
 */
public class HelpCommand extends AbstractCommand {
    // implementation details...
}

Requirement Definition in Markdown

Example of a specification item in doc/spec/system_requirements.md:

### Help Command
`req~help-command~1`

The system shall provide a help command that displays usage information.

Covers:

- feat~cli~1

Needs: impl, utest

Project Stack & Structure

• Tech Stack: Java 17+, Maven 3.8+, JUnit 5, Mockito, Hamcrest.
• Architecture:
  • openfasttrace-api: Core interfaces and contracts.
  • openfasttrace-core: Main tracing logic and algorithms.
  • openfasttrace-importer-*: Specialized importers (Markdown, Source Tag, XML, etc.).
  • openfasttrace-exporter-*: Data exporters.
  • openfasttrace-reporter-*: Report generators (HTML, PlainText, ASpec).
  • product: Uber-JAR assembly and CLI entry point.

Code Style & Conventions

• Clean Code: Meaningful names, small functiKons, single responsibility.
• Type References: Use plain class names with imports instead of fully qualified names such as java.util.List.
• Formatting: Use the project's Eclipse formatter (doc/itsallcode_formatter.xml).
• Logging: Use java.util.logging. Test config: core/src/test/resources/logging.properties.

Unit Tests

• Prefix test method names with test.
• Test each conditional branch in a separate test method.
• When asserting an exception, verify both its type and message.
• Keep only one invocation that may throw a runtime exception in the assertThrows lambda; prepare all inputs beforehand.

Development Workflow

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

Agent Skills & Critical Files

• Detailed Skills: See .agents/skills for domain knowledge (ID syntax, keywords).
• Key Resources:
  • README.md: General overview.
  • doc/developer_guide.md: Detailed build and internal info.
  • doc/user_guide.md: Comprehensive tool usage.
  • CONTRIBUTING.md: Human-AI collaboration guidelines.
  • doc/spec/system_requirements.md: System requirements specification.
  • doc/spec/design.md: High-level design documentation.
  • core/src/main/resources/usage.txt: CLI documentation.