@relipa/ai-flow-kit 0.0.5 → 0.0.6

package/custom/skills/review-plan/SKILL.md

@@ -20,6 +20,27 @@ keywords: review, code review, approve, summary, checklist
 - ✅ `superpowers:verification-before-completion` has run — tests pass
 - ✅ `impact-analysis` skill has run
 
+## Mode Selection
+
+Check `mode` in `.aiflow/context/current.json`:
+
+| Mode | Impact Analysis | Review Checklist | summary.md |
+|------|----------------|-----------------|-----------|
+| `fast` | Quick scan — reason from diff only | 3 items | Short format |
+| `full` | Full grep scan across codebase | 10 items | Full format |
+
+### Fast Track Impact Analysis (mode: fast)
+Assess impact by reasoning about the changed files only:
+1. List each file you modified
+2. For each file: "Does this file have callers/dependents outside the ticket scope?"
+3. If yes → list them and assign impact level
+4. DO NOT run grep on the full codebase
+
+### Fast Track Review Checklist (mode: fast)
+- [ ] All tests pass
+- [ ] No hardcoded credentials or secrets
+- [ ] No SQL injection risk in new queries
+
 ---
 
 ## Process

package/custom/templates/shared/gate-workflow.md

@@ -1,88 +1,88 @@
-## MANDATORY: Strict Gate Workflow
-
-> **Absolute Rule: Complete Gate N before entering Gate N+1.**
-> **Do not skip, shorten, or merge Gates.**
-
-You have superpowers. When a ticket context exists in `.aiflow/context/current.json`:
-- **Consult the "AI Skill Registry"** below to find instructions for each skill (`SKILL.md`).
-- **AUTO-START Gate 1 immediately** — do NOT wait for the developer to ask.
-- Read instructions and follow the gate sequence below — NO EXCEPTIONS.
-
----
-
-### GATE 1 — AI Analyze Requirement (auto-start)
-
-**INVOKE:** `read-study-requirement` skill
-
-AI actively reads ticket + source code to understand the requirement:
-1. Read `.aiflow/context/current.json` — ticket info
-2. Read source code — architecture, related files, data flow
-3. If anything is unclear — ask ONE question at a time, wait for reply
-4. Output `plan/[ticket-id]/requirement.md` with:
-   - Requirements summary, source code analysis
-   - Proposed solution and approach
-   - Impact analysis, effort estimate, testing plan
-5. Display "GATE 1: Requirement doc ready" → wait for **APPROVED**
-
-> **Tip:** If auto-start doesn't trigger, the developer can start this gate by typing: **"start"**, **"Gate 1"** or **"Analyze ticket"**.
-
-DO NOT just check format — **understand the content and propose solutions**.
-
-> **Telemetry:** Run `aiflow gate 1 start --ticket [ticket-id]` when starting this gate (auto-start or when developer types "start"/"Gate 1").
-> Run `aiflow gate 1 approved --ticket [ticket-id]` immediately when APPROVED is received.
-
----
-
-### GATE 2 — Implementation Plan (wait for APPROVED)
-
-**INVOKE:** `generate-spec` skill, then `superpowers:writing-plans`
-
-- Create a detailed TDD implementation plan based on the approved requirement.
-- Display: "GATE 2 PAUSED: type APPROVED to start coding".
-- CODE WILL NOT BE GENERATED until "APPROVED" is received.
-
-> **Telemetry:** Run `aiflow gate 2 start --ticket [ticket-id]` when starting this gate.
-> Run `aiflow gate 2 approved --ticket [ticket-id]` immediately when APPROVED is received.
-
----
-
-### GATE 3 — Code Generation (TDD only)
-
-Only runs after Gate 2 has been APPROVED.
-
-**INVOKE:** `superpowers:test-driven-development`
-- Complex feature (3+ files): `superpowers:subagent-driven-development`
-- Write tests FIRST — run to confirm FAIL -> implement -> PASS.
-- Bug fix EXTRA: `superpowers:systematic-debugging` + `investigate-bug` skill first.
-
-> **Telemetry:** Run `aiflow gate 3 start --ticket [ticket-id]` when starting this gate.
-
----
-
-### GATE 4 — AI Self-Review (wait for APPROVED)
-
-**INVOKE:** `review-plan` skill
-
-Mandatory order:
-1. `superpowers:verification-before-completion` — all tests must PASS
-2. `impact-analysis` skill — check for breaking changes
-3. Tick `custom/rules/review-checklist.md`
-4. Create `plan/[ticket-id]/summary.md`
-
-Then: "GATE 4 PAUSED: type APPROVED or BUG: [description]"
-- Coding bug -> fix -> repeat Gate 4.
-- Requirement bug -> return to Gate 1.
-
-> **Telemetry:** Run `aiflow gate 4 start --ticket [ticket-id]` when starting this gate.
-> Run `aiflow gate 4 approved --ticket [ticket-id]` immediately when APPROVED is received.
-
----
-
-### GATE 5 — Peer Review and Done
-
-Only runs after Gate 4 has been APPROVED.
-
-**INVOKE:** `superpowers:requesting-code-review`
-Guide on creating a Pull Request with the ticket link.
-
-> **Telemetry:** Run `aiflow gate 5 start --ticket [ticket-id]` when starting this gate.
+## MANDATORY: Strict Gate Workflow
+
+> **Absolute Rule: Complete Gate N before entering Gate N+1.**
+> **Do not skip, shorten, or merge Gates.**
+
+You have superpowers. When a ticket context exists in `.aiflow/context/current.json`:
+- **Consult the "AI Skill Registry"** below to find instructions for each skill (`SKILL.md`).
+- **AUTO-START Gate 1 immediately** — do NOT wait for the developer to ask.
+- Read instructions and follow the gate sequence below — NO EXCEPTIONS.
+
+---
+
+### GATE 1 — AI Analyze Requirement (auto-start)
+
+**INVOKE:** `read-study-requirement` skill
+
+AI actively reads ticket + source code to understand the requirement:
+1. Read `.aiflow/context/current.json` — ticket info
+2. Read source code — architecture, related files, data flow
+3. If anything is unclear — ask ONE question at a time, wait for reply
+4. Output `plan/[ticket-id]/requirement.md` with:
+   - Requirements summary, source code analysis
+   - Proposed solution and approach
+   - Impact analysis, effort estimate, testing plan
+5. Display "GATE 1: Requirement doc ready" → wait for **APPROVED**
+
+> **Tip:** If auto-start doesn't trigger, the developer can start this gate by typing: **"start"**, **"Gate 1"** or **"Analyze ticket"**.
+
+DO NOT just check format — **understand the content and propose solutions**.
+
+> **Telemetry:** Run `aiflow gate 1 start --ticket [ticket-id]` when starting this gate (auto-start or when developer types "start"/"Gate 1").
+> Run `aiflow gate 1 approved --ticket [ticket-id]` immediately when APPROVED is received.
+
+---
+
+### GATE 2 — Implementation Plan (wait for APPROVED)
+
+**INVOKE:** `generate-spec` skill, then `superpowers:writing-plans`
+
+- Create a detailed TDD implementation plan based on the approved requirement.
+- Display: "GATE 2 PAUSED: type APPROVED to start coding".
+- CODE WILL NOT BE GENERATED until "APPROVED" is received.
+
+> **Telemetry:** Run `aiflow gate 2 start --ticket [ticket-id]` when starting this gate.
+> Run `aiflow gate 2 approved --ticket [ticket-id]` immediately when APPROVED is received.
+
+---
+
+### GATE 3 — Code Generation (TDD only)
+
+Only runs after Gate 2 has been APPROVED.
+
+**INVOKE:** `superpowers:test-driven-development`
+- Complex feature (3+ files): `superpowers:subagent-driven-development`
+- Write tests FIRST — run to confirm FAIL -> implement -> PASS.
+- Bug fix EXTRA: `superpowers:systematic-debugging` + `investigate-bug` skill first.
+
+> **Telemetry:** Run `aiflow gate 3 start --ticket [ticket-id]` when starting this gate.
+
+---
+
+### GATE 4 — AI Self-Review (wait for APPROVED)
+
+**INVOKE:** `review-plan` skill
+
+Mandatory order:
+1. `superpowers:verification-before-completion` — all tests must PASS
+2. `impact-analysis` skill — check for breaking changes
+3. Tick `custom/rules/review-checklist.md`
+4. Create `plan/[ticket-id]/summary.md`
+
+Then: "GATE 4 PAUSED: type APPROVED or BUG: [description]"
+- Coding bug -> fix -> repeat Gate 4.
+- Requirement bug -> return to Gate 1.
+
+> **Telemetry:** Run `aiflow gate 4 start --ticket [ticket-id]` when starting this gate.
+> Run `aiflow gate 4 approved --ticket [ticket-id]` immediately when APPROVED is received.
+
+---
+
+### GATE 5 — Peer Review and Done
+
+Only runs after Gate 4 has been APPROVED.
+
+**INVOKE:** `superpowers:requesting-code-review`
+Guide on creating a Pull Request with the ticket link.
+
+> **Telemetry:** Run `aiflow gate 5 start --ticket [ticket-id]` when starting this gate.

