amplicode/spring-skills/spring-explore

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."

Explore Application

Collects primary project context in steps 0–6. Execute steps sequentially — each one builds on the results of the previous.

Important: if context has already been collected in the current conversation, do not repeat the exploration — use what is already known.

Step 0 — Predict involvement from the user's request

Tell the user: Step 0/6: Analyzing request...

Do NOT call any tools in this step.

Read the user's request and reason about what the implementation likely involves. Without calling any tools, make educated guesses based on naming conventions, domain language, and typical Spring Boot patterns:

• Entities — what domain objects are likely involved? (e.g. "create order" → Order, OrderItem)
• Repositories — which repositories probably exist for those entities?
• Services — what service classes are likely needed?
• Controllers — what REST controllers probably handle this area?
• Other beans/components — mappers, validators, event listeners, configs, etc.
• Files — what non-Java files are likely relevant? (e.g. DB migration scripts, application.properties, Liquibase changelogs, HTML templates). Do not list Java classes here — they belong to the categories above.

Build a preliminary gap list containing only what is genuinely required:

### Predicted involvement:
- Entities: Order, OrderItem, Customer
- Repositories: OrderRepository, CustomerRepository
- Services: OrderService
- Controllers: OrderController
- Other: OrderMapper
- Files: src/main/resources/db/migration/V1__create_orders.sql, application.properties

This prediction drives steps 1–5 — skip anything irrelevant to the task.

Step 1 — Define exploration goal and select paths

Tell the user: Step 1/6: Selecting exploration paths...

Do NOT call any tools in this step.

Read the current conversation context — the user's request, any prior exploration results, remaining gaps — and formulate the key exploration goal in one sentence. Show it to the user:

### Exploration goal:
Understand the Order aggregate structure and verify what repositories and mappers already exist.

Using this goal, go through each exploration path below and explicitly decide: include or skip, with a one-line reason. Do this for every path — do not skip the evaluation itself.

Project structure

• Fetch project summary — include if the tech stack, Spring Boot version, or module structure are needed. Skip if the task is narrowly scoped to specific classes.
• Detect persistence stack — include if any entity-touching path below is selected AND the stack (JPA vs JDBC) is not yet known from the conversation. Call list_module_dependencies: dependency on spring-boot-starter-data-jpa / hibernate → JPA; spring-boot-starter-data-jdbc / spring-data-jdbc → JDBC; neither → no supported persistence layer, skip entity-touching paths.
• List domain entities — include ONLY if the domain area is completely unknown and you cannot predict which entities are involved. If entities are already named in the request or predictable from context — skip. Do NOT use to get entity structure or resolve FQNs.
• List REST endpoints — include only if you need to check what already exists to avoid duplication or understand conventions. Skip if the request fully defines all endpoints from scratch.

Domain model

• Get entity description — include if entity fields or annotations are needed. Apply only to predicted entities, not all entities. Route by stack: JPA → get_entity_details, see `references/entity-description.md`; JDBC → get_jdbc_entity_details, see `references/entity-description-jdbc.md`.
• Get deep model from entity — include if relationships across multiple entities need to be traversed (e.g. nested resources, cascades). JPA only — for JDBC get_jdbc_entity_details already returns the full owned-children tree (aggregates) and inverse links (referencedBy); use the DDD path below instead. See `references/deep-model-based-on-jpa.md`.
• Get DDD model from entity — include if aggregate boundaries matter (e.g. URL design, cascade planning, DTO shaping). JPA: follow `references/ddd-model-based-on-jpa.md`. JDBC: call get_jdbc_entity_details and read aggregateRootFqn, aggregates, referencedBy directly — Spring Data JDBC enforces aggregate boundaries at the framework level.

Persistence

• Get entity repositories — include if repositories for predicted entities are unknown or need to be verified. See `references/entity-repositories.md`.
• Get entity components — include if you need a full picture of all components (repositories, services, controllers) for an entity. See `references/entity-components.md`.

Services

