cayenne-cgen

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.