Switching to xml for 110

Author: jabrena

.cursor/rules/110-java-maven-best-practices.md

@@ -37,7 +37,6 @@ Before applying Maven best practices recommendations, ensure the project is in a
 
 - **MANDATORY**: Run `./mvnw validate` or `mvn validate` before applying any Maven best practices recommendations
 - **VERIFY**: Ensure all validation errors are resolved before proceeding with POM modifications
-- **PREREQUISITE**: Project must compile and pass basic validation checks before optimization
 - **SAFETY**: If validation fails, not continue and ask the user to fix the issues before continuing
 - **MULTI-MODULE DISCOVERY**: After reading the root `pom.xml`, check whether it contains a `<modules>` section. If it does, read every child module's `pom.xml` before making any recommendations — analysis scope is the full module tree, not only the root
 - **CROSS-MODULE SCOPE**: When child modules exist, check each one for: hardcoded dependency versions that duplicate `<dependencyManagement>` in the parent, plugin configurations that duplicate `<pluginManagement>`, properties that should be centralized in the parent, and version drift (same artifact declared at different versions across sibling modules)

skills-generator/src/main/java/info/jab/pml/SkillsGenerator.java

@@ -1,10 +1,17 @@
 package info.jab.pml;
 
 import java.io.InputStream;
+import java.io.StringWriter;
 import java.util.Optional;
 import java.util.stream.Stream;
 import javax.xml.parsers.DocumentBuilder;
 import javax.xml.parsers.DocumentBuilderFactory;
+import javax.xml.transform.Transformer;
+import javax.xml.transform.TransformerFactory;
+import javax.xml.transform.stream.StreamResult;
+import javax.xml.transform.stream.StreamSource;
+import javax.xml.validation.Schema;
+import javax.xml.validation.SchemaFactory;
 import org.w3c.dom.Document;
 import org.w3c.dom.Element;
 import org.w3c.dom.NodeList;
@@ -36,7 +43,7 @@ public SkillsGenerator() {
      */
     public Stream<SkillOutput> generateAllSkills() {
         return SkillsInventory.skillDescriptors()
-            .map(d -> generateSkill(d.skillId(), d.requiresSystemPrompt()));
+            .map(d -> generateSkill(d.skillId(), d.requiresSystemPrompt(), d.useXml()));
     }
 
     /**
@@ -47,7 +54,7 @@ public Stream<SkillOutput> generateAllSkills() {
      * @throws RuntimeException if resources cannot be loaded or generation fails
      */
     public SkillOutput generateSkill(String skillId) {
-        return generateSkill(skillId, true);
+        return generateSkill(skillId, true, false);
     }
 
     /**
@@ -58,10 +65,24 @@ public SkillOutput generateSkill(String skillId) {
      * @return the generated skill output
      */
     public SkillOutput generateSkill(String skillId, boolean requiresSystemPrompt) {
+        return generateSkill(skillId, requiresSystemPrompt, false);
+    }
+
+    /**
+     * Generates SKILL.md and reference content for a given skill.
+     *
+     * @param skillId the skill identifier (e.g. 110-java-maven-best-practices)
+     * @param requiresSystemPrompt when false, skips system-prompt XML and reference generation
+     * @param useXml when true, loads skill from skills/{numericId}-skill.xml, validates against schema, transforms via XSLT
+     * @return the generated skill output
+     */
+    public SkillOutput generateSkill(String skillId, boolean requiresSystemPrompt, boolean useXml) {
         String referenceContent = requiresSystemPrompt
             ? generateReferenceContent(skillId, parseMetadata(skillId))
             : "";
-        String skillMdContent = loadSkillSummary(skillId);
+        String skillMdContent = useXml
+            ? loadSkillSummaryFromXml(skillId)
+            : loadSkillSummary(skillId);
         return new SkillOutput(skillId, skillMdContent, referenceContent);
     }
 
@@ -146,6 +167,49 @@ private String loadSkillSummary(String skillId) {
         }
     }
 
