@relipa/ai-flow-kit 0.0.6-beta.0 → 0.0.7-beta.0

package/custom/skills/impact-analysis/SKILL.md

@@ -20,6 +20,16 @@ keywords: impact, refactor, breaking change, scope
 
 ### Step 1: Find all usage (Dependency Map)
 
+**Preferred — If GitNexus MCP is available** (`.mcp.json` has `gitnexus` entry):
+```
+impact("ClassName")    → structured blast radius: callers, dependents, risk score
+detect_changes()       → reads current git diff, maps changed lines → affected symbols
+```
+- Use `impact()` when you know the class/function name being modified.
+- Use `detect_changes()` when starting Gate 4 review — it auto-detects what changed from git diff without needing to specify names.
+- One call replaces all grep commands below. Proceed directly to Step 2 with the result.
+
+**Fallback — grep manually** (if GitNexus not configured):
 ```bash
 # Find all files importing/calling the class/function being modified
 grep -r "ClassName\|functionName\|methodName" --include="*.php" .

package/custom/skills/read-study-requirement/SKILL.md

@@ -28,6 +28,13 @@ Check `mode` in `.aiflow/context/current.json` before starting:
 
 > Target: Gate 1 complete in **< 5 minutes**, minimum token usage.
 
+## Fast Mode Output Rules (CRITICAL)
+
+When creating `plan/[ticket-id]/summary.md` during Gate 1:
+- You must create the `summary.md` file after Gate 1 is APPROVED, to track session progress.
+- Keep `summary.md` concise. Only include short bullet points tracking Gates.
+- Do not write verbose implementation details in `summary.md` at Gate 1.
+
 1. Read `.aiflow/context/current.json` — ticket title, description, acceptance criteria
 2. Identify **directly affected files** from ticket text and file names only.
    DO NOT trace data flow or read unrelated source files.
@@ -73,6 +80,10 @@ Check `mode` in `.aiflow/context/current.json` before starting:
 1. Read `.aiflow/context/current.json` — ticket info from Backlog/Jira
 2. Read `CLAUDE.md` — understand project architecture, tech stack, conventions
 3. Read related source files — trace data flow, identify patterns, dependencies
+   - **If GitNexus MCP is available** (`.mcp.json` has `gitnexus` entry): invoke GitNexus MCP tools instead of reading files directly — one call returns full context without multi-file exploration:
+     - `gitnexus: context("ClassName")` → 360° view of a symbol (dependencies, callers, methods)
+     - `gitnexus: query("keyword or description")` → hybrid search across codebase
+     - Saves ~50% of token cost at this step vs reading files manually
    - **If task is a Bug Fix:** Invoke `superpowers:systematic-debugging` to trace root cause before proposing fixes.
 4. Read ticket comments — additional context from PM/team
 

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

@@ -41,6 +41,21 @@ Assess impact by reasoning about the changed files only:
 - [ ] No hardcoded credentials or secrets
 - [ ] No SQL injection risk in new queries
 
+## Fast Mode Output Rules (CRITICAL)
+
+When creating `plan/[ticket-id]/summary.md` in **fast mode**:
+- **Do not write long explanations or descriptions.**
+- **List format only:** Bullet points with `[NEW]`, `[MODIFIED]`, `[DELETED]`.
+- **Purpose:** Next to each file, write exactly 1 sentence explaining the *purpose* (the "why"), not the implementation details.
+
+**Example summary.md block:**
+```markdown
+### Gate 3 — Code
+- ✅ **Implemented batch endpoints**
+  - \`[NEW] src/controllers/BatchController.ts\`: Handle bulk export requests
+  - \`[MODIFIED] src/services/ExportService.ts\`: Added S3 upload integration
+```
+
 ---
 
 ## Process

package/custom/templates/spring-boot.md

