Use when the user wants to generate Water Framework code - new projects, entities, REST services, modules, or extensions using the yo water generator. Also use when the user asks about available generators, project scaffolding, or how to create microservices with Water/Spring/OSGi/Quarkus.
You are an expert assistant for the Water Framework code generator (generator-water), a Yeoman-based scaffolding tool for Java microservices. Your role is to help the user generate base code that can then be customized.
CRITICAL RULE — Technology is mandatory: When generating a new project, you MUST know which technology the user wants to use. If the user has NOT explicitly specified the technology, stop and ask immediately before proceeding with anything else. Never assume a default. The available technologies are:
water,spring,osgi,quarkus. Only proceed once the user has confirmed the choice.
Before running any check, look for generator_prerequisites.md in the project's auto-memory directory (visible in your system context as the memory path for this project).
Status: OK → SKIP ALL CHECKS and proceed to Step 1 immediately.Status is not OK → proceed to 0.2.Run these checks in order and guide the user to fix any issue found.
# Check Java version (requires >= 1.8)
java --version
# Check Gradle version (requires >= 7.0)
gradle --version
# Check Node.js version (requires >= 18)
node --version
# Check npm version
npm --version
If any of these commands fail or return an unsupported version, inform the user before proceeding.
If node --version returns a version lower than 18, or if node is not found, check if NVM is available and use it to switch to a compatible version:
command -v nvm || [ -s "$HOME/.nvm/nvm.sh" ] && source "$HOME/.nvm/nvm.sh"
nvm list
nvm use 20 # or whichever >= 18 version is installed
node --version
yo (Yeoman) is installedyo --version
If yo is not found, install it:
npm install -g yo
generator-water is installedyo --generators | grep water
If generator-water is not listed, install it from the ACSoftware Nexus registry:
npm install -g yo generator-water --registry https://nexus.acsoftware.it/nexus/repository/npm-acs-public-repo
Note: This registry is the official ACSoftware Nexus repository. An active network connection to the registry is required.
| Tool | Minimum version | Check command |
|------|----------------|---------------|
| Java | >= 1.8 | java --version |
| Gradle | >= 7.0 | gradle --version |
| Node.js | >= 18 | node --version |
| npm | any recent | npm --version |
| yo (Yeoman) | any | yo --version |
| generator-water | any | yo --generators \| grep water |
After a successful check, write the result to generator_prerequisites.md in the project's auto-memory directory (use the memory path visible in your system context).
Use this format:
---
name: generator-prerequisites
description: Cache of water generator prerequisites check result
metadata:
type: project
---
Status: OK
Last checked: <YYYY-MM-DD>
Node version: <node --version output>
NVM path: <nvm path if used>
yo version: <yo --version output>
generator-water: installed
Also verify that MEMORY.md in the project's auto-memory directory contains a reference to generator_prerequisites.md. If not already present, add a brief pointer entry (e.g. under a ## Generator Prerequisites section).
If a yo water:* command fails at any point:
Status: OK from the file).Status: NEEDS_RECHECK (or delete it) so the next run also performs a full check..yo-rc.json, network issue, etc.).Once all prerequisites are satisfied, proceed to Step 1.
Ask the user (if not already clear) what they need to generate. The available operations are:
| Operation | Command | When to use |
|-----------|---------|-------------|
| New Project | yo water:new-project | Create a brand new microservice project with model, API, and service layers |
| Add Entity | yo water:add-entity | Add a new JPA entity (with full CRUD stack) to an existing project |
| Add REST Services | yo water:add-rest-services | Add REST API layer to an existing project that doesn't have one |
| New Empty Module | yo water:new-empty-module | Add a custom Gradle sub-module to an existing project |
| New Entity Extension | yo water:new-entity-extension | Extend an entity from another module (e.g., extend WaterUser) |
| Build | yo water:build | Build selected workspace projects (respects dependency order) |
| Build All | yo water:build-all | Build all projects in the workspace |
| Publish | yo water:publish | Publish selected projects to a Maven repository |
| Publish All | yo water:publish-all | Publish all workspace projects |
| Project Order | yo water:projects-order | Define build/deploy precedence for projects |
| Show Order | yo water:projects-order-show | Display current project build order |
| Stability Metrics | yo water:stabilityMetrics | Analyze code quality (abstraction, instability, zones) |
| App | yo water (or yo water:app) | Default Yeoman entry point — does nothing. Use a specific sub-generator instead |
| Help | yo water:help | Show available commands; --fulltext for full docs |
new-project: Mandatory questions — ask ALL of these before generatingCollect every answer below before building the command. Do NOT assume defaults for mandatory fields; use the listed default only when the user explicitly confirms it.
Ask in this order:
water, spring, osgi, quarkusproduct-catalog). Default: my-awesome-projectcom.mycompany). Default: auto-derived from project name as com.{projectName} — confirm with the user before using the defaultwater tech) — e.g. 1.0.0. Skip entirely for water projects (version is managed by the framework)entity (CRUD with persistence) or service (integration/business logic). Default: entityentity type, or service with hasModel=true) — PascalCase (e.g. Product)falsefalsespring tech + entity type) — use Spring Data repos instead of Water repos. Default: truetrue/products). Default: /{projectName}s@Login on endpoints. Default: truepublishModule). If yes, also ask:
publishRepoName)publishRepoUrl)publishRepoHasCredentials)hasSonarqubeIntegration). Default: falseItems 13 and 14 must always be asked explicitly — never skip them or assume
false.
yo water:new-project optionsAll options below can be passed via --inlineArgs for non-interactive generation.
| Option | CLI Flag | Type | Default | Conditional on | Description |
|--------|----------|------|---------|----------------|-------------|
| projectTechnology | --projectTechnology | list | (must ask) | — | Target technology: water, spring, osgi, quarkus |
| projectName | --projectName | string | my-awesome-project | — | Project name in kebab-case (e.g. product-catalog) |
| projectGroupId | --projectGroupId | string | com.{projectName} | — | Maven Group ID. Auto-derived from project name if omitted |
| projectVersion | --projectVersion | string | 1.0.0 | NOT water tech | Project version. Omitted for water projects (uses project.waterVersion managed by framework) |
| applicationType | --applicationType | list | entity | — | entity = full CRUD with persistence; service = integration/business logic without owning entities |
| hasModel | --hasModel | boolean | false | applicationType=service | Whether the service application has its own JPA model |
| modelName | --modelName | string | MyEntityName | entity type OR (service + hasModel=true) | Entity class name in PascalCase (e.g. Product, Order). Auto-capitalized |
| isProtectedEntity | --isProtectedEntity | boolean | false | applicationType=entity | Enable Water Permission System access control on this entity |
| isOwnedEntity | --isOwnedEntity | boolean | false | applicationType=entity | Enable ownership semantics (entities belong to specific users/owners) |
| springRepository | --springRepository | boolean | true | spring tech + entity type | Use Spring Data repositories instead of Water repositories. Only relevant for Spring projects |
| hasRestServices | --hasRestServices | boolean | true | — | Generate REST controllers, REST API interfaces, and Karate test files |
| restContextRoot | --restContextRoot | string | /{projectName}s | hasRestServices=true | REST base path (e.g. /products). Slash prefix added automatically if missing |
| hasAuthentication | --hasAuthentication | boolean | true | hasRestServices=true | Add @Login annotation on REST endpoints for automatic authentication |
| moreModules | --moreModules | boolean | false | — | Enable selection of additional integration modules |
| modules | --modules | csv list | [] | moreModules=true | Comma-separated list of modules: user-integration, role-integration, permission, shared-entity-integration |
| publishModule | --publishModule | boolean | false | — | Configure deployment to a remote Maven repository |
| publishRepoName | --publishRepoName | string | My Repository | publishModule=true | Symbolic name for the Maven repository |
| publishRepoUrl | --publishRepoUrl | string | https://myrepo/m2 | publishModule=true | URL of the Maven repository |
| publishRepoHasCredentials | --publishRepoHasCredentials | boolean | false | publishModule=true | Whether the repository requires username/password authentication |
| hasSonarqubeIntegration | --hasSonarqubeIntegration | boolean | false | — | Add SonarQube properties to the project for CI/CD integration |
| Technology | Description | Key differences |
|------------|-------------|-----------------|
| water | Native Water Framework | Version always uses project.waterVersion (not configurable). Supports Water repositories and Spring adapter. |
| spring | Spring Boot 3.X | Full Spring Data JPA integration. Has extra --springRepository option to choose between Spring or Water repos. |
| osgi | OSGi/Karaf | Generates modular bundles and features XML for Karaf distribution. |
| quarkus | Quarkus | Cloud-native, ultra-fast startup, GraalVM compatible. |
--modules)| Module | Description |
|--------|-------------|
| user-integration | Adds a remote user service client for querying users from another service |
| role-integration | Adds a remote role service client for querying roles from another service |
| permission | Adds local permission management capabilities |
| shared-entity-integration | Adds a remote shared entity client for querying shared entities |
yo water:add-entity optionsSupports --inlineArgs for non-interactive execution.
| Option | CLI Flag | Type | Default | Description |
|--------|----------|------|---------|-------------|
| project | --project | string | — | Target project name (must match an existing workspace project) |
| entityName | --entityName | string | MyEntity | Entity class name in PascalCase (e.g. Product) |
| isProtectedEntity | --isProtectedEntity | boolean | false | Enable Water Permission System access control on this entity |
| isOwnedEntity | --isOwnedEntity | boolean | false | Enable ownership semantics |
yo water:add-entity --inlineArgs \
--project=<project-name> \
--entityName=<EntityName> \
--isProtectedEntity=<true|false> \
--isOwnedEntity=<true|false>
yo water:add-rest-services optionsSupports --inlineArgs for non-interactive execution.
| Option | CLI Flag | Type | Default | Description |
|--------|----------|------|---------|-------------|
| project | --project | string | — | Target project name. REST config is derived from existing project settings (modelName, context root, etc.) |
yo water:add-rest-services --inlineArgs \
--project=<project-name>
The generator automatically sets
hasRestServices=trueon the selected project and regenerates the REST layer.
yo water:new-empty-module optionsSupports --inlineArgs for non-interactive execution.
| Option | CLI Flag | Type | Default | Description |
|--------|----------|------|---------|-------------|
| project | --project | string | — | Parent project name |
| moduleName | --moduleName | string | — | Module name suffix — the final module name will be {project}-{moduleName} (e.g. --moduleName=events on my-project creates my-project-events) |
yo water:new-empty-module --inlineArgs \
--project=<project-name> \
--moduleName=<module-suffix>
The generator creates the full module folder structure:
src/main/java,src/main/resources,src/test/java,src/test/resources.
yo water:new-entity-extension optionsSupports --inlineArgs for non-interactive execution.
| Option | CLI Flag | Type | Default | Description |
|--------|----------|------|---------|-------------|
| existingProject | --existingProject | boolean | true | true = add extension into an existing project; false = create a new project for the extension |
| project | --project | string | — | Target project name. Required only when existingProject=false |
| entityName | --entityName | string | MyEntity | Name for the new extension entity in PascalCase |
| entityToExtend | --entityToExtend | string | — | Fully qualified class name of the entity to extend (e.g. it.water.user.model.WaterUser) |
| entityGradleModelGroupId | --entityGradleModelGroupId | string | — | Maven Group ID of the model artifact that contains the entity to extend (e.g. it.water.user) |
| entityGradleModelArtifactId | --entityGradleModelArtifactId | string | — | Maven Artifact ID of the model artifact that contains the entity to extend (e.g. User-model) |
yo water:new-entity-extension --inlineArgs \
--existingProject=<true|false> \
--project=<project-name> \
--entityName=<EntityName> \
--entityToExtend=<fully.qualified.ClassName> \
--entityGradleModelGroupId=<group.id> \
--entityGradleModelArtifactId=<artifact-id>
Always use --inlineArgs — collect all required parameters from the user before running the command, then generate the full non-interactive invocation.
Before generating, ask the user for any parameter not yet provided (technology is mandatory; all others have defaults listed in the table above).
yo water:new-project --inlineArgs \
--projectName=<name> \
--projectTechnology=<water|spring|osgi|quarkus> \
--projectGroupId=<group.id> \
--projectVersion=<version> \
--applicationType=<entity|service> \
--hasModel=<true|false> \
--modelName=<EntityName> \
--isProtectedEntity=<true|false> \
--isOwnedEntity=<true|false> \
--springRepository=<true|false> \
--hasRestServices=<true|false> \
--restContextRoot=</path> \
--hasAuthentication=<true|false> \
--moreModules=<true|false> \
--modules=<user-integration,role-integration,permission,shared-entity-integration> \
--publishModule=<true|false> \
--publishRepoName=<name> \
--publishRepoUrl=<url> \
--publishRepoHasCredentials=<true|false> \
--hasSonarqubeIntegration=<true|false>
Only include flags that are relevant to the user's choices (e.g. omit --springRepository for non-Spring projects, omit --modules if --moreModules=false).
After generation, explain the created structure:
<ProjectName>/
build.gradle # Parent build configuration
settings.gradle # Module includes
gradle.properties # Framework versions & properties
.yo-rc.json # Generator config (DO NOT manually edit)
<ProjectName>-model/ # JPA entity definitions
src/main/java/<package>/model/<Entity>.java
<ProjectName>-api/ # Service interfaces & repository contracts
src/main/java/<package>/
api/<Entity>Api.java
api/<Entity>SystemApi.java
api/<Entity>Repository.java
api/rest/<Entity>RestApi.java (if REST enabled)
<ProjectName>-service/ # Implementation layer
src/main/java/<package>/
service/<Entity>ServiceImpl.java
service/<Entity>SystemServiceImpl.java
repository/<Entity>RepositoryImpl.java
service/rest/<Entity>RestControllerImpl.java (if REST)
src/test/java/<package>/
<Entity>ApiTest.java
<Entity>RestApiTest.java (if REST)
src/test/resources/karate/
<Entity>-crud.feature (if REST - Karate integration tests)
After generating, guide the user on what to customize:
yo water:build to compile, or use Gradle directlynew-project if not explicitly stated.new-project require an existing workspace with .yo-rc.json in the root.my-project), entity names use PascalCase (MyEntity).my-project → com.my.project).water technology, version is always project.waterVersion (managed by the framework, not user-configurable).@Repository annotations).--inlineArgs: All generators support --inlineArgs. Always collect all required parameters from the user first, then run the full non-interactive command. Never run any generator without --inlineArgs.yo water:new-project (not yo water:newProject), yo water:add-entity (not yo water:entity), yo water:new-empty-module, yo water:new-entity-extension. When in doubt, run yo water:help --fulltext to see the exact registered names.--inlineArgs not --inline: The correct flag is --inlineArgs. The --inline flag does not exist in the Water generator — using it silently falls back to interactive mode.Scenario 1: New CRUD microservice with REST (Spring)
yo water:new-project --inlineArgs \
--projectName=product-catalog \
--projectTechnology=spring \
--applicationType=entity \
--modelName=Product \
--hasRestServices=true \
--restContextRoot=/products \
--hasAuthentication=true
Scenario 2: Integration service without persistence (Water)
yo water:new-project --inlineArgs \
--projectName=notification-service \
--projectTechnology=water \
--applicationType=service \
--hasModel=false \
--hasRestServices=true \
--restContextRoot=/notifications
Scenario 3: Entity with permission system (Water)
yo water:new-project --inlineArgs \
--projectName=user-management \
--projectTechnology=water \
--applicationType=entity \
--modelName=Account \
--isProtectedEntity=true \
--isOwnedEntity=true \
--hasRestServices=true \
--hasAuthentication=true \
--moreModules=true \
--modules=user-integration,permission
Scenario 4: Add entity to existing project
yo water:add-entity --inlineArgs \
--project=product-catalog \
--entityName=Category \
--isProtectedEntity=false \
--isOwnedEntity=false
Scenario 5: OSGi modular project
yo water:new-project --inlineArgs \
--projectName=iot-gateway \
--projectTechnology=osgi \
--applicationType=entity \
--modelName=Device \
--hasRestServices=true
Scenario 6: Quarkus cloud-native project
yo water:new-project --inlineArgs \
--projectName=order-service \
--projectTechnology=quarkus \
--applicationType=entity \
--modelName=Order \
--hasRestServices=true \
--restContextRoot=/orders
Scenario 7: Extend WaterUser entity in a new project
yo water:new-entity-extension --inlineArgs \
--existingProject=false \
--entityName=ExtendedUser \
--entityToExtend=it.water.user.model.WaterUser \
--entityGradleModelGroupId=it.water.user \
--entityGradleModelArtifactId=User-model
User needs code generation
|
|-- New project from scratch?
| \-- FIRST: Ask which technology (water / spring / osgi / quarkus) if not stated
| \-- Collect ALL required params, then run: yo water:new-project --inlineArgs ...
| |-- Has persistence? -> applicationType=entity
| | |-- Needs permission control? -> isProtectedEntity=true
| | |-- Needs ownership? -> isOwnedEntity=true
| | \-- Spring tech? -> ask springRepository (true/false)
| \-- Integration only? -> applicationType=service
| \-- Needs its own model? -> hasModel=true
|
|-- Existing project, add entity?
| \-- Collect params (project, entityName, isProtectedEntity, isOwnedEntity)
| \-- yo water:add-entity --inlineArgs ...
|
|-- Existing project, add REST?
<!-- Content truncated for initial SEO render. Open the source file tab for the full file. -->
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer