Trabuco

 ████████╗██████╗  █████╗ ██████╗ ██╗   ██╗ ██████╗ ██████╗
 ╚══██╔══╝██╔══██╗██╔══██╗██╔══██╗██║   ██║██╔════╝██╔═══██╗
    ██║   ██████╔╝███████║██████╔╝██║   ██║██║     ██║   ██║
    ██║   ██╔══██╗██╔══██║██╔══██╗██║   ██║██║     ██║   ██║
    ██║   ██║  ██║██║  ██║██████╔╝╚██████╔╝╚██████╗╚██████╔╝
    ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝╚═════╝  ╚═════╝  ╚═════╝ ╚═════╝
  

Generate production-ready Java projects — with the AI context your coding agents need built in.

Starting a new Java project is slow — even with a coding agent helping. You set up Maven modules, wire databases and tests, copy boilerplate from that one project that "mostly works," and then spend the first hour explaining every architectural convention to Claude Code, Cursor, Copilot, or Codex from scratch. Hours pass before you write a single line of business logic. Trabuco exists because your time — and your agent's context window — is better spent building features, not fighting configuration or re-teaching conventions.

Trabuco is a command-line tool that generates both halves of a modern Java codebase: a complete, production-ready multi-module Maven project and the AI context that teaches coding agents how to work in it. Run trabuco init, answer a few prompts (or pass flags for automation), and you get a fully wired Spring Boot codebase alongside task-specific prompts, quality specifications, per-agent rule files, and workflow hooks already configured for Claude Code, Codex, Cursor, and GitHub Copilot. No templates to download, no manual setup, and no session spent bootstrapping your agent's understanding of the project.

The generated code is production-grade by default. Spring Boot 3.4 with Spring Data JDBC (no JPA surprises), Flyway migrations, Testcontainers for real integration tests, Resilience4j circuit breakers, Google Java Format enforced by Spotless, ArchUnit rules that fail the build on layer violations, correlation-ID tracing, Prometheus metrics, OpenAPI + Swagger UI, and a global exception handler with sanitized responses. PostgreSQL, MySQL, MongoDB, or Redis — all configured with Docker Compose. JobRunr for background jobs; Kafka, RabbitMQ, AWS SQS, or GCP Pub/Sub for event-driven processing. The modular layout — Model, SQLDatastore / NoSQLDatastore, Shared, API, Worker, EventConsumer — has clean compile-time boundaries so API physically cannot import Worker code. Every opinion is deliberate: keyset pagination, no foreign-key constraints, Immutables at module boundaries, constructor injection only, bulk-bounded writes.

Alongside the code, Trabuco lays down an AI collaboration layer that the major coding agents load natively. The .ai/prompts/ directory ships task-specific guides (add-entity, add-endpoint, add-service, add-event, add-job, add-tool) plus JAVA_CODE_QUALITY.md — an authoritative specification covering architecture boundaries, exception handling, datastore performance (bulk I/O, keyset drain loops, denormalization), and testing standards. Per-agent rule files — CLAUDE.md for Claude Code, AGENTS.md for Codex, .cursor/rules/java.mdc for Cursor, .github/instructions/java.instructions.md for Copilot — wire those conventions into each tool's native discovery. Claude also gets .claude/skills/ for commit, PR, and review workflows; Codex and Cursor get hooks; Copilot gets setup steps. Every architectural convention lives in two places: enforced by the generated code and explained to the agents that will extend it.

Trabuco goes further. The AI Agent module ships production scaffolding for building AI agents themselves on Spring AI: tool calling, LLM input/output guardrails, multi-agent orchestration, knowledge-base integration, MCP server endpoint, the A2A (Agent-to-Agent) protocol, streaming responses, webhook callbacks, scope-based authorization, rate limiting, and correlation-ID tracing — wired, testable, and ready from the first commit. Trabuco itself is also an MCP server: run trabuco mcp and your coding agents invoke scaffolding operations natively (init_project, add_module, design_system, scan_project, suggest_architecture, migrate_project). And for legacy codebases, trabuco migrate uses Claude to analyze your entities, services, controllers, and repositories, then reorganizes them into Trabuco's architecture — converting JPA to Spring Data JDBC, replacing Quartz with JobRunr, generating all the configuration, and checkpointing each stage so it can resume after interruption.

