feat(skills): Improve structure of any SKILL.md with a defined Workflow (#683)

* feat(skills): Improve structure of any SKILL.md with a defined Workflow

Author: jabrena

skills-generator/src/main/resources/skill-indexes/030-skill.xml

@@ -19,18 +19,8 @@ Generate Architecture Decision Records (ADRs) for Java projects through an inter
 - ADR file storage configuration
 - Conversational information gathering: context, stakeholders, decision drivers, options with pros/cons, outcome, consequences
 - MADR template generation
-- Validation with `./mvnw validate` or `mvn validate` before proceeding
 ]]></goal>
 
-  <constraints>
-    <constraints-description>Before applying any ADR generation, ensure the project validates. If validation fails, stop immediately — do not proceed until all validation errors are resolved.</constraints-description>
-    <constraint-list>
-      <constraint>**MANDATORY**: Run `./mvnw validate` or `mvn validate` before applying any ADR generation</constraint>
-      <constraint>**SAFETY**: If validation fails, stop immediately — do not proceed until all validation errors are resolved</constraint>
-      <constraint>**BEFORE APPLYING**: Read the reference for detailed good/bad examples, constraints, and safeguards for each ADR generation pattern</constraint>
-    </constraint-list>
-  </constraints>
-
   <triggers>
     <trigger-list>
         <trigger>Generate ADR</trigger>
@@ -53,6 +43,21 @@ Generate Architecture Decision Records (ADRs) for Java projects through an inter
     </trigger-list>
   </triggers>
 
+  <steps>
+    <step number="1">
+      <step-title>Read ADR reference and gather context</step-title>
+      <step-content>Read `references/030-architecture-adr-general.md`, then collect context, stakeholders, decision drivers, options, and trade-offs through conversation.</step-content>
+    </step>
+    <step number="2">
+      <step-title>Synthesize and confirm decision</step-title>
+      <step-content>Summarize recommended option, rationale, and consequences, and confirm alignment with the user before creating the ADR artifact.</step-content>
+    </step>
+    <step number="3">
+      <step-title>Generate ADR output</step-title>
+      <step-content>Create a MADR-style ADR document with the final decision, alternatives, consequences, and follow-up actions.</step-content>
+    </step>
+  </steps>
+
   <references>
     <reference-list>
         <reference>references/030-architecture-adr-general.md</reference>

skills-generator/src/main/resources/skill-indexes/031-skill.xml

@@ -44,6 +44,31 @@ Guide stakeholders through a structured conversation to uncover and document tec
     </trigger-list>
   </triggers>
 
+  <steps>
+    <step number="0">
+      <step-title>Get current date</step-title>
+      <step-content>Run `date` before discovery and use it for ADR timestamps.</step-content>
+    </step>
+    <step number="1">
+      <step-title>Read reference and discover surface scope</step-title>
+      <step-content>Read `references/031-architecture-adr-functional-requirements.md`, infer CLI/API scope from project context, and ask a short clarifying question if unclear.</step-content>
+    </step>
+    <step number="2">
+      <step-title>Run conversational discovery</step-title>
+      <step-content>Ask one or two questions at a time to capture context, functional requirements, and technical decisions for CLI, REST API, or both.</step-content>
+      <step-constraints>
+        <step-constraint-list>
+          <step-constraint>Never ask all discovery questions at once</step-constraint>
+          <step-constraint>Validate summary with user before proposing ADR generation</step-constraint>
+        </step-constraint-list>
+      </step-constraints>
+    </step>
+    <step number="3">
+      <step-title>Generate ADR after explicit confirmation</step-title>
+      <step-content>Only after user confirms "proceed", generate the ADR document and provide concise next steps.</step-content>
+    </step>
+  </steps>
+
   <references>
     <reference-list>
         <reference>references/031-architecture-adr-functional-requirements.md</reference>

skills-generator/src/main/resources/skill-indexes/032-skill.xml

@@ -45,6 +45,31 @@ Guide stakeholders through a structured conversation to uncover and document arc
     </trigger-list>
   </triggers>
 
