@relipa/ai-flow-kit 0.1.4-beta.0 → 0.1.5-beta.0

package/custom/skills/ba-skills/{skill-ba-phan-tich-ban-dau-v1.md → skill-ba-initial-analysis-v1.md}

@@ -31,7 +31,7 @@ Kỹ năng này giúp Business Analyst (hoặc Agent) quét, đọc hiểu và c
     - Có quy tắc nghiệp vụ (Business rules) ngầm định nào không?
     - Luồng thay thế (Alternative flows) hoặc luồng lỗi (Exception flows) là gì?
 - **Bước 4: Soạn dự thảo Kết quả phân tích ban đầu:**
-  Áp dụng template phân tích ban đầu (`skill-ba-template-phan-tich-ban-dau-v1.md`) để điền thông tin và lập bảng Gap/Assumption.
+  Áp dụng template phân tích ban đầu (`skill-ba-initial-analysis-template-v1.md`) để điền thông tin và lập bảng Gap/Assumption.
 
 ## 4. Checklist kiểm tra (Checklist for Verification)
 - [ ] Đã xác định rõ Mục tiêu hệ thống/chức năng chưa? (Hệ thống giải quyết bài toán gì?)
@@ -41,4 +41,4 @@ Kỹ năng này giúp Business Analyst (hoặc Agent) quét, đọc hiểu và c
 - [ ] Không tự tiện bổ sung các tính năng ngoài phạm vi yêu cầu của khách hàng khi chưa có thảo luận/Q&A.
 
 ## 5. Output mong đợi (Expected Output)
-- File tài liệu phân tích ban đầu định dạng markdown, cấu trúc thống nhất dựa theo `@skill-ba-template-phan-tich-ban-dau-v1.md`, đặt tên theo chuẩn: `Tên chức năng_Kết quả phân tích(n).md` trong thư mục `TÀI LIỆU/output/Kết quả phân tích/`.
+- File tài liệu phân tích ban đầu định dạng markdown, cấu trúc thống nhất dựa theo `@skill-ba-initial-analysis-template-v1.md`, đặt tên theo chuẩn: `Analysis_v(n).md` trong thư mục `02.BA-Specs/01.Analysis/[functionId]/`.

package/custom/skills/ba-skills/{skill-ba-qa-v1.md → skill-ba-qna-v1.md}

@@ -13,7 +13,7 @@ Kỹ năng này giúp BA thiết kế các câu hỏi rõ ràng, khách quan và
 ## 3. Quy trình thực hiện (Step-by-step Process)
 - **Bước 1: Chuyển đổi Gap thành câu hỏi Q&A:**
   Từ danh sách khoảng trống phát hiện ở bước Phân tích ban đầu, chuyển mỗi dòng thành một câu hỏi Q&A cụ thể.
-- **Bước 2: Chuẩn hóa câu hỏi theo mẫu `@skill-ba-qa-template-v1.md`:**
+- **Bước 2: Chuẩn hóa câu hỏi theo mẫu `@skill-ba-qna-template-v1.md`:**
   - Xác định phân vùng nghiệp vụ (Module/Screen).
   - Trích dẫn yêu cầu hiện tại (Current Status/Requirement).
   - Nêu rõ vấn đề mơ hồ.
@@ -31,5 +31,5 @@ Kỹ năng này giúp BA thiết kế các câu hỏi rõ ràng, khách quan và
 - [ ] Đã cập nhật đúng và đầy đủ tất cả câu trả lời của khách hàng vào tài liệu phân tích chưa? (Không bỏ sót bất kỳ điểm chốt nào).
 
 ## 5. Output mong đợi (Expected Output)
-- File danh sách câu hỏi Q&A định dạng markdown, cấu trúc thống nhất dựa theo `@skill-ba-qa-template-v1.md`, đặt tên theo chuẩn: `Tên chức năng_Q&A(m).md` trong thư mục `TÀI LIỆU/output/QA/`.
+- File danh sách câu hỏi Q&A định dạng markdown, cấu trúc thống nhất dựa theo `@skill-ba-qna-template-v1.md`, đặt tên theo chuẩn: `QnA-Log_v(m).md` trong thư mục `02.BA-Specs/02.QnA/[functionId]/`.
 - Tài liệu phân tích được cập nhật tương ứng với phiên bản mới tăng dần `(n+1)`.

