@mark-gozner/aigile-method 0.4.5

package/core/instructions/java/java.instructions.md

@@ -0,0 +1,67 @@
+---
+description: 'Guidelines for building Java base applications'
+applyTo: '**/*.java'
+---
+
+# Java Development
+
+## General Java Development Practices
+- First, prompt the user if they want to integrate static analysis tools (SonarQube, PMD, Checkstyle)
+  into their project setup. If yes, provide guidance on tool selection and configuration.
+- If the user declines static analysis tools or wants to proceed without them, continue with implementing the Best practices, bug patterns and code smell prevention guidelines outlined below.
+- Address code smells proactively during development rather than accumulating technical debt.
+- Focus on readability, maintainability, and performance when refactoring identified issues.
+- Use IDE / Code editor reported warnings and suggestions to catch common patterns early in development.
+- Always follow SOLID, DRY, KISS, and YAGNI principles.
+- Adhere to OWASP security best practices.
+- Break tasks into the smallest units and solve step by step. 
+
+## Best practices
+
+- **Service Layer Pattern**: All business logic services must have an interface and an implementation. This enforces a clean definition of functionality, improves testability, and makes the codebase easier to understand and maintain. Example: `UserService` (interface) and `UserServiceImpl` (implementation).
+- **Records**: For classes primarily intended to store data (e.g., DTOs, immutable data structures), **Java Records should be used instead of traditional classes**.
+- **Pattern Matching**: Utilize pattern matching for `instanceof` and `switch` expression to simplify conditional logic and type casting.
+- **Type Inference**: Use `var` for local variable declarations to improve readability, but only when the type is explicitly clear from the right-hand side of the expression.
+- **Immutability**: Favor immutable objects. Make classes and fields `final` where possible. Use collections from `List.of()`/`Map.of()` for fixed data. Use `Stream.toList()` to create immutable lists.
+- **Streams and Lambdas**: Use the Streams API and lambda expressions for collection processing. Employ method references (e.g., `stream.map(Foo::toBar)`).
+- **Null Handling**: Avoid returning or accepting `null`. Use `Optional<T>` for possibly-absent values and `Objects` utility methods like `equals()` and `requireNonNull()`.
+
+### Naming Conventions
+
+- Follow Google's Java style guide:
+  - `UpperCamelCase` for class and interface names.
+  - `lowerCamelCase` for method and variable names.
+  - `UPPER_SNAKE_CASE` for constants.
+  - `lowercase` for package names.
+- Use nouns for classes (`UserService`) and verbs for methods (`getUserById`).
+- Avoid abbreviations and Hungarian notation.
+
+### Bug Patterns
+
+| Rule ID | Description                                                 | Example / Notes                                                                                  |
+| ------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `S2095` | Resources should be closed                                  | Use try-with-resources when working with streams, files, sockets, etc.                           |
+| `S1698` | Objects should be compared with `.equals()` instead of `==` | Especially important for Strings and boxed primitives.                                           |
+| `S1905` | Redundant casts should be removed                           | Clean up unnecessary or unsafe casts.                                                            |
+| `S3518` | Conditions should not always evaluate to true or false      | Watch for infinite loops or if-conditions that never change.                                     |
+| `S108`  | Unreachable code should be removed                          | Code after `return`, `throw`, etc., must be cleaned up.                                          |
+
+## Code Smells
+
+| Rule ID | Description                                            | Example / Notes                                                               |
+| ------- | ------------------------------------------------------ | ----------------------------------------------------------------------------- |
+| `S107`  | Methods should not have too many parameters            | Refactor into helper classes or use builder pattern.                          |
+| `S121`  | Duplicated blocks of code should be removed            | Consolidate logic into shared methods.                                        |
+| `S138`  | Methods should not be too long                         | Break complex logic into smaller, testable units.                             |
+| `S3776` | Cognitive complexity should be reduced                 | Simplify nested logic, extract methods, avoid deep `if` trees.                |
+| `S1192` | String literals should not be duplicated               | Replace with constants or enums.                                              |
+| `S1854` | Unused assignments should be removed                   | Avoid dead variables—remove or refactor.                                      |
+| `S109`  | Magic numbers should be replaced with constants        | Improves readability and maintainability.                                     |
+| `S1188` | Catch blocks should not be empty                       | Always log or handle exceptions meaningfully.                                 |
+
+## Build and Verification
+
+- After adding or modifying code, verify the project continues to build successfully.
+- If the project uses Maven, run `mvn clean install`.
+- If the project uses Gradle, run `./gradlew build` (or `gradlew.bat build` on Windows).
+- Ensure all tests pass as part of the build.

