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

package/custom/templates/shared/create-testcase-workflow.md

@@ -13,9 +13,9 @@ Các skill sau đây được cài tự động vào `.claude/skills/test-skills
 
 | Skill | File |
 |---|---|
-| `QA Writing Standards` | `.claude/skills/test-skills/rules/QA_Writing_Standards.md` |
-| `Directory & Naming Convention` | `.claude/skills/test-skills/rules/Directory_and_Naming_Convention.md` |
-| `Template TestCase` | `.claude/skills/test-skills/template/template_testcase.md` |
+| `QA Writing Standards` | `.claude/skills/test-skills/rules/qa-writing-standards.md` |
+| `Directory & Naming Convention` | `.claude/skills/test-skills/rules/directory-and-naming-convention.md` |
+| `Template TestCase` | `.claude/skills/test-skills/template/testcase-template.md` |
 | `00.01 Requirement Analysis` | `.claude/skills/test-skills/categories/00-core/00.01.requirement-analysis.md` |
 | `00.02 Risk Analysis` | `.claude/skills/test-skills/categories/00-core/00.02.risk-analysis.md` |
 | `00.03 Test Scenario Builder` | `.claude/skills/test-skills/categories/00-core/00.03.test-scenario-builder.md` |
@@ -46,40 +46,40 @@ Các skill sau đây được cài tự động vào `.claude/skills/test-skills
 ### Cấu trúc thư mục đầu ra
 
 ```
-docs/ak-{project}/testcase/
-├── Result/
-│   ├── [functionId]_01_Requirement_Analysis_Result.md     ← Gate 1 tạo
-│   ├── [functionId]_02_Test_Scenarios_Result.md           ← Gate 2 tạo
-│   ├── [functionId]_03_Test_Cases_Draft_Result.md         ← Gate 3 tạo
-│   └── [functionId]_04_Test_Cases_Final_Result.md         ← Gate 4 tạo (đồng thời với TestCase)
-├── QA/
-│   ├── [functionId]_01_Requirement_Analysis_QA.md         ← Gate 1 tạo (nếu có issue)
-│   ├── [functionId]_02_Scenario_Building_QA.md            ← Gate 2 tạo (nếu có issue)
-│   ├── [functionId]_03_Test_Design_QA.md                  ← Gate 3 tạo (nếu có issue)
-│   └── [functionId]_04_Test_Review_QA.md                  ← Gate 4 tạo
-└── TestCase/
-    └── [functionId]_TestCase.md                           ← Gate 4 tạo đồng thời với 04_Final_Result
+03.Testing/
+├── 01.Testcases/
+│   └── [functionId]/[functionId]_TestCase.md                  ← Gate 4 tạo
+└── 07.AI-Artifacts/
+    └── [functionId]/
+        ├── [functionId]_01_Requirement_Analysis_Result.md     ← Gate 1 tạo
+        ├── [functionId]_01_Requirement_Analysis_QA.md         ← Gate 1 tạo (nếu có issue)
+        ├── [functionId]_02_Test_Scenarios_Result.md           ← Gate 2 tạo
+        ├── [functionId]_02_Scenario_Building_QA.md            ← Gate 2 tạo (nếu có issue)
+        ├── [functionId]_03_Test_Cases_Draft_Result.md         ← Gate 3 tạo
+        ├── [functionId]_03_Test_Design_QA.md                  ← Gate 3 tạo (nếu có issue)
+        ├── [functionId]_04_Test_Cases_Final_Result.md         ← Gate 4 tạo (cùng TestCase)
+        └── [functionId]_04_Test_Review_QA.md                  ← Gate 4 tạo
 ```
 
-Ví dụ: `functionId = AD06`, `project = kcandy` → thư mục gốc là `docs/ak-kcandy/testcase/`
+Ví dụ: `functionId = AD06` → thư mục gốc là `03.Testing/`
 
 ---
 
 ### Quy trình tổng quan 4 Gates
 
 ```
-(testcase/ = docs/ak-{project}/testcase/ — viết tắt cho ngắn gọn)
+(AI-Artifacts/ = 03.Testing/07.AI-Artifacts/ — viết tắt cho ngắn gọn)
 
-[Input: SRS / Jira / Backlog / Spec file] → Pre-flight: xác định functionId + thư mục đầu ra
+[Input: SRS / Jira / Backlog / Spec file] → Pre-flight: BẮT BUỘC xác định functionId
     ↓
-Gate 1: Phân tích yêu cầu & Đánh giá rủi ro  → testcase/Result/ + testcase/QA/
+Gate 1: Phân tích yêu cầu & Đánh giá rủi ro  → AI-Artifacts/[functionId]/
     ↓ APPROVED
-Gate 2: Xây dựng Kịch bản (Scenario Building) → testcase/Result/ + testcase/QA/
+Gate 2: Xây dựng Kịch bản (Scenario Building) → AI-Artifacts/[functionId]/
     ↓ APPROVED
-Gate 3: Thiết kế Test Case chi tiết           → testcase/Result/ + testcase/QA/
+Gate 3: Thiết kế Test Case chi tiết           → AI-Artifacts/[functionId]/
     ↓ APPROVED
-Gate 4: Review & Tối ưu hóa                  → testcase/Result/ + testcase/QA/
-                                              + testcase/TestCase/[functionId]_TestCase.md
+Gate 4: Review & Tối ưu hóa                  → AI-Artifacts/[functionId]/
+                                              + 03.Testing/01.Testcases/[functionId]/[functionId]_TestCase.md
     ↓ APPROVED (Fully / Conditionally)
 Sẵn sàng thực thi kiểm thử
 ```