Table of Contents

• Features
• Installation
• Quick Start
• Migrating Legacy Projects
  • How It Works
  • Authentication
  • Migration Options
  • Checkpoints and Recovery
  • What Gets Migrated
• Managing Existing Projects
  • Project Health Check
  • Adding Modules
• CLI MCP Server
  • Configuration
  • Available Tools
• Generated Project Structure
• Modules
  • Model
  • SQLDatastore
  • NoSQLDatastore
  • Shared
  • API
  • Jobs
  • Worker
  • Events
  • EventConsumer
  • AI Agent
• Code Quality & Architecture
  • Auto-Formatting
  • Architecture Tests
  • AI Task Prompts
  • Code Review Workflow
• CI/CD
  • GitHub Actions
• Observability
  • Metrics
  • API Documentation
  • Request Tracing
  • Health Checks
  • Test Coverage
• Configuration Options
  • Available Modules
  • Java Version Detection
  • AI Coding Agents
  • CI/CD Provider
• Tech Stack
• Local Development
• Requirements
• Contributing
• License

Features

• AI-powered migration (experimental) — Transform existing Spring Boot projects into Trabuco's architecture with trabuco migrate
• Multi-module Maven structure — Clean separation between Model, Data, Services, API, Worker, and EventConsumer
• Incremental module addition — Start minimal and add modules as you need them with trabuco add
• Project health checks — Validate project structure and consistency with trabuco doctor
• Immutables everywhere — Type-safe, immutable DTOs and entities with builder pattern
• Spring Boot 3.4 — Latest LTS with Spring Data JDBC (not JPA — no magic, no surprises)
• SQL databases — PostgreSQL/MySQL support with Flyway migrations out of the box
• NoSQL databases — MongoDB/Redis support with Spring Data repositories
• Background jobs — JobRunr for fire-and-forget, delayed, recurring, and batch jobs
• Event-driven messaging — Kafka, RabbitMQ, AWS SQS, or GCP Pub/Sub with type-safe event contracts
• Testcontainers 2.x — Real database tests that actually work with Docker Desktop
• Circuit breakers — Resilience4j configured and ready to use
• Prometheus metrics — Micrometer with /actuator/prometheus endpoint
• API documentation — OpenAPI 3.0 with Swagger UI at /swagger-ui.html
• Correlation IDs — Request tracing with X-Correlation-ID header
• Health probes — Kubernetes-ready readiness and liveness endpoints
• Test coverage — JaCoCo reports for code coverage
• Docker Compose — Local development stack included
• IntelliJ run configs — Just open and run
• GitHub Actions CI — Opt-in CI workflow that adapts to your modules with --ci github
• Code quality enforcement — Google Java Format (Spotless), Maven Enforcer, and auto-formatting hooks
• Architecture tests — ArchUnit rules enforce constructor injection, layer boundaries, and no cyclic dependencies
• AI Agent module — Production-ready AI agent with Spring AI: tool calling, LLM guardrails, multi-agent orchestration, MCP server, A2A protocol, and knowledge base
• AI-friendly — Generates context files, coding rules, quality specs, and task prompts for Claude, Cursor, GitHub Copilot, and Codex
• CLI MCP server — trabuco mcp exposes all CLI functionality as structured tools for AI coding agents

Installation

npx (recommended for MCP use)

No installation needed — just reference trabuco-mcp in your AI agent config and npx handles everything:

claude mcp add trabuco -- npx -y trabuco-mcp

See CLI MCP Server > Configuration for all agent configs.

npm

npm install -g trabuco-mcp

Installs the MCP server wrapper globally. It downloads the correct Trabuco CLI binary for your platform on install.

From GitHub

curl -sSL https://raw.githubusercontent.com/arianlopezc/Trabuco/main/scripts/install.sh | bash

Using Go

go install github.com/arianlopezc/Trabuco/cmd/trabuco@latest

Make sure $GOPATH/bin (usually ~/go/bin) is in your PATH.

Quick Start

Interactive mode — just run trabuco init and answer a few questions.

Non-interactive mode — pass all options as flags:

# Basic API with PostgreSQL
trabuco init --name=myapp --group-id=com.company.myapp \
  --modules=Model,SQLDatastore,Shared,API --database=postgresql

