---
name: kickoff-java-project
description: Kicks off a new Java 25 Maven monorepo with Spring Boot 4, root dependencyManagement, Liquibase, Hibernate or jOOQ, JaCoCo aggregate, infrastructure (Terraform), and CI workflows. Use when the user wants to create or scaffold a new Java/Spring Boot project.
---

# Kickoff Java Project

Interactive workflow to scaffold a new **Java 25 / Spring Boot 4.0.3** Maven monorepo.

Primary reference: **Janus** (jOOQ, Kafka CDC, Redis, Terraform). Secondary: **Cerberus** (Hibernate patterns).

## Module Registry

| Module | File | Condition | Input |
|--------|------|-----------|-------|
| common, model, core, webapp, jacoco | [modules/base.md](modules/base.md) | Always | — |
| security | [modules/security.md](modules/security.md) | Always | — |
| kafka | [modules/kafka.md](modules/kafka.md) | Kafka=Yes | #7 |
| redis | [modules/redis.md](modules/redis.md) | Redis=Yes | #5 |

Shared conventions: [conventions.md](conventions.md). Version tables and copy-mappings: [reference.md](reference.md). Infrastructure: [infrastructure.md](infrastructure.md).

## Subagent Registry

| Agent | File | Type | Phase |
|-------|------|------|-------|
| kickoff-reference-reader | `agents/kickoff-reference-reader.md` | read-only (explore) | Section 4 |
| kickoff-infra-generator | `agents/kickoff-infra-generator.md` | writes files (generalPurpose) | Section 5 |

---

## Section 0: Locate reference repos

Janus is the primary reference (Spring Boot 4.0.3). Cerberus for Hibernate patterns.

1. Ask the user for the **local path to Janus** (e.g. `../humand-janus` or absolute path). This is always required.
2. If ORM = Hibernate, also ask for the **local path to Cerberus**.
3. Verify each path exists and contains a `pom.xml`.
4. If the user doesn't have a reference repo locally, offer to clone it:
   - Janus: `https://github.com/HumandDev/humand-janus`
   - Cerberus: `https://github.com/HumandDev/humand-cerberus`

---

## Section 1: Gather inputs

**Do not scaffold until all required inputs are confirmed.**

| # | Field | Required | Description |
|---|-------|----------|-------------|
| 1 | **Project name** | Yes | Artifact prefix (e.g. `my-service`). Derives groupId `co.humand.myservice`, base package `co.humand.myservice`. |
| 2 | **GitHub repository URL** | Yes | `https://github.com/Org/repo`, `git@github.com:Org/repo.git`, or `Org/repo`. |
| 3 | **ORM** | Yes | Hibernate or jOOQ. Hibernate → Cerberus reference. jOOQ → Janus reference. |
| 4 | **Parent directory** | No | Default: current working directory (`..`). |
| 5 | **Redis** | No | Default: No. If Yes: CacheConfiguration, CacheNames, application.yml redis block. |
| 6 | **Expose gRPC** | Yes | If Yes: add `publish-libs.yml` workflow. |
| 7 | **Kafka CDC** | Yes | If Yes: create `<prefix>-kafka` module. |
| 8 | **Own database** | Yes | If Yes: create `infrastructure/modules/db`. |
| 9 | **Worker** | Yes | Default: Yes when Kafka=Yes. Dual api+worker deployment. |
| 10 | **Load Balancer** | Yes | If Yes: ALB listener rules via LB submodule. |
| 11 | **LB priority** | If LB=Yes | Unique integer (Cerberus=194, Argus=195, Janus=196). |
| 12 | **Swagger/OpenAPI** | No | Default: Yes. If Yes: springdoc dep, OpenApiConfig, Api interface pattern. |
| 13 | **Datadog @Trace** | No | Default: No. If Yes: dd-trace-api dep, @Trace on service methods. |

If the user provided some values in their message, use them and ask only for missing required fields.

---

## Section 2: Resolve or clone target repo

1. Ask the user for the **local path** where the project should live (default: `../<project-name>`).
2. If the path exists and is a git repo, use it as **project root**.
3. If the path doesn't exist: `git clone <github-url> <target_path>`. If clone fails, offer `git init` + `git remote add`.

---

## Section 3: Load reference files

Always load:
- `reference.md` — versions, AWS env table, copy-mappings
- `conventions.md` — JSpecify, SB4 compat, pitfalls
- `modules/base.md` — common, model, core, webapp, jacoco
- `modules/security.md` — JWT security module
- `infrastructure.md` — Terraform, workflows

Conditionally load:
- **If Kafka=Yes**: `modules/kafka.md`
- **If Redis=Yes**: `modules/redis.md`

---

## Section 4: Reference read (subagent)

Launch `kickoff-reference-reader` subagent (`subagent_type="explore"`, model `fast`).