@@ -88,57 +88,47 @@ Sẵn sàng thực thi kiểm thử
 
 ### GATE 1 — Phân tích yêu cầu & Đánh giá rủi ro (auto-start)
 
-**Mục tiêu:** Tiếp nhận đầu vào, hiểu nghiệp vụ, xác định phạm vi kiểm thử, nhận diện rủi ro và phát hiện vấn đề cần làm rõ trước khi xây dựng kịch bản.
+**Mục tiêu:** Tiếp nhận đầu vào, hiểu nghiệp vụ, xác định phạm vi kiểm thử, nhận diện rủi ro và **đào sâu làm rõ toàn bộ vấn đề mơ hồ ngay tại gate này** (hỏi QA từng câu một, tiếp tục đến khi hết nghi vấn Critical/Major) — để Gate 2, 3, 4 phía sau hiếm khi phải dừng lại hỏi thêm.
 
 **Đầu ra (Outputs):**
-- `docs/ak-{project}/testcase/Result/[functionId]_01_Requirement_Analysis_Result.md`
-- `docs/ak-{project}/testcase/QA/[functionId]_01_Requirement_Analysis_QA.md` (nếu có issue)
+- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_01_Requirement_Analysis_Result.md`
+- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_01_Requirement_Analysis_QA.md` (nếu có issue)
 
 **Bước thực hiện:**
 
 #### Bước 0: Pre-flight — Xác định functionId và thư mục đầu ra
 
-**Xác định `functionId`:**
+**Xác định `functionId` (BẮT BUỘC):**
 
 Kiểm tra theo thứ tự ưu tiên:
 1. Trường `functionId` hoặc `screenId` trong `.aiflow/context/current.json`
 2. Rút gọn từ `ticketId` — bỏ dấu gạch, giữ ký hiệu (ví dụ: `AD-06` → `AD06`)
-3. Nếu không tìm thấy → **hỏi QA ngay**:
+3. Nếu không tìm thấy → **BẮT BUỘC hỏi QA ngay**:
 
 ```
 Không tìm thấy functionId trong context.
 Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-LOGIN, PM-003):
 ```
 
-→ Đợi QA trả lời, ghi nhận giá trị, dùng cho toàn bộ workflow.
+→ Đợi QA trả lời, ghi nhận giá trị, dùng cho toàn bộ workflow. KHÔNG ĐƯỢC TIẾP TỤC NẾU CHƯA CÓ functionId.
 
-**Xác định `{project}` và thư mục đầu ra:**
+**Xác định thư mục đầu ra:**
 
-1. Lấy `{project}` theo thứ tự ưu tiên:
-   - Trường `project` trong `.aiflow/context/current.json`
-   - Tên thư mục gốc workspace (chuyển lowercase, thay space bằng `-`)
-
-2. Kiểm tra tồn tại thư mục `docs/ak-{project}/testcase/` trong root dự án:
+1. Kiểm tra tồn tại thư mục `03.Testing/` trong root dự án:
    - **Tìm thấy** → thông báo xác nhận:
      ```
-     ✓ Thư mục đầu ra: docs/ak-{project}/testcase/
+     ✓ Thư mục đầu ra: 03.Testing/
      ✓ functionId: [functionId]
      → Bắt đầu Gate 1...
      ```
-   - **Không tìm thấy** → **hỏi QA**:
-     ```
-     Không tìm thấy thư mục docs/ak-{project}/testcase/.
-     Tên project là gì? (ví dụ: kcandy, crm-app)
-     ```
-     → Nhận tên project từ QA → chuyển lowercase → tạo toàn bộ cây thư mục:
+   - **Không tìm thấy** → tạo toàn bộ cây thư mục:
      ```
-     docs/ak-{project}/testcase/Result/
-     docs/ak-{project}/testcase/QA/
-     docs/ak-{project}/testcase/TestCase/
+     03.Testing/01.Testcases/[functionId]/
+     03.Testing/07.AI-Artifacts/[functionId]/
      ```
      → Thông báo:
      ```
-     ✓ Đã tạo thư mục: docs/ak-{project}/testcase/
+     ✓ Đã tạo thư mục: 03.Testing/
      ✓ functionId: [functionId]
      → Bắt đầu Gate 1...
      ```
@@ -150,7 +140,7 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 - Nếu có file yêu cầu thô được chỉ định → đọc file đó
 
 #### Bước 2: Phân tích yêu cầu và đánh giá rủi ro
-- **READ skill:** `.claude/skills/test-skills/rules/QA_Writing_Standards.md` — đọc trước để nắm quy ước chung
+- **READ skill:** `.claude/skills/test-skills/rules/qa-writing-standards.md` — đọc trước để nắm quy ước chung
 - **READ skill:** `.claude/skills/test-skills/categories/00-core/00.01.requirement-analysis.md`
 - **READ skill:** `.claude/skills/test-skills/categories/00-core/00.02.risk-analysis.md`
 - Phân tích đầy đủ **16 mục** theo skill 00.01:
@@ -171,17 +161,24 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
   15. Risk / điểm dễ lỗi
   16. Q&A / Out of Scope
 - Đánh giá rủi ro theo skill 00.02: kỹ thuật, dữ liệu, nghiệp vụ, hệ thống
