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

package/custom/skills/automation-testing/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: automation-testing
+description: Sinh Playwright TypeScript E2E test từ test case draft của tester. Dùng Playwright MCP để xem DOM THẬT của app và lấy selector chính xác (không đoán). Dùng khi tester muốn tạo script test tự động từ mô tả test case bằng ngôn ngữ tự nhiên.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_generate_locator, mcp__playwright__browser_click, mcp__playwright__browser_type, mcp__playwright__browser_fill_form, mcp__playwright__browser_select_option, mcp__playwright__browser_press_key, mcp__playwright__browser_wait_for, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_console_messages, mcp__playwright__browser_navigate_back, mcp__playwright__browser_close
+---
+
+# Skill: automation-testing
+
+Sinh **Playwright TypeScript** test scripts từ test case draft của tester.
+Điểm khác biệt cốt lõi so với "sinh code thuần": skill **mở app thật bằng Playwright MCP**,
+chụp cây accessibility/DOM và sinh selector từ element CÓ THẬT — nên script chạy được ngay,
+tester không cần biết TypeScript và hạn chế tối đa việc nhờ dev sửa selector.
+
+## Cách gọi
+
+```
+/automation-testing baseUrl: <url> [autoRun: true|false] [headed: true|false] [ticketId: <id>]
+---
+<test case draft của tester — text tự do, mỗi dòng một case>
+```
+
+Ví dụ:
+```
+/automation-testing baseUrl: http://localhost:3000 autoRun: false
+---
+1. Vào trang login, nhập đúng email/password → vào được dashboard
+2. Nhập sai password → hiện thông báo lỗi
+3. Để trống email → hiện validation lỗi
+```
+
+## Tham số (parse từ phần đầu lời gọi)
+
+Đọc các tham số từ text người dùng truyền vào (dạng `key: value`). Nếu không thấy, dùng default.
+
+| Param      | Default | Ý nghĩa |
+|------------|---------|---------|
+| `baseUrl`  | —       | URL web app đang test. **Bắt buộc.** Nếu thiếu → hỏi tester rồi mới tiếp tục. |
+| `autoRun`  | `false` | Tự chạy `npx playwright test` sau khi sinh script. |
+| `headed`   | `true`  | Hiện cửa sổ browser khi `autoRun=true`. |
+| `ticketId` | suy ra  | Thư mục con cho spec (`tests/e2e/specs/<ticketId>/`). Nếu thiếu → suy từ tên feature (vd `login`). |
+
+Phần text sau dấu `---` là **test case draft**.
+
+---
+
+## Phase 1 — Collect (Thu thập input)
+
+Đọc tất cả nguồn có sẵn, theo thứ tự ưu tiên:
+
+1. `plan/<ticketId>/requirement.md` (nếu có) — dùng `Read`.
+2. `plan/<ticketId>/plan.md` (nếu có).
+3. **Test case draft** — phần text sau `---` trong lời gọi.
+4. `custom/rules/test-patterns.md` — các pattern chuẩn (login, CRUD, form, modal...). **Luôn đọc file này** để áp dụng quy ước chung.
+
+Kiểm tra điều kiện tiên quyết:
+- Thiếu `baseUrl` → hỏi tester, dừng lại chờ.
+- Không có bất kỳ test case nào (cả draft lẫn requirement) → hỏi:
+  > "Bạn muốn test feature gì? Hãy mô tả các test case hoặc paste test case draft vào đây."
+
+---
+
+## Phase 2 — Analyze (Sinh danh sách test case có cấu trúc)
+
+Phân tích tất cả input và lập bảng test case:
+
+```
+## Test Cases — <Feature Name>
+
+| ID   | Tên test case            | Steps                                          | Expected Result            |
+|------|--------------------------|------------------------------------------------|----------------------------|
+| TC01 | Đăng nhập thành công      | 1. Vào /login 2. Nhập email+pass hợp lệ 3. Submit | Redirect về /dashboard  |
+| TC02 | Sai mật khẩu             | 1. Vào /login 2. Nhập sai pass 3. Submit       | Hiện error message         |
+| TC03 | Để trống email           | 1. Vào /login 2. Submit ngay                   | Hiện "Email là bắt buộc"   |
+```
+
+> ⚠️ **GATE 1 — BẮT BUỘC.** Hiển thị bảng và hỏi:
+> "Danh sách test cases trên đã đúng chưa? Cần thêm/sửa/xóa case nào không?
+> Xác nhận để tôi mở app và lấy selector thật."
+>
+> **Dừng lại, chờ tester xác nhận.** Không tự chuyển Phase 3.
+
+---
+
+## Phase 3 — Explore (Khám phá DOM thật qua Playwright MCP) 🔑
+
+Đây là bước quyết định độ chính xác. **Không được đoán selector** — phải lấy từ app thật.
+
+Với mỗi trang/màn hình liên quan trong các test case đã chốt:
+
+1. `mcp__playwright__browser_navigate` tới `<baseUrl><path>` (vd `http://localhost:3000/login`).
+2. `mcp__playwright__browser_snapshot` để lấy cây accessibility (role, name, ref của từng element).
+3. Với từng element cần thao tác (input, button, message...), dùng
+   `mcp__playwright__browser_generate_locator` để lấy **locator Playwright chuẩn** từ element thật.
+4. Nếu một test case cần đi qua nhiều bước (vd phải submit mới hiện error), dùng
+   `browser_type` / `browser_fill_form` / `browser_click` để **đi tới đúng trạng thái** rồi
+   `browser_snapshot` lại để lấy selector của element xuất hiện sau đó (error message, modal...).
+5. Ghi lại bảng ánh xạ: phần tử logic → locator thật. Ví dụ:
+
+   ```
+   Email field   → getByRole('textbox', { name: 'Email' })
+   Password field→ getByLabel('Mật khẩu')
+   Submit button → getByRole('button', { name: 'Đăng nhập' })
+   Error message → getByText('Sai tên đăng nhập hoặc mật khẩu')
+   ```
+
+Quy tắc ưu tiên locator (theo Playwright best practice):
+`getByRole` > `getByLabel` > `getByPlaceholder` > `getByText` > `getByTestId` > CSS.
+Chỉ dùng CSS/XPath khi không còn cách nào khác, và ghi chú lý do.
+
+> ⚠️ **Nếu không mở được app** (baseUrl sai, app chưa chạy, route không tồn tại):
+> báo rõ cho tester, **không** sinh selector đoán mò. Hỏi tester sửa baseUrl / khởi động app.
+>
+> Đóng browser bằng `mcp__playwright__browser_close` khi khám phá xong.
+
+### Nếu app yêu cầu đăng nhập (auth)
+
+Khi feature cần test nằm sau màn hình login:
+
+1. Khám phá selector trang login bằng MCP (như trên).
+2. Cập nhật `tests/e2e/auth.setup.ts`: thay 3 dòng locator mặc định (Email / Mật khẩu /
+   nút Đăng nhập) bằng **selector thật** vừa khám phá, và chỉnh `expectPathAfterLogin`.
+3. Hỏi tester **tài khoản test** (không hardcode tài khoản thật). Hướng dẫn họ điền vào `.env`:
+   `E2E_USER`, `E2E_PASSWORD`, `E2E_LOGIN_PATH`, `E2E_POST_LOGIN_PATH` (xem `.env.example`).
+   Có `E2E_USER` → auth tự bật: project `setup` đăng nhập 1 lần, lưu `.auth/user.json`,
+   các test sau tái dùng phiên (không login lại từng test).
+4. Test mà bản thân nó cần trạng thái **CHƯA đăng nhập** (vd chính test login/logout):
+   thêm ở đầu spec `test.use({ storageState: LOGGED_OUT })` (import `LOGGED_OUT` từ
+   `../../fixtures/test`).
+
+---
+
+## Phase 4 — Generate (Sinh script với selector thật)
+
+Sinh file theo cấu trúc:
+
+```
+tests/e2e/
+├── pages/
+│   ├── BasePage.ts            ← chỉ tạo nếu chưa có (đã có sẵn trong repo)
+│   └── <Feature>Page.ts       ← Page Object, locator lấy từ Phase 3
+├── specs/
+│   └── <ticketId>/
+│       └── <feature>.spec.ts  ← nhóm nhiều TCs (xem quy tắc bên dưới)
+└── fixtures/test.ts           ← chỉ tạo nếu chưa có (đã có sẵn)
+```
+
+Khi được gọi từ `coverage-check` (Phase 2d), output vào `test-plan/test-scripts/`:
+
+```
+test-plan/test-scripts/
+├── AD10_001.spec.ts   ← mỗi TC_ID một file riêng
+├── AD10_002.spec.ts
+└── ...
+```
+
+Quy tắc sinh code:
+
+- **`<Feature>Page.ts`**: kế thừa `BasePage`. Khai báo tất cả `Locator` ở constructor,
+  **dùng đúng locator lấy được ở Phase 3**. Mỗi hành động là một async method (vd `login()`).
+  Tham khảo `templates/PageObject.example.ts` để biết style.
+
+- **Đặt tên test function — bắt buộc chứa TC_ID:**
+  ```typescript
+  // ScreenID là mã màn hình/chức năng của từng dự án (AD10, LOGIN, ORD, ... — không cố định)
+  test.describe('[ScreenID] — Tên màn hình', () => {
+    test('[ScreenID_001] Mô tả scenario đầu tiên', async ({ page }) => {
+      // ...
+    })
+    test('[ScreenID_002] Mô tả scenario thứ hai', async ({ page }) => {
+      // ...
+    })
+  })
+  ```
+  Ví dụ thực tế (ScreenID tùy dự án): `[AD10_001]`, `[LOGIN_001]`, `[ORD_002]`
+
+  Format bắt buộc: `'[TC_ID] Mô tả scenario'` — TC_ID phải nằm ở **đầu tên test**, trong dấu `[]`.
+  Mục đích: khi chạy `--grep "AD10_001"` (hoặc TC_ID thực tế) sẽ select đúng test case, và kết quả map 1-1 với testcase document.
+
+- **`<feature>.spec.ts`**: import `{ test, expect }` từ `../../fixtures/test`.
+  dùng `test.describe('[ScreenID]', ...)` để nhóm. Assertion rõ ràng (`expect(...).toBeVisible()`...).
+- **Không tạo lại** `BasePage.ts` / `playwright.config.ts` / `fixtures/test.ts` /
+  `auth.setup.ts` / `support/auth.ts` nếu đã tồn tại (kiểm tra bằng `Glob` trước) —
+  với `auth.setup.ts` chỉ **sửa locator/đường dẫn**, không ghi đè toàn bộ.
+
+### Incremental Update — chỉ generate scripts mới hoặc đã thay đổi
+
+Khi được gọi với danh sách TC_IDs (từ `coverage-check` hoặc sau khi TESTER update testcases):
+
+1. **Kiểm tra scripts đã tồn tại:** `Glob` tìm các file trong `test-plan/test-scripts/*.spec.ts`
+2. **Phân loại từng TC_ID:**
+   - Nếu `[TC_ID].spec.ts` **chưa tồn tại** → `[NEW]` — sinh script mới
+   - Nếu `[TC_ID].spec.ts` **đã tồn tại** và TC nằm trong danh sách "đã thay đổi" (do TESTER chỉ định) → `[UPDATED]` — regenerate, overwrite
+   - Nếu `[TC_ID].spec.ts` **đã tồn tại** và không trong danh sách thay đổi → `[SKIP]` — không đụng vào
+3. **Chỉ mở DOM/Playwright MCP cho TCs cần generate** (`[NEW]` và `[UPDATED]`)
+4. **Báo cáo kết quả:**
+   ```
+   Script generation complete:
+     [NEW]     AD10_005.spec.ts — created
+     [UPDATED] AD10_002.spec.ts — regenerated (TC content changed)
+     [SKIP]    AD10_001.spec.ts — unchanged, kept existing
+     [SKIP]    AD10_003.spec.ts — unchanged, kept existing
+   ```
+
+Khi TESTER không chỉ định danh sách thay đổi (chạy lần đầu từ `coverage-check`), generate TẤT CẢ TCs có `Type = Auto` trong `final-testcases.md` mà chưa có script.
+
+---
+
+## Phase 5 — Execute
+
+Set `BASE_URL` = `baseUrl` khi chạy để Playwright dùng đúng app.
+
+### autoRun = false (default)
+In hướng dẫn chạy thủ công:
+```
+✅ Đã sinh script xong!
+
+Chạy test:
+  BASE_URL=<baseUrl> npx playwright test tests/e2e/specs/<ticketId>/
+  BASE_URL=<baseUrl> npx playwright test --headed     # hiện browser
+  npx playwright test --ui                              # mở Playwright UI
+Xem report:
+  npx playwright show-report
+```
+
+### autoRun = true
+1. Chạy bằng `Bash`:
+   `BASE_URL=<baseUrl> npx playwright test tests/e2e/specs/<ticketId>/ <--headed nếu headed=true>`
+2. Tóm tắt pass/fail cho tester (dễ đọc, không bắt đọc log thô).
+3. Nếu có test fail: chỉ ra TC nào fail, lý do, và đề xuất sửa.
+   In `npx playwright show-report` để mở HTML report.
+
+---
+
+## Nguyên tắc chung
+
+- **Gate trước khi sinh code** (Phase 2) là bắt buộc — tránh sinh sai hàng loạt.
+- **Selector phải đến từ DOM thật** (Phase 3) — đây là lý do tồn tại của skill này.
+- Viết test case, tên test, comment bằng **tiếng Việt** cho khớp draft của tester.
+- Nếu app yêu cầu đăng nhập trước, hỏi tester credentials test (đừng hardcode tài khoản thật).