package/custom/skills/ba-skills/{skill-ba-prototype-v1.md → skill-ba-ui-prototype-v1.md}

@@ -22,7 +22,7 @@ Kỹ năng này hướng dẫn BA thiết kế và hiện thực hóa giao diệ
   - Sử dụng bảng màu hiện đại (tránh màu đỏ/xanh lá gốc, dùng các màu trung tính, dịu mắt phối hợp hiệu ứng hover cho các nút bấm).
   - Đảm bảo thiết kế responsive cơ bản bằng media queries nếu cần.
 - **Bước 4: Kiểm tra và lưu trữ:**
-  Mở file HTML trên trình duyệt để kiểm tra trực quan. Lưu vào thư mục `TÀI LIỆU/output/design/`.
+  Mở file HTML trên trình duyệt để kiểm tra trực quan. Lưu vào thư mục `02.BA-Specs/03.UI-Prototypes/[functionId]/`.
 
 ## 4. Checklist kiểm tra (Checklist for Verification)
 - [ ] File HTML có tự chứa toàn bộ CSS không? (Không liên kết tới file CSS bên ngoài trừ font chữ hệ thống).
@@ -32,4 +32,4 @@ Kỹ năng này hướng dẫn BA thiết kế và hiện thực hóa giao diệ
 - [ ] Các phần tử tương tác (Button, Link, Input) có hiệu ứng trực quan khi hover hoặc focus không?
 
 ## 5. Output mong đợi (Expected Output)
-- Một file HTML độc lập chứa đầy đủ code HTML và CSS nội bộ, đặt tên theo chuẩn: `Tên chức năng_design.html` trong thư mục `TÀI LIỆU/output/design/`.
+- Một file HTML độc lập chứa đầy đủ code HTML và CSS nội bộ, đặt tên theo chuẩn: `UI-Prototype_v1.html` trong thư mục `02.BA-Specs/03.UI-Prototypes/[functionId]/`.

package/custom/skills/ba-skills/{skill-ba-viet-spec-uc-v1.md → skill-ba-write-uc-spec-v1.md}

@@ -23,16 +23,16 @@ Kỹ năng này giúp BA chuyển hóa toàn bộ các thông tin yêu cầu ngh
     - Giá trị mặc định (Default Value).
     - Mô tả hành vi (Description).
 - **Bước 4: Thiết kế sơ đồ Mermaid (Activity Flow):**
-  Áp dụng kỹ năng `@skill-ba-ve-luong-mermaid-v1.md` để vẽ và nhúng biểu đồ Mermaid.
+  Áp dụng kỹ năng `@skill-ba-mermaid-flowchart-v1.md` để vẽ và nhúng biểu đồ Mermaid.
 - **Bước 5: Đặc tả Business Rules (Quy tắc nghiệp vụ):**
-  Áp dụng kỹ năng `@skill-ba-xay-dung-business-rules-v1.md` để viết chi tiết các điều kiện kiểm tra, validation logic và câu thông báo lỗi đi kèm.
+  Áp dụng kỹ năng `@skill-ba-build-business-rules-v1.md` để viết chi tiết các điều kiện kiểm tra, validation logic và câu thông báo lỗi đi kèm.
 
 ## 4. Checklist kiểm tra (Checklist for Verification)
 - [ ] Luồng đi (Flow) có mô tả rõ ràng sự tương tác qua lại giữa Actor và System chưa?
 - [ ] Bảng mô tả UI Components có bị bỏ sót bất kỳ thành phần nào trên prototype HTML không?
 - [ ] Các Business Rules (BR) đã được đánh mã số rõ ràng (BR1, BR2, BR3...) để dễ tham chiếu chưa?
 - [ ] Mọi trường hợp báo lỗi đều có câu thông báo lỗi (Error message) đi kèm chi tiết chưa?
-- [ ] Tài liệu có sử dụng định dạng markdown chuẩn và cấu trúc thống nhất theo mẫu `@skill-ba-template-uc-v1.md` chưa?
+- [ ] Tài liệu có sử dụng định dạng markdown chuẩn và cấu trúc thống nhất theo mẫu `@skill-ba-uc-template-v1.md` chưa?
 
 ## 5. Output mong đợi (Expected Output)