-- **Issue Handling:**
-  - Critical/Major → DỪNG, tạo QA artifact, chờ phản hồi (không sinh Result artifact)
-  - Minor → Ghi TBD marker (`[TBD — <issue-id>: mô tả]`), tiếp tục, carry-forward sang gate sau
+
+#### Bước 2b: Đào sâu làm rõ với QA/Stakeholder (Interactive Clarification)
+**Mục tiêu:** xử lý dứt điểm mọi mơ hồ/nghi vấn ngay tại Gate 1 — đây là gate DUY NHẤT được phép dừng lại hỏi tự do; Gate 2-4 sau đó chỉ hỏi cho phát sinh thực sự mới (xem quy tắc ở các Gate đó).
+
+- **Critical/Major** → **KHÔNG** chỉ gộp vào một file QA rồi im lặng chờ. Hỏi ngay trong hội thoại theo đúng Interaction Rule đã khai báo (hỏi **TỪNG CÂU MỘT**, đợi QA trả lời rồi mới hỏi câu tiếp theo, KHÔNG hỏi dồn nhiều câu):
+  - Với mỗi nghi vấn ở mục 16 (Q&A/Out of Scope) hoặc phát sinh trong lúc phân tích 16 mục, ưu tiên đề xuất 2-3 cách hiểu/giả định hợp lý để QA chọn nhanh (multiple-choice) thay vì hỏi mở.
+  - Tiếp tục hỏi tuần tự, đào sâu thêm nếu câu trả lời còn hé lộ nghi vấn mới, cho đến khi **không còn Critical/Major nào chưa rõ**.
+  - Không sinh Result artifact (Bước 3) trước khi toàn bộ Critical/Major đã được làm rõ.
+- **Minor** → Ghi TBD marker (`[TBD — <issue-id>: mô tả]`), tiếp tục, carry-forward sang gate sau (không cần dừng hỏi).
 
 #### Bước 3: Soạn thảo kết quả phân tích yêu cầu
 - Artifact đầu ra phải có: Feature Summary, Actor & Persona, Business Rules (16 mục), Risk Matrix, Test Scope
-- Lưu: `docs/ak-{project}/testcase/Result/[functionId]_01_Requirement_Analysis_Result.md`
+- Lưu: `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_01_Requirement_Analysis_Result.md`
 
-#### Bước 4: Soạn thảo QA Artifact (nếu có issue)
-- Cấu trúc: Metadata, Detected Issues (Severity), Clarification Questions, Assumptions, Resolution Tracking
-- Lưu: `docs/ak-{project}/testcase/QA/[functionId]_01_Requirement_Analysis_QA.md`
+#### Bước 4: Soạn thảo QA Artifact (biên bản resolution, nếu có issue)
+- File này ghi lại **kết quả** của Bước 2b (đã hỏi gì, QA trả lời gì) — không phải cơ chế dừng chính.
+- Cấu trúc: Metadata, Detected Issues (Severity), Clarification Questions kèm Câu trả lời đã nhận, Assumptions, Resolution Tracking
+- Lưu: `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_01_Requirement_Analysis_QA.md`
 
 #### Bước 5: Gate Review & Pause
 - **INVOKE** `gate-review` skill (generate mode) — ghi `.aiflow/review/gate-1-[functionId].md`
@@ -193,9 +190,10 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 → Nếu blocked: làm theo gate-review skill response protocol
 
 **Definition of Done:**
-- [ ] `functionId` và `{project}` đã được xác định, thư mục đầu ra đã sẵn sàng
+- [ ] `functionId` đã được xác định, thư mục đầu ra đã sẵn sàng
 - [ ] File `01_Requirement_Analysis_Result.md` có đủ 16 mục + Risk Matrix + Test Scope
-- [ ] File `01_Requirement_Analysis_QA.md` đã tạo nếu có issue (Critical/Major đã giải quyết)
+- [ ] Toàn bộ Critical/Major đã được hỏi trực tiếp (từng câu một) và có câu trả lời từ QA — không còn nghi vấn bỏ ngỏ
+- [ ] File `01_Requirement_Analysis_QA.md` đã tạo nếu có issue, ghi lại đầy đủ câu hỏi + câu trả lời (Bước 2b)
 - [ ] Không có giả định nào được tự ý chốt thành fact mà không đưa vào QA
 
 > **Telemetry:** Run `ak gate 1 start --ticket [functionId]` khi bắt đầu gate này.
@@ -210,11 +208,11 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 **Điều kiện vào Gate 2:** Gate 1 đã **APPROVED** và `01_Requirement_Analysis_Result.md` đã hoàn chỉnh.
 
 **Đầu vào (Inputs):**