package/core/instructions/java/spring-boot.instructions.md

@@ -0,0 +1,122 @@
+---
+description: 'Guidelines for building Spring Boot base applications'
+applyTo: '**/*.java, **/*.kt'
+---
+
+# Spring Boot Development
+
+## General Spring Boot Instructions
+
+- Make only high confidence suggestions when reviewing code changes.
+- Write code with good maintainability practices, including comments on why certain design decisions were made.
+- Handle edge cases and write clear exception handling.
+- For libraries or external dependencies, mention their usage and purpose in comments.
+
+### Dependency Injection
+
+- Use constructor injection for all required dependencies.
+- Declare dependency fields as `private final`.
+
+### Configuration
+
+- Use YAML files (`application.yml`) for externalized configuration.
+- Environment Profiles: Use Spring profiles for different environments (dev, test, prod)
+- Configuration Properties: Use @ConfigurationProperties for type-safe configuration binding
+- Secrets Management: Externalize secrets using environment variables or secret management systems
+
+### Code Organization
+
+- Package Structure: Organize by feature/domain rather than by layer
+- Separation of Concerns: Keep controllers thin, services focused, and repositories simple
+- Utility Classes: Make utility classes final with private constructors
+
+## Spring Boot Project Structure
+
+- Use Java Spring Boot 3 (Maven, Java 21, Spring Web, Spring Data JPA, Lombok).
+- RestControllers handle all request/response logic.
+- ServiceImpl classes handle all database operation logic using Repository methods.
+- RestControllers must not autowire Repositories directly unless absolutely necessary.
+- ServiceImpl classes must not query the database directly (use Repositories).
+- Use DTOs for data transfer between RestControllers and ServiceImpl classes.
+- Entity classes are only for carrying data from database queries.
+-
+
+### RestController Conventions
+
+- Annotate with @RestController and specify class-level @RequestMapping.
+- Use best-practice HTTP method annotations (e.g., @PostMapping, @GetMapping).
+- Autowire dependencies in class methods without constructors unless specified.
+- Methods return ResponseEntity<ApiResponse>.
+- Implement all logic in try-catch blocks; handle errors with GlobalExceptionHandler.
+
+### ApiResponse & GlobalExceptionHandler
+
+- ApiResponse and GlobalExceptionHandler classes must be present and follow best practices for structure and error handling.
+
+### Service Layer
+
+- Place business logic in `@Service`-annotated classes.
+- Services should be stateless and testable.
+- Inject repositories via the constructor.
+- Service method signatures should use domain IDs or DTOs, not expose repository entities directly unless necessary.
+- Service classes are interfaces; implementations are ServiceImpl classes annotated with @Service.
+- Use Lombok's `@RequiredArgsConstructor` for constructor-based dependency injection in ServiceImpl classes. Declare all dependencies as `private final` fields.
+- ServiceImpl methods return DTOs (not entities) unless necessary.
+- Use repository methods with .orElseThrow for existence checks.
+- Use @Transactional or transactionTemplate for multiple sequential DB operations.
+
+### Repository Class Conventions
+
+- Annotate with @Repository.
+- Use interfaces extending JpaRepository<Entity, ID>.
+- Use JPQL for @Query methods.
+- Use @EntityGraph(attributePaths={...}) to avoid N+1 problems in relationship queries.
+- Use DTOs for multi-join queries with @Query.
+
+### Entity Class Conventions
+
+- Annotate with @Entity and @Data (Lombok).
+- Use @Id and @GeneratedValue(strategy=GenerationType.IDENTITY) for IDs.
+- Use FetchType.LAZY for relationships.
+- Annotate properties with validation annotations (e.g., @Size, @NotEmpty, @Email).
+
+### DTO Conventions
+
+- Use Java records for DTOs unless otherwise specified.
+- Include a compact canonical constructor for parameter validation (not null, blank, etc.).
+
+### Entity-DTO Mapping
+
+- Use MapStruct for mapping between JPA entities and domain/API models.
+- Create dedicated mapper interfaces annotated with `@Mapper(componentModel = "spring")` to enable Spring dependency injection.
+- MapStruct mappers should be injected into services via constructor injection.
+- Example: `@Mapper(componentModel = "spring") public interface UserMapper { UserDto toDto(User entity); User toEntity(UserDto dto); }`
+- Avoid manual mapping code in services; delegate all mapping logic to MapStruct mappers.
+
+### Logging
+
+- Use SLF4J for all logging (`private static final Logger logger = LoggerFactory.getLogger(MyClass.class);`).
+- Do not use concrete implementations (Logback, Log4j2) or `System.out.println()` directly.
+- Use parameterized logging: `logger.info("User {} logged in", userId);`.
+
+### Security & Input Handling
+
+- Use parameterized queries | Always use Spring Data JPA or `NamedParameterJdbcTemplate` to prevent SQL injection.
+- Validate request bodies and parameters using JSR-380 (`@NotNull`, `@Size`, etc.) annotations and `BindingResult`
+
+## Build and Verification
+
+- After adding or modifying code, verify the project continues to build successfully.
+- If the project uses Maven, run `mvn clean package`.
+- If the project uses Gradle, run `./gradlew build` (or `gradlew.bat build` on Windows).
+- Ensure all tests pass as part of the build.
+
+## Useful Commands
+
+| Gradle Command             | Maven Command                    | Description                                   |
+|:---------------------------|:---------------------------------|:----------------------------------------------|
+| `./gradlew bootRun`        | `./mvnw spring-boot:run`         | Run the application.                          |
+| `./gradlew build`          | `./mvnw package`                 | Build the application.                        |
+| `./gradlew test`           | `./mvnw test`                    | Run tests.                                    |
+| `./gradlew bootJar`        | `./mvnw spring-boot:repackage`   | Package the application as a JAR.             |
+| `./gradlew bootBuildImage` | `./mvnw spring-boot:build-image` | Package the application as a container image. |