# Add background jobs with Worker
trabuco init --name=myapp --group-id=com.company.myapp \
  --modules=Model,SQLDatastore,Shared,API,Worker --database=postgresql

# Add event-driven messaging with Kafka
trabuco init --name=myapp --group-id=com.company.myapp \
  --modules=Model,API,EventConsumer --message-broker=kafka

# Full setup with CI, AI agents, and all modules
trabuco init --name=myapp --group-id=com.company.myapp \
  --modules=Model,SQLDatastore,Shared,API,Worker,EventConsumer \
  --database=postgresql --message-broker=kafka --ai-agents=claude,cursor --ci github

Run your new project

cd myapp
mvn clean install
cd API && mvn spring-boot:run

Your API is now running at http://localhost:8080. Try the health endpoint:

curl http://localhost:8080/health

Migrating Legacy Projects

⚠️ Experimental Feature

The trabuco migrate command is under active development. While functional, results should be reviewed and may require manual adjustments. We recommend running with --dry-run first and testing thoroughly before relying on migrated code in production.

Set TRABUCO_ACKNOWLEDGE_EXPERIMENTAL=true to suppress the experimental warning in CI/CD pipelines.

The trabuco migrate command uses AI to analyze existing Spring Boot projects and transform them into Trabuco's multi-module architecture. It's designed for projects that have grown organically and need restructuring — or for teams adopting Trabuco's patterns for existing codebases.

# Basic migration
trabuco migrate /path/to/legacy-app

# Specify output directory
trabuco migrate /path/to/legacy-app -o ./migrated-app

# Dry run — analyze without generating files
trabuco migrate --dry-run /path/to/legacy-app

How It Works

Migration happens in 10 stages, each with checkpoints for recovery:

Before making changes, the AI shows you what it found and estimates the cost. In interactive mode (default), you confirm each major decision.

Authentication