-- `docs/ak-{project}/testcase/Result/[functionId]_01_Requirement_Analysis_Result.md`
+- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_01_Requirement_Analysis_Result.md`
 
 **Đầu ra (Outputs):**
-- `docs/ak-{project}/testcase/Result/[functionId]_02_Test_Scenarios_Result.md`
-- `docs/ak-{project}/testcase/QA/[functionId]_02_Scenario_Building_QA.md` (nếu có issue)
+- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_02_Test_Scenarios_Result.md`
+- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_02_Scenario_Building_QA.md` (nếu có issue)
 
 **Bước thực hiện:**
 
@@ -245,10 +243,11 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
   - Cột: Scenario ID, Feature/Module, Check List, Scenario Type, Target Req ID, Priority, Test Data
 - Business Flow Mapping (E2E diagram dạng text)
 - Draft RTM (Scenario ID → Requirement ID từ `01_Requirement_Analysis_Result.md`)
-- Lưu: `docs/ak-{project}/testcase/Result/[functionId]_02_Test_Scenarios_Result.md`
+- Lưu: `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_02_Test_Scenarios_Result.md`
 
-#### Bước 5: Soạn thảo QA Artifact (nếu có issue)
-- Lưu: `docs/ak-{project}/testcase/QA/[functionId]_02_Scenario_Building_QA.md`
+#### Bước 5: Soạn thảo QA Artifact (nếu có issue — NGOẠI LỆ)
+- **Chỉ tạo khi có vấn đề THỰC SỰ MỚI**, chỉ lộ ra khi xây dựng kịch bản (vd: một nhánh luồng nghiệp vụ không thấy được ở mức phân tích yêu cầu). **KHÔNG** hỏi lại điều đã có câu trả lời/assumption trong `01_Requirement_Analysis_Result.md` hoặc `01_Requirement_Analysis_QA.md` — đọc lại 2 file đó trước khi quyết định hỏi thêm.
+- Lưu: `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_02_Scenario_Building_QA.md`
 - Minor issues → TBD marker + carry-forward, tiếp tục workflow
 
 #### Bước 6: Gate Review & Pause
@@ -279,18 +278,18 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 **Điều kiện vào Gate 3:** Gate 2 đã **APPROVED** và `02_Test_Scenarios_Result.md` đã hoàn chỉnh.
 
 **Đầu vào (Inputs):**
-- `docs/ak-{project}/testcase/Result/[functionId]_01_Requirement_Analysis_Result.md`
-- `docs/ak-{project}/testcase/Result/[functionId]_02_Test_Scenarios_Result.md`
+- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_01_Requirement_Analysis_Result.md`
+- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_02_Test_Scenarios_Result.md`
 
 **Đầu ra (Outputs):**
-- `docs/ak-{project}/testcase/Result/[functionId]_03_Test_Cases_Draft_Result.md`
-- `docs/ak-{project}/testcase/QA/[functionId]_03_Test_Design_QA.md` (nếu có issue)
+- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_03_Test_Cases_Draft_Result.md`
+- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_03_Test_Design_QA.md` (nếu có issue)
 
 **Bước thực hiện:**
 
 #### Bước 1: Đọc template và quy ước bắt buộc
-- **READ template:** `.claude/skills/test-skills/template/template_testcase.md` — **BẮT BUỘC** tuân thủ 100%
-- **READ skill:** `.claude/skills/test-skills/rules/QA_Writing_Standards.md`
+- **READ template:** `.claude/skills/test-skills/template/testcase-template.md` — **BẮT BUỘC** tuân thủ 100%
+- **READ skill:** `.claude/skills/test-skills/rules/qa-writing-standards.md`
 
 #### Bước 2: Áp dụng kỹ thuật thiết kế TC cơ bản (luôn áp dụng)
 - **READ:** `.claude/skills/test-skills/categories/01-test-design/01.01.boundary-value-analysis.md` — BVA cho tất cả trường số/text có giới hạn
@@ -329,10 +328,11 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
   - **Section 3.5**: Exceptions & Systems (Error Guessing cases)
 - Bổ sung: Coverage Matrix (Scenario ID → TC ID), Test Data tổng hợp
 - Ghi TBD marker khi thiếu thông tin: `[TBD — <issue-id>: mô tả ngắn]`
-- Lưu: `docs/ak-{project}/testcase/Result/[functionId]_03_Test_Cases_Draft_Result.md`
+- Lưu: `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_03_Test_Cases_Draft_Result.md`
 
-#### Bước 7: Soạn thảo QA Artifact (nếu có issue)
-- Lưu: `docs/ak-{project}/testcase/QA/[functionId]_03_Test_Design_QA.md`
+#### Bước 7: Soạn thảo QA Artifact (nếu có issue — NGOẠI LỆ)
+- **Chỉ tạo khi có vấn đề THỰC SỰ MỚI**, chỉ lộ ra khi thiết kế test case chi tiết (vd: một tổ hợp dữ liệu biên chưa từng được nhắc tới). **KHÔNG** hỏi lại điều đã có câu trả lời/assumption trong artifact của Gate 1 hoặc Gate 2 — đọc lại các file đó trước khi quyết định hỏi thêm.
+- Lưu: `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_03_Test_Design_QA.md`
 - Cấu trúc: Metadata, Detected Issues, Clarification Questions, Assumptions, Resolution Tracking
 
 #### Bước 8: Gate Review & Pause
@@ -345,7 +345,7 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 → Nếu blocked: làm theo gate-review skill response protocol
 
 **Definition of Done:**
-- [ ] 100% tuân thủ `template_testcase.md` — không tự định nghĩa cấu trúc mới
+- [ ] 100% tuân thủ `testcase-template.md` — không tự định nghĩa cấu trúc mới
 - [ ] Mọi trường input (cả Required và Optional) đã qua ma trận skill 02.02
 - [ ] TC Name section 3.3 bắt đầu bằng `"Kiểm tra trường [Tên Trường]..."`
 - [ ] Coverage Matrix mapping Scenario ID → TC ID đầy đủ
@@ -364,13 +364,13 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 **Điều kiện vào Gate 4:** Gate 3 đã **APPROVED** và `03_Test_Cases_Draft_Result.md` đã hoàn chỉnh.
 
 **Đầu vào (Inputs):**
-- `docs/ak-{project}/testcase/Result/[functionId]_01_Requirement_Analysis_Result.md`
-- `docs/ak-{project}/testcase/Result/[functionId]_03_Test_Cases_Draft_Result.md`
+- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_01_Requirement_Analysis_Result.md`
+- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_03_Test_Cases_Draft_Result.md`
 
 **Đầu ra (Outputs) — sinh ĐỒNG THỜI:**
-- `docs/ak-{project}/testcase/Result/[functionId]_04_Test_Cases_Final_Result.md`
-- `docs/ak-{project}/testcase/QA/[functionId]_04_Test_Review_QA.md`
-- `docs/ak-{project}/testcase/TestCase/[functionId]_TestCase.md`
+- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_04_Test_Cases_Final_Result.md`
+- `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_04_Test_Review_QA.md`
+- `03.Testing/01.Testcases/[functionId]/[functionId]_TestCase.md`
 
 > **Quy tắc Gate 4:** Ba artifact trên phải được sinh ĐỒNG THỜI. Không tạo một file mà thiếu file kia.
 
