jikkou: Instructions file for Codex

AGENTS.md - Development Guidelines for AI Coding Agents

This document provides comprehensive guidelines for AI coding agents working on the Jikkou project - an open-source Resource as Code framework for Apache Kafka.

Project Overview

Jikkou is a Java based multi-module Maven project that provides Infrastructure as Code management for Apache Kafka resources. It's designed with a kubectl-inspired approach for managing Topics, ACLs, Quotas, Schemas, and Connectors.

• Language: Java 25
• Build System: Maven (multi-module)
• Architecture: Micronaut-based CLI and API server
• Distribution: Native binaries (GraalVM), JAR, Docker

Project Structure

jikkou/
├── cli/                              # Command-line interface (main entry)
├── core/                             # Core APIs and engine
├── server/                           # REST API server components
├── providers/                        # Resource provider implementations
├── template-jinja/                   # Jinja templating support
├── extension-rest-client/            # REST client extensions
├── resource-generator/               # Resource generation utilities
└── processor/                        # Processing components

Main Entry Points:

• CLI: io.jikkou.client.Jikkou
• Server: io.jikkou.rest.JikkouApiServer

Build, Test, and Lint Commands

Build Commands

# Full build with tests
./mvnw clean verify

# Build without tests
./mvnw clean verify -DskipTests

# Build specific module
./mvnw clean verify -pl cli

# Native build (requires GraalVM)
./mvnw clean verify -Pnative

# Docker image build
make

Test Commands

# Run all tests (unit + integration)
./mvnw test

# Run unit tests only
./mvnw surefire:test

# Run integration tests only
./mvnw failsafe:integration-test

# Run single test class
./mvnw test -Dtest=ClassNameTest

# Run single test method
./mvnw test -Dtest=ClassNameTest#methodName

# Run tests for specific module
./mvnw test -pl core

# Run tests with specific profile
./mvnw test -P native