Trabuco uses Claude (Anthropic's AI) for intelligent code transformation. You need an API key:

Option 1: Anthropic (recommended)

export ANTHROPIC_API_KEY=sk-ant-...
trabuco migrate /path/to/legacy-app

Option 2: OpenRouter (alternative)

OpenRouter provides access to Claude models without an Anthropic account:

export OPENROUTER_API_KEY=sk-or-...
trabuco migrate --provider=openrouter /path/to/legacy-app

You can also pass the key directly:

trabuco migrate --api-key=sk-ant-... /path/to/legacy-app

Migration Options

Checkpoints and Recovery

Migration creates checkpoints in .trabuco-migrate/ within your source project. If something goes wrong:

# Resume from where you left off
trabuco migrate --resume /path/to/legacy-app

# Rollback to a specific stage
trabuco migrate --rollback-to=entities /path/to/legacy-app

# Rollback completely (removes output directory)
trabuco migrate --rollback /path/to/legacy-app

Checkpoints track:

• Completed stages and their outputs
• AI decisions made (for transparency)
• Token usage and estimated cost
• Errors encountered

What Gets Migrated

Automatically converted:

Dependency replacements:

Requires manual attention:

• Complex JPA relationships (inheritance, embedded collections)
• Native SQL queries with JPA-specific syntax
• Custom Hibernate types
• AspectJ weaving

The AI flags these during migration and explains what needs manual review.

Cost Transparency

Before migration begins, Trabuco estimates the cost based on:

• Number of files to process
• Estimated input/output tokens
• Current model pricing

Example output:

Estimated Migration Cost:
  Files to process: 47
  Est. tokens:      ~70,500
  Est. cost:        $0.35 - $0.65

Actual cost is tracked during migration and saved in the checkpoint.

Managing Existing Projects

Trabuco isn't just for creating new projects — it can also validate and extend existing ones. The doctor command checks project health, and the add command lets you add modules incrementally as your needs evolve.

Project Health Check

The trabuco doctor command validates that your project is healthy and consistent:

cd myapp
trabuco doctor

Example output:

Trabuco Project Health Check
━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Project: myapp
Location: /Users/dev/myapp
Trabuco Version: 1.2.0

Running checks...

  ✓ Project structure valid
  ✓ Trabuco project detected
  ✓ Metadata file valid
  ✓ Parent POM valid
  ✓ Module POMs exist (4 modules)
  ✓ Java version consistent (21)
  ✓ Docker Compose in sync

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Status: HEALTHY
All 7 checks passed

Doctor options:

Auto-fix capabilities:

trabuco doctor --fix

This can automatically fix common issues like missing .trabuco.json metadata, out-of-sync module lists, and inconsistent Java versions across POMs.

Adding Modules

Start with a minimal project and add modules as you need them:

# Create a simple API project
trabuco init \
  --name=myapp \
  --group-id=com.company.myapp \
  --modules=Model,Shared,API

# Later, add a database
cd myapp
trabuco add SQLDatastore --database=postgresql

# Even later, add background jobs
trabuco add Worker

# Or add event-driven messaging
trabuco add EventConsumer --message-broker=kafka

The add command automatically:

• Runs doctor to validate the project before making changes
• Creates the module directory structure
• Updates the parent POM with the new module
• Adds required properties and dependencies
• Updates docker-compose.yml with necessary services
• Regenerates CI workflow with new services (if CI is configured)
• Regenerates AGENTS.md with updated module list
• Updates .trabuco.json metadata
• Auto-includes dependent modules (e.g., Worker includes Jobs)
• Prompts to add CI if not already configured

Add command options:

Interactive mode:

trabuco add

If you don't specify a module, Trabuco prompts you to select one and asks for any required options.

Dry-run example:

trabuco add SQLDatastore --database=postgresql --dry-run

This shows exactly what files will be created and modified without changing anything.

Backup and recovery:

By default, add creates a backup in .trabuco-backup/ before modifying files. If something goes wrong, you can restore from this backup. The backup is overwritten on each successful add operation.

Module compatibility:

CLI MCP Server

Trabuco includes a built-in Model Context Protocol server that exposes all CLI functionality as structured tools. Instead of running shell commands and parsing terminal output, AI coding agents get proper JSON schemas for inputs and structured JSON results — no string parsing, no color codes, no guessing.

trabuco mcp

This starts the MCP server over stdio. You don't run this command directly — your AI agent launches it automatically based on its configuration.

Configuration

Add Trabuco as an MCP server in your AI agent's configuration file. The recommended approach uses npx so there's nothing to install first:

Claude Code

claude mcp add trabuco -- npx -y trabuco-mcp

Or add to .mcp.json in your project root (shared with your team):

{
  "mcpServers": {
    "trabuco": {
      "command": "npx",
      "args": ["-y", "trabuco-mcp"]
    }
  }
}

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "trabuco": {
      "command": "npx",
      "args": ["-y", "trabuco-mcp"]
    }
  }
}

VS Code / GitHub Copilot — add to .vscode/mcp.json:

{
  "servers": {
    "trabuco": {
      "command": "npx",
      "args": ["-y", "trabuco-mcp"]
    }
  }
}

Codex — add to .codex/config.toml:

[mcp_servers.trabuco]
command = "npx"
args = ["-y", "trabuco-mcp"]

claude mcp add --transport stdio trabuco -- trabuco mcp

Available Tools

Once configured, your AI agent can use these tools:

Prompts

Prompts provide expert knowledge for complex decisions:

Resources

Resources provide stable reference data:

What this looks like in practice: Describe your business to your AI agent — "I need an intelligent assistant that can answer customer questions, check order status, and schedule deliveries" — and it calls suggest_architecture to match the ai-agent pattern, then init_project with Model,Shared,AIAgent to generate a complete AI agent with tools, guardrails, and MCP server.

Generated Project Structure