-- Một tài liệu đặc tả Use Case hoàn chỉnh định dạng markdown, đặt tên theo chuẩn: `Tên chức năng_UC.md` trong thư mục `TÀI LIỆU/output/UC/`.
+- Một tài liệu đặc tả Use Case hoàn chỉnh định dạng markdown, đặt tên theo chuẩn: `UC-Spec_v1.md` trong thư mục `02.BA-Specs/04.UC-Specs/[functionId]/`.

package/custom/skills/execute-flow/SKILL.md

@@ -159,7 +159,6 @@ Nhận về: danh sách kết quả per TC.
 
 ### Hiển thị kết quả
 
-```
 ⏸️ GATE 2: SCRIPT SYNC COMPLETE
 
 Gen mới: {N} | Updated: {N} | Skipped: {N}
@@ -170,7 +169,6 @@ Blocked: {N} TCs — xem lý do bên trên
 → Type APPROVED to run tests
 → Type SKIP: {TC_ID} để đánh dấu Pending và tiếp tục
 → Or provide feedback to fix scripts
-```
 
 Dừng. Chờ APPROVED.
 
@@ -307,26 +305,7 @@ Với mỗi TC failed, tạo `ak-test/{repo}/results/{screenId}/run-{N}/bugs/BUG
 
 BUG số: đếm file trong `bugs/` folder, +1. Format: `001`, `002`,...
 
-### Bước 6: Cập nhật TC file gốc
-
-Ghi kết quả vào các cột R1/R2 trong TC file:
-
-- R1 = lần chạy đầu tiên (run-1). Nếu R1 đã có giá trị → ghi vào R2.
-- R1 Tester = `AI-R1`, R2 Tester = `AI-R2`
-
-```markdown
-| AD10_001 | ... | ✅ Pass | {YYYY-MM-DD} | AI-R1 |   |   |   |
-| AD10_005 | ... | ❌ Fail | {YYYY-MM-DD} | AI-R1 |   |   |   |
-| AD10_023 | ... | ⏭️ Untest | - | - |   |   |   |
-```
-
-Cập nhật Section 2 — Test Execution Summary table:
-
-```markdown
-| Round {N} | {passed} | {failed} | {untest} | {pending} | {total} | {passed/total*100}% |
-```
-
-### Bước 7: Hiển thị Gate 3
+### Bước 6: Hiển thị Gate 3
 
 ```
 ⏸️ GATE 3: EXECUTION COMPLETE
@@ -361,8 +340,7 @@ Khi tester gõ `RETEST: AD10_005, AD10_008`:
    ```
 3. Xác định run number mới (run-{N+1})
 4. Tổ chức evidence vào `run-{N+1}/` (không xóa run cũ)
-5. Cập nhật R2 columns trong TC file
-6. Cập nhật bug status:
+5. Cập nhật bug status:
    - TC pass sau retest → ghi `RESOLVED` vào bug file: `**Status:** ✅ Resolved`
    - TC vẫn fail → ghi `**Retest {N}:** Still OPEN` vào bug file
 
@@ -382,11 +360,7 @@ Chỉ chạy sau Gate 3 APPROVED.
 
 Đọc `bugs/BUG-*.md` trong run folder: phân loại severity + status (Open/Resolved).
 
-### Bước 2: Cập nhật Section 2 trong TC file
-
-Cập nhật bảng Test Execution Summary với số liệu từ R1 và R2.
-
-### Bước 3: Sinh testreport.md
+### Bước 2: Sinh testreport.md
 
 Tạo `ak-test/{repo}/results/{screenId}/run-{N}/testreport.md` theo template chuẩn:
 
@@ -422,7 +396,7 @@ Tạo `ak-test/{repo}/results/{screenId}/run-{N}/testreport.md` theo template ch
 - Còn Critical hoặc High Open → No-go
 - Chỉ còn Medium/Low Open → Conditional go
 
-### Bước 4: Bug logging flow
+### Bước 3: Bug logging flow
 
 Hỏi từng bug theo thứ tự severity (Critical → High → Medium → Low):
 
@@ -443,9 +417,8 @@ Nếu tester gõ `Y`:
 
 Nếu `n` hoặc `SKIP-BUG`: ghi `Not logged` trong testreport.md Bug Summary.
 
-### Bước 5: Hiển thị Gate 4
+### Bước 4: Hiển thị Gate 4
 
-```
 ⏸️ GATE 4: REPORT READY
 
 Overall: {Pass / Fail / Conditional}