package/core/instructions/java.instructions.md

@@ -0,0 +1,67 @@
+---
+description: 'Guidelines for building Java base applications'
+applyTo: '**/*.java'
+---
+
+# Java Development
+
+## General Java Development Practices
+- First, prompt the user if they want to integrate static analysis tools (SonarQube, PMD, Checkstyle)
+  into their project setup. If yes, provide guidance on tool selection and configuration.
+- If the user declines static analysis tools or wants to proceed without them, continue with implementing the Best practices, bug patterns and code smell prevention guidelines outlined below.
+- Address code smells proactively during development rather than accumulating technical debt.
+- Focus on readability, maintainability, and performance when refactoring identified issues.
+- Use IDE / Code editor reported warnings and suggestions to catch common patterns early in development.
+- Always follow SOLID, DRY, KISS, and YAGNI principles.
+- Adhere to OWASP security best practices.
+- Break tasks into the smallest units and solve step by step. 
+
+## Best practices
+
+- **Service Layer Pattern**: All business logic services must have an interface and an implementation. This enforces a clean definition of functionality, improves testability, and makes the codebase easier to understand and maintain. Example: `UserService` (interface) and `UserServiceImpl` (implementation).
+- **Records**: For classes primarily intended to store data (e.g., DTOs, immutable data structures), **Java Records should be used instead of traditional classes**.
+- **Pattern Matching**: Utilize pattern matching for `instanceof` and `switch` expression to simplify conditional logic and type casting.
+- **Type Inference**: Use `var` for local variable declarations to improve readability, but only when the type is explicitly clear from the right-hand side of the expression.
+- **Immutability**: Favor immutable objects. Make classes and fields `final` where possible. Use collections from `List.of()`/`Map.of()` for fixed data. Use `Stream.toList()` to create immutable lists.
+- **Streams and Lambdas**: Use the Streams API and lambda expressions for collection processing. Employ method references (e.g., `stream.map(Foo::toBar)`).
+- **Null Handling**: Avoid returning or accepting `null`. Use `Optional<T>` for possibly-absent values and `Objects` utility methods like `equals()` and `requireNonNull()`.
+
+### Naming Conventions
+
+- Follow Google's Java style guide:
+  - `UpperCamelCase` for class and interface names.
+  - `lowerCamelCase` for method and variable names.
+  - `UPPER_SNAKE_CASE` for constants.
+  - `lowercase` for package names.
+- Use nouns for classes (`UserService`) and verbs for methods (`getUserById`).
+- Avoid abbreviations and Hungarian notation.
+
+### Bug Patterns
+
+| Rule ID | Description                                                 | Example / Notes                                                                                  |
+| ------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `S2095` | Resources should be closed                                  | Use try-with-resources when working with streams, files, sockets, etc.                           |
+| `S1698` | Objects should be compared with `.equals()` instead of `==` | Especially important for Strings and boxed primitives.                                           |
+| `S1905` | Redundant casts should be removed                           | Clean up unnecessary or unsafe casts.                                                            |
+| `S3518` | Conditions should not always evaluate to true or false      | Watch for infinite loops or if-conditions that never change.                                     |
+| `S108`  | Unreachable code should be removed                          | Code after `return`, `throw`, etc., must be cleaned up.                                          |
+
+## Code Smells
+
+| Rule ID | Description                                            | Example / Notes                                                               |
+| ------- | ------------------------------------------------------ | ----------------------------------------------------------------------------- |
+| `S107`  | Methods should not have too many parameters            | Refactor into helper classes or use builder pattern.                          |
+| `S121`  | Duplicated blocks of code should be removed            | Consolidate logic into shared methods.                                        |
+| `S138`  | Methods should not be too long                         | Break complex logic into smaller, testable units.                             |
+| `S3776` | Cognitive complexity should be reduced                 | Simplify nested logic, extract methods, avoid deep `if` trees.                |
+| `S1192` | String literals should not be duplicated               | Replace with constants or enums.                                              |
+| `S1854` | Unused assignments should be removed                   | Avoid dead variables—remove or refactor.                                      |
+| `S109`  | Magic numbers should be replaced with constants        | Improves readability and maintainability.                                     |
+| `S1188` | Catch blocks should not be empty                       | Always log or handle exceptions meaningfully.                                 |
+
+## Build and Verification
+
+- After adding or modifying code, verify the project continues to build successfully.
+- If the project uses Maven, run `mvn clean install`.
+- If the project uses Gradle, run `./gradlew build` (or `gradlew.bat build` on Windows).
+- Ensure all tests pass as part of the build.