@@ -401,19 +401,19 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
   - Final Test Cases (Approved, đã loại trùng và out-of-scope)
   - RTM Final (Req ID → Scenario ID → TC ID)
   - Sign-off Status (xem bảng bên dưới)
-- Lưu: `docs/ak-{project}/testcase/Result/[functionId]_04_Test_Cases_Final_Result.md`
+- Lưu: `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_04_Test_Cases_Final_Result.md`
 
 #### Bước 4: Soạn thảo QA Artifact
 - Artifact `[functionId]_04_Test_Review_QA.md` gồm: Metadata, Findings, Issues, Sign-off Status
-- Lưu: `docs/ak-{project}/testcase/QA/[functionId]_04_Test_Review_QA.md`
+- Lưu: `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_04_Test_Review_QA.md`
 
 #### Bước 5: Sinh TestCase Artifact — BẮT BUỘC đồng thời với Bước 3 & 4
-- Artifact `[functionId]_TestCase.md` theo `template_testcase.md` — **chỉ gồm:**
+- Artifact `[functionId]_TestCase.md` theo `testcase-template.md` — **chỉ gồm:**
   - **Mục 1**: Thông tin chung (điền functionId, ngày tạo)
   - **Mục 2**: Kết quả kiểm thử tổng hợp (reset về 0 chờ execution)
   - **Mục 3**: Danh sách Test Cases Chi Tiết (toàn bộ 5 sections đã Approved)
 - **KHÔNG chứa:** Review Summary, Findings, RTM, Coverage Matrix, Sign-off (thuộc `04_Final_Result.md`)
-- Lưu: `docs/ak-{project}/testcase/TestCase/[functionId]_TestCase.md`
+- Lưu: `03.Testing/01.Testcases/[functionId]/[functionId]_TestCase.md`
 
 #### Bước 6: Xác nhận Sign-off Status
 
@@ -451,7 +451,7 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 |---|---|---|
 | Gate 1 | `QA_Writing_Standards`, `00.01 Requirement Analysis`, `00.02 Risk Analysis` | `01_Requirement_Analysis_Result.md`, `01_QA.md` |
 | Gate 2 | `00.03 Scenario Builder`, `01.06 Error Guessing`, `03.02 Workflow Testing`, Domain skills | `02_Test_Scenarios_Result.md`, `02_QA.md` |
-| Gate 3 | `template_testcase`, `01.01 BVA`, `01.02 EP`, `01.03 Decision Table`, `01.06 Error Guessing`, `02.01`–`02.04`, `03.01`, `03.03`, `04.01`, `04.04` | `03_Test_Cases_Draft_Result.md`, `03_QA.md` |
+| Gate 3 | `testcase-template`, `01.01 BVA`, `01.02 EP`, `01.03 Decision Table`, `01.06 Error Guessing`, `02.01`–`02.04`, `03.01`, `03.03`, `04.01`, `04.04` | `03_Test_Cases_Draft_Result.md`, `03_QA.md` |
 | Gate 4 | `00.04 TC Review`, `99.01 Coverage Review` | `04_Final_Result.md`, `04_QA.md`, `[functionId]_TestCase.md` |
 
 ---
@@ -465,6 +465,8 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 - ✅ **BẮT BUỘC** chạy Bước 0 ở Gate 1 — xác nhận `functionId` và thư mục đầu ra trước khi làm bất cứ điều gì
 - ✅ **BẮT BUỘC** đọc skill từ `.claude/skills/test-skills/` — không suy luận từ bộ nhớ
 - ✅ **BẮT BUỘC** invoke `gate-review` cuối mỗi gate và chờ APPROVED
-- ✅ **BẮT BUỘC** tuân thủ 100% `template_testcase.md` ở Gate 3 và Gate 4
+- ✅ **BẮT BUỘC** tuân thủ 100% `testcase-template.md` ở Gate 3 và Gate 4
 - ✅ **BẮT BUỘC** ba artifact Gate 4 sinh ĐỒNG THỜI
 - ✅ **BẮT BUỘC** Issue Critical/Major phải giải quyết xong trước khi sinh Result artifact
