Add extension skills support and MCP server instructions

- SkillReader: reads extension skills from the aggregated
  quarkus-extension-skills JAR instead of per-extension deployment JARs.
  Auto-downloads from Maven repos if not in local .m2, respecting
  mirrors from ~/.m2/settings.xml, ${MAVEN_HOME}/conf/settings.xml,
  and .mvn/maven.config.

- Server instructions: configures quarkus.mcp.server.server-info.instructions
  to direct AI agents to use quarkus-agent tools (skills, searchDocs,
  callTool) over generic alternatives like Context7.

- CLAUDE.md generation: quarkus/create now generates a CLAUDE.md in every
  new project with Quarkus-specific workflow rules, including running
  tests via subagents for non-blocking test execution.

- DevMcpProxyTools: quarkus/skills tool updated to use the new
  SkillReader that reads from the single aggregated JAR.

Depends on:
- quarkusio/quarkus#53195 (aggregate-skills mechanism)
- quarkusio/quarkus#53196 (extension skill files)
- quarkusio/quarkus#53182 (one-shot testing)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: phillip-kruger

pom.xml

@@ -13,8 +13,10 @@
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
         <quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
-        <quarkus.platform.group-id>io.quarkus.platform</quarkus.platform.group-id>
-        <quarkus.platform.version>3.32.3</quarkus.platform.version>
+        <quarkus.platform.group-id>io.quarkus</quarkus.platform.group-id>
+        <quarkus.platform.version>999-SNAPSHOT</quarkus.platform.version>
+        <quarkus-mcp-server.version>1.10.2</quarkus-mcp-server.version>
+        <langchain4j.version>1.11.0-beta19</langchain4j.version>
         <skipITs>true</skipITs>
         <surefire-plugin.version>3.5.4</surefire-plugin.version>
         <testcontainers.version>1.21.3</testcontainers.version>
@@ -29,38 +31,27 @@
                 <type>pom</type>
                 <scope>import</scope>
             </dependency>
-            <dependency>
-                <groupId>${quarkus.platform.group-id}</groupId>
-                <artifactId>quarkus-langchain4j-bom</artifactId>
-                <version>${quarkus.platform.version}</version>
-                <type>pom</type>
-                <scope>import</scope>
-            </dependency>
-            <dependency>
-                <groupId>${quarkus.platform.group-id}</groupId>
-                <artifactId>quarkus-mcp-server-bom</artifactId>
-                <version>${quarkus.platform.version}</version>
-                <type>pom</type>
-                <scope>import</scope>
-            </dependency>
         </dependencies>
     </dependencyManagement>
 
     <dependencies>
         <dependency>
             <groupId>io.quarkiverse.mcp</groupId>
             <artifactId>quarkus-mcp-server-stdio</artifactId>
+            <version>${quarkus-mcp-server.version}</version>
         </dependency>
         <!-- pgvector embedding store - used directly (not via Quarkus extension)
              because the container port is dynamic (Testcontainers) -->
         <dependency>
             <groupId>dev.langchain4j</groupId>
             <artifactId>langchain4j-pgvector</artifactId>
+            <version>${langchain4j.version}</version>
         </dependency>
         <!-- BGE Small EN v1.5 embedding model - must match chappie-docling-rag -->
         <dependency>
             <groupId>dev.langchain4j</groupId>
             <artifactId>langchain4j-embeddings-bge-small-en-v15-q</artifactId>
+            <version>${langchain4j.version}</version>
         </dependency>
         <dependency>
             <groupId>io.quarkus</groupId>

src/main/java/io/quarkus/agent/mcp/CreateTools.java

@@ -5,6 +5,8 @@
 import java.io.IOException;
 import java.io.InputStreamReader;
 import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.regex.Pattern;