myapp/
├── pom.xml                          # Parent POM (module aggregator)
├── Model/                           # DTOs, Entities, Enums
│   └── src/main/java/.../model/
│       ├── dto/                     # Request/Response DTOs
│       ├── entities/                # Domain entities + DB records/documents
│       └── ImmutableStyle.java      # Immutables configuration
├── SQLDatastore/                    # SQL database layer (if selected)
│   └── src/
│       ├── main/
│       │   ├── java/.../sqldatastore/
│       │   │   ├── config/          # Database configuration
│       │   │   └── repository/      # Spring Data JDBC repositories
│       │   └── resources/
│       │       └── db/migration/    # Flyway SQL migrations
│       └── test/                    # Testcontainers integration tests
├── NoSQLDatastore/                  # NoSQL database layer (if selected)
│   └── src/
│       ├── main/java/.../nosqldatastore/
│       │   ├── config/              # NoSQL configuration
│       │   └── repository/          # Spring Data repositories
│       └── test/                    # Testcontainers integration tests
├── Shared/                          # Business logic & services
│   └── src/main/java/.../shared/
│       ├── config/                  # Circuit breaker config
│       └── service/                 # Service classes
├── API/                             # REST API (Spring Boot app)
│   └── src/main/
│       ├── java/.../api/
│       │   ├── controller/          # REST controllers
│       │   └── config/              # Web configuration
│       └── resources/
│           └── application.yml      # App configuration
├── Jobs/                            # Job services (auto-included with Worker)
│   └── src/main/java/.../jobs/
│       └── PlaceholderJobService.java  # Service for enqueueing jobs
├── Worker/                          # Background jobs (Spring Boot app)
│   └── src/main/
│       ├── java/.../worker/
│       │   ├── config/              # JobRunr configuration
│       │   └── handler/             # JobRequestHandler implementations
│       └── resources/
│           └── application.yml      # Worker configuration
├── Events/                          # Event publisher (auto-included with EventConsumer)
│   └── src/main/java/.../events/
│       └── EventPublisher.java      # Service for publishing events
├── EventConsumer/                   # Event listeners (Spring Boot app)
│   └── src/main/
│       ├── java/.../eventconsumer/
│       │   ├── config/              # Message broker configuration
│       │   └── listener/            # Event listener implementations
│       └── resources/
│           └── application.yml      # Consumer configuration
├── AIAgent/                         # AI Agent (Spring Boot app, if selected)
│   └── src/main/
│       ├── java/.../aiagent/
│       │   ├── config/              # ChatClient, MCP server, WebConfig
│       │   ├── security/            # Auth filter, scopes, guardrails, rate limiter
│       │   ├── tool/                # @Tool-annotated domain tools
│       │   ├── agent/               # Primary + Specialist agents
│       │   ├── brain/               # Scratchpad, reflection service
│       │   ├── knowledge/           # Knowledge base, token-free Q&A
│       │   ├── protocol/            # REST, A2A, discovery, SSE, webhooks
│       │   ├── task/                # Async task manager
│       │   └── event/               # Webhook dispatch
│       └── resources/
│           ├── application.yml      # Spring AI + Anthropic config
│           └── .well-known/
│               └── agent.json       # A2A discovery agent card
├── .ai/                             # AI context directory
│   ├── prompts/                     # Task guides and quality specs
│   │   ├── JAVA_CODE_QUALITY.md     # Code quality specification
│   │   ├── code-review.md           # Review checklist
│   │   ├── add-entity.md            # How to add an entity
│   │   ├── add-endpoint.md          # How to add a REST endpoint
│   │   ├── add-job.md               # How to add a background job
│   │   └── add-event.md             # How to add an event type
│   └── checkpoint.json              # Session state for AI continuity
├── .github/workflows/ci.yml         # GitHub Actions CI (if --ci github)
├── docker-compose.yml               # Local dev stack (database, message broker)
├── .run/                            # IntelliJ run configurations
├── .cursor/                         # Cursor IDE configuration
│   ├── rules/java.mdc               # Java coding rules
│   └── hooks.json                   # Auto-formatting hooks
├── CLAUDE.md                        # AI assistant context (Claude Code)
├── AGENTS.md                        # Cross-tool AI agent baseline
└── README.md                        # Project documentation

Note: SQLDatastore and NoSQLDatastore are mutually exclusive — choose one based on your data storage needs.

Modules

Model

The foundation. Contains all your data structures.

Key principle: Always use ImmutableX types and builders. Never instantiate interfaces directly.

// ✅ Correct
ImmutablePlaceholder entity = ImmutablePlaceholder.builder()
    .name("example")
    .description("description")
    .build();

// ❌ Avoid
Placeholder entity = Placeholder.fromRecord(record);

SQLDatastore

Database access layer using Spring Data JDBC.

Why JDBC over JPA? No lazy loading gotchas, no proxy magic, no @Transactional surprises. What you write is what runs.