+- ✅ **BẮT BUỘC** Gate 1 là gate đào sâu Q&A chính — hỏi QA từng câu một (Bước 2b) cho đến khi hết nghi vấn Critical/Major, trước khi chuyển Gate 2
+- ❌ **KHÔNG** ở Gate 2-4 tạo QA artifact/hỏi lại cho vấn đề đã có câu trả lời hoặc assumption rõ ràng trong artifact của gate trước — QA artifact ở các gate này chỉ dành cho phát sinh THỰC SỰ MỚI

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

@@ -29,28 +29,69 @@ If `taskType` is missing or unrecognized, default to the DEV workflow and ask ON
 
 > **For:** `feature` · `bug-fix` · `refactor` · `investigation` · `documentation`
 
+### Cấu trúc thư mục đầu ra
+
+```
+04.Coding/
+├── 00.Overview/_Index.md                          ← Tracker: F-ID | Ticket | Dev | Gate | PR (cập nhật mỗi gate)
+├── 01.Requirements/[functionId]/[ticketId].md    ← Gate 1 tạo
+├── 02.Plans/[functionId]/[ticketId].md           ← Gate 2 tạo
+├── 03.TDD-Notes/[functionId]/[ticketId].md       ← Gate 3 tạo
+├── 04.Reviews/[functionId]/[ticketId].md         ← Gate 4 tạo
+└── 05.Pull-Requests/[functionId]/[ticketId].md   ← Gate 5 tạo
+```
+
+- `[functionId]`: mã định danh chức năng **do dự án quy định** (ví dụ `F-001_User-Login`, `AD06`, `UC-LOGIN`) — không ép format. Một feature có thể có nhiều ticket → folder theo functionId, file theo ticketId.
+- `[ticketId]`: lấy từ `taskId` trong `.aiflow/context/current.json` (ví dụ `TICKET-100.md`).
+
 ### GATE 1 — AI Analyze Requirement (auto-start)
 
 **INVOKE:** `read-study-requirement` skill
 
 AI actively reads ticket + source code to understand the requirement:
+
+0. **Pre-flight — xác định `functionId` và thư mục đầu ra (BẮT BUỘC):**
+
+   Kiểm tra theo thứ tự ưu tiên:
+   1. Trường `functionId` hoặc `screenId` trong `.aiflow/context/current.json`
+   2. **Suy ra từ input**: nếu đầu vào có file UC Spec / tài liệu do BA bàn giao (trong `supplementaryContext[]`, description, hoặc file được chỉ định khi `ak use <file>`) → đọc nội dung file để tìm functionId, hoặc suy từ đường dẫn thư mục chứa file (ví dụ file nằm ở `02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v1.md` → lấy `[functionId]`). Có thể tra thêm `04.Coding/00.Overview/_Index.md` hoặc `00.Project-Overview/Function-List.md` theo tên feature.
+      → Tìm được ứng viên → **hỏi xác nhận** thay vì hỏi trống:
+      ```
+      functionId của task này có phải là [X] không? (Y / hoặc nhập giá trị đúng)
+      ```
+   3. Không suy ra được → hỏi DEV trực tiếp:
+      ```
+      Không tìm thấy functionId trong context.
+      Vui lòng cung cấp mã định danh chức năng theo quy ước dự án (ví dụ: F-001_User-Login, AD06):
+      ```
+
+   → Đợi DEV trả lời, dùng giá trị này cho toàn bộ 5 Gates. **KHÔNG ĐƯỢC TIẾP TỤC NẾU CHƯA CÓ functionId.**
+
+   Sau đó kiểm tra thư mục `04.Coding/` trong root dự án — chưa có thì tạo đủ cây thư mục (00.Overview → 05.Pull-Requests) và file tracker `00.Overview/_Index.md`. Thông báo:
+   ```
+   ✓ Thư mục đầu ra: 04.Coding/
+   ✓ functionId: [functionId]  ✓ ticketId: [ticketId]
+   → Bắt đầu Gate 1...
+   ```
+
 1. Read `.aiflow/context/current.json` — ticket info
 2. **Pre-flight: sync with remote** — run `git status --porcelain`; if working tree is clean, run `git pull --ff-only` to pull the latest source from remote. Skip the pull (with a `⚠️` notice to DEV) if there are uncommitted changes, the branch has diverged, or no remote tracking branch exists.
 3. Read source code — architecture, related files, data flow
 4. If anything is unclear — ask ONE question at a time, wait for reply
-5. Output `plan/[ticket-id]/requirement.md` with:
-   - Requirements summary, source code analysis
+5. Output `04.Coding/01.Requirements/[functionId]/[ticketId].md` with:
+   - Requirements summary (ticket summary + AC), source code analysis
    - Proposed solution and approach
    - Impact analysis, effort estimate, testing plan
-6. **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-1-[ticket-id].md`
-7. Display gate pause message from `gate-review` skill — wait for **APPROVED**
+6. Update tracker row in `04.Coding/00.Overview/_Index.md`: `| [F-ID] | [ticketId] | [feature] | [dev] | ✅⬜⬜⬜⬜ Gate 1 | - |`
+7. **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-1-[ticket-id].md`
+8. Display gate pause message from `gate-review` skill — wait for **APPROVED**
 
 **When APPROVED received:**
 → **INVOKE** `gate-review` skill (verify mode) — run `ak review check --gate 1 --ticket [ticket-id]`
 → If passed: run `ak gate 1 approved --ticket [ticket-id]` → proceed to Gate 2
 → If blocked: follow gate-review skill response protocol
 