+  <steps>
+    <step number="0">
+      <step-title>Get current date</step-title>
+      <step-content>Run `date` before discovery and use it for ADR timestamps.</step-content>
+    </step>
+    <step number="1">
+      <step-title>Read reference and open with quality challenge</step-title>
+      <step-content>Read `references/032-architecture-adr-non-functional-requirements.md` and begin with the challenge-first ISO 25010:2023 quality characteristics framing.</step-content>
+    </step>
+    <step number="2">
+      <step-title>Run consultative NFR discovery</step-title>
+      <step-content>Ask one or two questions at a time to capture drivers, constraints, quality priorities, options, and trade-off preferences tailored to the primary NFR category.</step-content>
+      <step-constraints>
+        <step-constraint-list>
+          <step-constraint>Never ask all discovery questions at once</step-constraint>
+          <step-constraint>Validate summary with user before proposing ADR generation</step-constraint>
+        </step-constraint-list>
+      </step-constraints>
+    </step>
+    <step number="3">
+      <step-title>Generate ADR after explicit confirmation</step-title>
+      <step-content>Only after user confirms "proceed", create the ADR including measurable Quality Metrics and Success Criteria.</step-content>
+    </step>
+  </steps>
+
   <references>
     <reference-list>
         <reference>references/032-architecture-adr-non-functional-requirements.md</reference>

skills-generator/src/main/resources/skill-indexes/033-skill.xml

@@ -47,6 +47,35 @@ Generate comprehensive Java project diagrams through a modular, step-based inter
     </trigger-list>
   </triggers>
 
+  <steps>
+    <step number="1">
+      <step-title>Validate project state</step-title>
+      <step-content>Run `./mvnw validate` or `mvn validate` before applying any diagram generation.</step-content>
+      <step-constraints>
+        <step-constraint-list>
+          <step-constraint>If validation fails, stop and ask to resolve errors first</step-constraint>
+        </step-constraint-list>
+      </step-constraints>
+    </step>
+    <step number="2">
+      <step-title>Read reference and configure diagram scope</step-title>
+      <step-content>Read `references/033-architecture-diagrams.md`, identify requested diagram types, and confirm output organization strategy (single-file, separate-files, or integrated docs).</step-content>
+    </step>
+    <step number="3">
+      <step-title>Generate PlantUML diagrams</step-title>
+      <step-content>Create requested diagrams in PlantUML syntax (sequence, class, C4 levels 1-3 only, state machine, ER) using project inputs and context.</step-content>
+      <step-constraints>
+        <step-constraint-list>
+          <step-constraint>Never generate C4 Level 4 (Code) diagrams</step-constraint>
+        </step-constraint-list>
+      </step-constraints>
+    </step>
+    <step number="4">
+      <step-title>Validate and finalize outputs</step-title>
+      <step-content>Check generated diagrams for syntax correctness and consistency with selected scope before final delivery.</step-content>
+    </step>
+  </steps>
+
   <references>
     <reference-list>
         <reference>references/033-architecture-diagrams.md</reference>

skills-generator/src/main/resources/skill-indexes/041-skill.xml

@@ -21,7 +21,7 @@ Guide the process of creating a structured plan using Cursor Plan mode. **This i
 - Required sections: Requirements Summary, Approach (with Mermaid), Task List, Execution Instructions, File Checklist, Notes
 - London Style (outside-in) TDD pattern
 - Plan execution discipline: update Status after each task before advancing
-- Plan file path: .cursor/plans/YYYY-MM-DD_<name>.plan.md
+- Plan storage: ask user for preferred folder and filename convention before creating artifact
 ]]></goal>
 
   <constraints>
@@ -32,6 +32,7 @@ Guide the process of creating a structured plan using Cursor Plan mode. **This i
       <constraint>**MUST**: Ask one or two questions at a time; never all at once</constraint>
       <constraint>**MUST**: Validate summary ("Does this capture what you need?") before proposing plan creation</constraint>
       <constraint>**MUST**: Wait for user to confirm "proceed" before generating the plan</constraint>
+      <constraint>**MUST**: Ask the user where they want to store the plan before generating the plan artifact</constraint>
       <constraint>**MUST**: Include Execution Instructions section in every generated plan</constraint>
     </constraint-list>
   </constraints>
@@ -49,6 +50,33 @@ Guide the process of creating a structured plan using Cursor Plan mode. **This i
     </trigger-list>
   </triggers>
 