package/core/instructions/spring-boot.instructions.md

@@ -0,0 +1,122 @@
+---
+description: 'Guidelines for building Spring Boot base applications'
+applyTo: '**/*.java, **/*.kt'
+---
+
+# Spring Boot Development
+
+## General Spring Boot Instructions
+
+- Make only high confidence suggestions when reviewing code changes.
+- Write code with good maintainability practices, including comments on why certain design decisions were made.
+- Handle edge cases and write clear exception handling.
+- For libraries or external dependencies, mention their usage and purpose in comments.
+
+### Dependency Injection
+
+- Use constructor injection for all required dependencies.
+- Declare dependency fields as `private final`.
+
+### Configuration
+
+- Use YAML files (`application.yml`) for externalized configuration.
+- Environment Profiles: Use Spring profiles for different environments (dev, test, prod)
+- Configuration Properties: Use @ConfigurationProperties for type-safe configuration binding
+- Secrets Management: Externalize secrets using environment variables or secret management systems
+
+### Code Organization
+
+- Package Structure: Organize by feature/domain rather than by layer
+- Separation of Concerns: Keep controllers thin, services focused, and repositories simple
+- Utility Classes: Make utility classes final with private constructors
+
+## Spring Boot Project Structure
+
+- Use Java Spring Boot 3 (Maven, Java 21, Spring Web, Spring Data JPA, Lombok).
+- RestControllers handle all request/response logic.
+- ServiceImpl classes handle all database operation logic using Repository methods.
+- RestControllers must not autowire Repositories directly unless absolutely necessary.
+- ServiceImpl classes must not query the database directly (use Repositories).
+- Use DTOs for data transfer between RestControllers and ServiceImpl classes.
+- Entity classes are only for carrying data from database queries.
+-
+
+### RestController Conventions
+
+- Annotate with @RestController and specify class-level @RequestMapping.
+- Use best-practice HTTP method annotations (e.g., @PostMapping, @GetMapping).
+- Autowire dependencies in class methods without constructors unless specified.
+- Methods return ResponseEntity<ApiResponse>.
+- Implement all logic in try-catch blocks; handle errors with GlobalExceptionHandler.
+
+### ApiResponse & GlobalExceptionHandler
+
+- ApiResponse and GlobalExceptionHandler classes must be present and follow best practices for structure and error handling.
+
+### Service Layer
+
+- Place business logic in `@Service`-annotated classes.
+- Services should be stateless and testable.
+- Inject repositories via the constructor.
+- Service method signatures should use domain IDs or DTOs, not expose repository entities directly unless necessary.
+- Service classes are interfaces; implementations are ServiceImpl classes annotated with @Service.
+- Use Lombok's `@RequiredArgsConstructor` for constructor-based dependency injection in ServiceImpl classes. Declare all dependencies as `private final` fields.
+- ServiceImpl methods return DTOs (not entities) unless necessary.
+- Use repository methods with .orElseThrow for existence checks.
+- Use @Transactional or transactionTemplate for multiple sequential DB operations.
+
+### Repository Class Conventions
+
+- Annotate with @Repository.
+- Use interfaces extending JpaRepository<Entity, ID>.
+- Use JPQL for @Query methods.
+- Use @EntityGraph(attributePaths={...}) to avoid N+1 problems in relationship queries.
+- Use DTOs for multi-join queries with @Query.
+
+### Entity Class Conventions
+
+- Annotate with @Entity and @Data (Lombok).
+- Use @Id and @GeneratedValue(strategy=GenerationType.IDENTITY) for IDs.
+- Use FetchType.LAZY for relationships.
+- Annotate properties with validation annotations (e.g., @Size, @NotEmpty, @Email).
+
+### DTO Conventions
+
+- Use Java records for DTOs unless otherwise specified.
+- Include a compact canonical constructor for parameter validation (not null, blank, etc.).
+
+### Entity-DTO Mapping
+
+- Use MapStruct for mapping between JPA entities and domain/API models.
+- Create dedicated mapper interfaces annotated with `@Mapper(componentModel = "spring")` to enable Spring dependency injection.
+- MapStruct mappers should be injected into services via constructor injection.
+- Example: `@Mapper(componentModel = "spring") public interface UserMapper { UserDto toDto(User entity); User toEntity(UserDto dto); }`
+- Avoid manual mapping code in services; delegate all mapping logic to MapStruct mappers.
+
+### Logging
+
+- Use SLF4J for all logging (`private static final Logger logger = LoggerFactory.getLogger(MyClass.class);`).
+- Do not use concrete implementations (Logback, Log4j2) or `System.out.println()` directly.
+- Use parameterized logging: `logger.info("User {} logged in", userId);`.
+
+### Security & Input Handling
+
+- Use parameterized queries | Always use Spring Data JPA or `NamedParameterJdbcTemplate` to prevent SQL injection.
+- Validate request bodies and parameters using JSR-380 (`@NotNull`, `@Size`, etc.) annotations and `BindingResult`
+
+## Build and Verification
+
+- After adding or modifying code, verify the project continues to build successfully.
+- If the project uses Maven, run `mvn clean package`.
+- If the project uses Gradle, run `./gradlew build` (or `gradlew.bat build` on Windows).
+- Ensure all tests pass as part of the build.
+
+## Useful Commands
+
+| Gradle Command             | Maven Command                    | Description                                   |
+|:---------------------------|:---------------------------------|:----------------------------------------------|
+| `./gradlew bootRun`        | `./mvnw spring-boot:run`         | Run the application.                          |
+| `./gradlew build`          | `./mvnw package`                 | Build the application.                        |
+| `./gradlew test`           | `./mvnw test`                    | Run tests.                                    |
+| `./gradlew bootJar`        | `./mvnw spring-boot:repackage`   | Package the application as a JAR.             |
+| `./gradlew bootBuildImage` | `./mvnw spring-boot:build-image` | Package the application as a container image. |

package/core/prompts/README.md

@@ -0,0 +1,11 @@
+1. Make sure you have Atlassin MCP set up and connected to your Jira instance via your token.
+2. Ensure that Github MCP is set up and connected to your GitHub account via personal access token.
+3. Change the variables in the prompt files to match your project settings:
+
+````
+{PROJECT_NAME} = your project name
+{JIRA_PROJECT_KEY} = your Jira project key
+````
+
+Place the prompt file (release-notes.prompt.md) in a directory accessible to VS Code and Copilot extension - under `.github/prompts` is recommended.
+Open Copilot extension select 'Agent' mode and type "/release-notes" to trigger the prompt.