• Get entity services — include if services for predicted entities are unknown or need to be verified. See `references/entity-services.md`.

Mappers

• Get entity mappers — include if the task involves DTOs and you need to know what mappers exist. See `references/entity-mappers.md`.

DTOs

• Get entity DTOs — include if you need to know what DTO classes already exist. See `references/entity-dtos.md`.

REST layer

• Get entity controllers — include if you need to find which controllers are associated with an entity. See `references/entity-controllers.md`.

Write out the evaluation explicitly, then produce the final plan from included paths only:

Example — for a request "Add a paginated endpoint returning all orders for a customer with order items and product names":

### Path evaluation:
- Fetch project summary: INCLUDE — need Spring Boot version and module structure
- Detect persistence stack: INCLUDE — entity-touching paths selected and stack unknown from conversation
- List domain entities: SKIP — Order, Customer, OrderItem, Product are predictable from the request
- List REST endpoints: INCLUDE — need to check if an orders endpoint already exists
- Get entity description: INCLUDE — need Order, OrderItem, Product fields for response DTO design
- Get deep model: SKIP — relationship structure is clear: Order → OrderItem → Product
- Get DDD model: SKIP — no cascade planning needed, just a read endpoint
- Get entity repositories: INCLUDE — need to verify OrderRepository exists and supports pagination
- Get entity components: SKIP — repositories are sufficient, no need for full component chain
- Get entity services: SKIP — no service layer changes expected
- Get entity mappers: INCLUDE — need to know if OrderMapper already exists before creating DTOs
- Get entity DTOs: INCLUDE — need to know if OrderDto already exists
- Get entity controllers: SKIP — will check via "List REST endpoints" instead
 
### Exploration plan:
1. Fetch project summary
2. Detect persistence stack
3. List REST endpoints (filter to order-related controllers)
4. Get entity description for Order, OrderItem, Product
5. Get entity repositories for Order
6. Get entity mappers for Order
7. Get entity DTOs for Order

Step 2 — Load references

Tell the user: Step 2/6: Loading relevant references...

Do NOT call any tools in this step.

Based on the exploration plan from step 1, load only the references needed for the selected paths that have not already been loaded in this conversation. After loading, proceed directly to step 3 — do NOT search files, glob, or explore the project structure manually. All project information must be obtained exclusively via MCP tools in steps 3–5.

If none of the paths require references — skip this step and proceed to step 3.

Step 3 — Build unified exploration plan

Tell the user: Step 3/6: Building exploration plan...

Do NOT call any tools in this step.

Using the selected paths from step 1 and the processes described in the loaded references, build a single unified numbered plan of MCP calls to execute in steps 4–5. Each item must be a concrete MCP tool call, not a category name.

### Unified exploration plan:
1. get_project_summary
2. list_project_endpoints
3. list_all_domain_entities (regexPattern=Owner) — resolve FQN
4. get_entity_details (Owner FQN)
5. get_entity_details (Pet FQN)
6. get_entity_details (Visit FQN)
7. list_entity_repositories (Owner FQN)
8. list_entity_repositories (Pet FQN)
9. list_entity_repositories (Visit FQN)

Step 4 — Execute exploration plan via subagent

Tell the user: Step 4/6: Executing exploration plan...

Spawn a subagent and pass it the following instructions:

Execute the exploration plan below by calling each MCP tool in order.
Use MCP tools directly (e.g. get_entity_details, list_entity_repositories).
 
Collect and return ALL results in full — do not summarize or truncate.
 
Secret redaction: if any returned value belongs to a key that looks like a credential
(`password`, `passwd`, `secret`, `token`, `api-key`, `apikey`, `access-key`, `private-key`,
`credentials`, `client-secret`, `auth`, or similar), replace only the value with `[REDACTED]`
and keep the key and surrounding structure intact. Never echo credential values verbatim.
 
Plan:
<paste the numbered plan from step 3 here>

Wait for the subagent to complete and collect all results before proceeding.