-> **Tip:** If auto-start doesn't trigger, the developer can start this gate by typing: **"start"**, **"Gate 1"** or **"Analyze ticket"**.
+> **Tip:** If auto-start doesn't trigger, the developer can start this gate by typing: **"start"**, **"Gate 1"** or **"Analyze ticket"**. If this chat session was already open when the ticket was loaded (`ak use`), those phrases won't mean anything to the AI yet since the `SessionStart` hook did not re-run — run **`/coding`** instead to load the ticket context manually.
 
 DO NOT just check format — **understand the content and propose solutions**.
 
@@ -63,8 +104,9 @@ DO NOT just check format — **understand the content and propose solutions**.
 
 **INVOKE:** `generate-spec` skill, then `superpowers:writing-plans`
 
-- Create a detailed TDD implementation plan based on the approved requirement.
-- Output `plan/[ticket-id]/plan.md` with the detailed TDD implementation plan.
+- Create a detailed TDD implementation plan based on the approved requirement (`04.Coding/01.Requirements/[functionId]/[ticketId].md`).
+- Output `04.Coding/02.Plans/[functionId]/[ticketId].md` with the detailed TDD implementation plan (step-by-step, file list, test-first order).
+- Update tracker row in `04.Coding/00.Overview/_Index.md` (Gate 2 ✅).
 - **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-2-[ticket-id].md`
 - Display gate pause message from `gate-review` skill — CODE WILL NOT BE GENERATED until all items checked and APPROVED received.
 
@@ -86,6 +128,10 @@ Only runs after Gate 2 has been APPROVED.
 - 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.
+- Output `04.Coding/03.TDD-Notes/[functionId]/[ticketId].md`:
+  - **Test List** — danh sách test viết TRƯỚC khi implement (checklist `- [ ] TC-01: ...`)
+  - **Implementation Notes** — ghi chú phát sinh trong quá trình code
+- Update tracker row in `04.Coding/00.Overview/_Index.md` (Gate 3 ✅) when tests PASS.
 
 > **Telemetry:** Run `ak gate 3 start --ticket [ticket-id]` when starting this gate. Run as-is — do NOT append shell redirects.
 
@@ -99,7 +145,8 @@ 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`
+4. Create `04.Coding/04.Reviews/[functionId]/[ticketId].md` — Test Results, Impact Analysis (files changed, affected features, breaking changes), Review Checklist
+5. Update tracker row in `04.Coding/00.Overview/_Index.md` (Gate 4 ✅)
 
 Then:
 - **INVOKE** `gate-review` skill (generate mode) — write `.aiflow/review/gate-4-[ticket-id].md`
@@ -124,7 +171,13 @@ Then:
 Only runs after Gate 4 has been APPROVED.
 
 **INVOKE:** `superpowers:requesting-code-review`
-Guide on creating a Pull Request with the ticket link.
+
+1. Create `04.Coding/05.Pull-Requests/[functionId]/[ticketId].md` — PR description gồm:
+   - Ticket link, danh sách thay đổi chính, How to Test, Checklist for Reviewer
+   - **Related Docs links:** UC Spec (`02.BA-Specs/04.UC-Specs/[functionId]/`), Test Case (`03.Testing/01.Testcases/[functionId]/`), Dev Plan (`04.Coding/02.Plans/[functionId]/[ticketId].md`)
+2. **Lưu tài liệu `04.Coding/` lên remote (GitLab) TRƯỚC khi tạo Pull Request.**
+3. Guide on creating a Pull Request — dùng nội dung file trên làm PR description.
+4. Update tracker row in `04.Coding/00.Overview/_Index.md` (Gate 5 ✅ Done + PR link).
 
 > **Telemetry:** Run `ak gate 5 start --ticket [ticket-id]` when starting this gate. Run as-is — do NOT append shell redirects.
 
@@ -357,7 +410,7 @@ Coverage: [N]% acceptance criteria
 
 ### GATE 1 — Pre-flight & Work Plan (auto-start)
 
-**INVOKE:** `execute-flow` skill (from `custom/skills/execute-flow/SKILL.md`)
+**INVOKE:** `execute-flow` skill (from `custom/skills/test-skills/execute-flow/SKILL.md`)
 
 Pre-flight checks (stop and report if any fail):
 0. **MCP Playwright is configured** — check `~/.claude/settings.json` (global user-level) for a `playwright` key in `mcpServers`. This is global — set once, works across all repos.
@@ -396,7 +449,7 @@ BASE_URL: [url]
 
 Only runs after Gate 1 APPROVED.
 
-**INVOKE:** `script-sync` skill (from `custom/skills/script-sync/SKILL.md`)
+**INVOKE:** `script-sync` skill (from `custom/skills/test-skills/script-sync/SKILL.md`)
 
 Hash-based TC↔script sync — for each TC in the file:
 - **New TC** (no matching `@tc-hash` in spec): generate Playwright test using MCP (`browser_navigate` → `browser_snapshot` → `browser_generate_locator`). Never fabricate selectors.

package/custom/templates/tools/claude.md