package/custom/skills/automation-testing/templates/BasePage.ts

@@ -0,0 +1,29 @@
+import { Page, Locator } from '@playwright/test'
+
+export abstract class BasePage {
+  readonly page: Page
+
+  constructor(page: Page) {
+    this.page = page
+  }
+
+  async navigate(path: string) {
+    await this.page.goto(path)
+    await this.waitForLoad()
+  }
+
+  async waitForLoad() {
+    await this.page.waitForLoadState('networkidle')
+  }
+
+  async takeScreenshot(name: string) {
+    await this.page.screenshot({
+      path: `evidence/${name}.png`,
+      fullPage: true,
+    })
+  }
+
+  async getPageTitle(): Promise<string> {
+    return this.page.title()
+  }
+}

package/custom/skills/automation-testing/templates/PageObject.example.ts

@@ -0,0 +1,29 @@
+// TEMPLATE THAM CHIẾU — không phải file chạy thật.
+// Skill dùng style này để sinh tests/e2e/pages/<Feature>Page.ts.
+// CÁC LOCATOR DƯỚI ĐÂY LÀ VÍ DỤ — khi sinh thật phải thay bằng locator
+// lấy từ Phase 3 (Playwright MCP browser_snapshot / browser_generate_locator).
+
+import { Page, Locator } from '@playwright/test';
+import { BasePage } from './BasePage';
+
+export class LoginPage extends BasePage {
+  readonly emailInput: Locator;
+  readonly passwordInput: Locator;
+  readonly submitButton: Locator;
+  readonly errorMessage: Locator;
+
+  constructor(page: Page) {
+    super(page);
+    // ↓ Locator THẬT lấy từ DOM ở Phase 3, ưu tiên getByRole > getByLabel > ...
+    this.emailInput = page.getByRole('textbox', { name: 'Email' });
+    this.passwordInput = page.getByLabel('Mật khẩu');
+    this.submitButton = page.getByRole('button', { name: 'Đăng nhập' });
+    this.errorMessage = page.getByText('Sai tên đăng nhập hoặc mật khẩu');
+  }
+
+  async login(email: string, password: string): Promise<void> {
+    await this.emailInput.fill(email);
+    await this.passwordInput.fill(password);
+    await this.submitButton.click();
+  }
+}