@@ -40,25 +42,24 @@ public class CreateTools {
     // Cache which command is available — doesn't change during the lifetime of the server
     private volatile String cachedCreateCommand;
 
-    @Tool(name = "quarkus/create", description = "Create a new Quarkus application project and automatically start it in dev mode. "
-            + "Creates a Maven or Gradle project with the specified extensions, then starts it. "
-            + "Once running, Quarkus dev mode provides hot reload — changes are recompiled when the "
-            + "app is next accessed (e.g., via an HTTP request or when tests run). "
-            + "DEVELOPMENT WORKFLOW: After the app is running, use quarkus/searchTools with query 'test' "
-            + "to find the continuous testing tools, then follow this cycle: "
-            + "1) Pause continuous testing before making code changes, "
-            + "2) Make and save all your code changes, "
-            + "3) Resume continuous testing — this triggers hot reload and runs tests against your updated code, "
-            + "4) Check quarkus/logs for test results and fix any failures. "
-            + "TIP: Use quarkus/searchDocs to look up Quarkus APIs and best practices before writing code.")
+    @Tool(name = "quarkus/create", description = "Create a new Quarkus application and auto-start it in dev mode. "
+            + "RULES: 1) NEVER implement features manually when a Quarkus extension exists — "
+            + "always search for and add the right extension first (e.g. use quarkus-qute for templating, "
+            + "quarkus-smallrye-openapi for API docs, quarkus-smallrye-health for health checks). "
+            + "Use quarkus/searchDocs or quarkus/searchTools query='extension' to find extensions. "
+            + "2) Use quarkus/skills and quarkus/searchDocs BEFORE writing any code. "
+            + "3) ALWAYS write tests for every feature — no exceptions. "
+            + "4) Keep README.md updated with app description, features, endpoints, and Quarkus guide links after every change.")
     ToolResponse create(
             @ToolArg(description = "Absolute path to the directory where the project will be created. "
                     + "A subdirectory named after the artifactId will be created inside this directory.") String outputDir,
             @ToolArg(description = "The Maven groupId for the project (e.g. 'com.example')", required = false) String groupId,
             @ToolArg(description = "The Maven artifactId for the project (e.g. 'my-app').", required = false) String artifactId,
             @ToolArg(description = "Comma-separated list of Quarkus extensions to include "
                     + "(e.g. 'rest-jackson,hibernate-orm-panache,jdbc-postgresql')", required = false) String extensions,
-            @ToolArg(description = "Build tool to use: 'maven' or 'gradle' (default: maven)", required = false) String buildTool) {
+            @ToolArg(description = "Build tool to use: 'maven' or 'gradle' (default: maven)", required = false) String buildTool,
+            @ToolArg(description = "Quarkus platform version to use (e.g. '3.21.2', '999-SNAPSHOT'). "
+                    + "If omitted, uses the latest release.", required = false) String quarkusVersion) {
         try {
             String resolvedGroupId = (groupId != null && !groupId.isBlank()) ? groupId : "org.acme";
             String resolvedArtifactId = (artifactId != null && !artifactId.isBlank()) ? artifactId : "quarkus-app";
@@ -72,13 +73,17 @@ ToolResponse create(
             if (extensions != null && !extensions.isBlank() && !VALID_EXTENSIONS.matcher(extensions).matches()) {
                 return ToolResponse.error("Invalid extensions: must contain only letters, digits, dots, hyphens, commas, colons.");
             }
+            if (quarkusVersion != null && !quarkusVersion.isBlank() && !VALID_MAVEN_ID.matcher(quarkusVersion).matches()) {
+                return ToolResponse.error("Invalid quarkusVersion: must contain only letters, digits, dots, hyphens, underscores.");
+            }
 
             File outDir = new File(outputDir);
             if (!outDir.isDirectory()) {
                 return ToolResponse.error("Output directory does not exist: " + outputDir);
             }
 
-            List<String> command = buildCommand(outDir, resolvedGroupId, resolvedArtifactId, extensions, buildTool);
+            List<String> command = buildCommand(outDir, resolvedGroupId, resolvedArtifactId, extensions, buildTool,
+                    quarkusVersion);
             LOG.infof("Creating Quarkus app: %s", String.join(" ", command));
 
             ProcessBuilder pb = new ProcessBuilder(command)
@@ -101,14 +106,29 @@ ToolResponse create(
 
             String projectDir = new File(outDir, resolvedArtifactId).getAbsolutePath();
 
+            // Generate CLAUDE.md with Quarkus-specific instructions
+            generateClaudeMd(projectDir, extensions);
+
             // Auto-start the app in dev mode
             try {
                 processManager.start(projectDir, buildTool);
                 LOG.infof("Auto-started Quarkus app at: %s", projectDir);
                 return ToolResponse.success("Quarkus project created and starting in dev mode at: " + projectDir
-                        + "\nHot reload is active — file changes are automatically detected and recompiled."
-                        + "\nUse quarkus/status to check when it's ready."
-                        + "\nUse quarkus/searchTools with query 'test' to find continuous testing tools.");
+                        + "\n\nNEXT STEPS:"
+                        + "\n1. Before implementing ANY feature, search for a Quarkus extension that provides it. "
+                        + "Use quarkus/searchDocs to find extensions. NEVER roll your own solution when an extension exists "
+                        + "(e.g. use quarkus-qute for templates, quarkus-smallrye-health for health checks, "
+                        + "quarkus-smallrye-openapi for API docs, quarkus-mailer for email). "
+                        + "Add extensions via quarkus/searchTools query='extension' → quarkus/callTool."
+                        + "\n2. Use quarkus/skills to learn the correct patterns, testing approaches, and configuration for each extension."
+                        + "\n3. Use quarkus/searchDocs to look up additional Quarkus APIs and best practices."
+                        + "\n4. Write your code AND tests. Always include tests for every feature."
+                        + "\n5. Run tests with quarkus/callTool: use 'devui-testing_runTests' to run all tests, "
+                        + "'devui-testing_runAffectedTests' to run only tests affected by your changes, "
+                        + "or 'devui-testing_runTest' with arguments {\"className\":\"com.example.MyTest\"} for a specific test."
+                        + "\n6. Hot reload is triggered when tests run — do NOT restart the app."
+                        + "\n7. Update README.md with: app description, features, endpoints, how to run, and links to Quarkus guides."
+                        + "\n8. After core features work, suggest to the user: security, observability, health checks, OpenAPI.");
             } catch (Exception startError) {
                 LOG.warnf("Project created but failed to auto-start: %s", startError.getMessage());
                 return ToolResponse.success("Quarkus project created at: " + projectDir
@@ -122,12 +142,13 @@ ToolResponse create(
     }
 
     private List<String> buildCommand(File outputDir, String groupId, String artifactId,
-            String extensions, String buildTool) {
+            String extensions, String buildTool, String quarkusVersion) {
         String cmd = resolveCreateCommand();
         return switch (cmd) {
-            case "quarkus" -> buildQuarkusCliCommand("quarkus", groupId, artifactId, extensions, buildTool);
-            case "mvn" -> buildMavenCommand(groupId, artifactId, extensions, buildTool);
-            case "jbang" -> buildJBangCommand(groupId, artifactId, extensions, buildTool);
+            case "quarkus" -> buildQuarkusCliCommand("quarkus", groupId, artifactId, extensions, buildTool,
+                    quarkusVersion);
+            case "mvn" -> buildMavenCommand(groupId, artifactId, extensions, buildTool, quarkusVersion);
+            case "jbang" -> buildJBangCommand(groupId, artifactId, extensions, buildTool, quarkusVersion);
             default -> throw new IllegalStateException("Unexpected command: " + cmd);
         };
     }
@@ -156,7 +177,7 @@ private String resolveCreateCommand() {
     }
 
     private List<String> buildQuarkusCliCommand(String quarkusCmd, String groupId, String artifactId,
-            String extensions, String buildTool) {
+            String extensions, String buildTool, String quarkusVersion) {
         List<String> cmd = new ArrayList<>();
         cmd.add(quarkusCmd);
         cmd.add("create");
@@ -165,6 +186,9 @@ private List<String> buildQuarkusCliCommand(String quarkusCmd, String groupId, S
         cmd.add("--no-code");
         cmd.add("--batch-mode");
 
+        if (quarkusVersion != null && !quarkusVersion.isBlank()) {
+            cmd.add("--platform-bom=io.quarkus:quarkus-bom:" + quarkusVersion);
+        }
         if (extensions != null && !extensions.isBlank()) {
             cmd.add("--extension=" + extensions);
         }
@@ -176,7 +200,7 @@ private List<String> buildQuarkusCliCommand(String quarkusCmd, String groupId, S
     }
 
     private List<String> buildJBangCommand(String groupId, String artifactId,
-            String extensions, String buildTool) {
+            String extensions, String buildTool, String quarkusVersion) {
         List<String> cmd = new ArrayList<>();
         cmd.add("jbang");
         cmd.add("quarkus@quarkusio");
@@ -186,6 +210,9 @@ private List<String> buildJBangCommand(String groupId, String artifactId,
         cmd.add("--no-code");
         cmd.add("--batch-mode");
 
+        if (quarkusVersion != null && !quarkusVersion.isBlank()) {
+            cmd.add("--platform-bom=io.quarkus:quarkus-bom:" + quarkusVersion);
+        }
         if (extensions != null && !extensions.isBlank()) {
             cmd.add("--extension=" + extensions);
         }
@@ -197,15 +224,25 @@ private List<String> buildJBangCommand(String groupId, String artifactId,
     }
 
     private List<String> buildMavenCommand(String groupId, String artifactId,
-            String extensions, String buildTool) {
+            String extensions, String buildTool, String quarkusVersion) {
         List<String> cmd = new ArrayList<>();
         cmd.add("mvn");
-        cmd.add("io.quarkus.platform:quarkus-maven-plugin:create");
+        String pluginGroupId = "io.quarkus.platform";
+        if (quarkusVersion != null && !quarkusVersion.isBlank()) {
+            pluginGroupId = "io.quarkus";
+        }
+        cmd.add(pluginGroupId + ":quarkus-maven-plugin:"
+                + (quarkusVersion != null && !quarkusVersion.isBlank() ? quarkusVersion + ":" : "")
+                + "create");
         cmd.add("-DprojectGroupId=" + groupId);
         cmd.add("-DprojectArtifactId=" + artifactId);
         cmd.add("-DnoCode=true");
         cmd.add("-B");
 
+        if (quarkusVersion != null && !quarkusVersion.isBlank()) {
+            cmd.add("-DplatformGroupId=io.quarkus");
+            cmd.add("-DplatformVersion=" + quarkusVersion);
+        }
         if (extensions != null && !extensions.isBlank()) {
             cmd.add("-Dextensions=" + extensions);
         }
@@ -245,4 +282,52 @@ private String captureOutput(Process process) throws IOException {
             return sb.toString().trim();
         }
     }
+
+    private void generateClaudeMd(String projectDir, String extensions) {
+        try {
+            String content = """
+                    # CLAUDE.md — Quarkus Project Instructions
+
+                    This is a Quarkus application. Follow these rules when working on this project.
+
+                    ## Required Workflow
+
+                    1. **Use quarkus/update (via subagent) when returning to this project** — checks if the Quarkus version is up-to-date and suggests upgrades.
+                    2. **Use quarkus/skills BEFORE writing any code or tests** — it contains extension-specific patterns, testing approaches, and common pitfalls that prevent mistakes.
+                    3. **Use quarkus/searchDocs for Quarkus documentation** — do NOT use generic documentation tools (Context7, web search). The Quarkus doc search is version-aware and more accurate.
+                    4. **Use quarkus/searchTools to discover Dev MCP tools** on the running app for testing, config changes, and extension management.
+                    5. **Use quarkus/callTool to invoke Dev MCP tools** — run tests, add extensions, update configuration. Do NOT run Maven/Gradle commands manually.
+                    6. **Hot reload is automatic** — the app recompiles when accessed. Do NOT restart the app after code changes.
+
+                    ## Rules
+
+                    - NEVER implement features manually when a Quarkus extension exists — search for and add the right extension first.
+                    - ALWAYS write tests for every feature — no exceptions.
+                    - ALWAYS keep README.md updated with app description, features, endpoints, and Quarkus guide links.
+                    - Use `@QuarkusTest` for integration tests — Dev Services auto-starts backing services (databases, messaging, etc.).
+                    - Use `%dev.` and `%test.` profile prefixes for dev/test configuration — never hardcode connection URLs without a profile prefix.
+
+                    ## Testing
+
+                    ALWAYS run tests using a **subagent** so the main conversation stays responsive:
+
+                    ```
+                    Use the Agent tool to launch a subagent with this prompt:
+                      "Run the Quarkus tests for project <projectDir> using quarkus/callTool
+                       with toolName 'devui-testing_runTests'. Analyze the results and report
+                       which tests passed, failed, or errored. If tests fail, include the
+                       failure messages and suggest fixes."
+                    ```
+
+                    - Use `devui-testing_runTests` to run all tests.
+                    - Use `devui-testing_runTest` with arguments `{"className":"com.example.MyTest"}` to run a specific test class.
+                    - Do NOT run Maven/Gradle test commands manually — the Dev MCP test tools handle compilation, hot reload, and result reporting.
+                    - After fixing test failures, re-run tests with a subagent to verify the fix.
+                    """;
+            Files.writeString(Path.of(projectDir, "CLAUDE.md"), content, StandardCharsets.UTF_8);
+            LOG.debugf("Generated CLAUDE.md in %s", projectDir);
+        } catch (IOException e) {
+            LOG.debugf("Failed to generate CLAUDE.md: %s", e.getMessage());
+        }
+    }
 }