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

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

@@ -1,194 +1,194 @@
----
-name: review-plan
-description: Gate 4 — After AI generates code, the developer reviews source code + summary. Developer must provide APPROVED or report a bug before closing the task.
-keywords: review, code review, approve, summary, checklist
----
-
-# Review Plan — Gate 4
-
-> **GATE 4: Runs after AI has completed code generation.**
->
-> Principle: AI self-reviews first (verification + impact-analysis), then presents a summary to the developer. The developer decides: APPROVED or report a bug.
-
----
-
-## Conditions to enter Gate 4
-
-- ✅ Gate 1 (requirement doc) has been APPROVED
-- ✅ Gate 2 (implementation plan) has been APPROVED
-- ✅ AI has completed code generation (Gate 3)
-- ✅ `superpowers:verification-before-completion` has run — tests pass
-- ✅ `impact-analysis` skill has run
-
-## Mode Selection
-
-Check `mode` in `.aiflow/context/current.json`:
-
-| Mode | Impact Analysis | Review Checklist | summary.md |
-|------|----------------|-----------------|-----------|
-| `fast` | Quick scan — reason from diff only | 3 items | Short format |
-| `full` | Full grep scan across codebase | 10 items | Full format |
-
-### Fast Track Impact Analysis (mode: fast)
-Assess impact by reasoning about the changed files only:
-1. List each file you modified
-2. For each file: "Does this file have callers/dependents outside the ticket scope?"
-3. If yes → list them and assign impact level
-4. DO NOT run grep on the full codebase
-
-### Fast Track Review Checklist (mode: fast)
-- [ ] All tests pass
-- [ ] No hardcoded credentials or secrets
-- [ ] No SQL injection risk in new queries
-
-## Fast Mode Output Rules (CRITICAL)
-
-When creating `plan/[ticket-id]/summary.md` in **fast mode**:
-- **Do not write long explanations or descriptions.**
-- **List format only:** Bullet points with `[NEW]`, `[MODIFIED]`, `[DELETED]`.
-- **Purpose:** Next to each file, write exactly 1 sentence explaining the *purpose* (the "why"), not the implementation details.
-
-**Example summary.md block:**
-```markdown
-### Gate 3 — Code
-- ✅ **Implemented batch endpoints**
-  - \`[NEW] src/controllers/BatchController.ts\`: Handle bulk export requests
-  - \`[MODIFIED] src/services/ExportService.ts\`: Added S3 upload integration
-```
-
----
-
-## Process
-
-### Step 1: AI self-review (before showing the developer)
-
-Run in the following mandatory order:
-
-```
-1. superpowers:verification-before-completion
-   → All tests must PASS. If any fail → fix immediately, do not show the developer.
-
-2. impact-analysis skill
-   → Check for breaking changes and side effects.
-
-3. review-checklist (.rules/review-checklist.md)
-   → Tick each item in the checklist.
-```
-
-**If any step fails → fix first, do not proceed to Step 2.**
-
-### Step 2: Create Summary Report
-
-Create file `plan/[ticket-id]/summary.md`:
-
-```markdown
-# Summary: [Ticket ID] — [Title]
-
-**Date:** [YYYY-MM-DD]
-**Status:** Waiting for DEV review
-
----
-
-## Implementation Details
-
-| File | Change | Reason |
-|------|----------|-------|
-| [path/to/file] | Created / Modified | [reason] |
-
----
-
-## Acceptance Criteria — results
-
-| Criteria | Status | Notes |
-|---------|--------|---------|
-| [Criteria 1] | ✅ Done | [implementation details] |
-| [Criteria 2] | ✅ Done | |
-
----
-
-## Tests Written
-
-| Test file | Test cases | Coverage |
-|-----------|-----------|---------|
-| [file] | [N] cases | [X%] |
-
-**Test output:**
-```
-[Paste test results here]
-```
-
----
-
-## Impact Analysis results
-
-**Level:** 🟢 Low / 🟡 Medium / 🔴 High
-
-**Impact Scope:**
-- [File/Service A] — [reason for impact / lack of impact]
-
-**Breaking changes:** None / [description if any]
-
----
-
-## Review Checklist
-
-- [ ] Code compiles and all tests pass
-- [ ] No hardcoded credentials / config
-- [ ] Security: no SQL injection, no exposure of sensitive data
-- [ ] Impact Analysis has been run
-- [ ] Naming and Code Style follow conventions
-- [ ] Sufficient tests (unit + integration)
-- [ ] No dead code / leftover console.logs
-```
-
-### Step 3: GATE 4 — Present to Developer
-
-```markdown
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-⏸️  GATE 4: WAITING FOR DEV REVIEW
-
-I have completed implementation and self-review.
-Summary: plan/[ticket-id]/summary.md
-
-**Self-review results:**
-- Tests: ✅ [N] passed / ❌ [N] failed  
-- Impact: [Low/Medium/High]
-- Checklist: [N/N] items ✅
-
-**You need to:**
-1. Review the summary above
-2. Check the source code if necessary
-3. Run manual tests if desired
-
-**After review, reply with one of the following:**
-
-✅ If OK: type **"APPROVED"**
-🐛 If there are bugs: type **"BUG: [description]"**
-   → If a requirement bug: I will return to Gate 1
-   → If a coding bug: I will fix and repeat Gate 4
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-### Step 4: Handle feedback
-
-**If the developer types "APPROVED":**
-→ Invoke `superpowers:requesting-code-review` to send for peer review
-→ Guide on creating a Pull Request
-
-**If the developer types "BUG: [description]" — coding bug:**
-→ Analyze bug, fix, rerun verification
-→ Repeat from Step 1 of Gate 4
-
-**If the developer types "BUG: [description]" — requirement bug:**
-→ Notify: "This is a requirement bug, requirement document needs update"
-→ Return to Gate 1, update requirement.md, wait for APPROVED again
-
----
-
-## Mandatory Rules
-
-- ❌ **DO NOT** invoke `requesting-code-review` before the developer provides APPROVED
-- ❌ **DO NOT** decide "task is done" on your own — must be confirmed by the developer
-- ✅ **MUST** run verification + impact-analysis before showing the developer
-- ✅ **MUST** clearly classify: requirement bug vs coding bug
-- ✅ **MUST** update summary.md each time changes are made
+---
+name: review-plan
+description: Gate 4 — After AI generates code, the developer reviews source code + summary. Developer must provide APPROVED or report a bug before closing the task.
+keywords: review, code review, approve, summary, checklist
+---
+
+# Review Plan — Gate 4
+
+> **GATE 4: Runs after AI has completed code generation.**
+>
+> Principle: AI self-reviews first (verification + impact-analysis), then presents a summary to the developer. The developer decides: APPROVED or report a bug.
+
+---
+
+## Conditions to enter Gate 4
+
+- ✅ Gate 1 (requirement doc) has been APPROVED
+- ✅ Gate 2 (implementation plan) has been APPROVED
+- ✅ AI has completed code generation (Gate 3)
+- ✅ `superpowers:verification-before-completion` has run — tests pass
+- ✅ `impact-analysis` skill has run
+
+## Mode Selection
+
+Check `mode` in `.aiflow/context/current.json`:
+
+| Mode | Impact Analysis | Review Checklist | summary.md |
+|------|----------------|-----------------|-----------|
+| `fast` | Quick scan — reason from diff only | 3 items | Short format |
+| `full` | Full grep scan across codebase | 10 items | Full format |
+
+### Fast Track Impact Analysis (mode: fast)
+Assess impact by reasoning about the changed files only:
+1. List each file you modified
+2. For each file: "Does this file have callers/dependents outside the ticket scope?"
+3. If yes → list them and assign impact level
+4. DO NOT run grep on the full codebase
+
+### Fast Track Review Checklist (mode: fast)
+- [ ] All tests pass
+- [ ] No hardcoded credentials or secrets
+- [ ] No SQL injection risk in new queries
+
+## Fast Mode Output Rules (CRITICAL)
+
+When creating `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` in **fast mode**:
+- **Do not write long explanations or descriptions.**
+- **List format only:** Bullet points with `[NEW]`, `[MODIFIED]`, `[DELETED]`.
+- **Purpose:** Next to each file, write exactly 1 sentence explaining the *purpose* (the "why"), not the implementation details.
+
+**Example summary.md block:**
+```markdown
+### Gate 3 — Code
+- ✅ **Implemented batch endpoints**
+  - \`[NEW] src/controllers/BatchController.ts\`: Handle bulk export requests
+  - \`[MODIFIED] src/services/ExportService.ts\`: Added S3 upload integration
+```
+
+---
+
+## Process
+
+### Step 1: AI self-review (before showing the developer)
+
+Run in the following mandatory order:
+
+```
+1. superpowers:verification-before-completion
+   → All tests must PASS. If any fail → fix immediately, do not show the developer.
+
+2. impact-analysis skill
+   → Check for breaking changes and side effects.
+
+3. review-checklist (.rules/review-checklist.md)
+   → Tick each item in the checklist.
+```
+
+**If any step fails → fix first, do not proceed to Step 2.**
+
+### Step 2: Create Summary Report
+
+Create file `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md`:
+
+```markdown
+# Summary: [Ticket ID] — [Title]
+
+**Date:** [YYYY-MM-DD]
+**Status:** Waiting for DEV review
+
+---
+
+## Implementation Details
+
+| File | Change | Reason |
+|------|----------|-------|
+| [path/to/file] | Created / Modified | [reason] |
+
+---
+
+## Acceptance Criteria — results
+
+| Criteria | Status | Notes |
+|---------|--------|---------|
+| [Criteria 1] | ✅ Done | [implementation details] |
+| [Criteria 2] | ✅ Done | |
+
+---
+
+## Tests Written
+
+| Test file | Test cases | Coverage |
+|-----------|-----------|---------|
+| [file] | [N] cases | [X%] |
+
+**Test output:**
+```
+[Paste test results here]
+```
+
+---
+
+## Impact Analysis results
+
+**Level:** 🟢 Low / 🟡 Medium / 🔴 High
+
+**Impact Scope:**
+- [File/Service A] — [reason for impact / lack of impact]
+
+**Breaking changes:** None / [description if any]
+
+---
+
+## Review Checklist
+
+- [ ] Code compiles and all tests pass
+- [ ] No hardcoded credentials / config
+- [ ] Security: no SQL injection, no exposure of sensitive data
+- [ ] Impact Analysis has been run
+- [ ] Naming and Code Style follow conventions
+- [ ] Sufficient tests (unit + integration)
+- [ ] No dead code / leftover console.logs
+```
+
+### Step 3: GATE 4 — Present to Developer
+
+```markdown
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+⏸️  GATE 4: WAITING FOR DEV REVIEW
+
+I have completed implementation and self-review.
+Summary: AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md
+
+**Self-review results:**
+- Tests: ✅ [N] passed / ❌ [N] failed  
+- Impact: [Low/Medium/High]
+- Checklist: [N/N] items ✅
+
+**You need to:**
+1. Review the summary above
+2. Check the source code if necessary
+3. Run manual tests if desired
+
+**After review, reply with one of the following:**
+
+✅ If OK: type **"APPROVED"**
+🐛 If there are bugs: type **"BUG: [description]"**
+   → If a requirement bug: I will return to Gate 1
+   → If a coding bug: I will fix and repeat Gate 4
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Step 4: Handle feedback
+
+**If the developer types "APPROVED":**
+→ Invoke `superpowers:requesting-code-review` to send for peer review
+→ Guide on creating a Pull Request
+
+**If the developer types "BUG: [description]" — coding bug:**
+→ Analyze bug, fix, rerun verification
+→ Repeat from Step 1 of Gate 4
+
+**If the developer types "BUG: [description]" — requirement bug:**
+→ Notify: "This is a requirement bug, requirement document needs update"
+→ Return to Gate 1, update requirement.md, wait for APPROVED again
+
+---
+
+## Mandatory Rules
+
+- ❌ **DO NOT** invoke `requesting-code-review` before the developer provides APPROVED
+- ❌ **DO NOT** decide "task is done" on your own — must be confirmed by the developer
+- ✅ **MUST** run verification + impact-analysis before showing the developer
+- ✅ **MUST** clearly classify: requirement bug vs coding bug
+- ✅ **MUST** update summary.md each time changes are made

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

@@ -88,7 +88,7 @@ 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):**
 - `03.Testing/07.AI-Artifacts/[functionId]/[functionId]_01_Requirement_Analysis_Result.md`
@@ -161,16 +161,23 @@ 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: `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
+#### 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
@@ -185,7 +192,8 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 **Definition of Done:**
 - [ ] `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.
@@ -237,7 +245,8 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 - Draft RTM (Scenario ID → Requirement ID từ `01_Requirement_Analysis_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)
+#### 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
 