@@ -1,224 +1,224 @@
-# Spring Boot AI System Prompt
-
-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
-
-- **Java:** 17+
-- **Spring Boot:** 3.x
-- **Build Tool:** Maven (prefer) or Gradle
-- **ORM:** Spring Data JPA + Hibernate
-- **Database:** MySQL / PostgreSQL
-- **Testing:** JUnit 5 + Mockito + AssertJ
-- **Utilities:** Lombok, MapStruct
-- **API Style:** RESTful JSON
-
----
-
-## Architecture
-
-Follow strict **Layered Architecture**:
-
-```
-Controller (HTTP layer)
-    ↓
-Service (Business logic)
-    ↓
-Repository (Data access - Spring Data JPA)
-    ↓
-Entity / Domain Model
-```
-
-### Package Structure
-
-```
-com.company.project/
-├── controller/         # \@RestController — HTTP endpoints only
-├── service/
-│   ├── impl/           # \@Service — business logic implementation
-│   └── [Interface].java
-├── repository/         # \@Repository — extends JpaRepository
-├── entity/             # \@Entity — JPA entities
-├── dto/
-│   ├── request/        # Input DTOs (e.g. CreateUserRequest)
-│   └── response/       # Output DTOs (e.g. UserResponse)
-├── mapper/             # MapStruct mappers (Entity ↔ DTO)
-├── exception/
-│   ├── GlobalExceptionHandler.java  # \@RestControllerAdvice
-│   └── [CustomException].java
-├── config/             # \@Configuration classes
-└── util/               # Pure utility helpers (stateless)
-```
-
----
-
-## Controller Rules
-
-- Annotate with `\@RestController` + `\@RequestMapping`
-- **Only** handle HTTP concerns: parse request, call service, return response
-- Never put business logic in Controller
-- Always use DTOs — never expose Entity directly
-- Use `ResponseEntity<T>` for explicit HTTP status control
-- Validate input with `\@Valid` + Bean Validation annotations
-
----
-
-## Service Rules
-
-- Always define an **interface**, implement in the `impl/` package
-- Annotate implementation with `\@Service`
-- All business logic lives here
-- Use `\@Transactional` at the method level (not class level)
-- Throw specific custom exceptions, not generic `RuntimeException`
-- Never return an Entity — always convert to DTO via Mapper
-
----
-
-## Repository Rules
-
-- 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
-
----
-
-## Entity Rules
-
-- Use Lombok: `\@Getter`, `\@Setter`, `\@NoArgsConstructor`, `\@AllArgsConstructor`, `\@Builder`
-- Avoid `\@Data` on entities (causes issues with `equals/hashCode` + lazy loading)
-- Always use `\@Table(name = "snake_case_table_name")`
-- Use `\@Column(name = "snake_case_column_name")` explicitly
-- For soft delete: add `deleted` boolean + `deletedAt` timestamp
-- Extend `BaseEntity` for audit fields (`createdAt`, `updatedAt`)
-
----
-
-## DTO Rules
-
-- Use separate DTOs for **Request** and **Response** — never share
-- Use Lombok: `\@Getter`, `\@Builder`, `\@AllArgsConstructor`, `\@NoArgsConstructor`
-- Validate in the Request DTO with Bean Validation (`\@NotBlank`, `\@Email`, `\@NotNull`, `\@Size`)
-- Never expose internal fields (password hash, audit timestamps) in the Response DTO
-
----
-
-## MapStruct Mapper Rules
-
-- Use `\@Mapper(componentModel = "spring")` — inject as a Spring bean
-- Define explicit mappings with `\@Mapping` when field names differ
-- Never do manual mapping (`new DTO(); dto.setField(entity.getField())`)
-
----
-
-## Exception Handling
-
-- Create custom exceptions extending `RuntimeException`
-- Handle all exceptions in one `\@RestControllerAdvice` class
-- Return a consistent error response format
-- Never expose stack traces to the client
-
----
-
-## Testing Rules
-
-### Unit Tests (Service layer)
-- Test class: `[ServiceImpl]Test.java`
-- Mock all dependencies with `\@ExtendWith(MockitoExtension.class)` + `\@Mock`
-- Test happy path + edge cases + exception scenarios
-- Use AssertJ: `assertThat(result).isEqualTo(expected)`
-
-### Integration Tests (Controller layer)
-- Use `\@SpringBootTest` + `\@AutoConfigureMockMvc`
-- Test full HTTP flow with `MockMvc`
-- Use `\@Sql` or Testcontainers for database state
-
----
-
-## Naming Conventions
-
-| Element | Convention | Example |
-|---------|-----------|---------|
-| Class | PascalCase | `UserService`, `OrderController` |
-| Method | camelCase | `findById`, `createOrder` |
-| Variable | camelCase | `userResponse`, `orderId` |
-| Constant | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
-| Package | lowercase | `com.company.project.service` |
-| DB Table | snake_case | `user_orders`, `product_items` |
-| DB Column | snake_case | `created_at`, `user_id` |
-| REST endpoint | kebab-case | `/api/v1/user-profiles` |
-| Request DTO | `[Action][Resource]Request` | `CreateOrderRequest` |
-| Response DTO | `[Resource]Response` | `OrderResponse` |
-
----
-
-## API Design
-
-- Version all APIs: `/api/v1/...`
-- Use plural nouns for resources: `/users`, `/orders`
-- HTTP methods: `GET` (read), `POST` (create), `PUT` (full update), `PATCH` (partial), `DELETE`
-- Return `201 Created` for POST, `200 OK` for GET/PUT/PATCH, `204 No Content` for DELETE
-- Use consistent pagination: `?page=0&size=20&sort=createdAt,desc`
-
-```
-GET    /api/v1/users              → 200 list
-POST   /api/v1/users              → 201 created
-GET    /api/v1/users/{id}         → 200 or 404
-PUT    /api/v1/users/{id}         → 200 or 404
-DELETE /api/v1/users/{id}         → 204 or 404
-GET    /api/v1/users/{id}/orders  → 200 nested resource
-```
-
----
-
-## Performance Rules
-
-- Always use pagination — never return unbounded lists
-- Avoid N+1: use `\@EntityGraph` or `JOIN FETCH` in JPQL
-- Add database indexes on frequently queried columns
-- Use `\@Transactional(readOnly = true)` on read-only service methods
-- For heavy read operations, consider projection interfaces
-
----
-
-## Security Rules
-
-- Never log passwords, tokens, or sensitive PII
-- Hash passwords with BCrypt: `passwordEncoder.encode(rawPassword)`
-- Validate and sanitize all user inputs via Bean Validation
-- Use `\@PreAuthorize` for method-level security
-- Never return stack traces to API consumers
-- Store secrets in environment variables / Vault — never in code
-
----
-
-## Logging Rules
-
-- Use SLF4J with Lombok `\@Slf4j`
-- `log.info` — normal business events
-- `log.warn` — recoverable issues (not found, validation fail)
-- `log.error` — unexpected exceptions (always include `ex` as the second argument)
-- Never log sensitive data (password, credit card, token)
-
----
-
-## Common Anti-Patterns to Avoid
-
-- ❌ `\@Autowired` field injection → use constructor injection (Lombok `\@RequiredArgsConstructor`)
-- ❌ `\@Data` on JPA entities → use `\@Getter \@Setter` separately
-- ❌ Returning `Entity` directly from Controller → always use DTO
-- ❌ `SELECT *` or unbounded `findAll()` → always paginate
-- ❌ Business logic in Controller → move to Service
-- ❌ Catching and swallowing exceptions → handle properly or rethrow
-- ❌ `new RuntimeException("something")` → create a specific custom exception
-- ❌ Hardcoding config values → use `\@Value` or `\@ConfigurationProperties`
-- ❌ `\@Transactional` on Controller → only on Service methods
-
----
-
-When explaining changes, refer to the [Spring Boot Official Documentation](https://docs.spring.io/spring-boot/docs/current/reference/html/) and [Spring Data JPA](https://docs.spring.io/spring-data/jpa/docs/current/reference/html/) conventions.
+# Spring Boot AI System Prompt
+
+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
+
+- **Java:** 17+
+- **Spring Boot:** 3.x
+- **Build Tool:** Maven (prefer) or Gradle
+- **ORM:** Spring Data JPA + Hibernate
+- **Database:** MySQL / PostgreSQL
+- **Testing:** JUnit 5 + Mockito + AssertJ
+- **Utilities:** Lombok, MapStruct
+- **API Style:** RESTful JSON
+
+---
+
+## Architecture
+
+Follow strict **Layered Architecture**:
+
+```
+Controller (HTTP layer)
+    ↓
+Service (Business logic)
+    ↓
+Repository (Data access - Spring Data JPA)
+    ↓
+Entity / Domain Model
+```
+
+### Package Structure
+
+```
+com.company.project/
+├── controller/         # \@RestController — HTTP endpoints only
+├── service/
+│   ├── impl/           # \@Service — business logic implementation
+│   └── [Interface].java
+├── repository/         # \@Repository — extends JpaRepository
+├── entity/             # \@Entity — JPA entities
+├── dto/
+│   ├── request/        # Input DTOs (e.g. CreateUserRequest)
+│   └── response/       # Output DTOs (e.g. UserResponse)
+├── mapper/             # MapStruct mappers (Entity ↔ DTO)
+├── exception/
+│   ├── GlobalExceptionHandler.java  # \@RestControllerAdvice
+│   └── [CustomException].java
+├── config/             # \@Configuration classes
+└── util/               # Pure utility helpers (stateless)
+```
+
+---
+
+## Controller Rules
+
+- Annotate with `\@RestController` + `\@RequestMapping`
+- **Only** handle HTTP concerns: parse request, call service, return response
+- Never put business logic in Controller
+- Always use DTOs — never expose Entity directly
+- Use `ResponseEntity<T>` for explicit HTTP status control
+- Validate input with `\@Valid` + Bean Validation annotations
+
+---
+
+## Service Rules
+
+- Always define an **interface**, implement in the `impl/` package
+- Annotate implementation with `\@Service`
+- All business logic lives here
+- Use `\@Transactional` at the method level (not class level)
+- Throw specific custom exceptions, not generic `RuntimeException`
+- Never return an Entity — always convert to DTO via Mapper
+
+---
+
+## Repository Rules
+
+- 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
+
+---
+
+## Entity Rules
+
+- Use Lombok: `\@Getter`, `\@Setter`, `\@NoArgsConstructor`, `\@AllArgsConstructor`, `\@Builder`
+- Avoid `\@Data` on entities (causes issues with `equals/hashCode` + lazy loading)
+- Always use `\@Table(name = "snake_case_table_name")`
+- Use `\@Column(name = "snake_case_column_name")` explicitly
+- For soft delete: add `deleted` boolean + `deletedAt` timestamp
+- Extend `BaseEntity` for audit fields (`createdAt`, `updatedAt`)
+
+---
+
+## DTO Rules
+
+- Use separate DTOs for **Request** and **Response** — never share
+- Use Lombok: `\@Getter`, `\@Builder`, `\@AllArgsConstructor`, `\@NoArgsConstructor`
+- Validate in the Request DTO with Bean Validation (`\@NotBlank`, `\@Email`, `\@NotNull`, `\@Size`)
+- Never expose internal fields (password hash, audit timestamps) in the Response DTO
+
+---
+
+## MapStruct Mapper Rules
+
+- Use `\@Mapper(componentModel = "spring")` — inject as a Spring bean
+- Define explicit mappings with `\@Mapping` when field names differ
+- Never do manual mapping (`new DTO(); dto.setField(entity.getField())`)
+
+---
+
+## Exception Handling
+
+- Create custom exceptions extending `RuntimeException`
+- Handle all exceptions in one `\@RestControllerAdvice` class
+- Return a consistent error response format
+- Never expose stack traces to the client
+
+---
+
+## Testing Rules
+
+### Unit Tests (Service layer)
+- Test class: `[ServiceImpl]Test.java`
+- Mock all dependencies with `\@ExtendWith(MockitoExtension.class)` + `\@Mock`
+- Test happy path + edge cases + exception scenarios
+- Use AssertJ: `assertThat(result).isEqualTo(expected)`
+
+### Integration Tests (Controller layer)
+- Use `\@SpringBootTest` + `\@AutoConfigureMockMvc`
+- Test full HTTP flow with `MockMvc`
+- Use `\@Sql` or Testcontainers for database state
+
+---
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Class | PascalCase | `UserService`, `OrderController` |
+| Method | camelCase | `findById`, `createOrder` |
+| Variable | camelCase | `userResponse`, `orderId` |
+| Constant | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
+| Package | lowercase | `com.company.project.service` |
+| DB Table | snake_case | `user_orders`, `product_items` |
+| DB Column | snake_case | `created_at`, `user_id` |
+| REST endpoint | kebab-case | `/api/v1/user-profiles` |
+| Request DTO | `[Action][Resource]Request` | `CreateOrderRequest` |
+| Response DTO | `[Resource]Response` | `OrderResponse` |
+
+---
+
+## API Design
+
+- Version all APIs: `/api/v1/...`
+- Use plural nouns for resources: `/users`, `/orders`
+- HTTP methods: `GET` (read), `POST` (create), `PUT` (full update), `PATCH` (partial), `DELETE`
+- Return `201 Created` for POST, `200 OK` for GET/PUT/PATCH, `204 No Content` for DELETE
+- Use consistent pagination: `?page=0&size=20&sort=createdAt,desc`
+
+```
+GET    /api/v1/users              → 200 list
+POST   /api/v1/users              → 201 created
+GET    /api/v1/users/{id}         → 200 or 404
+PUT    /api/v1/users/{id}         → 200 or 404
+DELETE /api/v1/users/{id}         → 204 or 404
+GET    /api/v1/users/{id}/orders  → 200 nested resource
+```
+
+---
+
+## Performance Rules
+
+- Always use pagination — never return unbounded lists
+- Avoid N+1: use `\@EntityGraph` or `JOIN FETCH` in JPQL
+- Add database indexes on frequently queried columns
+- Use `\@Transactional(readOnly = true)` on read-only service methods
+- For heavy read operations, consider projection interfaces
+
+---
+
+## Security Rules
+
+- Never log passwords, tokens, or sensitive PII
+- Hash passwords with BCrypt: `passwordEncoder.encode(rawPassword)`
+- Validate and sanitize all user inputs via Bean Validation
+- Use `\@PreAuthorize` for method-level security
+- Never return stack traces to API consumers
+- Store secrets in environment variables / Vault — never in code
+
+---
+
+## Logging Rules
+
+- Use SLF4J with Lombok `\@Slf4j`
+- `log.info` — normal business events
+- `log.warn` — recoverable issues (not found, validation fail)
+- `log.error` — unexpected exceptions (always include `ex` as the second argument)
+- Never log sensitive data (password, credit card, token)
+
+---
+
+## Common Anti-Patterns to Avoid
+
+- ❌ `\@Autowired` field injection → use constructor injection (Lombok `\@RequiredArgsConstructor`)
+- ❌ `\@Data` on JPA entities → use `\@Getter \@Setter` separately
+- ❌ Returning `Entity` directly from Controller → always use DTO
+- ❌ `SELECT *` or unbounded `findAll()` → always paginate
+- ❌ Business logic in Controller → move to Service
+- ❌ Catching and swallowing exceptions → handle properly or rethrow
+- ❌ `new RuntimeException("something")` → create a specific custom exception
+- ❌ Hardcoding config values → use `\@Value` or `\@ConfigurationProperties`
+- ❌ `\@Transactional` on Controller → only on Service methods
+
+---
+
+When explaining changes, refer to the [Spring Boot Official Documentation](https://docs.spring.io/spring-boot/docs/current/reference/html/) and [Spring Data JPA](https://docs.spring.io/spring-data/jpa/docs/current/reference/html/) conventions.

package/docs/common/AIFLOW.md

@@ -28,7 +28,7 @@ PM writes ticket on Backlog/Jira
         ▼
 ⛩️ GATE 3 — Code Generation (TDD)           [AI]
   AI writes tests first → implement → tests pass
-  Commit each small step
+  Verify implementation works
         │ Code done
         ▼
 ⛩️ GATE 4 — AI Self-Review                  [AI + DEV]
@@ -65,6 +65,7 @@ AI Flow Kit allows you to manage multiple tasks in the same repository without l
 - **`aiflow task pause`**: Save current context and gate progress to `.aiflow/tasks/<taskId>/`.
 - **`aiflow task switch <id>`**: Pause current task and switch to another.
 - **`aiflow task resume <id>`**: Restore context and gate state. AI auto-resumes from the correct gate.
+- **`aiflow task next`**: Approve the current gate, clear context, and prepare the task for a fresh session (saves tokens).
 
 ---
 
@@ -182,7 +183,7 @@ Summary:
 1. Read the approved requirement document
 2. **Invoke** `superpowers:writing-plans` → create detailed implementation plan
 3. Break down into TDD tasks: test first → implement → verify
-4. Define commit strategy (small, focused commits)
+4. Define verification strategy (evidence before claims)
 5. Present plan and wait for APPROVED
 
 **Implementation Plan Structure:**
@@ -193,7 +194,6 @@ Summary:
 │   ├── Task 2: Implement [component]
 │   ├── Task 3: Write test for [next scenario]
 │   └── ...
-├── Commit Strategy
 └── Test Commands
 ```
 
@@ -202,7 +202,7 @@ Summary:
 ```
 ⏸️ GATE 2: IMPLEMENTATION PLAN READY
 
-Tasks: [N] | Commits: [N] | Test-first tasks: [N]
+Tasks: [N] | Verification: [N] | Test-first tasks: [N]
 
 → Type APPROVED to start coding
 → Or provide feedback to adjust
@@ -227,7 +227,7 @@ Tasks: [N] | Commits: [N] | Test-first tasks: [N]
 2. `superpowers:test-driven-development` — write tests FIRST
 3. Run tests → confirm FAIL
 4. Implement code → tests PASS
-5. Commit each small step
+5. Verify implementation works
 
 #### Bug fix task (extra):
 1. `superpowers:systematic-debugging` — trace root cause, NO guessing
@@ -238,10 +238,16 @@ Tasks: [N] | Commits: [N] | Test-first tasks: [N]
 1. Ensure tests cover current behavior
 2. Refactor in small steps — keep tests green continuously
 
+**Fast Mode (tdd-lean):**
+In fast mode, AI uses the `tdd-lean` skill instead of per-test TDD to save massive token costs:
+1. **Batch Red:** Write ALL tests at once. Run once. (Confirm all fail).
+2. **Batch Green:** Implement ALL code at once. Run once. (Confirm all pass).
+3. **Discipline:** After every run, discard full stack traces and keep ONLY the summary line.
+
 **Gate 3 Output:**
 - Code implementation finished
 - All tests PASS
-- Committed
+- Verified (evidence provided)
 
 ---