+  <steps>
+    <step number="0">
+      <step-title>Get current date</step-title>
+      <step-content>Run `date` before planning and use it to derive the plan filename prefix `YYYY-MM-DD`.</step-content>
+    </step>
+    <step number="1">
+      <step-title>Read reference and gather context</step-title>
+      <step-content>Read `references/041-planning-plan-mode.md` and ask one or two questions at a time to clarify requirements, constraints, and target scope.</step-content>
+    </step>
+    <step number="2">
+      <step-title>Validate summary and confirm proceed</step-title>
+      <step-content>Summarize understanding, ask "Does this capture what you need?", and wait for explicit "proceed" before creating the plan artifact.</step-content>
+    </step>
+    <step number="3">
+      <step-title>Confirm plan storage location</step-title>
+      <step-content>Ask where the user wants to store the plan (for example, `.cursor/plans/` or another folder) and confirm the target filename pattern before writing.</step-content>
+    </step>
+    <step number="4">
+      <step-title>Generate structured plan artifact</step-title>
+      <step-content>Create the plan at the confirmed location using required sections and YAML frontmatter, including Execution Instructions.</step-content>
+    </step>
+    <step number="5">
+      <step-title>Apply execution discipline</step-title>
+      <step-content>When executing tasks from the plan, update the Status column after each task before moving to the next one.</step-content>
+    </step>
+  </steps>
+
   <references>
     <reference-list>
         <reference>references/041-planning-plan-mode.md</reference>

skills-generator/src/main/resources/skill-indexes/042-skill.xml

@@ -51,6 +51,29 @@ Guide the process of turning an implementation plan (`*.plan.md`) into an OpenSp
     </trigger-list>
   </triggers>
 
+  <steps>
+    <step number="1">
+      <step-title>Read and summarize plan input</step-title>
+      <step-content>Read the provided `*.plan.md`, summarize scope, and identify candidate change-id and affected capabilities.</step-content>
+    </step>
+    <step number="2">
+      <step-title>Check OpenSpec CLI and install gate</step-title>
+      <step-content>Run `openspec --version`; if missing, provide npm installation guidance for macOS, Linux, and Windows before proceeding.</step-content>
+    </step>
+    <step number="3">
+      <step-title>Initialize or detect OpenSpec project</step-title>
+      <step-content>From the parent directory containing `openspec/`, run project checks and offer `openspec init` (without `--tools`) when initialization is needed.</step-content>
+    </step>
+    <step number="4">
+      <step-title>Create or update change artifacts</step-title>
+      <step-content>Explain whether this is a new or existing change, then create/update proposal, design, tasks, and spec deltas using a stable change-id.</step-content>
+    </step>
+    <step number="5">
+      <step-title>Validate and close workflow</step-title>
+      <step-content>Run `openspec validate --all`; when checklist tasks are complete, guide the user to archive the change with `openspec archive &lt;change-id&gt;`.</step-content>
+    </step>
+  </steps>
+
   <references>
     <reference-list>
       <reference>references/042-planning-openspec.md</reference>

skills-generator/src/main/resources/skill-indexes/043-skill.xml

@@ -30,7 +30,6 @@ Use **`gh`** to work with GitHub issues: **first** run an **interactive** check
       <constraint>**FIRST** (after gate): Verify `gh` is available before issuing subcommands</constraint>
       <constraint>**TABLES**: Prefer `--json` + markdown pipe tables for issue list summaries</constraint>
       <constraint>**THREAD**: For analysis, include body and all comments (or explicitly summarize with omissions noted)</constraint>
-      <constraint>**014**: For user stories from issues, use `@014-agile-user-story` and align answers with GitHub-sourced text</constraint>
     </constraint-list>
   </constraints>
 
@@ -44,6 +43,29 @@ Use **`gh`** to work with GitHub issues: **first** run an **interactive** check
     </trigger-list>
   </triggers>
 
+  <steps>
+    <step number="1">
+      <step-title>Run interactive install gate</step-title>
+      <step-content>Check `gh --version`; if missing, stop and ask whether the user wants installation guidance before any issue operations.</step-content>
+    </step>
+    <step number="2">
+      <step-title>Verify authentication and repository context</step-title>
+      <step-content>Confirm `gh auth status`, authenticate if needed, and establish target repository context via `--repo` or git remote.</step-content>
+    </step>
+    <step number="3">
+      <step-title>List issues and milestones</step-title>
+      <step-content>Retrieve issues (optionally by milestone/state) using `gh issue list --json` and present summaries as markdown pipe tables.</step-content>
+    </step>
+    <step number="4">
+      <step-title>Load full thread for analysis</step-title>
+      <step-content>Read issue body and all comments via `gh issue view --json` or `--comments`, then provide evidence-based analysis.</step-content>
+    </step>
+    <step number="5">
+      <step-title>Chain to user story workflow when requested</step-title>
+      <step-content>When user asks for user stories and Gherkin from issues, hand off to `@014-agile-user-story` using GitHub-sourced content.</step-content>
+    </step>
+  </steps>
+
   <references>
     <reference-list>
         <reference>references/043-planning-github-issues.md</reference>

