| name | cayenne-cgen |
| description | Use this skill whenever the user wants to (re)generate Cayenne entity Java classes from a DataMap. Trigger on phrases like 'generate Java classes', 'regenerate entities', 'run cgen', 'create the entity classes', 'why is the Artist class missing fields', 'where did the `_Abstract*` classes come from', 'sync the entity classes with the model', or any request to materialize Java from the DataMap. Also trigger as a follow-up after modeling changes (someone added an entity, attribute, or relationship and now the Java side is stale). This skill exclusively uses the `mcp__cayenne__cgen_run` MCP tool — it does NOT use `mvn cayenne:cgen` or the Gradle cgen task. |
cayenne-cgen
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 generates anyway using a sensible default config (all entities, makePairs=true, destination derived from the Maven layout). A missing <cgen> block is not an error and must never stop you from running the tool.
Required reading
${CLAUDE_PLUGIN_ROOT}/references/mcp-tools.md — cgen_run tool reference (arguments, return shape, failure modes).${CLAUDE_PLUGIN_ROOT}/references/cgen-config.md — every <cgen> field; needed when the user has to add or tweak the config block.${CLAUDE_PLUGIN_ROOT}/references/project-layout.md — locate the project descriptor.
Step 1 — Resolve project and DataMap
The MCP tool needs two arguments:
projectPath — absolute path to the top-level project descriptor (cayenne-*.xml). Not a DataMap file.dataMap — the name as it appears in <map name="..."> in the descriptor. Not a file path.
Locate the descriptor via project-layout.md. If multiple descriptors exist, ask which one. Open the descriptor to extract the DataMap names from <map> elements.
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 — Call cgen_run
mcp__cayenne__cgen_run({
"projectPath": "<absolute path to cayenne-*.xml>",
"dataMap": "<map name from the descriptor>"
})
Call the tool directly for each DataMap — never inspect the DataMap for a <cgen> block first, and never treat its absence as a blocker. The tool generates with a default config when no block exists.
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 3 — Surface the result
The tool returns structured JSON. Report:
summary.filesConsidered and summary.filesWritten verbatim — these are the headline.- The first few entries in
files (relative paths). Full list is informational; offer to dump it if the user asks.
error, when non-null — this is blocking. Read the message and explain in user terms (a missing entity class name, a bad template path, an invalid <destDir>, etc.).resolved.destDir — the absolute output directory. If the DataMap had no <cgen> block, the tool generated from a synthesized default; report this destination so the user can confirm it's right, and offer to persist a <cgen> block (via cayenne-modeling) if they want to customize destination, templates, or entity filtering.
cgen always runs in full, but rewrites a file only when the generated contents differ from what is on disk. So files is exactly what changed, and a status of up_to_date means the Java was already in sync with the model — say so plainly rather than implying work was skipped.
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 pre-check the DataMap for a
<cgen> block before calling cgen_run, and do not add a block before running. A missing block is not an error — the tool generates with defaults. Only add a <cgen> block afterward if the user wants to persist or customize the config.
- 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.