NoSQLDatastore

NoSQL database access layer using Spring Data.

Supported databases:

• MongoDB — Document store with flexible schemas
• Redis — Key-value store for high-performance caching and data

Shared

Business logic and cross-cutting concerns.

Services convert between PlaceholderRecord (database) and ImmutablePlaceholder (domain) at the boundary.

API

The REST API module — a runnable Spring Boot application.

Endpoints use ImmutablePlaceholderRequest for input and ImmutablePlaceholderResponse for output.

Jobs

Job service module — contains services for enqueueing background jobs.

The Jobs module is auto-included when Worker is selected. Job request schemas (sealed interfaces and records) live in the Model module for decoupled access.

Enqueueing jobs via service:

@Autowired
private PlaceholderJobService jobService;

// Fire-and-forget (immediate)
jobService.processAsync("data");

// Delayed (at specific time)
jobService.processAt("data", Instant.now().plusHours(1));

// Batch (multiple items)
jobService.processBatch(List.of("item1", "item2", "item3"));

Worker

Background job processing module — a runnable Spring Boot application using JobRunr.

Architecture: Jobs module contains request contracts, Worker module contains handlers. This allows any module to enqueue jobs without circular dependencies.

Supported job types:

Storage notes:

• Worker uses your selected datastore (SQL or MongoDB) for job persistence
• If you select Redis, Worker uses PostgreSQL for job storage (Redis is deprecated in JobRunr 8+)
• If no datastore is selected, Worker defaults to PostgreSQL
• Jobs module is auto-included when Worker is selected

Events

Event publisher module — contains services for publishing events to message brokers.

The Events module is auto-included when EventConsumer is selected. Event schemas (sealed interfaces and records) live in the Model module for decoupled access.

Publishing events:

@Autowired
private EventPublisher eventPublisher;

// Publish an event
eventPublisher.publish(new PlaceholderCreatedEvent("id-123", "Example", Instant.now()));

EventConsumer

Event consumer module — a runnable Spring Boot application that listens for events.

Supported message brokers:

Architecture: Events module contains the publisher service, EventConsumer module contains listeners. This allows any module to publish events without circular dependencies. Event schemas live in the Model module.

Listener examples:

// Kafka
@KafkaListener(topics = "${app.kafka.topics.placeholder-events}")
public void handleEvent(PlaceholderEvent event) { ... }

// RabbitMQ
@RabbitListener(queues = "${app.rabbitmq.queues.placeholder-events}")
public void handleEvent(PlaceholderEvent event) { ... }

// AWS SQS
@SqsListener("${app.sqs.queue.placeholder-events}")
public void handleEvent(PlaceholderEvent event, Acknowledgement ack) { ... }

// GCP Pub/Sub (uses Spring Integration)
@ServiceActivator(inputChannel = "placeholderInputChannel")
public void handleEvent(PlaceholderEvent event, BasicAcknowledgeablePubsubMessage msg) { ... }

AI Agent

Production AI agent module — a runnable Spring Boot application powered by Spring AI with Anthropic Claude.

Architecture: The AI Agent follows Anthropic's production recommendations. Deterministic operations (listing items, checking stock) use plain code — no LLM tokens spent. The LLM is only invoked when natural language understanding or judgment is required (routing, multi-step reasoning, error recovery). The circuit breaker (@CircuitBreaker(name = "llm")) protects against LLM API outages with automatic fallback responses.

Multi-agent pattern:

User message → Primary Agent (orchestrator)
                    │
                    ├── calls domain tools directly (simple queries)
                    │
                    └── calls askSpecialist tool (complex queries)
                              │
                              └── Specialist Agent (worker)
                                      └── calls specialist tools

The Primary Agent decides when to delegate — same mechanism as any other tool call. The Specialist Agent never calls back (acyclic flow prevents infinite loops).

Security pipeline (every request):

Request → ApiKeyAuthFilter → ScopeInterceptor → RateLimiter
        → InputGuardrailAdvisor (LLM) → Agent → OutputGuardrailAdvisor (regex) → Response

Graceful degradation: All LLM-dependent beans use @ConditionalOnBean(ChatModel.class). Without an ANTHROPIC_API_KEY, the application starts and serves non-AI endpoints (capabilities, health). The /chat endpoint returns a helpful message instead of failing.