**Prompt:** Full content of `agents/kickoff-reference-reader.md` plus:
- `janusPath`: from Section 0
- `cerberusPath`: from Section 0 (null if not Hibernate)
- `orm`: from Section 1 input #3
- `options`: from Section 1 inputs #5-13
- `projectName`: from Section 1 input #1

**Wait** for the structured report. Validate version numbers against `reference.md`.
If drift detected, warn the user before proceeding.

The report output is used in Section 5 for both main-thread scaffolding and the infra-generator subagent.

---

## Section 5: Scaffold (parallel)

### Step 1: Launch infra-generator (parallel)

Launch `kickoff-infra-generator` subagent (`subagent_type="generalPurpose"`, model `fast`).

**Prompt:** Full content of `agents/kickoff-infra-generator.md` plus:
- `targetRepoPath`: project root from Section 2
- `janusPath`: from Section 0
- `infraTemplates`: Section 7 from reference-reader output
- `workflowTemplates`: Section 6 from reference-reader output
- `copyVerbatimFiles`: Section 2 from reference-reader output
- `projectName`, `projectPrefix`, `githubRepo`: from Section 1
- `options`: from Section 1 inputs

### Step 2: Maven + Java scaffolding (main thread, runs in parallel)

While the infra-generator runs, scaffold Maven POMs and Java source files:

1. Apply conventions from `conventions.md` throughout.
2. Use Module POMs (Section 3) and Java Source Templates (Section 4) from the reference-reader output.
3. Follow patterns in `modules/base.md`, `modules/security.md`, and conditionally `modules/kafka.md`, `modules/redis.md`.
4. Use Application Config (Section 5) from the reference-reader output for application.yml files.
5. Copy-verbatim files (Section 2) for .mvn/, .gitignore, Dockerfile, mvnw, signing-key.pem, jwks.json.
6. Substitute project name, groupId, base package, artifact paths, and ORM-specific blocks.

### Step 3: Wait for infra-generator

Check infra-generator output. Review warnings. If any files were not generated, create them manually using `infrastructure.md` patterns.

---

## Section 6: Verification

### a) Maven build

```bash
./mvnw spotless:apply
./mvnw verify
```

Fix any failures. Common fixes are documented in `conventions.md` (Known Pitfalls section).

### b) Terraform formatting

```bash
cd infrastructure && terraform fmt -recursive
```

### c) Generate AGENTS.md files

Generate an `AGENTS.md` for each submodule and root, following Janus's structure:

- **Root AGENTS.md**: project identity, overview table (Java 25, SB 4.0.3, ORM, etc.), module structure, naming conventions, feature creation workflow, code conventions, key commands, security, ports
- **`<prefix>-common/AGENTS.md`**: module purpose, when to add utilities
- **`<prefix>-model/AGENTS.md`**: repository pattern, entity conventions, Liquibase rules, jOOQ/Hibernate codegen notes
- **`<prefix>-core/AGENTS.md`**: domain catalog (empty initially), exception handling, cache conventions (if Redis)
- **`<prefix>-security/AGENTS.md`**: SecurityConfigurationProperties, CORS, JwtScope
- **`<prefix>-kafka/AGENTS.md`** (if Kafka): consumer catalog (empty), CDC event model structure, cross-ref `/add-java-kafka-cdc-consumer`
- **`<prefix>-webapp/AGENTS.md`**: endpoints (actuator only initially), controller conventions, GlobalExceptionHandler, JaCoCo rules, integration test patterns
- **`infrastructure/AGENTS.md`**: module structure, architecture (api/worker), key commands

---

## Section 7: CodeArtifact

The project depends on `co.humand.libraries` hosted on AWS CodeArtifact:

```bash
aws sso login --profile DEV
aws codeartifact get-authorization-token --domain humand --domain-owner 518514628507 --region us-east-1 --query authorizationToken --output text --profile DEV
```

If the build fails resolving `co.humand:*` dependencies, remind the user to authenticate.

---

## Section 8: Error handling

- **Reference repo not found**: Ask the user for the correct path or offer to clone from GitHub.
- **Clone fails**: Instruct user to create the repo on GitHub first, or offer `git init` + `git remote add`.
- **Maven build fails**: Check parent relativePath, module paths, POM references. If `co.humand:*` resolution fails, see Section 7.

---

## Section 9: Post-scaffold suggestions

After the project is scaffolded and verified:

- **If Kafka=Yes**: "Run `/add-java-kafka-cdc-consumer` to add your first CDC consumer."
- "Add your first endpoint following the controller conventions in `<prefix>-webapp/AGENTS.md`."
- "Update JaCoCo thresholds in `<prefix>-webapp/pom.xml` as you add tests."

---

## Documentation

When you need up-to-date documentation (Spring Boot 4, Spring Framework, Maven, Liquibase, jOOQ, etc.), use **Context7** MCP: resolve the library with `resolve-library-id` then query with `query-docs`.