@@ -456,7 +429,6 @@ Recommendation: {Go / No-go / Conditional go}
 → Review: [ak-test/{repo}/results/{screenId}/run-{N}/testreport.md](ak-test/{repo}/results/{screenId}/run-{N}/testreport.md)
 → Type APPROVED to sign off
 → Type NO-GO: {reason} to reject release
-```
 
 Dừng. Chờ APPROVED hoặc NO-GO.
 
@@ -493,7 +465,6 @@ SKIP-BUG: BUG-{NNN}                   # bỏ qua không log bug này
 
 - ✅ Dừng ở mỗi gate, chờ APPROVED trước khi proceed
 - ✅ `run-{N}` không bao giờ bị xóa hay overwrite — luôn tạo folder mới
-- ✅ R1/R2 trong TC file gốc được cập nhật sau mỗi lần chạy
 - ✅ Hỏi từng bug một — không auto-log toàn bộ
 - ❌ Không lấy expected result từ PR/code — chỉ từ TC file
 - ❌ Không skip gate kể cả khi "chỉ có 1 TC"

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

@@ -44,93 +44,45 @@ Tester Gate 2 produces multiple review files — one per sub-phase. Use a letter
 
 ---
 
-## Mode 1: GENERATE — Write Review File
+## Mode 1: GENERATE — Prepare Inline Review & Output Document
 
-### Step 1: Extract checklist items from gate output
+When generating the output for a gate (e.g. `requirement.md` or `plan.md`), follow these steps:
 
-Read the output you just created. For each **top-level section** in the output, create one checklist item — a one-line summary of what that section contains. The summary must be specific enough to identify the content without opening the output file.
+### Step 1: Ensure review directories and comments database exist
 
-**Extraction rules:**
-- One item per top-level section (H2 heading or named block)
-- Format: `**[Section name]**: [one-line summary of actual content]`
-- Maximum 12 items per gate. If more than 12 sections, group related ones.
-- The summary is the actual content, not a description of the category. ✅ "Scope: Auth module + User management (payment OUT of scope)" not ❌ "Scope: the scope section"
+1. Always create the directory `.aiflow/review/` if it doesn't exist.
+2. Check if `.aiflow/review/comments-[ticket-id].json` exists (where `[ticket-id]` comes from `.aiflow/context/current.json` → `ticketId` field).
+3. If the JSON file does not exist, initialize it by writing an empty array `[]` (or `{ "comments": [] }`) to it. This ensures that the CLI verification commands do not fail due to a missing file when there are no comments.
 
-**Examples by gate:**
-
-Dev Gate 1 (requirement.md has 4 sections → 4 items):
-```
-- [ ] **Requirements Summary**: Add batch export endpoint returning signed S3 URL, triggered by POST /exports
-- [ ] **Proposed Solution**: New ExportService + S3Adapter; reuse existing AuthMiddleware for permissions
-- [ ] **Impact Analysis**: Medium — touches ExportController, UserService (permission check added)
-- [ ] **Effort Estimate**: M (3–4 days)
-```
-
-Tester Gate 1 (test-analysis.md):
-```
-- [ ] **Scope**: Auth module + User management only; payment and notifications OUT of scope
-- [ ] **Functional Analysis**: Login, logout, session management, password reset, role-based access (3 roles)
-- [ ] **Risk Areas**: High — session token handling; Medium — email format validation
-- [ ] **Test Approach**: 60% automation (Playwright), 40% manual; ~18 TCs estimated
-- [ ] **Effort Estimate**: M (2–3 days)
-```
-
-### Step 2: Write the review file
-
-**File path:** `.aiflow/review/gate-[N]-[ticket-id].md`
-
-For Tester Gate 2 sub-phases, use the lettered form: `.aiflow/review/gate-2a-[ticket-id].md`, `.aiflow/review/gate-2b-[ticket-id].md`, etc.
-
-Where `[ticket-id]` comes from `.aiflow/context/current.json` → `ticketId` field. If ticketId is unavailable, use `unknown`.
-
-**File template:**
-
-```markdown
-# Gate [N] Review — [TICKET-ID]
-> Status: PENDING | Generated: YYYY-MM-DD
-
-## How to review
-- Toggle `[ ]` → `[x]` for each item you have read and agree with
-- Add a comment under any item you want changed: `<!-- your comment here -->`
-- Type `APPROVED` in chat when done
-
----
-
-## Checklist
-
-- [ ] **[Section]**: [one-line summary]
-- [ ] **[Section]**: [one-line summary]
-(... one per section, max 12)
-
----
-
-## Review Notes
-<!-- Optional: overall notes -->
-```
+### Step 2: Write the gate output file
+Write the gate output file (e.g. `plan/[ticket-id]/requirement.md`, `plan/[ticket-id]/plan.md`, or `docs/ak-[project]/...`) as specified by the gate instructions.
 
 ### Step 3: Display gate pause message
 
-After writing the file, display in chat:
+Instruct the user to review the generated document. Tell them that they can hover over any line and add inline comments in VS Code using the native commenting UI, or edit the file to add standard HTML comments `<!-- comment -->` if they are not using the VS Code extension.
+
+Display in chat:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ⏸️  GATE [N] PAUSED — REVIEW REQUIRED
 
-📋 Open in VSCode: [.aiflow/review/gate-[N]-[ticket-id].md](.aiflow/review/gate-[N]-[ticket-id].md)
+📋 Open in VS Code: [path/to/generated/file.md](path/to/generated/file.md)
 
-  • Toggle [ ] → [x] for each item you agree with
-  • Add <!-- comment --> under any item needing changes
-  • Type APPROVED when all items are addressed
+  • Review the generated document content directly.
+  • Hover over any line to add specific comments (inline review).
+  • Mark comments as "Resolved" in VS Code once addressed.
+  • Type APPROVED when done.
 
-⚠️  APPROVED will not be accepted until all checkboxes are checked.
+⚠️  APPROVED will not be accepted until all inline comments are resolved.
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
 ---
 
-## Mode 2: VERIFY — Check Review File on APPROVED
+## Mode 2: VERIFY — Check Comments and Checklist on APPROVED
 
-When the developer types `APPROVED`, run this before accepting:
+When the developer types `APPROVED`, run this check:
 
 ### Step 1: Run CLI check
 
@@ -138,58 +90,30 @@ When the developer types `APPROVED`, run this before accepting:
 ak review check --gate [N] --ticket [ticket-id]
 ```
 