Connecting AI assistants:

# Claude Code
claude mcp add --transport http my-agent http://localhost:8080/mcp

# Or via .mcp.json in your repo
{"mcpServers": {"my-agent": {"type": "http", "url": "http://localhost:8080/mcp"}}}

Endpoints:

Getting started:

# Generate project with AI Agent
trabuco init --name=my-agent --group-id=com.company.agent --modules=Model,Shared,AIAgent

# Start without API key (infrastructure endpoints only)
cd my-agent && mvn spring-boot:run -pl AIAgent

# Start with full AI capabilities
ANTHROPIC_API_KEY=your-key mvn spring-boot:run -pl AIAgent

Customization:

1. Replace PlaceholderTools methods with your domain tools (follow the @Tool + @ToolParam annotations)
2. Update the system prompt in PrimaryAgent for your domain's personality and rules
3. Add domain-specific ALLOW/BLOCK criteria in InputGuardrailAdvisor
4. Replace KnowledgeBase entries with your FAQ content
5. Configure API keys and rate limits in application.yml

Immutables: All DTOs (ChatRequest, ChatResponse, AskRequest, AskResponse, JsonRpcRequest, JsonRpcResponse, WebhookRegisterRequest) and value objects (CallerIdentity, MemoryEntry, ReflectionDecision, TaskEvent, WebhookRegistration) use the Immutables library with the project's @ImmutableStyle — consistent with all other modules.

Observability: Actuator + Prometheus metrics are pre-configured. Spring AI auto-instruments ChatClient calls, providing gen_ai.client.token.usage metrics for cost tracking. Correlation IDs propagate through the full agent pipeline (guardrail → agent → tools → reflection) via MDC.

Code Quality & Architecture

Generated projects come with strict code quality enforcement out of the box. Every project includes Google Java Format via Spotless, Maven Enforcer for dependency rules, and ArchUnit for architecture tests. These run as part of the normal build — violations fail the build, not just a linter warning.

Auto-Formatting

All generated code follows Google Java Format (2-space indentation, specific import ordering). Trabuco runs spotless:apply during project generation so your code is formatted from the first commit.

Manual commands:

mvn spotless:apply      # Auto-format all Java files
mvn spotless:check      # Check formatting without modifying (CI-friendly)
mvn enforcer:enforce    # Check dependency rules

IDE integration: When you select AI coding agents during setup, Trabuco generates auto-formatting hooks so code stays formatted as you work:

Architecture Tests

The Shared module includes ArchUnit tests that enforce architectural rules at build time:

These tests run as part of mvn test and fail the build if violated. To add project-specific rules, edit Shared/src/test/java/.../shared/ArchitectureTest.java.

AI Task Prompts

Every generated project includes an .ai/ directory with task-specific guides for AI coding assistants. Instead of relying on the AI to guess your project's patterns, these prompts provide step-by-step instructions with file locations and code examples.

The checkpoint.json file tracks session state (current work, completed steps, test status) so AI assistants can resume context across sessions.

Code Review Workflow

The generated project includes AI task prompts and quality specifications that support structured code review. Claude Code gets a /review skill that reviews code against the project's quality specification.

How it works:

1. The AI reads .ai/prompts/JAVA_CODE_QUALITY.md for the project's quality rules
2. Claude Code loads path-scoped rules from .claude/rules/ when Java files are accessed
3. The AI reviews code against relevant rules and reports findings by severity

Review categories: code-quality, modern-java, architecture, security, testing

CI/CD

GitHub Actions

Trabuco can generate a GitHub Actions CI workflow that matches your project's module configuration. The workflow is opt-in — pass --ci github during init or answer the CI prompt in interactive mode.

# Generate project with CI
trabuco init --name=myapp --group-id=com.company.myapp \
  --modules=Model,SQLDatastore,Shared,API --database=postgresql --ci github

The generated .github/workflows/ci.yml runs on pushes and pull requests to main and includes:

Conditional services: The workflow automatically includes Docker services based on your modules:

Regeneration on module addition: When you add a module with trabuco add, the CI workflow is automatically regenerated to include the new services. If CI wasn't configured during init, you'll be prompted to add it after a module addition.

Observability

