@edupia-tutor/spec-driven-docs 0.14.0

package/skills/qc/qa-runner/e2e.md

@@ -0,0 +1,49 @@
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# Gen Script — E2E Journey
+
+Skill **tự chứa**: convert journey `.Test.md` → Python pytest + Playwright đầu→cuối xuyên nhiều màn/module. Chỉ cần load file này.
+
+## Khi nào trigger
+- Convert TC E2E journey (output qa-designer e2e/journey) sang script; TC đã Reviewed
+
+## Khi KHÔNG trigger
+- Test 1 màn/field → `functional/*` · 1 điểm tích hợp → `integration.md`
+
+## Quy ước script (bám CLAUDE.md)
+- Tiền đề: `.Test.md` đã Reviewed. KHÔNG hardcode → `Env.*`/`CONFIG`; KHÔNG `time.sleep()` → `expect()`.
+- Dùng chuỗi Page Object xuyên các màn; verify points (V1…Vn) thành các `assert_*()` rõ ràng.
+- **Tiền điều kiện qua fixture** (tài khoản role, dữ liệu lớp/buổi); **cleanup** sau journey; mỗi journey độc lập.
+- Cần verify hệ thống ngoài (DB/CRM) → client/fixture riêng. Bọc mỗi chặng `with step("…")` (`from utils.steps import step`, **KHÔNG Allure**); assertion `expect()`; marker `@pytest.mark.e2e`.
+- Naming: class `TestFeatureE2E`, method `test_E2E_<NN>_<snake>`.
+
+## Phase 1 — Clarify
+Đọc journey `.Test.md` · các màn/PO + hệ thống verify · tài khoản role & data cần dựng · điểm cleanup.
+
+## Phase 2 — Generate
+Mỗi journey → 1 test; bọc từng bước `with step("…")`; cuối journey verify đủ V1…Vn (tạo/mã/định tuyến/đồng bộ/danh sách).
+Journey còn phụ thuộc gap → tạo test `@pytest.mark.skip(reason="GAP-xx")` hoặc xfail.
+
+## Phase 3 — Verify
+`py_compile` + `pytest --collect-only -q` · chạy (môi trường staging + CRM) · cập nhật Status TC.
+**Phân loại FAIL: script-bug vs product-gap** — journey fail vì 1 bước feature chưa wire = gap (giữ FAIL/skip + bằng chứng), không phải lỗi script; sai selector/state mới sửa script.
+
+## Output
+Script `tests/<project>/e2e/test_<feature>.py` + Page Object/client tái dùng. Bàn giao `qa-reviewer`.
+
+## Phase 4 — Report (bắt buộc sau khi chạy test)
+Report = **Playwright Trace viewer + pytest-html** (KHÔNG Allure, KHÔNG dashboard tự viết).
+
+1. Chạy test kèm pytest-html (trace đã bật sẵn ở conftest → mỗi test có `test-results/<nodeid>/trace.zip`):
+   ```bash
+   pytest tests/<project>/e2e/test_<feature>.py --html=reports/<feature>/report.html --self-contained-html
+   ```
+2. Gửi cho người dùng:
+   - HTML report: `reports/<feature>/report.html` (self-contained, mở trực tiếp).
+   - Trace từng test (debug step-by-step): `python3 -m playwright show-trace test-results/<nodeid>/trace.zip`.
+   - Tóm tắt: **TOTAL / PASS / FAIL / SKIP** + duration.
+3. TC Fail → mở trace tương ứng để xem timeline/DOM snapshot/network, phân loại script-bug vs product-gap; ghi mô tả lỗi tiếng Việt dễ hiểu vào Status/khối kết quả của `.Test.md`.

package/skills/qc/qa-runner/exploratory/session.md

