@relipa/ai-flow-kit 0.2.0-beta.2 → 0.2.1

package/custom/skills/ingest-data/SKILL.md

@@ -133,17 +133,41 @@ Nếu người dùng yêu cầu sửa (thêm/bớt ý, đổi log đích, sửa
 - **Chỉ là tham khảo** → hiển thị: `ℹ️ Nội dung này không phát sinh task — chỉ lưu làm tài liệu tham khảo. Gate 3 kết thúc.` rồi chạy `ak gate 3 skip --ticket [ticket-id] --reason "<1 câu lý do>"` (không cần `ak gate 3 start` trước) và dừng, không hỏi thêm. Việc này đóng gate đúng cách — dashboard (ai-flow-ex) hiển thị "⏭ Gate 3 skipped — \<lý do\>" thay vì để task treo mãi ở trạng thái "sẵn sàng chạy Gate 3".
 - **Có hành động cụ thể** → tiếp tục Bước 3. Khi không chắc (ví dụ nội dung vừa có FYI vừa có 1 ý cần sửa code) — nghiêng về đề xuất task cho phần cần hành động, bỏ qua phần FYI, không tự bịa task cho phần không rõ.
 
+**Riêng khi nguồn là `Confirmations-Log`** (khách hàng CHỐT chính thức 1 thay đổi requirement) — đây là trường hợp dễ đề xuất thiếu task nhất nếu chỉ dựa vào Action items viết sẵn trong nội dung (vd chỉ thấy 1 bug fix được nêu tên, bỏ sót toàn bộ phần spec/testcase phát sinh từ chính rule vừa chốt). Trước khi sang Bước 3, tự chạy qua đủ checklist tối thiểu sau — không hiển thị checklist này cho PM, chỉ dùng để tự rà soát không bỏ sót:
+
+1. **UC Spec** — functionId này đã có UC Spec chưa, và rule vừa chốt đã phản ánh trong Spec chưa? Chưa → task `spec`.
+2. **System Requirement** — chỉ cần nếu có task `coding` theo sau (Gate 1 coding sẽ tự chặn nếu System Requirement thiếu/lệch version, xem `CLAUDE.md` pre-check) → task `system-requirement`.
+3. **Impact analysis** — thay đổi có đủ phức tạp/rủi ro (ảnh hưởng nhiều module/feature khác, hoặc PM cần thấy effort/scope trước khi giao việc) để cần 1 tài liệu đánh giá riêng, tách khỏi Gate 1 coding không? Cần → task `impact-analysis`.
+4. **Coding** — có thay đổi hành vi hệ thống cần code không? Cần → task `coding` (tách thành nhiều task nhỏ nếu phạm vi lớn, mỗi task 1 title riêng).
+5. **Data migration/backfill** — rule mới có áp dụng hồi tố lên dữ liệu đã tồn tại không (khác với chỉ áp dụng từ nay về sau)? Có → thêm 1 task `coding` **riêng** cho việc migration/backfill, không gộp chung với task coding chính (2 rủi ro/effort khác nhau, cần review riêng).
+6. **Create/Update testcase** — cần → task `test`.
+7. **Execute test** — cần → task `execute-test`.
+
+Không phải mục nào cũng luôn có (case rule chỉ áp dụng tương lai thì mục 5 = không cần) — nhưng phải đi qua đủ 7 mục và có lý do trước khi kết luận không cần, không bỏ qua mục nào chỉ vì nội dung entry không viết thành Action item rõ ràng.
+
 ### 5.3 Bước 3 — Đề xuất danh sách task
 
 Mỗi task gồm:
 
 | Trường | Ghi chú |
 |---|---|
-| `type` | `spec` (tạo/update UC Spec) · `coding` · `test` · `other` (update tài liệu không thuộc BA/QA/Dev, vd Rules) |
+| `type` | `spec` (tạo/update UC Spec) · `system-requirement` (tạo/update System Requirement) · `impact-analysis` (đánh giá phạm vi ảnh hưởng, tách riêng khỏi Gate 1 coding) · `coding` (bao gồm cả migration/backfill, tách task riêng nếu cần) · `test` (tạo/update testcase) · `execute-test` (thực thi testcase có sẵn) · `other` (update tài liệu không thuộc BA/QA/Dev, vd Rules) |
 | `title` | Ngắn, hành động rõ (vd "Cập nhật flow OTP theo feedback khách — tăng thời hạn 30s → 90s") |
-| `track` | BA / Dev / QA — để PM biết ai sẽ nhận task này |
+| `track` | BA / Dev / QA / Analyst — để PM biết ai sẽ nhận task này |
 | `description` | Theo đúng template mục 6.1 `PM Workflow_v1.0.md`: |
 
+Mỗi `type` map thẳng vào 1 task type có sẵn khi người nhận chạy `ak use TICKET-XXX` (không cần Gate workflow mới — xem `scripts/use.js` cho danh sách đầy đủ):
+
+| `type` task | Task type chọn ở `ak use` |
+|---|---|
+| `spec` | 📋 Create Spec |
+| `system-requirement` | 📐 Create System Requirement |
+| `impact-analysis` | 📊 Impact Analysis |
+| `coding` | 🐛 Bug Fix / ✨ Feature / 🔄 Refactor (tuỳ nội dung task) |
+| `test` | ✅ Create TestCase |
+| `execute-test` | ▶️ Execute Test |
+| `other` | Không map task type nào — tuỳ nội dung, người nhận tự xử lý ngoài Gate workflow |
+
 ```text
 ## Nội dung task
 [Mô tả task do AI đề xuất]
@@ -190,33 +214,57 @@ Check LOCAL trước, chỉ hỏi khi thật sự chưa biết (Vấn đề 5.1)
 2. Đã có → dùng luôn, hiển thị rõ cho PM biết đang dùng project nào + nguồn (đã lưu từ lần trước).
 3. Chưa có → hiển thị danh sách project vừa fetch được, PM chọn 1 → lưu lại bằng `ak backlog-set-default-project <id> <key>` hoặc `ak jira-set-default-project <key>` — để lần sau không hỏi lại.
 
+### 5.6b Bước 6b — Ticket cha (chỉ hỏi khi danh sách có ≥ 2 task)
+
+Nếu danh sách chỉ có 1 task, không có gì để gộp — coi `parentTicket.mode = "none"` và bỏ qua bước này.
+
+Nếu ≥ 2 task, hỏi đúng 1 câu:
+
+```text
+Gộp N task này dưới 1 ticket cha?
+1. Tạo mới ticket cha
+2. Dùng ticket cha có sẵn — cho biết ticket ID
+3. Không cần ticket cha
+```
+
+- **(1)** → hỏi PM 1 tiêu đề ngắn cho ticket cha (gợi ý: dùng lại "Tổng quan nội dung thay đổi" đã soạn cho task `spec` ở Bước 3, nếu có; không có thì tự tóm tắt 1 câu). `parentTicket = { "mode": "create", "title": "...", "description": "..." }`.
+- **(2)** → PM nhập ticket ID có sẵn. `parentTicket = { "mode": "existing", "existingId": "<ID do PM nhập>" }`. Việc xác minh ticket đó có tồn tại thật diễn ra ở Bước 7 (khi gọi `ak tasks create-tickets`) — không tự coi là đúng trước khi có kết quả lệnh.
+- **(3)** → `parentTicket = { "mode": "none" }`.
+
+⚠️ **Chưa xác minh trên instance thật:** liên kết cha-con cần Backlog project đã bật tính năng phân cấp issue (Subtasking), hoặc Jira project hỗ trợ field `parent` trực tiếp (rõ nhất với project dạng team-managed; company-managed có thể cần issue type `Subtask` riêng — chưa test). Nếu Bước 7 báo lỗi `parent-create-failed`/`parent-not-found`, hoặc 1 task con lỗi do gán parent thất bại — hiển thị nguyên lỗi cho PM, hỏi PM muốn: thử lại với ticket cha khác, tiếp tục tạo các ticket con không gắn parent (`mode: "none"`), hay dừng lại để PM xử lý cấu hình Backlog/Jira trước.
+
 ### 5.7 Bước 7 — Tạo ticket
 
 1. Ghi danh sách task đã duyệt ra 1 file JSON tạm (vd `.aiflow/tmp/tasks-[ticketId].json`), đúng shape mà `ak tasks create-tickets` đọc (xem `scripts/ticket-writer.js`):
    ```json
    {
      "target": "backlog",
+     "parentTicket": { "mode": "create", "title": "...", "description": "..." },
      "tasks": [
        { "type": "coding", "title": "...", "description": "..." }
      ]
    }
    ```
+   `parentTicket` lấy nguyên từ kết quả Bước 6b (bỏ field này hoặc `{"mode": "none"}` nếu không gộp ticket cha).
 2. Chạy `ak tasks create-tickets <file> --json`.
 3. Đọc kết quả JSON trả về:
    - `{"error":"missing-write-credentials", "field": "...", "message": "..."}` → **đây không phải lỗi hệ thống** — hiển thị đúng `message` cho PM, hỏi PM nhập giá trị key ngay trong hội thoại (dùng luôn khung chat làm nơi PM "nhập & submit"), nhận giá trị → chạy `ak credentials set <field> "<giá trị PM vừa nhập>"` → chạy lại bước 2 (retry đúng 1 lần; nếu vẫn lỗi, báo PM key có thể sai/chưa đủ quyền, không tự thử lại vô hạn).
    - `{"error":"missing-project", ...}` → quay lại Bước 6 (chưa xác định được project).
-   - Thành công (`ok: true`) → mỗi task có `ticketId` + `url` riêng; task nào `ok: false` (lỗi phía Backlog/Jira, vd thiếu field) → báo rõ cho PM, các task khác đã tạo vẫn giữ nguyên (không rollback).
+   - `{"error":"parent-not-found", "message": "..."}` → ticket cha PM cung cấp ở Bước 6b (2) không tồn tại/không đọc được — báo PM, quay lại Bước 6b để nhập ID khác hoặc chọn phương án khác.
+   - `{"error":"parent-create-failed", "message": "..."}` → tạo ticket cha thất bại (thường do project chưa hỗ trợ phân cấp issue) — hiển thị nguyên lỗi, hỏi PM có muốn tạo lại không gắn ticket cha (`mode: "none"`) hay dừng lại.
+   - Thành công (`ok: true`) → mỗi task có `ticketId` + `url` riêng, có thêm `parent` (ticket cha vừa tạo/dùng, nếu có); task nào `ok: false` (lỗi phía Backlog/Jira, vd thiếu field) → báo rõ cho PM, các task khác đã tạo vẫn giữ nguyên (không rollback).
 
 ### 5.8 Bước 8 — Ghi ngược liên kết + đóng Gate
 
-1. Append vào cuối đúng entry gốc (Meetings-Log/QnA-Log/Confirmations-Log) 1 dòng:
+1. Append vào cuối đúng entry gốc (Meetings-Log/QnA-Log/Confirmations-Log) 1 dòng, kèm ticket cha nếu có:
    ```text
-   → Tasks created: TICKET-101 (coding), TICKET-102 (test)
+   → Tasks created: TICKET-100 (parent), TICKET-101 (coding), TICKET-102 (test)
    ```
    Việc sửa file này đi qua đúng branch đang dùng ở Gate 2 (không tạo MR riêng — gộp vào cùng thay đổi, hoặc nếu MR đã mở/merge thì tạo 1 commit nhỏ tiếp theo trên cùng branch/1 MR mới tuỳ trạng thái branch lúc đó).
 2. Hiển thị tổng kết:
    ```text
    ✅ GATE 3 DONE — Đã tạo N/N ticket trên [Backlog/Jira]:
+     - Ticket cha: TICKET-100 — <url>  (bỏ dòng này nếu không gộp ticket cha)
      - TICKET-101 (coding) — <url>
      - TICKET-102 (test) — <url>
    → Dev/QA chạy `ak use TICKET-XXX` trên từng ticket để bắt đầu Gate tương ứng (Coding/QA workflow hiện có).

package/custom/skills/report-customer/SKILL.md

@@ -1,99 +1,99 @@
----
-name: report-customer
-description: Write an incident report for customers or customer service after a production bug fix. Non-technical, easy-to-understand language.
-keywords: report, incident, customer, customer service, CS
----
-
-# Report Customer (Incident Report)
-
-## When to use
-
-- After fixing a bug that affects users/customers
-- Customer Service needs a report explaining the cause to customers
-- Need to document the incident for future reference
-
----
-
-## Process
-
-### Step 1: Gather information
-
-Collect from `investigate-bug` results or developer descriptions:
-- Ticket ID and title
-- Discovery time / impact duration
-- Number of affected users / orders
-- Identified root cause
-- Deployment status
-
-### Step 2: Write the report
-
-Fill in the structure below. **Use simple language, avoiding technical jargon.**
-
----
-
-## Standard Structure
-
-Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md`
-(Vietnamese ticket → Vietnamese report; otherwise English). CS can request a specific language
-explicitly, which overrides auto-detect. Structure below is shown in English.
-
-```markdown
-## 📋 Incident Verification Report
-
-**Ticket ID:** [ID]
-**Assigned to:** [Dev Name]
-**Resolution Date:** [YYYY-MM-DD]
-**Status:** ✅ Resolved / 🔄 In Progress
-
----
-
-### 1. Summary
-
-[1–2 sentences describing the issue in non-technical language.
-Example: "Between 14:00–15:30 on [Date], some 
-users were unable to complete order payments."]
-
----
-
-### 2. Root Cause
-
-[Simple explanation, no code references.
-Example: "Due to a system update failing to correctly handle 
-slow connections with the payment gateway."]
-
----
-
-### 3. Resolution
-
-[Steps taken by the technical team.
-Example: "Updated the timeout handling mechanism and deployed 
-the fix at 16:00 on [Date]."]
-
----
-
-### 4. Data Impact
-
-- Was existing data affected? [Yes / No]
-- Data recovery status: [Update script run / Not necessary]
-
----
-
-### 5. Expected Behavior
-
-[Actions the customer should take to verify normal operation.
-Example: "Customers can now attempt payment normally.
-If problems persist, please contact our support hotline..."]
-```
-
----
-
-## Writing Rules
-
-- ✅ Simple language, avoid technical jargon
-- ✅ Honest about scope and duration of impact
-- ✅ Focus on **user impact**, not code details
-- ✅ Always include instructions for the customer to verify the fix
-- ❌ Do not blame third parties unless certain
-- ❌ Do not commit to specific deadlines unless certain
-
-Present clearly and professionally, in the language determined above.
+---
+name: report-customer
+description: Write an incident report for customers or customer service after a production bug fix. Non-technical, easy-to-understand language.
+keywords: report, incident, customer, customer service, CS
+---
+
+# Report Customer (Incident Report)
+
+## When to use
+
+- After fixing a bug that affects users/customers
+- Customer Service needs a report explaining the cause to customers
+- Need to document the incident for future reference
+
+---
+
+## Process
+
+### Step 1: Gather information
+
+Collect from `investigate-bug` results or developer descriptions:
+- Ticket ID and title
+- Discovery time / impact duration
+- Number of affected users / orders
+- Identified root cause
+- Deployment status
+
+### Step 2: Write the report
+
+Fill in the structure below. **Use simple language, avoiding technical jargon.**
+
+---
+
+## Standard Structure
+
+Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md`
+(Vietnamese ticket → Vietnamese report; otherwise English). CS can request a specific language
+explicitly, which overrides auto-detect. Structure below is shown in English.
+
+```markdown
+## 📋 Incident Verification Report
+
+**Ticket ID:** [ID]
+**Assigned to:** [Dev Name]
+**Resolution Date:** [YYYY-MM-DD]
+**Status:** ✅ Resolved / 🔄 In Progress
+
+---
+
+### 1. Summary
+
+[1–2 sentences describing the issue in non-technical language.
+Example: "Between 14:00–15:30 on [Date], some 
+users were unable to complete order payments."]
+
+---
+
+### 2. Root Cause
+
+[Simple explanation, no code references.
+Example: "Due to a system update failing to correctly handle 
+slow connections with the payment gateway."]
+
+---
+
+### 3. Resolution
+
+[Steps taken by the technical team.
+Example: "Updated the timeout handling mechanism and deployed 
+the fix at 16:00 on [Date]."]
+
+---
+
+### 4. Data Impact
+
+- Was existing data affected? [Yes / No]
+- Data recovery status: [Update script run / Not necessary]
+
+---
+
+### 5. Expected Behavior
+
+[Actions the customer should take to verify normal operation.
+Example: "Customers can now attempt payment normally.
+If problems persist, please contact our support hotline..."]
+```
+
+---
+
+## Writing Rules
+
+- ✅ Simple language, avoid technical jargon
+- ✅ Honest about scope and duration of impact
+- ✅ Focus on **user impact**, not code details
+- ✅ Always include instructions for the customer to verify the fix
+- ❌ Do not blame third parties unless certain
+- ❌ Do not commit to specific deadlines unless certain
+
+Present clearly and professionally, in the language determined above.

package/custom/templates/nestjs.md

@@ -1,72 +1,5 @@
-# NestJS AI System Prompt
-
-You are an expert NestJS developer. Follow these modular architecture rules and best practices.
-
----
-
-## Project Architecture
-
-NestJS follows a strict **Module-based** architecture. Every feature should be contained in its own module.
-
-```
-src/
-├── app.module.ts
-├── main.ts
-└── features/
-    └── [feature-name]/
-        ├── [feature].module.ts
-        ├── [feature].controller.ts
-        ├── [feature].service.ts
-        ├── [feature].entity.ts (if using TypeORM)
-        └── dto/
-            ├── create-[feature].dto.ts
-            └── update-[feature].dto.ts
-```
-
----
-
-## NestJS Rules
-
-- Use **Constructor Injection** for all dependencies.
-- Always use **DTOs** (Data Transfer Objects) with `class-validator` for input validation.
-- Annotate controllers with `@Controller()`.
-- Use `@Injectable()` for services.
-- Leverage **Pipes** for data transformation and validation.
-- Leverage **Interceptors** for logging and response mapping.
-
-```typescript
-// ✅ Good: DTO with validation
-export class CreateUserDto {
-  @IsEmail()
-  email: string;
-
-  @IsString()
-  @MinLength(8)
-  password: string;
-}
-```
-
----
-
-## Testing Rules
-
-- Use the built-in **Jest** testing suite.
-- Use `Test.createTestingModule` to create isolated environments for unit tests.
-
-```typescript
-describe('UsersService', () => {
-  let service: UsersService;
-
-  beforeEach(async () => {
-    const module: TestingModule = await Test.createTestingModule({
-      providers: [UsersService],
-    }).compile();
-
-    service = module.get<UsersService>(UsersService);
-  });
-
-  it('should be defined', () => {
-    expect(service).toBeDefined();
-  });
-});
-```
+# NestJS AI System Prompt
+
+You are an expert NestJS developer. Follow these modular architecture rules and best practices.
+
+> **Rules & code examples:** Read `.rules/javascript/nestjs-rules.md` (architecture, module rules, testing) and `.rules/javascript/nestjs-examples.md` (code samples per rule area) **in full** before writing or modifying any NestJS code in this project.

package/custom/templates/nodejs-express.md

@@ -1,73 +1,5 @@
-# Node.js Express AI System Prompt
-
-You are an expert Node.js developer specialized in the Express.js framework. Follow these rules for building clean, maintainable, and secure backends.
-
----
-
-## Project Structure
-
-Follow the **Controller-Service-Repository** pattern:
-
-```
-src/
-├── controllers/    # Route handlers — parse input, call service, return response
-├── services/       # Business logic — core logic, database transactions
-├── repositories/   # Data access — database queries, ORM interactions
-├── models/         # Database models (Sequelize/Prisma/Mongoose)
-├── middleware/     # Custom Express middleware (auth, logging)
-├── routes/         # Route definitions
-├── dtos/           # Input/Output Data Transfer Objects (if using TS)
-├── utils/          # Stateless helper functions
-└── config/         # App configuration
-```
-
----
-
-## Express Rules
-
-- Use **Async/Await** for all asynchronous operations — avoid callbacks or manual promise chains.
-- Always use a global error handler middleware. Never use `try/catch` in controllers if you use an async-wrapper middleware.
-- Validate all incoming data using `Joi`, `Zod`, or `express-validator`.
-- Keep controllers thin; they should only handle request parsing and response formatting.
-
-```javascript
-// ✅ Good: Controller calls service
-export const createUser = async (req, res, next) => {
-    const userData = req.body;
-    const user = await userService.create(userData);
-    res.status(201).json(user);
-};
-```
-
----
-
-## Security Rules
-
-- Never expose stack traces in production.
-- Use `helmet` to set secure HTTP headers.
-- Sanitize input to prevent NoSQL/SQL injection.
-- Use `argon2` or `bcrypt` for password hashing.
-- Standardize on JWT for authentication.
-
----
-
-## Testing Rules
-
-- Use **Jest** and **Supertest** for testing.
-- Test every API endpoint with integration tests.
-- Mock external services (Email, Payment Gateways).
-
-```javascript
-// Example test
-import request from 'supertest';
-import app from '../app';
-
-describe('POST /api/users', () => {
-    it('should create a new user', async () => {
-        const response = await request(app)
-            .post('/api/users')
-            .send({ email: 'test@example.com', password: 'password123' });
-        expect(response.status).toBe(201);
-    });
-});
-```
+# Node.js Express AI System Prompt
+
+You are an expert Node.js developer specialized in the Express.js framework. Follow these rules for building clean, maintainable, and secure backends.
+
+> **Rules & code examples:** Read `.rules/javascript/nodejs-express-rules.md` (structure, framework rules, security, testing) and `.rules/javascript/nodejs-express-examples.md` (code samples per rule area) **in full** before writing or modifying any Express code in this project.