Metrics

All runtime modules expose Prometheus metrics at /actuator/prometheus. These include:

• JVM metrics (memory, GC, threads)
• HTTP request metrics (latency, status codes)
• Database connection pool metrics
• Circuit breaker state

API Documentation

The API module includes Swagger UI for interactive API exploration:

• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI spec: http://localhost:8080/api-docs

Disable in production by setting SPRINGDOC_ENABLED=false.

Request Tracing

Every request is assigned a correlation ID for distributed tracing:

• Incoming X-Correlation-ID header is preserved
• If not present, a new UUID is generated
• Correlation ID is included in all log entries
• Correlation ID is returned in response headers

Health Checks

Health endpoints for monitoring and orchestration:

• /actuator/health — Overall health
• /actuator/health/readiness — Kubernetes readiness probe
• /actuator/health/liveness — Kubernetes liveness probe

Database and message broker connectivity is automatically included.

Test Coverage

JaCoCo is configured for test coverage reporting. After running tests, coverage reports are available at:

• <module>/target/site/jacoco/index.html

Run tests with coverage:

mvn test

Configuration Options

Available Modules

Notes:

• SQLDatastore and NoSQLDatastore are mutually exclusive
• Worker uses your datastore for job persistence (defaults to PostgreSQL if none selected)
• Jobs module is auto-included when Worker is selected (not shown in CLI)
• Events module is auto-included when EventConsumer is selected (not shown in CLI)

Java Version Detection

Trabuco automatically detects installed Java versions on your system. In interactive mode, version options show detection status:

Java version:
> 21 (LTS until 2031 - Recommended) [detected]
  25 (Latest LTS) [not detected]

If you select an undetected version, you'll be asked to confirm. In non-interactive mode, a warning is shown but the project is still generated. Use --strict to fail instead:

# Warns but continues
trabuco init --name=myapp --group-id=com.example --modules=Model --java-version=25

# Fails if Java 25 not installed
trabuco init --name=myapp --group-id=com.example --modules=Model --java-version=25 --strict

AI Coding Agents

Trabuco generates context files, coding rules, and quality hooks for popular AI coding assistants. These aren't generic instructions — they contain your project's actual module structure, dependency boundaries, and quality standards.

Every agent also gets AGENTS.md — a cross-tool baseline with the project's structure, build commands, module dependencies, and coding patterns. Codex uses AGENTS.md as its primary context file, so when selected it receives the full project architecture and coding standards.

In interactive mode, you'll be prompted to select which agents you want context files for. In non-interactive mode:

# Generate for specific agents
trabuco init --name=myapp --group-id=com.example --modules=Model,API --ai-agents=claude,cursor

# Generate for all agents
trabuco init --name=myapp --group-id=com.example --modules=Model,API --ai-agents=claude,cursor,copilot,codex

All agents also get the .ai/ directory with task prompts and quality specifications. See Code Quality & Architecture for details.

CI/CD Provider

Trabuco can generate a CI/CD workflow during project creation. In interactive mode, you'll be prompted to choose a CI provider. In non-interactive mode, use the --ci flag:

# Generate with GitHub Actions CI
trabuco init --name=myapp --group-id=com.example --modules=Model,SQLDatastore,Shared,API \
  --database=postgresql --ci github

Currently supported providers:

See CI/CD for details on what the workflow includes.

Tech Stack

Local Development

The generated project includes a docker-compose.yml for local development:

docker-compose up -d    # Start database (and message broker if EventConsumer selected)
mvn spring-boot:run -pl API

If you selected EventConsumer, the docker-compose includes the appropriate local service:

• Kafka — Kafka with Zookeeper
• RabbitMQ — RabbitMQ with management UI
• AWS SQS — LocalStack with auto-created queue
• GCP Pub/Sub — Pub/Sub emulator with auto-created topic/subscription

Running Tests

mvn test                # All tests
mvn test -pl Model      # Single module

Note: SQLDatastore and NoSQLDatastore tests require Docker to be running (Testcontainers).

Requirements

• Java 21+ (21, 25, or 26 — Trabuco auto-detects installed versions)
• Maven 3.8+
• Docker (for Testcontainers and local development)

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT License — do whatever you want with it.

Built with Trabuco. Now go build something amazing.