package/custom/templates/spring-boot.md

@@ -2,6 +2,8 @@
 
 You are an expert Java Spring Boot developer. Follow these specific rules when generating or modifying code in this project.
 
+> **Code examples:** See `.rules/java/spring-boot-examples.md` — read it when generating code for a specific layer.
+
 ---
 
 ## Project Stack
@@ -63,25 +65,6 @@ com.company.project/
 - Use `ResponseEntity<T>` for explicit HTTP status control
 - Validate input with `\@Valid` + Bean Validation annotations
 
-```java
-// ✅ Good
-\@PostMapping
-public ResponseEntity<UserResponse> createUser(
-        \@Valid \@RequestBody CreateUserRequest request) {
-    UserResponse response = userService.create(request);
-    return ResponseEntity.status(HttpStatus.CREATED).body(response);
-}
-
-// ❌ Bad — business logic in controller
-\@PostMapping
-public ResponseEntity<User> createUser(\@RequestBody User user) {
-    if (userRepository.existsByEmail(user.getEmail())) {
-        throw new RuntimeException("Email exists");
-    }
-    return ResponseEntity.ok(userRepository.save(user));
-}
-```
-
 ---
 
 ## Service Rules
@@ -93,59 +76,16 @@ public ResponseEntity<User> createUser(\@RequestBody User user) {
 - Throw specific custom exceptions, not generic `RuntimeException`
 - Never return an Entity — always convert to DTO via Mapper
 
-```java
-// ✅ Good
-public interface UserService {
-    UserResponse create(CreateUserRequest request);
-    UserResponse findById(Long id);
-}
-
-\@Service
-\@RequiredArgsConstructor
-public class UserServiceImpl implements UserService {
-
-    private final UserRepository userRepository;
-    private final UserMapper userMapper;
-
-    \@Override
-    \@Transactional
-    public UserResponse create(CreateUserRequest request) {
-        if (userRepository.existsByEmail(request.getEmail())) {
-            throw new DuplicateEmailException(request.getEmail());
-        }
-        User user = userMapper.toEntity(request);
-        User saved = userRepository.save(user);
-        return userMapper.toResponse(saved);
-    }
-}
-```
-
 ---
 
 ## Repository Rules
 
-- Extend `JpaRepository<Entity, ID>` or `JpaRepository` with Specification
+- Extend `JpaRepository<Entity, ID>`
 - Use **method name queries** for simple queries
 - Use `\@Query` (JPQL) for complex queries — avoid native SQL unless necessary
 - Never add business logic here
 - Use `\@EntityGraph` to solve N+1 problems
 
-```java
-// ✅ Good
-public interface UserRepository extends JpaRepository<User, Long> {
-
-    boolean existsByEmail(String email);
-
-    Optional<User> findByEmailAndDeletedFalse(String email);
-
-    \@Query("SELECT u FROM User u JOIN FETCH u.roles WHERE u.id = :id")
-    Optional<User> findByIdWithRoles(\@Param("id") Long id);
-}
-
-// ❌ Bad — N+1 problem
-List<Order> findAll(); // If Order has \@ManyToOne User, this causes N+1
-```
-
 ---
 
 ## Entity Rules
@@ -157,36 +97,6 @@ List<Order> findAll(); // If Order has \@ManyToOne User, this causes N+1
 - For soft delete: add `deleted` boolean + `deletedAt` timestamp
 - Extend `BaseEntity` for audit fields (`createdAt`, `updatedAt`)
 
-```java
-// ✅ Good
-\@Entity
-\@Table(name = "users")
-\@Getter
-\@Setter
-\@NoArgsConstructor
-\@AllArgsConstructor
-\@Builder
-public class User extends BaseEntity {
-
-    \@Id
-    \@GeneratedValue(strategy = GenerationType.IDENTITY)
-    private Long id;
-
-    \@Column(name = "email", nullable = false, unique = true, length = 255)
-    private String email;
-
-    \@Column(name = "full_name", nullable = false, length = 100)
-    private String fullName;
-
-    \@Column(name = "deleted", nullable = false)
-    \@Builder.Default
-    private boolean deleted = false;
-
-    \@OneToMany(mappedBy = "user", cascade = CascadeType.ALL, fetch = FetchType.LAZY)
-    private List<Order> orders = new ArrayList<>();
-}
-```
-
 ---
 
 ## DTO Rules
@@ -196,40 +106,6 @@ public class User extends BaseEntity {
 - Validate in the Request DTO with Bean Validation (`\@NotBlank`, `\@Email`, `\@NotNull`, `\@Size`)
 - Never expose internal fields (password hash, audit timestamps) in the Response DTO
 
-```java
-// Request DTO
-\@Getter
-\@NoArgsConstructor
-\@AllArgsConstructor
-\@Builder
-public class CreateUserRequest {
-
-    \@NotBlank(message = "Email is required")
-    \@Email(message = "Invalid email format")
-    private String email;
-
-    \@NotBlank(message = "Full name is required")
-    \@Size(min = 2, max = 100, message = "Full name must be 2-100 characters")
-    private String fullName;
-
-    \@NotBlank(message = "Password is required")
-    \@Size(min = 8, message = "Password must be at least 8 characters")
-    private String password;
-}
-
-// Response DTO
-\@Getter
-\@NoArgsConstructor
-\@AllArgsConstructor
-\@Builder
-public class UserResponse {
-    private Long id;
-    private String email;
-    private String fullName;
-    private LocalDateTime createdAt;
-}
-```
-
 ---
 
 ## MapStruct Mapper Rules
@@ -238,23 +114,6 @@ public class UserResponse {
 - Define explicit mappings with `\@Mapping` when field names differ
 - Never do manual mapping (`new DTO(); dto.setField(entity.getField())`)
 
-```java
-\@Mapper(componentModel = "spring")
-public interface UserMapper {
-
-    \@Mapping(target = "createdAt", source = "createdAt")
-    UserResponse toResponse(User user);
-
-    \@Mapping(target = "id", ignore = true)
-    \@Mapping(target = "deleted", ignore = true)
-    \@Mapping(target = "createdAt", ignore = true)
-    \@Mapping(target = "updatedAt", ignore = true)
-    User toEntity(CreateUserRequest request);
-
-    List<UserResponse> toResponseList(List<User> users);
-}
-```
-
 ---
 
 ## Exception Handling
@@ -264,46 +123,6 @@ public interface UserMapper {
 - Return a consistent error response format
 - Never expose stack traces to the client
 
-```java
-// Custom exception
-public class ResourceNotFoundException extends RuntimeException {
-    public ResourceNotFoundException(String resource, Long id) {
-        super(String.format("%s with id %d not found", resource, id));
-    }
-}
-
-// Global handler
-\@RestControllerAdvice
-\@Slf4j
-public class GlobalExceptionHandler {
-
-    \@ExceptionHandler(ResourceNotFoundException.class)
-    public ResponseEntity<ErrorResponse> handleNotFound(ResourceNotFoundException ex) {
-        log.warn("Resource not found: {}", ex.getMessage());
-        return ResponseEntity.status(HttpStatus.NOT_FOUND)
-                .body(ErrorResponse.of("NOT_FOUND", ex.getMessage()));
-    }
-
-    \@ExceptionHandler(MethodArgumentNotValidException.class)
-    public ResponseEntity<ErrorResponse> handleValidation(MethodArgumentNotValidException ex) {
-        List<String> errors = ex.getBindingResult()
-                .getFieldErrors()
-                .stream()
-                .map(e -> e.getField() + ": " + e.getDefaultMessage())
-                .toList();
-        return ResponseEntity.status(HttpStatus.BAD_REQUEST)
-                .body(ErrorResponse.of("VALIDATION_FAILED", errors.toString()));
-    }
-
-    \@ExceptionHandler(Exception.class)
-    public ResponseEntity<ErrorResponse> handleGeneral(Exception ex) {
-        log.error("Unexpected error", ex);
-        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
-                .body(ErrorResponse.of("INTERNAL_ERROR", "An unexpected error occurred"));
-    }
-}
-```
-
 ---
 
 ## Testing Rules
@@ -314,104 +133,11 @@ public class GlobalExceptionHandler {
 - Test happy path + edge cases + exception scenarios
 - Use AssertJ: `assertThat(result).isEqualTo(expected)`
 
-```java
-\@ExtendWith(MockitoExtension.class)
-class UserServiceImplTest {
-
-    \@Mock
-    private UserRepository userRepository;
-
-    \@Mock
-    private UserMapper userMapper;
-
-    \@InjectMocks
-    private UserServiceImpl userService;
-
-    \@Test
-    void create_shouldReturnUserResponse_whenEmailIsUnique() {
-        // Arrange
-        CreateUserRequest request = CreateUserRequest.builder()
-                .email("test\@example.com")
-                .fullName("Test User")
-                .build();
-        User user = User.builder().id(1L).email("test\@example.com").build();
-        UserResponse expected = UserResponse.builder().id(1L).build();
-
-        given(userRepository.existsByEmail(request.getEmail())).willReturn(false);
-        given(userMapper.toEntity(request)).willReturn(user);
-        given(userRepository.save(user)).willReturn(user);
-        given(userMapper.toResponse(user)).willReturn(expected);
-
-        // Act
-        UserResponse result = userService.create(request);
-
-        // Assert
-        assertThat(result).isEqualTo(expected);
-        verify(userRepository).save(user);
-    }
-
-    \@Test
-    void create_shouldThrowDuplicateEmailException_whenEmailAlreadyExists() {
-        CreateUserRequest request = CreateUserRequest.builder()
-                .email("existing\@example.com").build();
-        given(userRepository.existsByEmail(request.getEmail())).willReturn(true);
-
-        assertThatThrownBy(() -> userService.create(request))
-                .isInstanceOf(DuplicateEmailException.class);
-        verify(userRepository, never()).save(any());
-    }
-}
-```
-
 ### Integration Tests (Controller layer)
 - Use `\@SpringBootTest` + `\@AutoConfigureMockMvc`
 - Test full HTTP flow with `MockMvc`
 - Use `\@Sql` or Testcontainers for database state
 
-```java
-\@SpringBootTest
-\@AutoConfigureMockMvc
-class UserControllerIntegrationTest {
-
-    \@Autowired
-    private MockMvc mockMvc;
-
-    \@Autowired
-    private ObjectMapper objectMapper;
-
-    \@Test
-    void createUser_shouldReturn201_whenRequestIsValid() throws Exception {
-        CreateUserRequest request = CreateUserRequest.builder()
-                .email("test\@example.com")
-                .fullName("Test User")
-                .password("password123")
-                .build();
-
-        mockMvc.perform(post("/api/v1/users")
-                        .contentType(MediaType.APPLICATION_JSON)
-                        .content(objectMapper.writeValueAsString(request)))
-                .andExpect(status().isCreated())
-                .andExpect(jsonPath("$.email").value("test\@example.com"))
-                .andExpect(jsonPath("$.id").isNumber());
-    }
-
-    \@Test
-    void createUser_shouldReturn400_whenEmailIsInvalid() throws Exception {
-        CreateUserRequest request = CreateUserRequest.builder()
-                .email("not-an-email")
-                .fullName("Test")
-                .password("password123")
-                .build();
-
-        mockMvc.perform(post("/api/v1/users")
-                        .contentType(MediaType.APPLICATION_JSON)
-                        .content(objectMapper.writeValueAsString(request)))
-                .andExpect(status().isBadRequest())
-                .andExpect(jsonPath("$.code").value("VALIDATION_FAILED"));
-    }
-}
-```
-
 ---
 
 ## Naming Conventions
@@ -458,14 +184,6 @@ GET    /api/v1/users/{id}/orders  → 200 nested resource
 - Use `\@Transactional(readOnly = true)` on read-only service methods
 - For heavy read operations, consider projection interfaces
 
-```java
-// ✅ Read-only transaction
-\@Transactional(readOnly = true)
-public Page<UserResponse> findAll(Pageable pageable) {
-    return userRepository.findAll(pageable).map(userMapper::toResponse);
-}
-```
-
 ---
 
 ## Security Rules
@@ -487,23 +205,6 @@ public Page<UserResponse> findAll(Pageable pageable) {
 - `log.error` — unexpected exceptions (always include `ex` as the second argument)
 - Never log sensitive data (password, credit card, token)
 
-```java
-\@Slf4j
-\@Service
-public class UserServiceImpl implements UserService {
-
-    public UserResponse findById(Long id) {
-        log.info("Finding user by id: {}", id);
-        return userRepository.findById(id)
-                .map(userMapper::toResponse)
-                .orElseThrow(() -> {
-                    log.warn("User not found: id={}", id);
-                    return new ResourceNotFoundException("User", id);
-                });
-    }
-}
-```
-
 ---
 
 ## Common Anti-Patterns to Avoid