+    private String loadSkillSummaryFromXml(String skillId) {
+        String numericId = extractNumericId(skillId);
+        String xmlResource = "skills/" + numericId + "-skill.xml";
+        String xsltResource = "schemas/skill-to-markdown.xslt";
+        String schemaResource = "schemas/skill.xsd";
+        try (
+            InputStream xmlStream = getResource(xmlResource);
+            InputStream xsltStream = getResource(xsltResource);
+            InputStream schemaStream = getResource(schemaResource)
+        ) {
+            if (xmlStream == null) {
+                throw new RuntimeException("Skill XML not found: " + xmlResource);
+            }
+            if (xsltStream == null) {
+                throw new RuntimeException("XSLT not found: " + xsltResource);
+            }
+            if (schemaStream == null) {
+                throw new RuntimeException("Schema not found: " + schemaResource);
+            }
+            SchemaFactory factory = SchemaFactory.newInstance(javax.xml.XMLConstants.W3C_XML_SCHEMA_NS_URI);
+            Schema schema = factory.newSchema(new StreamSource(schemaStream));
+            DocumentBuilderFactory docFactory = DocumentBuilderFactory.newInstance();
+            docFactory.setSchema(schema);
+            docFactory.setNamespaceAware(true);
+            DocumentBuilder builder = docFactory.newDocumentBuilder();
+            builder.parse(xmlStream);
+
+            TransformerFactory tf = TransformerFactory.newInstance();
+            Transformer transformer = tf.newTransformer(new StreamSource(xsltStream));
+            StringWriter writer = new StringWriter();
+            try (InputStream xmlStreamForTransform = getResource(xmlResource)) {
+                if (xmlStreamForTransform == null) {
+                    throw new RuntimeException("Skill XML not found: " + xmlResource);
+                }
+                transformer.transform(new StreamSource(xmlStreamForTransform), new StreamResult(writer));
+            }
+            String content = writer.toString();
+            return appendProjectTagToDescription(content);
+        } catch (Exception e) {
+            throw new RuntimeException("Failed to load and transform skill XML: " + xmlResource, e);
+        }
+    }
+
     private String appendProjectTagToDescription(String content) {
         boolean hasLicense = content.contains("license:");
         return content.lines()

skills-generator/src/main/java/info/jab/pml/SkillsInventory.java

@@ -46,7 +46,7 @@ public static Stream<String> skillIds() {
 
         for (InventoryEntry entry : entries) {
             String numericId = entry.numericId();
-            validateSkillSummaryExists(numericId);
+            validateSkillSummaryExists(numericId, entry.useXml());
             String skillId = entry.requiresSystemPrompt()
                 ? resolveSkillIdFromPrefix(Integer.parseInt(numericId))
                 : entry.skillId();
@@ -57,26 +57,26 @@ public static Stream<String> skillIds() {
     }
 
     /**
-     * Returns skill descriptors (skillId + requiresSystemPrompt) for generator use.
+     * Returns skill descriptors (skillId + requiresSystemPrompt + useXml) for generator use.
      */
     public static Stream<SkillDescriptor> skillDescriptors() {
         List<InventoryEntry> entries = loadInventory();
         List<SkillDescriptor> descriptors = new ArrayList<>();
         for (InventoryEntry entry : entries) {
             String numericId = entry.numericId();
-            validateSkillSummaryExists(numericId);
+            validateSkillSummaryExists(numericId, entry.useXml());
             String skillId = entry.requiresSystemPrompt()
                 ? resolveSkillIdFromPrefix(Integer.parseInt(numericId))
                 : entry.skillId();
-            descriptors.add(new SkillDescriptor(skillId, entry.requiresSystemPrompt()));
+            descriptors.add(new SkillDescriptor(skillId, entry.requiresSystemPrompt(), entry.useXml()));
         }
         return descriptors.stream();
     }
 
     /**
-     * Skill ID and whether it requires a system prompt for reference generation.
+     * Skill ID, whether it requires a system prompt for reference generation, and whether to use XML source.
      */
-    public record SkillDescriptor(String skillId, boolean requiresSystemPrompt) {}
+    public record SkillDescriptor(String skillId, boolean requiresSystemPrompt, boolean useXml) {}
 
     /**
      * Resolves skillId by finding the system-prompt XML that starts with {@code {id}-}.
@@ -186,20 +186,39 @@ private static List<InventoryEntry> parseInventory(String json) {
                     throw new RuntimeException("Entry with id " + numericId
                         + " has requiresSystemPrompt=false but no skillId specified.");
                 }
-                entries.add(new InventoryEntry(numericId, requiresSystemPrompt, skillId));
+                boolean useXml = parseXmlFlag(node);
+                entries.add(new InventoryEntry(numericId, requiresSystemPrompt, skillId, useXml));
             }
             return entries;
         } catch (Exception e) {
             throw new RuntimeException("Failed to parse skill inventory", e);
         }
     }
 
-    private static void validateSkillSummaryExists(String numericId) {
-        String resourceName = "skills/" + numericId + "-skill.md";
+    private static boolean parseXmlFlag(JsonNode node) {
+        if (!node.has("xml")) {
+            return false;
+        }
+        JsonNode xmlNode = node.get("xml");
+        if (xmlNode.isBoolean()) {
+            return xmlNode.asBoolean();
+        }
+        if (xmlNode.isTextual()) {
+            String s = xmlNode.asText().toLowerCase();
+            return "true".equals(s) || "yes".equals(s) || "1".equals(s);
+        }
+        return false;
+    }
+
+    private static void validateSkillSummaryExists(String numericId, boolean useXml) {
+        String resourceName = useXml
+            ? "skills/" + numericId + "-skill.xml"
+            : "skills/" + numericId + "-skill.md";
         try (InputStream stream = getResource(resourceName)) {
             if (stream == null) {
                 throw new RuntimeException("Skill summary not found: " + resourceName
-                    + ". Add skills/" + numericId + "-skill.md for each skill in the inventory.");
+                    + ". Add skills/" + numericId + (useXml ? "-skill.xml" : "-skill.md")
+                    + " for each skill in the inventory.");
             }
         } catch (Exception e) {
             if (e instanceof RuntimeException re) {
@@ -225,6 +244,8 @@ private static InputStream getResource(String name) {
      * Single entry from skill-inventory.json. When requiresSystemPrompt is true,
      * skillId is derived by matching system-prompts with prefix {@code {numericId}-}.
      * When false, skillId must be provided and no system-prompt is required.
+     * When useXml is true, skill summary is loaded from skills/{numericId}-skill.xml
+     * and transformed via schema validation and XSLT; otherwise from skills/{numericId}-skill.md.
      */
-    public record InventoryEntry(String numericId, boolean requiresSystemPrompt, String skillId) {}
+    public record InventoryEntry(String numericId, boolean requiresSystemPrompt, String skillId, boolean useXml) {}
 }

skills-generator/src/main/resources/schemas/skill-to-markdown.xslt

@@ -35,8 +35,9 @@ metadata:
     <xsl:apply-templates select="reference"/>
   </xsl:template>
 
+  <!-- Preserve line breaks: do not use normalize-space() which collapses newlines -->
   <xsl:template match="goal">
-    <xsl:value-of select="normalize-space(.)"/>
+    <xsl:value-of select="."/>
     <xsl:text>
 
 </xsl:text>

skills-generator/src/main/resources/skill-inventory.json

@@ -4,7 +4,7 @@
   {"id": "021", "requiresSystemPrompt": false, "skillId": "021-architecture-functional-requirements-rest"},
   {"id": "030", "requiresSystemPrompt": false, "skillId": "030-architecture-non-functional-requirements"},
   {"id": "040", "requiresSystemPrompt": false, "skillId": "040-planning-enhance-ai-plan-mode"},
-  {"id": 110},
+  {"id": 110, "xml": true},
   {"id": 111},
   {"id": 112},
   {"id": 113},

skills-generator/src/main/resources/skills/110-skill.md

@@ -10,32 +10,29 @@
 
   <title>Maven Best Practices</title>
   <description>Use when you need to review, improve, or troubleshoot a Maven pom.xml file — including dependency management with BOMs, plugin configuration, version centralization, multi-module project structure, build profiles, or any situation where you want to align your Maven setup with industry best practices.</description>
-  <goal>
-    <![CDATA[
-    Improve Maven POM configuration using industry-standard best practices.
+  <goal><![CDATA[
+Improve Maven POM configuration using industry-standard best practices.
 
-Core areas:
-Dependency management via `<dependencyManagement>` and BOMs
-Standard directory layout (`src/main/java`, `src/test/java`)
-Centralized plugin management
-Build profiles for environment-specific settings
-Readable POM structure with version properties
-Explicit repository declaration
-Version centralization
-Multi-module project structure with proper inheritance
-Cross-module version consistency
+**What is covered in this Skill?**
 
-Multi-module scope: After reading the root `pom.xml`, check for a `<modules>` section. If present, read **every** child module's `pom.xml` before making any recommendations.
-Check each child for hardcoded versions that duplicate parent `<dependencyManagement>`, redundant `<pluginManagement>` blocks, properties that should be centralized, and version drift across sibling modules.
-    ]]>
-  </goal>
+- Dependency management via `<dependencyManagement>` and BOMs
+- Standard directory layout (`src/main/java`, `src/test/java`)
+- Centralized plugin management
+- Build profiles for environment-specific settings
+- Readable POM structure with version properties
+- Explicit repository declaration
+- Version centralization
+- Multi-module project structure with proper inheritance
+- Cross-module version consistency
+- Multi-module scope: After reading the root `pom.xml`, check for a `<modules>` section. If present, read **every** child module's `pom.xml` before making any recommendations.
+- Check each child for hardcoded versions that duplicate parent `<dependencyManagement>`, redundant `<pluginManagement>` blocks, properties that should be centralized, and version drift across sibling modules.
+]]></goal>
 
   <constraints>
     <constraints-description>Before applying Maven best practices recommendations, ensure the project is in a valid state by running Maven validation. This helps identify any existing configuration issues that need to be resolved first. For multi-module projects, scope analysis must cover every child module POM — not just the root.</constraints-description>
     <constraint-list>
       <constraint>**MANDATORY**: Run `./mvnw validate` or `mvn validate` before applying any Maven best practices recommendations</constraint>
       <constraint>**VERIFY**: Ensure all validation errors are resolved before proceeding with POM modifications</constraint>
-      <constraint>**PREREQUISITE**: Project must compile and pass basic validation checks before optimization</constraint>
       <constraint>**SAFETY**: If validation fails, do not continue and ask the user to fix the issues before continuing</constraint>
       <constraint><![CDATA[**MULTI-MODULE DISCOVERY**: After reading the root `pom.xml`, check whether it contains a `<modules>` section. If it does, read every child module's `pom.xml` before making any recommendations — analysis scope is the full module tree, not only the root]]></constraint>
       <constraint><![CDATA[**CROSS-MODULE SCOPE**: When child modules exist, check each one for: hardcoded dependency versions that duplicate `<dependencyManagement>` in the parent, plugin configurations that duplicate `<pluginManagement>`, properties that should be centralized in the parent, and version drift (same artifact declared at different versions across sibling modules)]]></constraint>