From: Svjatoslav Agejenko <svjatoslav@svjatoslav.eu>
Date: Mon, 23 Feb 2026 16:48:37 +0000 (+0200)
Subject: Add `AGENTS.md` with build commands, guidelines, and coding standards for CLI Helper... 
X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=commitdiff_plain;h=1ddcb1d96d791fc81741f8ea7f6d0ed503a723c2;p=cli-helper.git

Add `AGENTS.md` with build commands, guidelines, and coding standards for CLI Helper project
---

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..bfd7786
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,120 @@
+This document provides build commands, coding standards, and guidelines for all agentic coding agents working on the CLI Helper project.
+
+# Project Overview
+
+CLI Helper is a zero-dependency Java library for building command-line interfaces. It provides:
+- Interactive user prompts (`CLIHelper`) for booleans, numbers, strings, files, and directories
+- A fuzzy-search terminal menu (`Menu`)
+- A CLI argument parser (`Parser` + `Option` subclasses)
+
+License: CC0 1.0 Universal (public domain). Author: Svjatoslav Agejenko.
+
+# Build Commands
+
+This is a Maven project. All commands should be run from the repository root.
+
+Compile the project:
+
+    mvn clean compile
+
+Run all tests:
+
+    mvn test
+
+Run a single test class:
+
+    mvn test -Dtest=ParserTest
+
+Run a single test method:
+
+    mvn test -Dtest=ParserTest#testParse
+
+Generate JavaDoc:
+
+    mvn javadoc:javadoc
+
+Package the JAR:
+
+    mvn clean package
+
+# Java Version
+
+**Java 8** is required. The `maven-compiler-plugin` enforces `source=8` and `target=8`.
+
+Do NOT use Java 9+ features:
+- No `var` (local variable type inference)
+- No records, sealed classes, or text blocks
+- No `List.of()`, `Map.of()`, or other Java 9+ collection factories
+- No modules (`module-info.java`)
+
+Java 8 features (streams, lambdas, method references, `Optional`) ARE available and used in the codebase.
+
+# Dependencies
+
+- **Runtime:** None (zero-dependency library -- keep it that way)
+- **Test:** JUnit 4.13.2 (`junit:junit`)
+
+Do NOT add new runtime dependencies without explicit approval.
+
+# Test Framework
+
+Use **JUnit 4** (not JUnit 5). Tests use:
+- `@Test`, `@Before`, `@After` annotations from `org.junit`
+- Static imports from `org.junit.Assert`: `assertTrue`, `assertFalse`, `assertEquals`
+- Test classes go in `src/test/java/` mirroring the main source package structure
+
+# Code Style
+
+## Formatting
+- **Indentation:** 4 spaces (no tabs)
+
+## JavaDoc
+- **Every method** (public, protected, package-private, and private) must have JavaDoc
+- **Every class** must have a class-level JavaDoc comment
+- Use `@param`, `@return`, and `@throws` tags as appropriate
+- Use `{@code ...}` for inline code references and `{@link ...}` for type references
+- Use `<pre>{@code ...}</pre>` for multi-line code examples
+
+## Fluent API Pattern
+Option subclasses use self-referencing generics for method chaining:
+```java
+public abstract class Option<T, I extends Option<?, I>> { ... }
+```
+Use `@SuppressWarnings("unchecked")` on methods that cast `this` to the self-type:
+```java
+@SuppressWarnings("unchecked")
+public I setMandatory() {
+    this.mandatory = true;
+    return (I) this;
+}
+```
+
+## Enums
+- Enums use UPPER_SNAKE_CASE values (e.g., `MUST_EXIST`, `ONE_OR_MORE`)
+
+# Source Layout
+
+```
+src/
+  main/java/eu/svjatoslav/commons/cli_helper/
+    CLIHelper.java                          # Interactive prompts (static utility)
+    Menu.java                               # Fuzzy-search terminal menu
+    parameter_parser/
+      Option.java                           # Abstract base for CLI options
+      Parser.java                           # CLI argument parser
+      ParameterCount.java                   # Enum: NONE, ONE, ONE_OR_MORE
+      parameter/
+        DirectoryOption.java                # Single directory option
+        DirectoryOptions.java               # Multi-directory option
+        ExistenceType.java                  # Enum: MUST_EXIST, MUST_NOT_EXIST, DOES_NOT_MATTER
+        FileOption.java                     # Single file option
+        FileOptions.java                    # Multi-file option
+        FloatOption.java                    # Float parameter option
+        IntegerOption.java                  # Integer parameter option
+        NullOption.java                     # Boolean flag (no parameters)
+        StringOption.java                   # Single string option
+        StringOptions.java                  # Multi-string option
+  test/java/eu/svjatoslav/commons/cli_helper/
+    parameter_parser/
+      ParserTest.java                       # Tests for Parser
+```