@@ -321,7 +330,8 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 - Ghi TBD marker khi thiếu thông tin: `[TBD — <issue-id>: mô tả ngắn]`
 - 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)
+#### 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
 
@@ -458,3 +468,5 @@ Vui lòng cung cấp mã định danh cho chức năng này (ví dụ: AD06, TC-
 - ✅ **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,21 +29,62 @@ 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
+
+```
+AK-Docs/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 ở `AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v1.md` → lấy `[functionId]`). Có thể tra thêm `AK-Docs/04.Coding/00.Overview/_Index.md` hoặc `AK-Docs/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 `AK-Docs/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: AK-Docs/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 `AK-Docs/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 `AK-Docs/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]`
@@ -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 (`AK-Docs/04.Coding/01.Requirements/[functionId]/[ticketId].md`).
+- Output `AK-Docs/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 `AK-Docs/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 `AK-Docs/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 `AK-Docs/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 `AK-Docs/04.Coding/04.Reviews/[functionId]/[ticketId].md` — Test Results, Impact Analysis (files changed, affected features, breaking changes), Review Checklist
+5. Update tracker row in `AK-Docs/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 `AK-Docs/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 (`AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/`), Test Case (`AK-Docs/03.Testing/01.Testcases/[functionId]/`), Dev Plan (`AK-Docs/04.Coding/02.Plans/[functionId]/[ticketId].md`)
+2. **Lưu tài liệu `AK-Docs/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 `AK-Docs/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.
 

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 `AK-Docs/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 `AK-Docs/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".