skills-generator/src/main/resources/skill-indexes/044-skill.xml

@@ -44,6 +44,29 @@ Use **`jira`** to work with Jira issues: **first** run an **interactive** check
     </trigger-list>
   </triggers>
 
+  <steps>
+    <step number="1">
+      <step-title>Run interactive install gate</step-title>
+      <step-content>Check `jira version`; if missing, stop and ask whether the user wants installation guidance before any issue operations.</step-content>
+    </step>
+    <step number="2">
+      <step-title>Verify Jira CLI configuration</step-title>
+      <step-content>Ensure Jira CLI is configured (site/account/token flow via CLI prompts) before running private workspace commands.</step-content>
+    </step>
+    <step number="3">
+      <step-title>List issues with optional JQL</step-title>
+      <step-content>Retrieve issues using basic listing or JQL filters and present summaries as markdown pipe tables.</step-content>
+    </step>
+    <step number="4">
+      <step-title>Load issue details and discussion</step-title>
+      <step-content>Read full issue descriptions and all comments for analysis, explicitly noting any omissions when summarizing.</step-content>
+    </step>
+    <step number="5">
+      <step-title>Execute core Jira actions when requested</step-title>
+      <step-content>Support create, assign, transition, and add-comment actions using CLI commands while avoiding secret exposure.</step-content>
+    </step>
+  </steps>
+
   <references>
     <reference-list>
       <reference>references/044-planning-jira.md</reference>

skills-generator/src/main/resources/skill-indexes/110-skill.xml

@@ -48,6 +48,25 @@ Improve Maven POM configuration using industry-standard best practices.
     </trigger-list>
   </triggers>
 
+  <steps>
+    <step number="1">
+      <step-title>Validate project before recommendations</step-title>
+      <step-content>Run `./mvnw validate` or `mvn validate` and stop if validation fails.</step-content>
+    </step>
+    <step number="2">
+      <step-title>Read reference and analyze root POM</step-title>
+      <step-content>Read `references/110-java-maven-best-practices.md`, then inspect root `pom.xml` structure, dependency management, plugin management, properties, and profiles.</step-content>
+    </step>
+    <step number="3">
+      <step-title>Expand to full module tree when present</step-title>
+      <step-content>If root has a `&lt;modules&gt;` section, read every child `pom.xml` and evaluate cross-module duplication, centralization opportunities, and version drift.</step-content>
+    </step>
+    <step number="4">
+      <step-title>Provide prioritized best-practice recommendations</step-title>
+      <step-content>Propose concrete, safe improvements aligned with Maven best practices and full-module findings.</step-content>
+    </step>
+  </steps>
+
   <references>
     <reference-list>
         <reference>references/110-java-maven-best-practices.md</reference>

skills-generator/src/main/resources/skill-indexes/111-skill.xml

@@ -41,6 +41,25 @@ Add essential Maven dependencies that enhance code quality and safety through a
     </trigger-list>
   </triggers>
 
+  <steps>
+    <step number="1">
+      <step-title>Validate project before changes</step-title>
+      <step-content>Run `./mvnw validate` or `mvn validate` and stop if validation fails.</step-content>
+    </step>
+    <step number="2">
+      <step-title>Read dependency reference and ask guided questions</step-title>
+      <step-content>Read `references/111-java-maven-dependencies.md` and ask one-by-one in strict order: JSpecify, conditional Enhanced Compiler Analysis, VAVR, and ArchUnit.</step-content>
+    </step>
+    <step number="3">
+      <step-title>Add only selected dependencies</step-title>
+      <step-content>Implement only the dependencies and scopes chosen by the user, preserving existing pom.xml structure.</step-content>
+    </step>
+    <step number="4">
+      <step-title>Report trade-offs and next checks</step-title>
+      <step-content>Summarize what was added, why, and any recommended follow-up validations or tooling alignment.</step-content>
+    </step>
+  </steps>
+
   <references>
     <reference-list>
         <reference>references/111-java-maven-dependencies.md</reference>