-For Tester Gate 2 sub-phases, pass the lettered gate identifier:
-
-```bash
-ak review check --gate 2a --ticket [ticket-id]
-ak review check --gate 2b --ticket [ticket-id]
-```
-
 ### Step 2: Interpret result
 
-**Exit code 0 — all checked:**
+**Exit code 0 — all checked & resolved:**
 - Gate proceeds normally
 - Run telemetry: `ak gate [N] approved --ticket [ticket-id]`
 - Continue to next gate
 
 **Exit code 1 — file missing:**
-```
-  ✗ Review file not found for gate N, ticket PROJ-33
-```
-AI response:
-> "The review file wasn't found. Let me regenerate it."
-Then re-run Mode 1 (generate) and display the gate pause message again.
+- AI response: "The review session files weren't found. Let me prepare them."
+- Re-run Mode 1 (initialize `comments-[ticket-id].json` and output file) and display pause message.
 
 **Exit code 1 — items with comments (need revision):**
-```
-  Items with comments (need AI revision):
-    • **Risk Areas**: High — session token handling
-      Comment: "Missing: SQL injection risk on login form"
-```
-AI response:
-1. Read each comment
-2. Update the specific section in the gate output file
-3. Rewrite only the flagged items in the review file (keep already-checked `[x]` items as-is)
-4. Display updated gate pause message
-
-**Exit code 1 — unchecked items, no comment:**
-```
-  Items unchecked (no comment):
-    • **Scope**: Auth module only
-```
-AI response:
-> "Item(s) are unchecked without a comment. Please either:
-> - Check `[x]` if you agree with the content, or
-> - Add `<!-- your comment -->` on the next line if you want changes."
-Do NOT re-generate. Wait for developer to update the file.
+If the CLI reports unresolved comments, the AI must:
+1. Read the unresolved comments returned by the CLI (which include file path, line number, and comment text).
+2. Read the source file at those line numbers to understand the context.
+3. Update the specific sections of the document to address the comments.
+4. Tell the user what was updated, ask them to mark the comment thread as resolved in VS Code, and type `APPROVED`.
 
 ---
 
 ## Mandatory Rules
 
 - ❌ **NEVER** accept `APPROVED` without first running `ak review check`
