ai-plugin - clarifying cgen flow

Author: andrus

ai-plugin/references/cgen-config.md

@@ -49,7 +49,7 @@ Note the **different namespace** for `<cgen>` (`http://cayenne.apache.org/schema
 
 | Field | Default | Meaning |
 |---|---|---|
-| `<destDir>` | — | Output directory, **relative to the project XML directory** (the directory containing `cayenne-*.xml`). Typical values: `.`, `../java`, `../../main/java`. Absolute paths also work. |
+| `<destDir>` | — | Output directory, **relative to the directory containing `*.map.xml`**. Typical values: `.`, `../java`, `../../main/java`. |
 | `<mode>` | `entity` | What to generate. `entity` = per-entity classes. `all` = per-entity classes + a single DataMap class with named-query helpers. |
 
 ### Pairs vs single class
@@ -107,13 +107,45 @@ The MCP tool:
 1. Loads the project at `projectPath`.
 2. Finds the named DataMap (`dataMap` argument).
 3. Reads its embedded `<cgen>` block.
-4. Resolves `destDir` relative to the project file.
+4. Resolves `destDir` relative to the `*.map.xml` file.
 5. Runs the generator. Returns a JSON object listing files `written`, files `skipped` (already up-to-date), and any `errors`.
 
 If the DataMap has no `<cgen>` block, the tool returns an error and the user must add one — typically via the `cayenne-modeling` skill or the Modeler GUI.
 
-## Recommended starting config
+## Determining `destDir`
+
+`destDir` is relative to the directory that contains `*.map.xml`.
+
+**Before writing the default config, inspect the project tree** to find the Java source root and express it as a relative path from the map file's directory. Do not blindly paste `../java`.
+
+### Standard Maven layout
+
+Map files are frequently placed in a package subdirectory under `resources/` rather than directly in `resources/` itself. Count the directory levels between `resources/` and the map file and add that many extra `../` segments.
+
+| Map file location | `destDir` |
+|---|---|
+| `src/main/resources/mydb.map.xml` | `../java` |
+| `src/main/resources/com/mydb.map.xml` | `../../java` |
+| `src/main/resources/com/example/mydb.map.xml` | `../../../java` |
+| `src/main/resources/com/example/app/mydb.map.xml` | `../../../../java` |
+| `src/test/resources/mydb.map.xml` | `../java` |
+| `src/test/resources/com/example/app/mydb.map.xml` | `../../../../java` |
+
+The rule: one `../` to escape `resources/`, then one `../` per package segment, then `java`. Always verify by resolving the resulting path mentally before writing it.
 
+### Non-standard layouts
+
+If the project doesn't follow Maven conventions, locate the actual Java sources:
+
+1. Look for existing `.java` files or a `src/` directory near the map file.
+2. Compute the relative path from the map file's directory to that sources root.
+3. If no Java sources exist yet, ask the user where generated classes should go.
+
+### Distinguishing main vs test maps
+
+If the map file lives under a test resource directory (`src/test/resources/`, `test/`, or a path containing `test`), the generated classes belong in the test source tree. Point `destDir` there rather than at the main sources — test entity classes mixed into `src/main/java/` are a common mistake.
+
+## Recommended starting config
 
 ```xml
 <cgen xmlns="http://cayenne.apache.org/schema/12/cgen">
@@ -125,10 +157,12 @@ If the DataMap has no `<cgen>` block, the tool returns an error and the user mus
 </cgen>
 ```
 
-Assuming the project XML lives at `src/main/resources/cayenne-mydb.xml`, this writes to `src/main/java/<package>/`.
+The `../java` value above assumes a standard Maven layout (`src/main/resources/` or `src/test/resources/`). Adjust if the project uses a non-standard layout — see "Determining `destDir`" above.
 
 ## Anti-patterns
 
 - Setting `<makePairs>false</makePairs>` to "simplify" — you lose the ability to add user code without it being overwritten on the next cgen run.
 - Editing `_<Entity>.java` files (the superclasses). They are regenerated. Customize `<Entity>.java` (the subclass) instead.
 - `<destDir>` as an absolute path checked into source — breaks reproducibility for other developers. Use a relative path.
+- Pasting `../java` blindly without checking the actual project layout. Inspect the tree first; see "Determining `destDir`" above.
+- Pointing a test DataMap's `destDir` at `src/main/java/` — test entity classes belong in the test source tree.

ai-plugin/skills/cayenne-cgen/SKILL.md

@@ -23,7 +23,7 @@ description: "Use this skill whenever the user wants to (re)generate Cayenne ent
 -->
 # cayenne-cgen
 
-Run Cayenne's class generator on a DataMap via the `mcp__cayenne__cgen_run` MCP tool. Reads the embedded `<cgen>` block in the DataMap to determine destination, mode, templates, etc.
+Run Cayenne's class generator on a DataMap via the `mcp__cayenne__cgen_run` MCP tool. The tool reads the embedded `<cgen>` block in the DataMap to determine destination, mode, templates, etc.; if no block is present the tool reports an error and the skill adds a default one then retries.
 
 ## Required reading
 
@@ -42,26 +42,7 @@ Locate the descriptor via `project-layout.md`. If multiple descriptors exist, as
 
 If the user named the DataMap directly (e.g. "regenerate classes for the customers DataMap"), use that. If they said "regenerate everything" and there are multiple DataMaps, run `cgen_run` once per DataMap in sequence (the tool generates per-DataMap).
 
-## Step 2 — Verify `<cgen>` block exists
-
-Before calling the tool, check the target DataMap for a `<cgen xmlns="http://cayenne.apache.org/schema/12/cgen">` block. If missing:
-
-1. Don't call `cgen_run` blindly — it will return an error.
-2. Either:
-   - **Add a minimal block** by delegating to the `cayenne-modeling` skill. Use the starter config from `cgen-config.md`:
-     ```xml
-     <cgen xmlns="http://cayenne.apache.org/schema/12/cgen">
-         <destDir>../java</destDir>
-         <mode>entity</mode>
-         <makePairs>true</makePairs>
-         <usePkgPath>true</usePkgPath>
-         <createPKProperties>true</createPKProperties>
-     </cgen>
-     ```
-     Confirm `destDir` with the user — it's relative to the project XML directory and decides where generated `.java` files land.
-   - Or, if the user prefers the GUI, suggest the `cayenne-modeler` skill and tell them to configure the DataMap's "Class Generation" tab.
-
-## Step 3 — Call `cgen_run`
+## Step 2 — Call `cgen_run`
 
 ```
 mcp__cayenne__cgen_run({
@@ -72,7 +53,11 @@ mcp__cayenne__cgen_run({
 
 If the tool is not available (MCP server not registered), surface `cayenne-mcp-server/README.md` and stop. **Do not** suggest `mvn cayenne:cgen` or the Gradle cgen task.
 
-## Step 4 — Surface the result
+If the tool errors because no `<cgen>` block is present in the DataMap, add a minimal one using the starting config approach from `cgen-config.md`
+
+If the `destDir` can't be determined reliably (non-standard project layout, empty project, etc.), conform it with the user
+
+## Step 3 — Surface the result
 
 The tool returns structured JSON. Report:
 
@@ -82,14 +67,14 @@ The tool returns structured JSON. Report:
 
 If `writtenCount` is 0 and `skippedCount` covers everything, say so — it means everything is already up-to-date and no work was needed.
 
-## Step 5 — Next steps
+## Step 4 — Next steps
 
 - If new `_<Entity>.java` superclass files were generated, gently remind the user not to edit those — they will be overwritten next run. User code goes in the matching `<Entity>.java` subclass.
 - If the user just ran reverse engineering, this skill is the natural follow-up. Cross-link back to `cayenne-modeling` if they need to tweak names/types before regenerating.
 
 ## Anti-patterns
 
-- **Do not** call `cgen_run` without verifying the `<cgen>` block exists — the tool returns an error and confuses the user.
+- **Do not** pre-check the DataMap for a `<cgen>` block before calling `cgen_run`. Call the tool first; add the default config only if the tool reports it is missing.
 - **Do not** suggest Maven (`mvn cayenne:cgen`) or Gradle (`cayenneCgen`) goals when MCP is unavailable. Those build plugins are out of scope. Point at MCP setup instead.
 - **Do not** edit `_<Entity>.java` files. Generated superclasses. Edit `<Entity>.java` subclasses.
 - **Do not** confuse `projectPath` and `dataMap` arguments. `projectPath` is a file system path to `cayenne-*.xml`. `dataMap` is a logical name (e.g. `mydb`), not a path to `mydb.map.xml`.