@@ -1,13 +1,13 @@
-# Claude AI System Instructions
-
-You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.
-
-> **Important:** Always read `.aiflow/context/current.json` to load ticket context and check the `plan/` directory for existing progress before starting any task.
-
-If Gate 1 does not auto-start, wait for the developer to type **"start"**, **"Gate 1"** or **"Analyze ticket"**.
-
-## Interaction Rules:
-
-- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
-- **NEVER BATCH QUESTIONS:** Only ask one question per message.
-- **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".
+# Claude AI System Instructions
+
+You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.
+
+> **Important:** Always read `.aiflow/context/current.json` to load ticket context and check the `04.Coding/` docs directory for existing progress before starting any task.
+
+If Gate 1 does not auto-start, wait for the developer to type **"start"**, **"Gate 1"** or **"Analyze ticket"**.
+
+## Interaction Rules:
+
+- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
+- **NEVER BATCH QUESTIONS:** Only ask one question per message.
+- **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".

package/custom/templates/tools/copilot.md

@@ -1,12 +1,12 @@
-# GitHub Copilot Custom Instructions
-
-You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.
-
-> **Important:** Always check for context in `.aiflow/context/current.json` and progress in the `plan/` folder before suggesting changes.
-
-If the Gate Workflow hasn't started, wait for the developer to type **"start"** or **"Gate 1"**.
-
-## Interaction Rules:
-- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
-- **NEVER BATCH QUESTIONS:** Only ask one question per message.
-- **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".
+# GitHub Copilot Custom Instructions
+
+You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.
+
+> **Important:** Always check for context in `.aiflow/context/current.json` and progress in the `04.Coding/` docs folder before suggesting changes.
+
+If the Gate Workflow hasn't started, wait for the developer to type **"start"** or **"Gate 1"**.
+
+## Interaction Rules:
+- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
+- **NEVER BATCH QUESTIONS:** Only ask one question per message.
+- **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".

package/custom/templates/tools/cursor.md

@@ -1,12 +1,12 @@
-# Cursor AI Project Rules
-
-You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.
-
-> **Important:** Always check `.aiflow/context/current.json` and the `plan/` directory before starting any task to understand current context and progress.
-
-If Gate 1 doesn't auto-start, wait for the developer to type **"start"**, **"Gate 1"** or **"Analyze ticket"**.
-
-## Interaction Rules:
-- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
-- **NEVER BATCH QUESTIONS:** Only ask one question per message.
-- **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".
+# Cursor AI Project Rules
+
+You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.
+
+> **Important:** Always check `.aiflow/context/current.json` and the `04.Coding/` docs directory before starting any task to understand current context and progress.
+
+If Gate 1 doesn't auto-start, wait for the developer to type **"start"**, **"Gate 1"** or **"Analyze ticket"**.
+
+## Interaction Rules:
+- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
+- **NEVER BATCH QUESTIONS:** Only ask one question per message.
+- **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".

package/custom/templates/tools/gemini.md

@@ -1,22 +1,22 @@
-# Gemini AI System Instructions
-
-You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.
-
-> **Important:** When starting a session, always read `.aiflow/context/current.json` to load ticket context and check the `plan/` directory for existing progress.
-
-If no instructions are automatically followed, wait for the developer to type **"start"** or **"Gate 1"** to start the analysis.
-
-## Interaction Rules:
-- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
-- **NEVER BATCH QUESTIONS:** Only ask one question per message.
-- **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".
-- **PROJECT CONVENTIONS:** Before writing any output file (plan, requirement, summary), read `custom/rules/project-conventions.md`. These rules override upstream skill defaults.
-
-## Telemetry Command (detect once, use everywhere)
-
-Before the first gate, run this to detect the correct `ak` command for your environment:
-```bash
-command -v ak >/dev/null 2>&1 && echo "USE: ak" || echo "USE: ak.cmd"
-```
-Use whichever prints (e.g. `ak` on native Linux/Mac/Windows, `ak.cmd` on WSL without ak installed).
-All `ak gate ...` examples below assume the detected command. Substitute accordingly.
+# Gemini AI System Instructions
+
+You are an expert AI assistant specialized in this project's stack. Follow the Gate Workflow and Team Rules strictly.
+
+> **Important:** When starting a session, always read `.aiflow/context/current.json` to load ticket context and check the `04.Coding/` docs directory for existing progress.
+
+If no instructions are automatically followed, wait for the developer to type **"start"** or **"Gate 1"** to start the analysis.
+
+## Interaction Rules:
+- **COLLABORATIVE SKILLS:** When a skill (like `read-study-requirement`) says to "ask one question at a time", you MUST stop and wait for the developer's reply before proceeding.
+- **NEVER BATCH QUESTIONS:** Only ask one question per message.
+- **WAIT FOR APPROVAL:** Do not move to the next Gate until you receive "APPROVED".
+- **PROJECT CONVENTIONS:** Before writing any output file (plan, requirement, summary), read `custom/rules/project-conventions.md`. These rules override upstream skill defaults.
+
+## Telemetry Command (detect once, use everywhere)
+
+Before the first gate, run this to detect the correct `ak` command for your environment:
+```bash
+command -v ak >/dev/null 2>&1 && echo "USE: ak" || echo "USE: ak.cmd"
+```
+Use whichever prints (e.g. `ak` on native Linux/Mac/Windows, `ak.cmd` on WSL without ak installed).
+All `ak gate ...` examples below assume the detected command. Substitute accordingly.