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

package/README.md

@@ -23,81 +23,49 @@ Developers only need a single command to load ticket context → AI automaticall
 > [!TIP]
 > After running `aiflow init`, documentation files are automatically copied to `.aiflow/docs/` in your project for easy access.
 
-- **[Quick Start Guide](./docs/common/QUICK_START.md)** — Step-by-step instructions for developers.
-- **[Full Workflow (5 Gates)](./docs/common/AIFLOW.md)** — In-depth look at the Gate process.
-- **[Troubleshooting](./docs/common/troubleshooting.md)** — Common issues and fixes.
-- **[Integration Guide](./docs/common/ai-integration.md)** — Advanced tool setup (Claude, Cursor, Gemini).
-- **[Changelog](./docs/common/CHANGELOG.md)** — Version history and release notes.
+- **[Quick Start Guide](https://gitlab.relipa.vn/ai/ai-flow-kit/-/blob/main/docs/common/QUICK_START.md)** — Step-by-step instructions for developers.
+- **[Full Workflow (5 Gates)](https://gitlab.relipa.vn/ai/ai-flow-kit/-/blob/main/docs/common/AIFLOW.md)** — In-depth look at the Gate process.
+- **[Troubleshooting](https://gitlab.relipa.vn/ai/ai-flow-kit/-/blob/main/docs/common/troubleshooting.md)** — Common issues and fixes.
+- **[Integration Guide](https://gitlab.relipa.vn/ai/ai-flow-kit/-/blob/main/docs/common/ai-integration.md)** — Advanced tool setup (Claude, Cursor, Gemini).
+- **[Changelog](https://gitlab.relipa.vn/ai/ai-flow-kit/-/blob/main/docs/common/CHANGELOG.md)** — Version history and release notes.
 
 ---
 
 ## Overview Flow
 
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                        TECH LEAD                                 │
-│  npm publish @relipa/ai-flow-kit  →  developer: npm install -g          │
-└─────────────────────────────────┬───────────────────────────────┘
-                                  │
-                    ┌─────────────▼─────────────┐
-                    │      aiflow init           │
-                    │  --framework spring-boot   │
-                    │  --adapter backlog         │
-                    └─────────────┬─────────────┘
-                                  │ setup
-                    ┌─────────────▼──────────────────────────────┐
-                    │           Project                           │
-                    │  .claude/                                   │
-                    │  ├── skills/          ← superpowers + custom│
-                    │  ├── hooks/           ← SessionStart hook   │
-                    │  └── settings.json    ← hook config         │
-                    │  .aiflow/                                   │
-                    │  ├── context/         ← ticket context      │
-                    │  └── versions/        ← versioned skills    │
-                    │  .rules/              ← team rules (java/)  │
-                    │  CLAUDE.md            ← framework template  │
-                    │  .mcp.json            ← MCP adapter config  │
-                    └─────────────┬──────────────────────────────┘
-                                  │
-               ┌──────────────────▼──────────────────┐
-               │          Developer workflow          │
-               │                                      │
-               │  1. aiflow use PROJ-33                │
-               │     └─ Pull title, description,      │
-               │        and comments from Backlog     │
-               │     └─ Save → .claude/context/       │
-               │                                      │
-               │  2. claude  (open Claude terminal)    │
-               │                                      │
-               │  3. "Fix bug PROJ-33"  (1 line)       │
-               └──────────────────┬──────────────────┘
-                                  │
-               ┌──────────────────▼──────────────────┐
-               │           Claude AI                  │
-               │                                      │
-               │  SessionStart hook injected          │
-               │  using-superpowers skill             │
-               │       ↓                              │
-               │  Read CLAUDE.md (spring-boot rules)  │
-               │       ↓                              │
-               │  Read context/current.json (PROJ-33) │
-               │       ↓                              │
-               │  Auto-detect: bug-fix task           │
-               │       ↓                              │
-               │  Invoke investigate-bug skill        │
-               │  → inherits systematic-debugging     │
-               │  → trace Controller→Service→Repo     │
-               │  → git blame to understand history   │
-               │  → propose minimal fix               │
-               │       ↓                              │
-               │  Invoke impact-analysis skill        │
-               │  → check breaking changes            │
-               └──────────────────┬──────────────────┘
-                                  │
-               ┌──────────────────▼──────────────────┐
-               │          Developer review            │
-               │  git diff → test → commit            │
-               └──────────────────────────────────────┘
+PM writes ticket on Backlog/Jira
+        │
+        ▼
+⛩️ GATE 1 — AI Analyze Requirement          [AI + DEV]
+  aiflow use PROJ-33   →   claude
+  AI loads ticket + reads source code
+  AI asks clarifying questions (max 1 in Fast mode)
+  AI outputs: plan/PROJ-33/requirement.md (Lite in Fast mode)
+  DEV reviews → "APPROVED"
+        │ APPROVED
+        ▼
+⛩️ GATE 2 — Implementation Plan             [AI + DEV]
+  AI creates detailed coding plan (TDD steps)
+  DEV reviews → "APPROVED"
+        │ APPROVED
+        ▼
+⛩️ GATE 3 — Code Generation (TDD)           [AI]
+  AI writes tests first → implement → tests pass
+  Commit each small step
+        │ Code done
+        ▼
+⛩️ GATE 4 — AI Self-Review                  [AI + DEV]
+  AI runs: verification + impact-analysis + checklist
+  AI generates: plan/PROJ-33/summary.md
+  DEV reviews → "APPROVED" or "BUG: [description]"
+        │ APPROVED
+        ▼
+⛩️ GATE 5 — Peer Review & PR                [DEV + Peer]
+  Create Pull Request → peer review → merge
+        │
+        ▼
+       DONE
 ```
 
 ---
@@ -123,6 +91,7 @@ npm uninstall -g @relipa/ai-flow-kit
 |---------|-------------|
 | `aiflow init` | Setup framework, adapters, and multi-AI rules. |
 | `aiflow use <ticket>` | Load ticket context (Backlog/Jira). |
+| `aiflow task` | Manage multiple tasks — pause, switch, resume. |
 | `aiflow prompt` | Generate tool-optimized prompts (`--env cursor`). |
 | `aiflow telemetry` | Manage telemetry tracking (enable/disable/status). |
 | `aiflow guide` | View integrated multi-AI integration guide. |
@@ -135,6 +104,9 @@ Initial setup for the project. Run once per project.
 # Single framework + adapter
 aiflow init --framework spring-boot --adapter backlog
 
+# Force enable RTK token compression
+aiflow init --with-rtk
+
 # Multiple frameworks and adapters
 aiflow init --framework spring-boot,reactjs --adapter backlog,jira
 ```
@@ -181,12 +153,52 @@ aiflow use PROJ-33 --comments-from 3
 # Manual input
 aiflow use --manual
 
+# Load from local file (JSON or plain text)
+aiflow use --file task.md
+
+# Modes (Fast is default)
+aiflow use PROJ-33          # Fast Mode: skip Q&A, target < 5 min
+aiflow use PROJ-33 --full   # Full Mode: deep analysis with Q&A
+
 # Save with custom name
 aiflow use PROJ-33 --save sprint-42-bug
 ```
 
 ---
 
+### `aiflow task`
+
+Manage multiple tasks — pause a task, switch to another, and resume later while keeping full progress.
+
+```bash
+aiflow task status                  # show active task and pending tasks
+aiflow task list                    # list all saved tasks
+aiflow task pause                   # pause current task (saves context + gate progress)
+aiflow task pause --note "waiting for API spec"   # pause with a note
+aiflow task switch PROJ-99          # pause current + switch to another task
+aiflow task resume PROJ-33          # resume a paused task (restores context + gate state)
+aiflow task reset  PROJ-33          # reset to Gate 1 (keeps ticket context, clears progress)
+aiflow task remove PROJ-33          # permanently delete all saved data for the task
+```
+
+**Use case — switching tasks mid-flow:**
+
+```bash
+# Working on PROJ-33 at Gate 2...
+aiflow task pause               # pauses and saves PROJ-33 progress
+
+aiflow use PROJ-99              # loads urgent task (auto-pauses current)
+claude                          # AI starts Gate 1 for PROJ-99
+
+# Done with PROJ-99, resuming PROJ-33
+aiflow task resume PROJ-33      # restores context
+claude                          # AI resumes from Gate 2 automatically
+```
+
+Task state (context + gate progress) is saved in `.aiflow/tasks/<taskId>/`.
+
+---
+
 ### `aiflow doctor`
 
 Check if the setup is complete.

package/bin/aiflow.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 const { program } = require('commander');
 const chalk = require('chalk');
@@ -15,6 +15,7 @@ const promptCommand   = require('../scripts/prompt');
 const removeCommand   = require('../scripts/remove');
 const guideCommand    = require('../scripts/guide');
 const telemetryCommand= require('../scripts/telemetry/cli');
+const taskCommand     = require('../scripts/task');
 const { record }      = require('../scripts/telemetry/record');
 
 program
@@ -60,6 +61,8 @@ program
     .option('-f, --framework <types>', 'framework(s), comma-separated (e.g. spring-boot,reactjs)')
     .option('-a, --adapter <types>', 'adapter(s), comma-separated (e.g. backlog,jira)')
     .option('-e, --env <types>', 'AI environment(s)/tool(s), comma-separated (e.g. cursor,gemini,copilot)')
+    .option('--with-rtk', 'force enable RTK token compression hook')
+    .option('--no-rtk', 'skip RTK setup even if RTK is detected')
     .action((options) => {
         options.frameworks = options.framework
             ? options.framework.split(',').map(s => s.trim()).filter(Boolean)
@@ -69,7 +72,7 @@ program
             : [];
         options.aiTools = options.env
             ? options.env.split(',').map(s => s.trim()).filter(Boolean)
-            : Object.keys(require('../scripts/init').AI_TOOL_FILES || {});
+            : Object.keys(require('../scripts/init').AI_TOOL_FILES || {}).filter(t => t !== 'generic');
 
         record('command.invoked', { command: 'init' });
         initCommand(options);
@@ -85,6 +88,8 @@ program
     .option('--with-comments', 'load all comments (default: description only)')
     .option('--comments-last <n>', 'load only the last N comments', parseInt)
     .option('--comments-from <n>', 'load comments from index N onward (0-based)', parseInt)
+    .option('--fast', 'fast mode: minimal Q&A, concise requirement doc (Default)')
+    .option('--full', 'full mode: force complete analysis with Q&A (default)')
     .action((target, options) => {
         record('command.invoked', { command: 'use' });
         useCommand(target, options);
@@ -118,6 +123,45 @@ program
         console.log(detector.formatOutput(result, options.verbose));
     });
 
+// ── task ─────────────────────────────────────────────────────
+const taskCmd = program.command('task').description('Manage multiple tasks — pause, switch, resume');
+
+taskCmd
+    .command('status')
+    .description('Show active task and pending tasks')
+    .action(() => { record('command.invoked', { command: 'task.status' }); taskCommand('status'); });
+
+taskCmd
+    .command('list')
+    .description('List all saved tasks')
+    .action(() => { record('command.invoked', { command: 'task.list' }); taskCommand('list'); });
+
+taskCmd
+    .command('pause')
+    .description('Pause current task and save progress')
+    .option('-n, --note <text>', 'note about why you are pausing')
+    .action((opts) => { record('command.invoked', { command: 'task.pause' }); taskCommand('pause', { note: opts.note }); });
+
+taskCmd
+    .command('switch <ticket-id>')
+    .description('Pause current task and switch to another')
+    .action((ticketId) => { record('command.invoked', { command: 'task.switch' }); taskCommand('switch', { taskId: ticketId }); });
+
+taskCmd
+    .command('resume <ticket-id>')
+    .description('Resume a paused task')
+    .action((ticketId) => { record('command.invoked', { command: 'task.resume' }); taskCommand('resume', { taskId: ticketId }); });
+
+taskCmd
+    .command('reset <ticket-id>')
+    .description('Reset task to Gate 1 (keeps ticket context, clears gate progress)')
+    .action((ticketId) => { record('command.invoked', { command: 'task.reset' }); taskCommand('reset', { taskId: ticketId }); });
+
+taskCmd
+    .command('remove <ticket-id>')
+    .description('Permanently delete all saved data for a task')
+    .action((ticketId) => { record('command.invoked', { command: 'task.remove' }); taskCommand('remove', { taskId: ticketId }); });
+
 // ── context ───────────────────────────────────────────────────
 program
     .command('context [action]')

package/custom/rules/java/spring-boot-examples.md

@@ -0,0 +1,329 @@
+# Spring Boot Code Examples
+
+Reference examples for each layer. Read the relevant section when generating code for that layer.
+
+---
+
+## Controller
+
+```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
+
+```java
+// Interface
+public interface UserService {
+    UserResponse create(CreateUserRequest request);
+    UserResponse findById(Long id);
+}
+
+// Implementation
+\@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);
+    }
+
+    \@Override
+    \@Transactional(readOnly = true)
+    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);
+                });
+    }
+
+    \@Transactional(readOnly = true)
+    public Page<UserResponse> findAll(Pageable pageable) {
+        return userRepository.findAll(pageable).map(userMapper::toResponse);
+    }
+}
+```
+
+---
+
+## Repository
+
+```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
+
+```java
+\@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
+
+```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
+
+```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
+
+```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"));
+    }
+}
+```
+
+---
+
+## Unit Tests (Service layer)
+
+```java
+\@ExtendWith(MockitoExtension.class)
+class UserServiceImplTest {
+
+    \@Mock
+    private UserRepository userRepository;
+
+    \@Mock
+    private UserMapper userMapper;
+
+    \@InjectMocks
+    private UserServiceImpl userService;
+
+    \@Test
+    void create_shouldReturnUserResponse_whenEmailIsUnique() {
+        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);
+
+        UserResponse result = userService.create(request);
+
+        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)
+
+```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"));
+    }
+}
+```

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

@@ -12,6 +12,60 @@ keywords: ticket, requirement, study, read, context, backlog, jira, analyze, und
 
 ---
 
+## Mode Selection
+
+Check `mode` in `.aiflow/context/current.json` before starting:
+
+| Mode | Trigger | Behaviour |
+|------|---------|-----------|
+| `fast` | `aiflow use TICKET --fast` | Jump to **[Fast Track](#fast-track-mode-fast)** below |
+| `full` | `aiflow use TICKET --full` | Use standard steps — full Q&A + all 6 sections |
+| `auto` (default) | `aiflow use TICKET` | Standard steps |
+
+---
+
+## Fast Track (mode: fast)
+
+> Target: Gate 1 complete in **< 5 minutes**, minimum token usage.
+
+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.
+3. Q&A: Ask at most **ONE** question if there is a blocking ambiguity.
+   If the ticket + source file names make intent clear → skip Q&A entirely.
+   Wait for answer before writing the requirement doc.
+4. Output `plan/[ticket-id]/requirement.md` with **3 sections only**:
+
+```markdown
+# Requirement: [Ticket ID] — [Title]
+
+**Date:** [YYYY-MM-DD]  **Mode:** fast  **Status:** ⏸️ Waiting for DEV Approval
+
+## 1. Requirements Summary
+[2–4 sentence restatement of what needs to change and why]
+
+**Acceptance Criteria:**
+- [ ] [each AC from ticket]
+
+## 3. Files to Create / Modify
+| Action | File | Change |
+|--------|------|--------|
+| Modify | [path] | [what changes] |
+
+## 5. Effort Estimate
+| Task | Size |
+|------|------|
+| Tests | S/M/L |
+| Implementation | S/M/L |
+| **Total** | **S/M/L** |
+```
+
+5. Display Gate 1 prompt and wait for `APPROVED`.
+
+> After APPROVED, proceed to Gate 2. The lean doc is intentional — Gate 2 plan will fill in the details.
+
+---
+
 ## Steps
 
 ### Step 1: Load Ticket & Read Source Code