package/custom/skills/automation-testing/templates/playwright.config.ts

@@ -0,0 +1,39 @@
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './tests/e2e/specs',
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: 1,
+  reporter: [
+    ['html', { outputFolder: 'playwright-report' }],
+    ['json', { outputFile: 'test-results/results.json' }],
+  ],
+
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+    video: 'on-first-retry',
+    headless: !process.env.HEADED,
+    locale: 'vi-VN',
+  },
+
+  projects: [
+    // Auth setup (chỉ chạy khi có E2E_USER trong .env)
+    ...(process.env.E2E_USER
+      ? [{ name: 'setup', testMatch: /auth\.setup\.ts/ }]
+      : []),
+    {
+      name: 'chromium',
+      use: {
+        ...devices['Desktop Chrome'],
+        ...(process.env.E2E_USER ? { storageState: '.auth/user.json' } : {}),
+      },
+      dependencies: process.env.E2E_USER ? ['setup'] : [],
+    },
+  ],
+
+  outputDir: 'test-results',
+})

package/custom/skills/automation-testing/templates/spec.example.ts

@@ -0,0 +1,29 @@
+// TEMPLATE THAM CHIẾU — không phải file chạy thật.
+// Skill dùng style này để sinh tests/e2e/specs/<ticketId>/<feature>.spec.ts.
+// ID test (TC01...) phải khớp bảng test case đã chốt ở Phase 2.
+
+import { test, expect } from '../../fixtures/test';
+import { LoginPage } from '../../pages/LoginPage';
+
+test.describe('Đăng nhập hệ thống', () => {
+  test('TC01 - Đăng nhập thành công với credentials hợp lệ', async ({ page }) => {
+    const loginPage = new LoginPage(page);
+    await loginPage.navigate('/login');
+    await loginPage.login('admin@example.com', 'Password123');
+    await expect(page).toHaveURL(/\/dashboard/);
+  });
+
+  test('TC02 - Hiển thị lỗi khi nhập sai mật khẩu', async ({ page }) => {
+    const loginPage = new LoginPage(page);
+    await loginPage.navigate('/login');
+    await loginPage.login('admin@example.com', 'wrong-password');
+    await expect(loginPage.errorMessage).toBeVisible();
+  });
+
+  test('TC03 - Hiển thị validation khi để trống email', async ({ page }) => {
+    const loginPage = new LoginPage(page);
+    await loginPage.navigate('/login');
+    await loginPage.submitButton.click();
+    await expect(page.getByText('Email là bắt buộc')).toBeVisible();
+  });
+});