@@ -0,0 +1,36 @@
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# Session Template & Convert Findings — Exploratory
+
+Skill **tự chứa**, 2 mode:
+- **Mode 1:** sinh session note template trước khi test.
+- **Mode 2:** convert findings (#BUG/#IDEA) → bug report + functional TC mới.
+
+## Khi nào trigger
+- Mode 1: "tạo template cho session" / trước exploratory session
+- Mode 2: "convert findings" / "tạo bug report" / sau session
+
+## Khi KHÔNG trigger
+- Sinh charter → `qa-designer/exploratory/charter.md` · review session note → `qa-reviewer/script/exploratory.md`
+
+---
+
+## Mode 1 — Generate Session Template
+Input: charter + tour + tester + time-box. Tạo file gồm: metadata (date/tester/charter/tour/env/data) ·
+`#SETUP` (bước chuẩn bị) · `#TEST` (5–8 gợi ý theo tour) · `#BUG` template (title, severity, steps,
+expected/actual) · `#QUESTION`, `#IDEA` placeholder · summary cuối session.
+→ `{paths.qc_dir}/exploratory/sessions/<YYYY-MM-DD>_<tester>.md`
+
+## Mode 2 — Convert Findings
+Input: session note (#BUG + #IDEA).
+- **Bug report** mỗi #BUG: title, severity, priority, steps to reproduce, expected/actual, hypothesis root cause.
+- **Functional TC mới:** mỗi #BUG đã fix → 1–2 TC regression; mỗi #IDEA → TC nếu đủ rõ (hoặc backlog).
+  Đặt đúng layer; bám format TC (Test Data list, Trace BR, 🚫 Block); trace "Origin: Exploratory session <date>".
+- **Weekly summary** (nếu yêu cầu): overview, top findings, coverage gap, recommendations.
+
+## Output
+Mode 1: file session note. Mode 2: bug reports + file TC trong `{paths.qc_dir}/{UC-ID}/test-cases/` + summary.

package/skills/qc/qa-runner/functional/api.md

@@ -0,0 +1,35 @@
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# Gen Script — Functional API
+
+Skill **tự chứa**: convert `.Test.md` API → Python pytest (requests/httpx), không qua UI. Chỉ cần load file này.
+
+## Khi nào trigger
+- Convert TC API (output qa-designer functional/api) sang script; TC đã Reviewed
+
+## Khi KHÔNG trigger
+- Test qua UI → `functional/gui-screen.md` · tích hợp đa thành phần → `integration.md`
+
+## Quy ước script (bám CLAUDE.md)
+- Tiền đề: `.Test.md` đã Reviewed. KHÔNG hardcode base URL/token → `Env.*`/`CONFIG`.
+- Client API gói trong helper/fixture (base url, auth header); KHÔNG rải request rời rạc trong test.
+- Assertion: `assert` cho status code + field response (jsonpath); `with step(...)` (`from utils.steps`) cho mỗi call.
+- Marker `@pytest.mark.api` + category; fixture `function`; test độc lập (tạo→cleanup data qua API/teardown).
+- Naming: class `TestFeatureAPI`, method `test_TC<NNN>_<snake>`.
+
+## Phase 1 — Clarify
+Đọc `.Test.md` · base url/auth/role · client/fixture đã có chưa · data setup/cleanup.
+
+## Phase 2 — Generate
+Mỗi TC → 1 test gọi endpoint với request từ Test Data; assert **status code + field body** theo Expected.
+Nhóm happy/validation/auth/not-found/edge. Data từ `test_data/`.
+
+## Phase 3 — Verify
+`py_compile` + `pytest --collect-only -q` · chạy · cập nhật Status TC · in mapping.
+
+## Output
+Script `tests/<project>/functional/api/test_<feature>.py` + API client/fixture nếu mới. Bàn giao `qa-reviewer`.

package/skills/qc/qa-runner/functional/gui-feature.md

@@ -0,0 +1,51 @@
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# Gen Script — Functional GUI Feature (đa màn hình)
+
+Skill **tự chứa**: convert `.Test.md` feature span ≥2 màn → Python pytest + Playwright. Chỉ cần load file này.
+
+## Khi nào trigger
+- Convert TC feature đa màn (output qa-designer gui-feature) sang script; TC đã Reviewed
+
+## Khi KHÔNG trigger
+- Gọn 1 màn → `functional/gui-screen.md` · API → `functional/api.md` · đầu-cuối + đồng bộ → `e2e.md`
+
+## Quy ước script (bám CLAUDE.md)
+- Tiền đề: `.Test.md` đã Reviewed. KHÔNG `time.sleep()` → `expect()`/auto-wait; KHÔNG hardcode → `Env.*`/`CONFIG`.
+- **Một Page Object / màn**; điều hướng giữa màn là action trả về PO màn kế (`return NextPage(self.page)`).
+- PO 3 lớp (kế thừa slim `BasePage`, **KHÔNG Allure**) + bọc bước `with step("…")` (`from utils.steps import step`); assertion `expect()`; mọi interaction qua PO; selector constants `UPPER_SNAKE`.
+- Marker + fixture pytest-playwright từ root `tests/conftest.py` (`page`/`logged_in_page`/`logged_in_page_gv`/`login_page`/`dashboard`); test độc lập + cleanup; naming `Test*{...}` / `test_TC<NNN>_<snake>`.
+
+## Phase 1 — Clarify
+Đọc `.Test.md` · liệt kê các màn/PO cần · state truyền giữa màn · fixture dựng tiền điều kiện (data qua nhiều bước).
+**Probe DOM thật trước khi viết selector** (SPA React/Next không `data-testid`): dump class/`aria-label`/role → BEM `feature__el`, carousel dot thường `role="tab"` + class `--active` (không `aria-selected`).
+
+## Phase 2 — Generate
+**PHỦ HẾT 100%**: 1 test cho **MỌI** TC trong file (`grep -cE "^#{2,4} *TC_"` = số test phải sinh), KHÔNG chọn tập đại diện, KHÔNG để TC nào Draft; TC bất khả thi → `pytest.skip`/`xfail` + lý do.
+Bọc mỗi chặng bằng `with step("…")`; dùng chuỗi PO theo điều hướng.
+Phủ TC điều hướng forward/back/giữ-reset state. Data từ `test_data/`. Marker mới (`bva ep e2e`…) đăng ký `pytest.ini`.
+
+## Phase 3 — Verify
+`py_compile` + `pytest --collect-only -q` (**số collect = tổng TC**; thiếu → sinh nốt) · chạy · cập nhật Status TC (verify KHÔNG còn Draft) · in mapping.
+**Gom nhóm role/account** tự áp qua `utils/test_ordering.py` (root conftest); fixture auth mới → `register_auth_fixtures([...])`. ⚠️ Run dài bị **WSL suspend** có thể gây flaky login/timeout → re-run TC đó + merge report.
+**Phân loại FAIL: script-bug (sửa selector/logic, chạy lại) vs product-gap** (feature chưa wire/defect → giữ FAIL + ghi bằng chứng vào khối "Kết quả thực thi" đầu `.Test.md`, không fake-pass).
+
+## Output
+Script + nhiều Page Object (mỗi màn) trong `pages/<project>/...`. Bàn giao `qa-reviewer` (script).
+
+## Phase 4 — Report (bắt buộc sau khi chạy test)
+Report = **Playwright Trace viewer + pytest-html** (KHÔNG Allure, KHÔNG dashboard tự viết).
+
+1. Chạy test kèm pytest-html (trace đã bật sẵn ở conftest → mỗi test có `test-results/<nodeid>/trace.zip`):
+   ```bash
+   pytest tests/<project>/.../test_<feature>.py --html=reports/<feature>/report.html --self-contained-html
+   ```
+2. Gửi cho người dùng:
+   - HTML report: `reports/<feature>/report.html` (self-contained, mở trực tiếp).
+   - Trace từng test (debug step-by-step): `python3 -m playwright show-trace test-results/<nodeid>/trace.zip`.
+   - Tóm tắt: **TOTAL / PASS / FAIL / SKIP** + duration.
+3. TC Fail → mở trace tương ứng để xem timeline/DOM snapshot/network, phân loại script-bug vs product-gap; ghi mô tả lỗi tiếng Việt dễ hiểu vào Status/khối kết quả của `.Test.md`.

package/skills/qc/qa-runner/functional/gui-screen.md

@@ -0,0 +1,55 @@
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# Gen Script — Functional GUI Screen (1 màn hình)
+
+Skill **tự chứa**: convert `.Test.md` (1 màn) → Python pytest + Playwright. Chỉ cần load file này.
+
+## Khi nào trigger
+- "generate script cho [Screen]" / convert TC sang Python; đã có `.Test.md` (output qa-designer gui-screen), TC đã Reviewed
+
+## Khi KHÔNG trigger
+- Chưa có TC `.md` → chạy qa-designer trước · TC chưa review → qa-reviewer trước
+- Feature cross-screen → `functional/gui-feature.md` · API → `functional/api.md`
+
+## Quy ước script (bám CLAUDE.md)
+- Tiền đề: có `.Test.md` đã Reviewed. KHÔNG `time.sleep()` → `expect()`/auto-wait; KHÔNG hardcode → `Env.*`/`CONFIG`.
+- Page Object 3 lớp (kế thừa slim `BasePage`, **KHÔNG Allure**): locators `_x()` → actions `verb_noun()`+`with step("…")`+`return self` → assertions `assert_x()`+`expect()`; mọi interaction **qua PO** (không `page.click()` trực tiếp); selector constants `UPPER_SNAKE` đầu class.
+- Bọc bước bằng `with step("…")` (`from utils.steps import step`) — **KHÔNG Allure** · marker category+domain (đăng ký `pytest.ini`) · fixture pytest-playwright từ root `tests/conftest.py` (`page`/`logged_in_page`/`logged_in_page_gv`/`login_page`/`dashboard`) · test độc lập + cleanup.
+- Naming: class `TestFeature{UI,Functional,Negative}`, method `test_TC<NNN>_<snake>`; docstring = TC title; comment TC_ID + link `.md`.
+
+## Phase 1 — Clarify
+Đọc `.Test.md` (confirm Reviewed) · platform (web Playwright/mobile) · Page Object đã có chưa → tạo nếu cần · fixture setup data?
+**Probe DOM thật trước khi viết selector** (SPA không `data-testid`): dump class/`aria-label`/role bằng script Playwright tạm → ghi selector đúng (BEM `feature__el`; element interactive có thể `role="tab/menuitem"` + class `--active`).
+
+## Phase 2 — Generate
+**PHỦ HẾT 100%**: sinh 1 `test_TC<NNN>_<scenario>` cho **MỌI** TC trong file — KHÔNG chọn tập đại diện, KHÔNG bỏ TC nào. Đếm tổng TC đầu file (`grep -cE "^#{2,4} *TC_"`) = số test phải sinh.
+TC không thể tự động hóa (precondition bất khả thi, cần data cố định, feature chưa wire) → vẫn viết 1 test với `pytest.skip("lý do")` / `pytest.mark.xfail` — KHÔNG để Draft.
+Map nhóm GUI→`TestFeatureUI`, Functional→`TestFeatureFunctional`, Negative→`TestFeatureNegative`. Assertion qua `assert_*()` của PO; test data từ `test_data/`, không hardcode. Marker mới (`bva ep`…) đăng ký `pytest.ini`.
+
+## Phase 3 — Verify
+`py_compile` + `pytest --collect-only -q` (**số collect = tổng TC trong file**, nếu thiếu → quay lại Phase 2 sinh nốt) · chạy test · cập nhật **Status** TC (Pass/Fail/Skip) · in mapping TC_ID→function→file.
+**Gom nhóm role/account**: thứ tự chạy đã tự gom cùng (role, account) liền nhau qua `utils/test_ordering.py` (hook ở root conftest) — fixture auth mới thì `register_auth_fixtures([...])`.
+⚠️ Run dài có thể bị **WSL suspend** (máy ngủ) làm vài TC lỗi login/timeout = flaky (không phải gap SP) → re-run đúng các TC đó + merge vào report (xem `report/report.md`).
+**Verify KHÔNG còn Draft**: `grep -c "Status: Draft" <file>.Test.md` = 0 trước khi bàn giao.
+**Mỗi FAIL phân loại script-bug vs product-gap** (probe trực tiếp): sai selector/expectation → sửa script & chạy lại; feature không phản hồi sau timeout → giữ FAIL + ghi bằng chứng (không fake-pass).
+
+## Output
+Script `tests/<project>/.../test_<screen>.py` + Page Object `pages/<project>/.../<Screen>Page.py` (nếu mới).
+Bàn giao `qa-reviewer` (script).
+
+## Phase 4 — Report (bắt buộc sau khi chạy test)
+Report = **Playwright Trace viewer + pytest-html** (KHÔNG Allure, KHÔNG dashboard tự viết).
+
+1. Chạy test kèm pytest-html (trace đã bật sẵn ở conftest → mỗi test có `test-results/<nodeid>/trace.zip`):
+   ```bash
+   pytest tests/<project>/.../test_<screen>.py --html=reports/<feature>/report.html --self-contained-html
+   ```
+2. Gửi cho người dùng:
+   - HTML report: `reports/<feature>/report.html` (self-contained, mở trực tiếp).
+   - Trace từng test (debug step-by-step): `python3 -m playwright show-trace test-results/<nodeid>/trace.zip`.
+   - Tóm tắt: **TOTAL / PASS / FAIL / SKIP** + duration.
+3. TC Fail → mở trace tương ứng để xem timeline/DOM snapshot/network, phân loại script-bug vs product-gap; ghi mô tả lỗi tiếng Việt dễ hiểu vào Status/khối kết quả của `.Test.md`.

package/skills/qc/qa-runner/integration.md

@@ -0,0 +1,47 @@
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# Gen Script — Integration
+
+Skill **tự chứa**: convert `.Test.md` tích hợp (API↔DB↔service↔queue↔UI) → Python pytest. Chỉ cần load file này.
+
+## Khi nào trigger
+- Convert TC integration (output qa-designer integration/*) sang script; TC đã Reviewed
+
+## Khi KHÔNG trigger
+- Chỉ 1 endpoint/UI đơn → `functional/*` · hành trình đầu-cuối → `e2e.md`
+
+## Quy ước script (bám CLAUDE.md)
+- Tiền đề: `.Test.md` đã Reviewed. KHÔNG hardcode endpoint/DSN/topic → `Env.*`/`CONFIG`.
+- Mỗi hệ thống có client/helper riêng (API client, DB session, Kafka producer/consumer) gói trong fixture.
+- Verify đúng chặng: response (assert), DB (query qua fixture), event (consume + assert payload).
+- **Cleanup bắt buộc** sau khi tạo data; test độc lập; concurrency dùng thread/async khi cần.
+- Bọc mỗi chặng `with step("…")` (`from utils.steps import step`, **KHÔNG Allure**); assertion `expect()`; marker `@pytest.mark.integration` + domain; naming `TestFeatureIntegration` / `test_TC<NNN>_<snake>`.
+
+## Phase 1 — Clarify
+Đọc `.Test.md` · chuỗi tích hợp & chặng cần verify · client/fixture (API/DB/Kafka) đã có chưa · setup/teardown data.
+
+## Phase 2 — Generate
+Mỗi TC → 1 test theo data flow: gọi action → verify từng chặng (response/DB/event). Nhóm happy/contract-negative/failure-retry/concurrency/đồng bộ.
+
+## Phase 3 — Verify
+`py_compile` + `pytest --collect-only -q` · chạy (cần môi trường staging/CRM/Kafka) · cập nhật Status TC.
+
+## Output
+Script `tests/<project>/integration/test_<feature>.py` + client/fixture (DB/Kafka/API) nếu mới. Bàn giao `qa-reviewer`.
+
+## Phase 4 — Report (bắt buộc sau khi chạy test)
+Report = **Playwright Trace viewer + pytest-html** (KHÔNG Allure, KHÔNG dashboard tự viết).
+
+1. Chạy test kèm pytest-html (trace đã bật sẵn ở conftest → mỗi test có `test-results/<nodeid>/trace.zip`):
+   ```bash
+   pytest tests/<project>/integration/test_<feature>.py --html=reports/<feature>/report.html --self-contained-html
+   ```
+2. Gửi cho người dùng:
+   - HTML report: `reports/<feature>/report.html` (self-contained, mở trực tiếp).
+   - Trace từng test (debug step-by-step): `python3 -m playwright show-trace test-results/<nodeid>/trace.zip`.
+   - Tóm tắt: **TOTAL / PASS / FAIL / SKIP** + duration.
+3. TC Fail → mở trace tương ứng để xem timeline/DOM snapshot/network, phân loại script-bug vs product-gap; ghi mô tả lỗi tiếng Việt dễ hiểu vào Status/khối kết quả của `.Test.md`.

package/skills/qc/qa-runner/non-functional.md

@@ -0,0 +1,49 @@
+---
+version: 1.0
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# Gen Script — Non-Functional
+
+Skill **tự chứa**: convert TC non-functional (performance/security/accessibility/compatibility) → script/đo. Chỉ cần load file này.
+
+## Khi nào trigger
+- Convert TC non-functional (output qa-designer non-functional) sang script/kịch bản đo; TC đã Reviewed
+
+## Khi KHÔNG trigger
+- Kiểm thử chức năng → `functional/*` · tích hợp → `integration.md`
+
+## Quy ước script (bám CLAUDE.md)
+- Tiền đề: `.Test.md` đã Reviewed, có **ngưỡng đo cụ thể**. KHÔNG hardcode → `Env.*`/`CONFIG`.
+- Mỗi loại dùng công cụ phù hợp, gói trong fixture/helper:
+  - **Performance:** đo response time / throughput (pytest + timer, hoặc tích hợp k6/locust); assert ngưỡng.
+  - **Security:** test authZ (role không quyền → 403), input injection, PII không lộ, session/timeout, rate limit.
+  - **Accessibility:** axe-core/lighthouse qua Playwright; assert vi phạm = 0 ở mức WCAG mục tiêu.
+  - **Compatibility:** parametrize trình duyệt/thiết bị.
+- Assert theo **ngưỡng pass** trong TC bằng `expect()`/`assert`; bọc bước `with step("…")` (`from utils.steps import step`, **KHÔNG Allure**); marker `@pytest.mark.{performance,security,accessibility}`.
+
+## Phase 1 — Clarify
+Đọc `.Test.md` · loại + ngưỡng + công cụ · môi trường/tải mẫu · data đặc biệt.
+
+## Phase 2 — Generate
+Mỗi TC → 1 test đo + assert ngưỡng; đánh dấu test cần môi trường/tải riêng (`@pytest.mark.slow`).
+
+## Phase 3 — Verify
+`py_compile` + collect · chạy (môi trường phù hợp) · cập nhật Status TC + số đo thực tế.
+
+## Output
+Script `tests/<project>/non_functional/test_<feature>.py` + helper đo/scan. Bàn giao `qa-reviewer`.
+
+## Phase 4 — Report (bắt buộc sau khi chạy test)
+Report = **Playwright Trace viewer + pytest-html** (KHÔNG Allure, KHÔNG dashboard tự viết).
+
+1. Chạy test kèm pytest-html (trace đã bật sẵn ở conftest → mỗi test có `test-results/<nodeid>/trace.zip`):
+   ```bash
+   pytest tests/<project>/non_functional/test_<feature>.py --html=reports/<feature>/report.html --self-contained-html
+   ```
+2. Gửi cho người dùng:
+   - HTML report: `reports/<feature>/report.html` (self-contained, mở trực tiếp) + số đo thực tế.
+   - Trace từng test (debug step-by-step): `python3 -m playwright show-trace test-results/<nodeid>/trace.zip`.
+   - Tóm tắt: **TOTAL / PASS / FAIL / SKIP** + duration.
+3. TC Fail → mở trace tương ứng để xem timeline/DOM snapshot/network, phân loại script-bug vs product-gap; ghi mô tả lỗi tiếng Việt dễ hiểu + số đo vào Status/khối kết quả của `.Test.md`.

package/skills/qc/qa-runner/report/report.md

@@ -0,0 +1,37 @@
+---
+version: 1.1
+updated: 2026-06-11
+ported_from: ai-automation-qc-base
+---
+
+# Report — Playwright Trace + pytest-html (stack chuẩn)
+
+Skill **tự chứa**: sinh report sau khi chạy test. Stack chuẩn dự án dùng **Playwright
+Trace viewer** + **pytest-html** (KHÔNG Allure, KHÔNG dashboard tự viết). Chỉ cần load file này.
+
+## Khi nào trigger
+- Sau khi chạy test cần xuất report / xem lại bằng chứng (trace, screenshot).
+
+## Cơ chế (đã dựng sẵn ở tests/conftest.py)
+- **Trace viewer**: fixture `context` (root conftest) gọi `context.tracing.start(screenshots=True, snapshots=True, sources=True)`; teardown lưu `test-results/<nodeid>/trace.zip`.
+  - Xem: `python3 -m playwright show-trace test-results/<...>/trace.zip` → timeline + DOM snapshot + network + console (UI giống Playwright report bản JS).
+- **pytest-html**: 1 file HTML self-contained. Hook `pytest_runtest_makereport` (root conftest) đính screenshot full-page khi FAIL/SKIP.
+  - Mặc định `reports/report.html` (pytest.ini). Theo feature: `--html=reports/<feature>/report.html --self-contained-html`.
+
+## Quy trình
+1. Chạy test với report theo feature:
+   ```
+   python3 -m pytest tests/<project>/<file>.py \
+       --html=reports/<feature>/report.html --self-contained-html
+   ```
+   (Trace tự bật trong conftest → test-results/<nodeid>/trace.zip cho mọi test.)
+2. Báo path:
+   - HTML: `reports/<feature>/report.html` (on WSL, the Windows-accessible path is `\\wsl.localhost\<distro>\<repo-path>\reports\<feature>\report.html`).
+   - Trace TC fail: `test-results/<nodeid>/trace.zip` + lệnh `playwright show-trace`.
+   - Tóm tắt TOTAL / PASS / FAIL / SKIP + duration.
+
+## Nguyên tắc
+- KHÔNG dùng Allure, KHÔNG sinh dashboard HTML tự viết (đã bỏ utils/html_report.py & cộng sự).
+- Evidence trung thực: trace + screenshot phản ánh đúng lần run; FAIL/gap giữ nguyên.
+- `reports/` và `test-results/` đã gitignore (artifact nặng) — không commit.
+- Interpreter `python3`; browser = the system/installed Chromium configured via `browser_type_launch_args` in the root conftest (see the qc-playwright module) — do not hard-code a binary path.

package/skills/setup-ai-first/SKILL.md

@@ -0,0 +1,216 @@
+---
+description: Sets up the Spec-Driven Development framework in any backend project from scratch. Trigger when: "/setup-ai-first", "setup spec-driven workflow", "initialize ai-first framework", "cài đặt framework", "khởi tạo spec-driven", "set up this workflow", "how do I start using this framework".
+---
+
+# /setup-ai-first — Initialize Spec-Driven Docs in a Project
+
+Walk the user through a one-time setup that creates all required directories, installs CLAUDE.md, and verifies the environment.
+
+## Precondition Check
+
+First, ask: "Bạn đang ở project nào? Cho tôi đường dẫn root của project."
+
+Check if already set up:
+- If `.claude/commands/` exists with `.md` files → report "Already set up. Run `/validate-traces` to check status."
+- If `specs/` exists → offer to re-initialize or skip
+
+## Step 1 — Create Directory Structure
+
+Create the following directories (skip if already exist):
+
+```
+{project-root}/
+├── specs/
+│   ├── product-definition/   # Output of /define-product
+│   └── domain-knowledge/     # Business dictionary + core entities
+├── .trace/                   # Traceability state (.trace/{domain}/{prd-slug}/{UC-ID}.tsv)
+└── .agent/
+    └── review/               # Output of /refine-prd ({prd-slug}-findings.yaml)
+```
+
+**Feature-package layout** — per-feature artifacts are NOT pre-created here; each command
+creates its own folder on demand under `specs/{domain}/{prd-slug}/`:
+
+```
+specs/{domain}/{prd-slug}/
+├── prd.md                    # /generate-prd
+├── bdd/                      # /generate-bdd (.feature files)
+├── tech-docs/                # /generate-tech-docs
+└── design-spec/              # /generate-design-spec (FE/App only)
+```
+
+Report each directory created or already existing.
+
+## Step 2 — Copy Slash Commands
+
+Tell the user:
+
+> "Framework này đã cài slash commands vào Claude tự động qua skill system.
+> Nếu bạn muốn dùng commands trực tiếp trong Claude Code project (`.claude/commands/`), chạy lệnh sau:"
+
+```bash
+# Copy all commands from plugin to project
+mkdir -p {project-root}/.claude/commands
+cp {plugin-dir}/commands/*.md {project-root}/.claude/commands/
+```
+
+Note: The `.claude/commands/` copies are optional. Skills in this framework work without them.
+
+## Step 3 — Create CLAUDE.md
+
+Check if `{project-root}/CLAUDE.md` exists:
+- If yes: ask "CLAUDE.md đã tồn tại. Merge template vào hay bỏ qua?"
+- If no: create from template in `templates/architecture.template.md`
+
+After creating, instruct:
+> "Mở CLAUDE.md và điền vào các placeholder `{{...}}` với thông tin dự án của bạn.
+> Đặc biệt quan trọng: §1 (project overview) và §3 (coding standards)."
+
+## Step 4 — Create project-context.yaml
+
+Create `{project-root}/.agent/project-context.yaml`:
+
+```yaml
+# Project context for AI-First workflow
+# Fill in all fields before starting
+
+project:
+  name: "{{PROJECT_NAME}}"
+  description: "{{ONE_LINE_DESCRIPTION}}"
+
+tech_stack:
+  language: "{{LANGUAGE}}"           # e.g. Java 21, Python 3.12, Node.js 20
+  framework: "{{FRAMEWORK}}"         # e.g. Spring Boot 3.x, FastAPI, NestJS
+  build_tool: "{{BUILD_TOOL}}"       # e.g. Gradle, Maven, npm
+  test_framework: "{{TEST_FW}}"      # e.g. JUnit 5, pytest, Jest
+  orm: "{{ORM}}"                     # e.g. Hibernate/JPA, SQLAlchemy, Prisma
+  database: "{{DATABASE}}"           # e.g. PostgreSQL, MySQL, MongoDB
+
+conventions:
+  build_command: "{{BUILD_COMMAND}}"   # e.g. ./gradlew build -x test
+  test_command: "{{TEST_COMMAND}}"     # e.g. ./gradlew test
+  service_run: "{{RUN_COMMAND}}"       # e.g. ./gradlew bootRun
+  ticket_prefix: "{{TICKET_PREFIX}}"  # e.g. PROJ, FEAT, PD
+
+domains: []  # List your business domains, e.g. [rental, payment, user]
+```
+
+## Step 5 — Verify Setup
+
+Run a quick check:
+- [ ] `specs/` directory exists
+- [ ] `.trace/` directory exists
+- [ ] `.agent/project-context.yaml` exists
+- [ ] `CLAUDE.md` exists
+
+Report:
+```
+/setup-ai-first Complete ✅
+
+Directories created: {N}
+Files created:
+  ✅ CLAUDE.md (needs customization)
+  ✅ .agent/project-context.yaml (needs customization)
+```
+
+# Report Footer — Standard Command Output Format
+
+Every command report must end with this standard footer section.
+
+## Status Badge
+
+Choose one based on outcome:
+- `✅ Complete` — all steps succeeded, no issues found
+- `❌ Failed` — command could not complete due to a blocking error
+- `⚠️ Warnings` — completed with non-blocking issues that should be reviewed
+
+## Output Artifacts
+
+List every file created or modified by this command:
+```
+Output Artifacts:
+  {created|updated} {file-path} ({brief description})
+  {created|updated} {file-path} ({brief description})
+```
+
+If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
+
+## Pipeline Position
+
+Print a one-line map of the pipeline with the CURRENT command's phase marked `◀ bạn ở đây`,
+so the user always sees where this command sits in the end-to-end flow:
+
+```
+Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+```
+
+Find the current command in this phase legend and mark **its** phase in the map above:
+
+| Phase | Commands |
+|-------|----------|
+| Discovery | `/define-product` |
+| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
+| Design Spec | `/generate-design-spec` |
+| BDD | `/generate-bdd` · `/review-context` (BDD) |
+| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
+| Code | `/generate-code` · `/review-code` |
+| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
+| QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
+| Trace Audit | `/validate-traces` |
+
+For a **review command**, also append the 3-step review loop with the current step marked, e.g.:
+`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
+
+**Cross-cutting commands** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
+`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) sit outside the linear pipeline —
+**omit the Pipeline line entirely** for these (do not force-fit them onto the map).
+
+## Next Command Suggestion
+
+Suggest the logical next command based on workflow phase:
+
+| Current command         | Suggest next                                  |
+|-------------------------|-----------------------------------------------|
+| /setup-ai-first         | `/define-product` to start your first feature |
+| /define-product         | `/generate-prd {product-definition-file}`     |
+| /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
+| /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
+| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
+| /generate-bdd           | `/review-context {feature-file}` to verify coverage |
+| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
+| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
+| /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
+| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/dev-gen-test {UC-ID}` |
+| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
+| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
+| /dev-run-test (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/dev-smoke-test {UC-ID}` or create PR            |
+| /dev-smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; all OK → create PR |
+| /fix-bug                | Create PR and link to ticket                  |
+| /debug                  | `/fix-bug {ticket-id}` if fix needed          |
+| /report-bug             | Send to dev (`/fix-bug {BUG-ID}`); if coverage gap → `/propose-scenario {UC-ID}` |
+| /propose-scenario       | Notify PO/Dev to review the proposal in `feedback/bdd-proposals/` |
+| /learn                  | Continue working — lesson applies on next command |
+| /sync                   | `/validate-traces` for full coverage; act on any `📥 tester feedback` surfaced |
+| /update-framework       | Review `git diff .agent/`, commit; `/sync` for project content |
+
+Format the footer as:
+```
+---
+Status   : {badge}
+{Output Artifacts block}
+Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+           (review cmd) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
+Next     : {suggested command with example arguments}
+```
+*(Omit the `Pipeline` line for cross-cutting commands listed above.)*
+