amplicode/spring-skills/mapper-creator

Preflight: Spring MCP

This skill is part of the Spring Agent Toolkit and is designed to work with the Spring MCP server (provided by the Amplicode IntelliJ plugin). Before doing anything else, check your tool list for any Spring MCP tool — they are exposed under the amplicode MCP server (e.g. get_project_summary, list_module_dependencies, get_entity_details); harnesses that flatten MCP tools into the tool list use the mcp__amplicode__ prefix on the same names.

• If at least one Amplicode tool is available — MCP is connected. Proceed with the skill below.
• If none are available — stop and invoke the `amplicode-install` skill (bundled with the Spring Agent Toolkit). It installs the Amplicode plugin and walks the user through the «Настроить Spring Agent» welcome-screen button + MCP-client restart. After it completes, the MCP tools become available — resume this skill.
• If amplicode-install is not registered in your skill list, tell the user (in their language): "This skill needs the Amplicode IntelliJ plugin and its MCP server. Install it from https://amplicode.ru/marketplace into IntelliJ IDEA Ultimate/Community or GigaIDE, open any project, click «Настроить Spring Agent» on the Amplicode welcome screen, then restart your MCP client."

Mapper Creator

Creates a mapper (MapStruct interface/abstract class or custom converter) for converting between an entity and a DTO.

CRITICAL: Code ONLY from examples/ files. If no matching example -- STOP and ask user.

CRITICAL: For questions with a fixed set of choices, prefer `AskUserQuestion` > its analogue > plain text list. Plain numbered text lists are the last resort when no interactive tool is available.

CRITICAL: Read the conversation context BEFORE running Step 1. Half the questions in Steps 2–3 may already be answered by the user's prompt and prior turns. Re-asking what was already said is the #1 reason this skill feels slow.

Defaults

Smart defaults: If the user says "use defaults", "all defaults", "default settings" -- skip all questions where "Always ask?" = NO. Ask only the required ones.

Smart answer recognition: When the user directly provides a value instead of choosing from a list -- accept it. Examples:

• Question "Which entity?" -> user answers "Order" -> that IS the entity
• Question "Mapper type?" -> user answers "mapstruct" -> that IS the choice
• If the user gave multiple answers in one message -> accept all, skip the answered questions
• NEVER re-ask what the user has already answered (even indirectly)

Batch questions: Group related questions into a single AskUserQuestion call (up to 4 questions):

• The main question (mapper type) is always asked SEPARATELY
• Do not group questions from DIFFERENT decision branches
• Prefer AskUserQuestion; fall back to plain text only if the tool is unavailable

Step 0 -- Conversation context first (REQUIRED, no tool calls)

Before any MCP call, before any question, re-read the user's prompt and the prior turns of this conversation and extract whatever is already stated. This step costs nothing and prevents the most common failure mode of this skill — asking the user something they already said.

Build a mental checklist of inputs and tick off everything the user has already provided, explicitly or implicitly:

For every input that is explicitly or strongly implicitly answered: mark it as decided and skip the corresponding question in Steps 2–3. Do NOT ask "which entity?" if the user wrote "create a mapper for Order to OrderDto" — both entity and DTO are answered. Do NOT ask "MapStruct or Custom?" if the user wrote "create a MapStruct mapper".

For every input that is not answered: defer to the Decision-making principle below — try to derive it from project context first (Step 1), and only then ask.

Step 0 is mental, not a tool call. Do not announce it to the user. Do not write "Step 0 done". Just internalize what the user already said before proceeding to Step 1.

Decision-making principle — context first, then ask

Before asking the user any question, attempt to derive the answer from the context already gathered: project summary, module dependencies, entity details, existing files in the package, prior turns of this conversation, and the user's original prompt. Only ask when the context yields no clear default or when the choice is genuinely user-specific (e.g. which entity, which DTO).

Hierarchy of decisions:

1. Context is unambiguous → decide silently, do NOT ask.