package/custom/skills/ba-skills/skill-ba-phan-tich-ban-dau-v1.md

@@ -0,0 +1,44 @@
+# Skill: Phân tích yêu cầu ban đầu (BA Analyst) - Phiên bản v1
+
+## 1. Mục đích (Purpose)
+Kỹ năng này giúp Business Analyst (hoặc Agent) quét, đọc hiểu và cấu trúc hóa các yêu cầu thô được cung cấp bởi khách hàng hoặc các stakeholders. Mục tiêu là phân tách rõ ràng giữa các thông tin thực tế (Facts) và các giả định (Assumptions), phát hiện các khoảng trống nghiệp vụ (Gaps), và tạo cơ sở cho việc lập danh sách câu hỏi làm rõ (Q&A) cũng như dự thảo spec ban đầu.
+
+## 2. Kiến thức cần có (Prerequisite Knowledge)
+- **Tư duy phân tích (Analytical Thinking):** Khả năng chia nhỏ một yêu cầu lớn thành các luồng nghiệp vụ nhỏ và các thành phần cấu thành.
+- **Phân biệt Fact vs. Assumption:**
+  - *Fact (Sự thật):* Thông tin được ghi rõ ràng trong tài liệu, được khẳng định từ khách hàng.
+  - *Assumption (Giả định):* Những giả thiết do BA đưa ra dựa trên kinh nghiệm hoặc ngữ cảnh mà chưa được khách hàng xác nhận bằng văn bản.
+- **Kỹ thuật Gap Analysis:** Kỹ thuật nhận diện các điểm chưa thống nhất, các thông tin bị thiếu (ví dụ: thiếu thông báo lỗi khi validate thất bại, thiếu quy tắc lưu trữ vào cơ sở dữ liệu, thiếu mô tả quyền truy cập).
+- **Thuật ngữ phần mềm cơ bản:** Khách hàng (Client), Người dùng (User), Tác nhân (Actor), Ràng buộc (Constraints), Luồng chính (Happy Path), Trường hợp ngoại lệ (Edge cases).
+
+## 3. Quy trình thực hiện (Step-by-step Process)
+- **Bước 1: Tiếp nhận và đọc quét (Read & Scan):**
+  Đọc toàn bộ tài liệu đầu vào (ví dụ trong folder `TÀI LIỆU/input/`) ít nhất 2 lần để nắm bức tranh tổng thể và ngữ cảnh nghiệp vụ.
+  Sau đó đọc source code liên quan (nếu workspace có source repos):
+  - Ưu tiên đọc: data models/entity, API endpoints hiện tại, service/business logic
+  - Mục đích: hiểu hệ thống đang tồn tại, tìm constraints kỹ thuật, tránh đề xuất mâu thuẫn architecture
+  - Nếu GitNexus MCP có sẵn: dùng `gitnexus: query()` / `gitnexus: context()` thay vì đọc file trực tiếp
+- **Bước 2: Phân loại thông tin (Categorize):**
+  Trích xuất các thông tin theo các cấu trúc:
+    - Mục tiêu của chức năng.
+    - Các tác nhân tham gia vào luồng.
+    - Các yêu cầu chức năng (các hành động, nút bấm, trường thông tin).
+    - Các yêu cầu phi chức năng (bảo mật, hiệu năng, nền tảng hệ điều hành/trình duyệt).
+- **Bước 3: Nhận diện và ghi nhận Gap (Identify Gaps):**
+  Đối chiếu từng yêu cầu chức năng với các câu hỏi:
+    - Dữ liệu đầu vào của trường này có giới hạn độ dài/định dạng không?
+    - Nếu để trống thì hệ thống xử lý thế nào? Có thông báo lỗi gì không?
+    - 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.
+
+## 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ì?)
+- [ ] Đã làm rõ tất cả các Tác nhân (Actors) tham gia chưa?
+- [ ] Đã bóc tách hết các trường thông tin (Inputs) được liệt kê trong tài liệu thô chưa?
+- [ ] Đã ghi nhận rõ ràng danh sách các điểm mơ hồ hoặc thiếu thông tin dưới dạng **Gap/Assumption** chưa?
+- [ ] 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/`.

package/custom/skills/ba-skills/skill-ba-prototype-v1.md

@@ -0,0 +1,35 @@
+# Skill: Thiết kế Layout và Prototype HTML/CSS - Phiên bản v1
+
+## 1. Mục đích (Purpose)
+Kỹ năng này hướng dẫn BA thiết kế và hiện thực hóa giao diện người dùng (UI mockup/prototype) dưới dạng mã nguồn HTML/CSS tự chứa (self-contained). Prototype giúp khách hàng hình dung trực quan luồng đi của màn hình, đồng thời giúp lập trình viên và kiểm thử viên xác định chính xác cấu trúc trang, ID của các phần tử và vị trí hiển thị lỗi.
+
+## 2. Kiến thức cần có (Prerequisite Knowledge)
+- **HTML5 Semantic Tags:** Sử dụng các thẻ ngữ nghĩa như `<header>`, `<main>`, `<section>`, `<nav>`, `<form>`, `<input>`, `<button>`, `<label>` để trang web có cấu trúc chuẩn SEO và dễ kiểm thử.
+- **Vanilla CSS Layouts:** Thành thạo Flexbox và CSS Grid để dựng bố cục nhanh chóng, đáp ứng tốt trên các kích thước màn hình khác nhau (Responsive).
+- **Nguyên lý UX/UI cơ bản:**
+  - *Primary Flow & Visual Hierarchy:* Làm nổi bật các thành phần quan trọng bằng kích thước, màu sắc và độ tương phản (ví dụ: nút bấm chính).
+  - *Bố cục F-pattern & Z-pattern:* Đặt tiêu đề, logo ở góc trên bên trái, thông tin quan trọng chạy ngang và chéo xuống nút bấm thực thi ở góc dưới bên phải.
+  - *Khoảng trắng (Whitespace):* Giữ khoảng cách hợp lý giữa các nhóm thông tin (Chunking) để tránh rối mắt.
+
+## 3. Quy trình thực hiện (Step-by-step Process)
+- **Bước 1: Phân tích các thành phần (Wireframing mentally):**
+  Dựa trên tài liệu phân tích, liệt kê tất cả các phần tử UI cần có (ví dụ: Logo, Tiêu đề, Ô nhập ID, Ô nhập Password, Nút Đăng nhập, Link Quên mật khẩu, Vùng hiển thị lỗi).
+- **Bước 2: Dựng khung HTML:**
+  - Viết mã HTML chuẩn. Bắt buộc đặt các thuộc tính `id`, `name`, `type`, `placeholder` rõ ràng cho các ô nhập liệu (ví dụ: `<input type="text" id="username" name="username"...>`).
+  - Đưa các thông báo lỗi (Error message) vào đúng vị trí dưới các ô nhập liệu, gán class dạng `.error-message` hoặc `.inline-error` và tạm ẩn đi bằng CSS (`display: none;` hoặc thông qua trạng thái ẩn) nhưng vẫn có mặt trong mã nguồn để Tester biết vị trí hiển thị.
+- **Bước 3: Tạo kiểu dáng CSS:**
+  - Sử dụng thẻ `<style>` nội bộ nằm ngay trong file HTML (để file HTML tự chứa tất cả tài nguyên, dễ chia sẻ và import vào tài liệu spec).
+  - 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/`.
+
+## 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).
+- [ ] Tất cả các trường nhập liệu đã có thẻ `<label>` tương ứng và thuộc tính `id`, `name` chưa?
+- [ ] Vị trí các thông báo lỗi (Alert và Inline error) đã được dựng sẵn trong code và định dạng rõ ràng chưa?
+- [ ] Giao diện có hiển thị cân đối trên cả màn hình Desktop và Mobile không?
+- [ ] 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/`.

package/custom/skills/ba-skills/skill-ba-qa-template-v1.md

@@ -0,0 +1,21 @@
+# Skill: Template Q&A - Phiên bản v1
+
+Mẫu tài liệu dùng để trình bày danh sách câu hỏi Q&A và theo dõi phản hồi từ khách hàng.
+
+---
+
+# Tài liệu Q&A: [Tên Chức Năng]
+
+*Tài liệu này dùng để theo dõi các vấn đề nghiệp vụ cần làm rõ giữa đội ngũ dự án và khách hàng. Trạng thái bao gồm: **Open** (Đang chờ phản hồi), **Confirmed** (Đã thống nhất).*
+
+## Danh sách câu hỏi Q&A
+
+| ID | Chức năng / Màn hình | Nội dung yêu cầu hiện tại | Câu hỏi / Điểm chưa rõ | Đề xuất giải pháp (Options) | Câu trả lời của Khách hàng | Trạng thái |
+| :-: | :--- | :--- | :--- | :--- | :--- | :-: |
+| **QA-01** | *Đăng nhập* | *Có text link đổi mật khẩu* | *Text link này sẽ dẫn sang URL cụ thể nào? Hệ thống tự sinh OTP gửi mail hay chuyển sang màn nhập email?* | *- Option A: Chuyển sang URL `/forgot-password` để nhập Email nhận link reset.<br>- Option B: Hiển thị popup nhập SĐT nhận OTP.* | *Khách hàng phản hồi: Chọn Option A, link URL là `/forgot-password`* | **Confirmed** |
+| **QA-02** | | | | | | **Open** |
+
+---
+## Lịch sử cập nhật tài liệu
+*Sau mỗi lần nhận phản hồi, BA cập nhật bảng trên và ghi nhận lịch sử tại đây:*
+- **Ngày [dd/mm/yyyy]:** Nhận phản hồi lần 1 từ khách hàng cho câu hỏi QA-01. Cập nhật trạng thái sang **Confirmed** và chỉnh sửa tài liệu Phân tích bản đầu tương ứng.

package/custom/skills/ba-skills/skill-ba-qa-v1.md

@@ -0,0 +1,35 @@
+# Skill: Xử lý và Thiết kế Q&A (Q&A Specification) - Phiên bản v1
+
+## 1. Mục đích (Purpose)
+Kỹ năng này giúp BA thiết kế các câu hỏi rõ ràng, khách quan và chuyên nghiệp để gửi tới khách hàng/stakeholders nhằm làm rõ các khoảng trống nghiệp vụ (Gaps). Đồng thời, hướng dẫn cách tiếp nhận câu trả lời để cập nhật tài liệu phân tích một cách nhất quán, tránh hiểu sai hoặc tự ý giả định thông tin.
+
+## 2. Kiến thức cần có (Prerequisite Knowledge)
+- **Kỹ năng giao tiếp bằng văn bản (Written Communication):** Sử dụng câu từ ngắn gọn, lịch sự, đi thẳng vào vấn đề.
+- **Kỹ thuật đặt câu hỏi mở và đóng:**
+    - Tránh câu hỏi mập mờ (ví dụ: "Hệ thống có cần khóa tài khoản không?").
+    - Nên đưa ra các tùy chọn rõ ràng (ví dụ: "Khi nhập sai mật khẩu liên tiếp, hệ thống sẽ xử lý thế nào? Tùy chọn A: Khóa tài khoản sau 5 lần sai trong 30 phút. Tùy chọn B: Chỉ hiển thị thông báo lỗi mà không khóa tài khoản. Tùy chọn C: Ý kiến khác...").
+- **Tư duy kiểm thử (Testing Mindset):** Đứng dưới góc nhìn của Tester để hỏi về các biên dữ liệu, các trường hợp lỗi mạng, mất kết nối cơ sở dữ liệu, hoặc dữ liệu không hợp lệ.
+
+## 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`:**
+  - 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ồ.
+  - Đưa ra các giải pháp đề xuất (Options) cùng giả định của BA.
+- **Bước 3: Nhận phản hồi và Cập nhật (Process Responses):**
+  - Khi nhận được câu trả lời từ khách hàng: Đọc kỹ để đảm bảo câu trả lời đã giải quyết triệt để câu hỏi. Nếu câu trả lời vẫn chưa rõ ràng, tiếp tục duy trì trạng thái "Open" và hỏi lại ở version tiếp theo.
+  - Nếu đã rõ ràng: Đánh dấu "Resolved" và cập nhật thông tin đó trực tiếp vào tài liệu phân tích hiện tại (`Kết quả phân tích(n).md`).
+  - Ghi nhận lịch sử thay đổi để Dev/Test nắm được lý do thay đổi logic.
+
+## 4. Checklist kiểm tra (Checklist for Verification)
+- [ ] Mỗi câu hỏi có chỉ rõ phần màn hình/tính năng liên quan không?
+- [ ] Câu hỏi có sử dụng từ ngữ trung lập, không mang tính áp đặt ý kiến chủ quan của BA không?
+- [ ] Có đưa ra các phương án gợi ý (Option A, Option B...) cho các vấn đề phức tạp để khách hàng dễ lựa chọn không?
+- [ ] Các thuật ngữ viết tắt trong câu hỏi có được giải thích rõ không?
+- [ ] Đã 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/`.
+- 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-template-phan-tich-ban-dau-v1.md

@@ -0,0 +1,30 @@
+# Skill: Template Phân Tích Ban Đầu - Phiên bản v1
+
+Mẫu tài liệu này được sử dụng để trình bày kết quả phân tích yêu cầu ban đầu sau khi bóc tách từ tài liệu thô.
+
+---
+
+# Tài liệu Phân Tích Yêu Cầu Ban Đầu: [Tên Chức Năng]
+
+## 1. Mục tiêu chức năng
+*Mô tả ngắn gọn chức năng này dùng để làm gì? Giải quyết nhu cầu gì của doanh nghiệp hoặc người dùng?*
+
+## 2. Các tác nhân chính (Actors)
+*Liệt kê danh sách các tác nhân (User, Admin, Manager...) sẽ tương tác trực tiếp hoặc gián tiếp với chức năng.*
+
+## 3. Yêu cầu chức năng chi tiết (Functional Requirements)
+*Bóc tách chi tiết các tính năng nhỏ, các nút bấm, các hành động mà hệ thống phải xử lý.*
+- **Giao diện/Trường thông tin:** Liệt kê các trường dữ liệu cần hiển thị hoặc nhập liệu.
+- **Quy tắc nhập liệu sơ bộ:** Định dạng, bắt buộc hay không (Required/Optional).
+
+## 4. Yêu cầu phi chức năng (Non-Functional Requirements)
+*Các yêu cầu về bảo mật, hiệu suất, khả năng tương thích, hoặc giao diện UX/UI đặc thù.*
+
+## 5. Bảng Phân Tích Khoảng Trống & Giả Định (Gap & Assumption Analysis)
+
+| # | Tính năng/Luồng nghiệp vụ | Hiện trạng mô tả thô | Khoảng trống (Gap) / Sự mơ hồ phát hiện | Giả định của BA (Assumption) | Đề xuất giải pháp / Q&A ID tương ứng |
+| :-: | :--- | :--- | :--- | :--- | :--- |
+| 1 | *Ví dụ: Nhập Password* | *Mật khẩu được che giấu* | *Có nút show/hide mật khẩu hay không? Đăng nhập sai bao nhiêu lần thì khóa?* | *Mặc định không hiển thị nút show/hide. Cho phép nhập sai tối đa 5 lần.* | *Xem Q&A_01* |
+| 2 | | | | | |
+
+*Lưu ý: Bảng này là cơ sở quan trọng nhất để tạo ra danh sách câu hỏi Q&A chuẩn xác cho khách hàng.*

package/custom/skills/ba-skills/skill-ba-template-uc-v1.md

@@ -0,0 +1,83 @@
+# Skill: Template Đặc tả Use Case (Use Case Spec) - Phiên bản v1
+
+Cấu trúc chuẩn của một tài liệu đặc tả Use Case hoàn chỉnh dùng để chuyển giao cho Dev/Test.
+
+---
+
+# Tài liệu Đặc Tả Use Case: Chức năng [Tên Chức Năng]
+
+## 1. Thông tin chung (General Information)
+
+| Thuộc tính | Mô tả chi tiết |
+| :--- | :--- |
+| **Tên chức năng (Function Name)** | [Tên chức năng chính xác] |
+| **Mô tả (Description)** | [Tóm tắt mục đích và giá trị nghiệp vụ của chức năng] |
+| **Tác nhân (Actors)** | [Danh sách các tác nhân sử dụng hoặc bị tác động] |
+| **Tác nhân kích hoạt (Trigger)** | [Sự kiện kích hoạt luồng xử lý này] |
+| **Điều kiện tiên quyết (Pre-Conditions)** | [Các điều kiện hệ thống hoặc trạng thái dữ liệu bắt buộc phải có trước khi thực hiện] |
+| **Điều kiện sau xử lý (Post-Conditions)** | [Trạng thái của hệ thống và dữ liệu sau khi kết thúc thành công] |
+
+### Luồng xử lý chính (Main Flow)
+
+| Bước | Tác nhân (Actor Action) | Hệ thống (System Response) |
+| :-: | :--- | :--- |
+| 1 | Người dùng kích hoạt sự kiện... | Hệ thống hiển thị giao diện... |
+| 2 | Người dùng nhập các thông tin... | |
+| 3 | Người dùng nhấn nút... | Hệ thống kiểm tra và thực hiện... |
+| 4 | | Hệ thống thông báo thành công và chuyển hướng... |
+
+### Các luồng thay thế / ngoại lệ (Alternative / Exception Flows)
+
+- **Alternative Flow A: [Tên luồng thay thế]**
+  - Thực hiện từ bước [X] của Luồng chính:
+  - Các bước xử lý: ...
+- **Exception Flow B: [Tên luồng lỗi]**
+  - Thực hiện khi xảy ra lỗi: ...
+  - Các bước xử lý: ...
+
+---
+
+## 2. Mô tả màn hình (Screen Description)
+*Nhúng code HTML của màn hình prototype hoặc ảnh chụp mockup tại đây:*
+
+```html
+<!-- Dán code HTML/CSS prototype ở đây -->
+```
+
+---
+
+## 3. Mô tả thành phần giao diện (UI Components Description)
+
+| # | Tên Component | Loại Component | Cho phép sửa | Bắt buộc | Giá trị mặc định | Quy tắc định dạng & Giới hạn dữ liệu | Mô tả hành vi & tương tác |
+| :-: | :--- | :--- | :-: | :-: | :--- | :--- | :--- |
+| 1 | `ログインID` | Textbox | Yes | Yes | None | Độ dài: 3-20 ký tự. Chỉ chữ và số. Không chứa khoảng trắng. | Ô nhập tên tài khoản của người dùng. |
+| 2 | `ログイン` | Button | N/A | N/A | N/A | N/A | Nhấn để gửi thông tin đăng nhập lên hệ thống. |
+| 3 | | | | | | | |
+
+---
+
+## 4. Sơ đồ luồng hoạt động (Activity Flow Diagram)
+*Sử dụng biểu đồ Mermaid để trực quan hóa quy trình xử lý.*
+
+```mermaid
+graph TD
+    %% Viết mã nguồn Mermaid tại đây
+```
+
+---
+
+## 5. Quy tắc nghiệp vụ (Business Rules)
+
+### BR1: Quy tắc kiểm tra dữ liệu đầu vào (Validation Rules)
+*Định nghĩa các lỗi khi người dùng nhập dữ liệu sai hoặc để trống.*
+- **[BR1.1] Trống dữ liệu bắt buộc:** Nếu bất kỳ trường bắt buộc nào bị trống khi nhấn nút thực thi:
+  - Hệ thống dừng xử lý.
+  - Hiển thị lỗi tương ứng: `[Tên thông báo lỗi]` dưới ô nhập liệu bị trống.
+- **[BR1.2] Định dạng dữ liệu không hợp lệ:** ...
+
+### BR2: Quy tắc lưu trữ dữ liệu (Saving Rules)
+*Định nghĩa cách dữ liệu được ghi nhận vào cơ sở dữ liệu.*
+- **[BR2.1]** Hệ thống ghi nhận thời gian đăng nhập vào bảng `user_logs` với các trường: `user_id`, `login_time`, `status`.
+
+### BR3: Quy tắc phân quyền & Bảo mật (Authorization & Security Rules)
+- **[BR3.1]** Sau 5 lần nhập sai mật khẩu liên tiếp, tài khoản tự động bị khóa trong 30 phút.