-- ❌ **NEVER** re-generate already-checked `[x]` items when doing a partial revision
-- ✅ **ALWAYS** create `.aiflow/review/` directory if it doesn't exist (use `mkdir -p`)
+- ✅ **ALWAYS** ensure `.aiflow/review/` directory exists (use `mkdir -p`)
+- ✅ **ALWAYS** initialize `.aiflow/review/comments-[ticket-id].json` with `[]` if not present when starting a gate pause.
 - ✅ **ALWAYS** use the ticket ID from `.aiflow/context/current.json` in the file name
-- ✅ **ALWAYS** keep review items specific to the actual content — not generic category names
 - ✅ **ALWAYS** use lettered suffixes (`gate-2a`, `gate-2b`, …) for Tester Gate 2 sub-phases — never plain `gate-2`

package/custom/skills/generate-testcase/SKILL.md

@@ -99,13 +99,11 @@ Liệt kê scenarios theo nhóm, output vào `test-plan/checklist.md`:
 📙 **Regression** _(nếu Dev Artifacts Check Bước 2 tìm thấy impacted areas)_
 - Mỗi item ghi rõ: "Regression — [vùng ảnh hưởng] — [lý do từ PR diff]"
 
-```
 ⏸️ GATE 2 — PHASE 2a: SCENARIOS READY
 Scenarios: [N] total
 - Functional: [N] | Non-functional: [N] | Integration: [N] | Exploratory: [N] | Regression: [N]
 → Review: [test-plan/checklist.md](test-plan/checklist.md)
 → Type APPROVED to proceed to Phase 2b
-```
 
 ---
 
@@ -178,14 +176,12 @@ Output testcases: `test-plan/test-cases/[ScreenID]-testcases.md`
 | **Total** | **[S/M/L/XL]** |
 ```
 
-```
 ⏸️ GATE 2 — PHASE 2b: TESTCASES GENERATED
 Test cases: [N] total ([N] positive / [N] negative / [N] edge)
 Test plan:  [test-plan/test-plan.md](test-plan/test-plan.md)
 → Review: [test-plan/test-cases/](test-plan/test-cases/)
 → Type APPROVED to proceed to Phase 2c (Review & Optimize)
 → Or provide feedback to update
-```
 
 ---
 
@@ -229,18 +225,15 @@ Kiểm tra theo thứ tự, output vào `test-plan/review-report.md`:
    Priority: High (phải fix trước Phase 2d) / Medium / Low (có thể defer)
 ```
 
-```
 ⏸️ GATE 2 — PHASE 2c: REVIEW COMPLETE
 Issues: [N] duplicate | [N] problematic | [N] to optimize | [N] missing
 High priority chưa xử lý: [N]
 → Review: [test-plan/review-report.md](test-plan/review-report.md)
 → Type APPROVED to proceed to Phase 2d (chỉ khi High priority = 0)
 → Or provide specific fixes to apply
-```
 
 **Nếu nhận được APPROVED mà còn issues Priority High chưa xử lý → từ chối ngay:**
 
-```
 ⛔ PHASE 2c BLOCKED — Còn [N] issues Priority HIGH chưa được xử lý:
 
 | TC_ID | Vấn đề | Đề xuất sửa |
@@ -250,7 +243,6 @@ High priority chưa xử lý: [N]
 → Cung cấp fixes cho các issues trên, sau đó gõ APPROVED.
 ❌ APPROVED chỉ được chấp nhận khi không còn issues Priority High.
 Medium và Low có thể defer — không block APPROVED.
-```
 
 ---