Examples: language and module from get_project_summary; MapStruct presence from list_module_dependencies; mapper package from the DTO's package; className from {Entity}Mapper; componentModel from Spring presence; mapperType when the user said "MapStruct" or "Custom" outright.

1. Context gives a strong signal → state the decision + alternatives in one line, let the user override or stay silent.

Format: `` Will create OrderMapper (MapStruct, componentModel=spring, in the same package as OrderDto). Alternatives: Custom mapper. OK? `` The user can answer "ok" / "yes" / silence → accept; or name an alternative → switch.

1. Context yields no clear default → ask with `AskUserQuestion` (preferred) or its analogue, with the recommended option first and `(Recommended)` appended. Fall back to plain text if no interactive tool is available.

1. Context is fully empty for a critical input → ask plainly.

This applies to: which entity, which DTO (when neither was mentioned), the user's intent itself.

How to ask — prefer AskUserQuestion

When a question must be asked, prefer the `AskUserQuestion` tool (or its analogue) over writing a numbered list in the response body. Fall back to plain text only if no interactive choice tool is available.

Rules for AskUserQuestion calls in this skill:

• Each call may contain up to 4 questions that are independent of each

other (the tool will render them together). Use this to batch related decisions in one round-trip.

• Each question has 2–4 options. The tool auto-adds an "Other" choice

for free-form input — never include it manually.

• Mark the recommended option by putting it first with (Recommended)

appended to the label.

• header is a 12-char chip label (e.g. "Mapper", "Methods", "Package").
• Each option has a description explaining what the choice means.

When AskUserQuestion is not the right tool:

• Free-form input where there is no enumerable set of options

(e.g. arbitrary class name) — ask in plain text.

• The "single confirmation line" form from principle 2 — that is a plain

yes/no, not an enumerated choice.

The screen-driven question lists in Steps 2–3 below are a fallback for case 4. They are NOT a script to execute top-to-bottom. If a question's answer is already determined by principles 1–3, skip the question.

Step 1 -- Gather minimal project context (automatic, no questions)

Call only the MCP tools whose result is actually consumed by a later step. Do not pre-fetch "in case we need it" — every variable here must have a concrete downstream user.

That is the entire Step 1. Do NOT fetch:

• Spring Boot version — no branching depends on it
• application.properties path — Step 5 writes nothing to properties
• mainPackage — Step 4 derives the mapper package from the DTO's

package, not from the project root

• get_entity_details / list_class_members — these depend on knowing

the entity and DTO, which happens in Step 2. Defer them to Step 2.

• list_entity_mappers — needed only at Step 13 of the MapStruct

reference (uses = {...} resolution) and only per association entity, which is unknown until entityDetails is fetched. Defer to Step 13, do NOT pre-fetch in Step 1.

If multi-module project (multiple modules in get_project_summary): Ask which module to use. Then re-call list_module_dependencies for that module.

componentModel — simplified

Determine componentModel from presentDeps:

• Spring (any spring-boot-starter* or spring-context) → SPRING
• Otherwise → DEFAULT

CDI is intentionally not auto-detected. If the user has a CDI project and wants componentModel = "cdi", they will say so explicitly; the skill should not branch on it by default.

Step 2 -- Entity and DTO

By Step 0 you should already know entity and DTO if the user mentioned them. Most common cases:

• User wrote "create a mapper for Order to OrderDto" → both known, skip

the questions, go straight to the parallel fetch below.

• `dto-creator` just delegated → entity and DTO are passed in by the

delegating skill. Never ask, never re-derive.

• User wrote "create a mapper for Order" → entity is Order. The DTO

is the most recently created/discussed DTO for that entity in this conversation, OR — if there are multiple candidates — call list_entity_dtos(orderFqn) and pick the unique one. Only ask if there are multiple and no other signal.

Ask only when context is genuinely empty. When asking, prefer plain text (entity/DTO names are free-form input — AskUserQuestion is the wrong tool here):

Which entity should I create a mapper for? And which DTO to map to?