@edupia-tutor/spec-driven-docs 0.14.7 → 0.14.8

package/skills/spec/SKILL.md

@@ -4,459 +4,16 @@ description: Sinh file BDD .feature từ một PRD đã duyệt, hoặc sinh tà
 
 # Spec Skills — BDD & Technical Design
 
-Skill này xử lý hai lệnh: `/generate-bdd` để tạo file BDD feature, và `/generate-tech-docs` để tạo tài liệu technical design.
+Skill này xử lý `/generate-bdd` và `/generate-tech-docs`. Để **không lệch schema/gate**, skill KHÔNG nhân bản — mỗi lệnh thực thi **y hệt** command tương ứng.
 
----
-
-## /generate-bdd — Generate BDD Feature Files
-
-### Gate
-
-<!-- Directory: specs/*/*/*.md (file PRD ở gốc feature folder) -->
-# Gate — Quy trình vào chuẩn cho mọi lệnh
-
-Mọi lệnh PHẢI chạy gate này trước khi thực thi phần logic riêng của nó.
-
-## Bước 0 — Kiểm tra chế độ Sub-Agent
-
-Trước tiên, kiểm tra xem `$ARGUMENTS` có phải là payload JSON từ một orchestrator hay không:
-
-1. Thử parse `$ARGUMENTS` dưới dạng JSON.
-2. Nếu parse thành công **và** chứa `"_agent_mode": true`:
-   - **Bỏ qua hoàn toàn Bước 1, 2 và 3 của Gate này.**
-   - Đặt target file = `payload.target_file`
-   - Đặt loaded context = `payload.context` (KHÔNG chạy context-loader.md)
-   - Đặt phạm vi UC = `payload.uc_id` (chỉ xử lý UC này)
-   - Đặt line range = `payload.uc_section` (chỉ đọc đúng section đó của PRD)
-   - Đặt dimension = `payload.dimension` nếu có (lệnh review per-UC: chỉ review đúng lăng kính này)
-   - Đi thẳng tới phần logic riêng của lệnh.
-3. Nếu `$ARGUMENTS` không phải JSON hoặc không có `_agent_mode` → tiếp tục sang Bước 1 (chế độ thường).
-
-## Bước 0-B — Kiểm tra Model
-
-*Bỏ qua bước này nếu `_agent_mode: true` (sub-agent — orchestrator đã kiểm tra rồi).*
-
-Các lệnh sinh nội dung và review phức tạp đòi hỏi khả năng suy luận mạnh.
-Dùng model nhỏ hơn sẽ rủi ro: bỏ sót edge case, phân tích spec thiếu sót, vi phạm kiến trúc.
-
-Hiển thị và chờ phản hồi:
-
-```
-⚙️  MODEL CHECK
-──────────────────────────────────────────────────────────────────
-  Recommended  : claude-opus-4 (hoặc model Opus mới nhất)
-  Why needed   : Phân tích spec, review kiến trúc, sinh code đòi hỏi
-                 suy luận sâu. Model nhỏ hơn dễ bỏ sót edge case.
-
-  Cách đổi trong Claude Code:
-    • Settings → Model → chọn "claude-opus"
-    • hoặc: /model → chọn claude-opus
-
-  Đang chạy claude-opus?
-    Y — đúng, đang dùng claude-opus → tiếp tục
-    S — bỏ qua kiểm tra (tôi chấp nhận rủi ro chất lượng thấp hơn với model hiện tại)
-──────────────────────────────────────────────────────────────────
-```
-
-- "Y" → tiếp tục sang Bước 1.
-- "S" → tiếp tục sang Bước 1 (người dùng chấp nhận rủi ro, thêm ⚠️ vào report cuối).
-- "N" hoặc bất kỳ giá trị nào khác → **DỪNG.** Xuất: "Vui lòng chuyển sang claude-opus rồi chạy lại lệnh này."
-
-## Bước 1 — Xác định Target File
-
-1. Nếu `$ARGUMENTS` được cung cấp và trỏ tới một file tồn tại → dùng trực tiếp làm target.
-2. Nếu `$ARGUMENTS` là một **UC-ID / ticket ID / tên rút gọn** (không có path) → phân giải thành file bằng cách glob theo bố cục feature-package. `{prd-slug}` lúc này **chưa biết**, nên dùng wildcard `*` cho segment đó, và `**` đệ quy dưới `bdd/` để phủ hết các thư mục con theo platform (`bdd/web/`, `bdd/app/`, `bdd/system/`):
-   - **Lệnh BDD** (target là `.feature`): `{specs_dir}/{domain}/*/bdd/**/{UC-ID}*.feature` — hoặc `{specs_dir}/*/*/bdd/**/{UC-ID}*.feature` nếu domain cũng chưa biết. Nếu lệnh ngụ ý một platform/scope cụ thể (vd: system tech-doc cần BDD `system/`), ưu tiên kết quả trong thư mục con platform đó.
-   - **Lệnh PRD** (target là file PRD `{TICKET-ID}-{prd-slug}.md` — file `.md` duy nhất ở gốc feature folder, cạnh `bdd/`): `{specs_dir}/{domain}/*/{TICKET-ID}*.md` nếu biết TICKET-ID; nếu không, `{specs_dir}/{domain}/*/*.md` (khớp feature folder có id tương ứng), hoặc `{specs_dir}/*/*/*.md` nếu domain cũng chưa biết. *(Glob `*/*.md` ở cấp gốc folder chỉ khớp PRD — tech-docs/design-spec `.md` nằm sâu hơn trong thư mục con.)*
-   - **Lệnh tech-docs**: `{specs_dir}/{domain}/*/tech-docs/{UC-ID}*-tech-design*.md`.
-   - **Lệnh design-spec**: `{specs_dir}/{domain}/*/design-spec/{TICKET-ID}*.md`.
-
-   Khi một file khớp: đặt nó làm target **và** ghi lại `domain` + `prd_slug` từ path của nó (theo quy tắc trích xuất trong `context-loader.md` Bước 1 — `prd_slug` = segment đầu tiên sau `{specs_dir}/{domain}/`). Mọi path mà lệnh đọc/ghi về sau (BDD/tech-docs/design-spec/trace cùng cấp) đều dùng **`prd_slug` đã phân giải đó**, nên tất cả artifact nằm chung một feature package. Nếu nhiều file khớp (vd: nhiều platform), chọn theo platform/scope của lệnh hoặc liệt kê ra và hỏi.
-3. Nếu `$ARGUMENTS` rỗng hoặc không tìm thấy file khớp:
-   - Liệt kê các file trong thư mục liên quan của lệnh này (vd: `specs/*/*/*.md` — file PRD ở gốc mỗi feature folder — cho lệnh PRD, `specs/*/*/bdd/**/*.feature` cho lệnh BDD).
-   - Hiển thị danh sách cho người dùng và hỏi: "Bạn muốn làm việc với file nào? (Nhập số thứ tự hoặc tên file)"
-   - Chờ người dùng chọn rồi mới tiếp tục.
-
-## Bước 2 — Chạy Context Loader
-
-Nạp toàn bộ context của dự án bằng cách làm theo quy trình trong `steps/context-loader.md`.
-Lưu toàn bộ context đã nạp vào bộ nhớ để dùng xuyên suốt phiên làm việc của lệnh.
-
-## Bước 3 — CHECKPOINT
-
-Sau khi hoàn thành Bước 1 và 2, hiển thị bản tóm tắt và chờ xác nhận:
-
-```
-CHECKPOINT
------------
-Target     : {resolved file path}
-Project    : {project.name từ project-context.yaml}
-Tech stack : {language} / {framework}
-Module     : {module nếu có, else "not configured"}
-Domains    : {danh sách domain, ngăn cách bởi dấu phẩy}
-
-Tiếp tục? (Y/N)
-```
-
-Chờ người dùng trả lời rõ ràng "Y" hoặc "N" rồi mới tiếp tục.
-- "Y" → tiếp tục sang các bước riêng của lệnh bên dưới.
-- "N" → dừng lại và hỏi người dùng muốn thay đổi gì.
-
-
-Cũng verify: Kiểm tra PRD `Status` là `approved` (không phải `draft`).
-- Nếu `draft`: cảnh báo "PRD vẫn đang draft. Vẫn tiếp tục? Findings từ /refine-prd có thể chưa được xử lý."
-
-### UC Decomposition
-
-Với mỗi Use Case trong PRD, suy ra scenario. Trình bày outline:
-
-```
-{DOMAIN}-UC1: {Name}
-  SC1: Happy path — {client/role type} — {success scenario}
-  SC2: Happy path — {other client/role type} (if applicable)
-  SC3: Validation error — {invalid input}
-  SC4: Not found / resource missing
-  BRs covered: BR-1, BR-2
-
-{DOMAIN}-UC2: {Name}
-  ...
-```
-
-**CHECKPOINT** — Hỏi: "Outline này đúng chưa? Có scenario nào còn thiếu không?"
-Chờ xác nhận trước khi sinh file.
-
-### Generate
-
-Với mỗi UC, ghi `specs/{domain}/{prd-slug}/bdd/{UC-ID}-{slug}.feature`:
-
-```gherkin
-# @trace.source=specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
-# @trace.uc={UC-ID}
-Feature: {UC Name}
-
-  Background:
-    Given the system is running
-    And a {persona} is authenticated
-
-  Scenario: SC1 — {Happy path description}
-    Given {precondition}
-    When {action}
-    Then {expected outcome}
-    And {secondary outcome if any}
-
-  Scenario: SC2 — {Another happy path}
-    Given {precondition}
-    When {action}
-    Then {expected outcome}
-
-  Scenario: SC3 — Validation error
-    Given {precondition}
-    When {invalid action}
-    Then the system returns a validation error
-    And the error message mentions "{field}"
-
-  Scenario: SC4 — Resource not found
-    Given no {resource} exists with id {id}
-    When {action}
-    Then the system returns a not-found error
-```
-
-### Quality Check
-
-Sau khi sinh, tự đánh giá:
-- [ ] Mỗi acceptance criteria từ PRD có ít nhất một scenario
-- [ ] Mỗi business rule được phủ bởi ít nhất một scenario
-- [ ] Có error scenario (validation, not-found, unauthorized)
-- [ ] Scenario atomic (một behavior mỗi scenario)
-- [ ] Không có chi tiết implementation trong feature file (không SQL, không tên class)
-
-### Output
-
-```
-/generate-bdd Complete — {domain}
-
-Files created:
-  ✅ specs/{domain}/{prd-slug}/bdd/{UC-ID}-{slug}.feature ({N} scenarios)
-  ...
-
-Quality: {score}%
-```
-
-# Report Footer — Định dạng output chuẩn cho mọi lệnh
-
-Mọi report của lệnh phải kết thúc bằng section footer chuẩn này.
-
-## Status Badge
-
-Chọn một theo kết quả:
-- `✅ Complete` — mọi bước thành công, không có vấn đề
-- `❌ Failed` — lệnh không hoàn thành được do lỗi chặn
-- `⚠️ Warnings` — hoàn thành nhưng có vấn đề không chặn, nên review lại
-
-## Output Artifacts
-
-Liệt kê mọi file được tạo hoặc sửa bởi lệnh này:
-```
-Output Artifacts:
-  {created|updated} {file-path} ({mô tả ngắn})
-  {created|updated} {file-path} ({mô tả ngắn})
-```
-
-Nếu không ghi file nào (vd: lệnh review hoặc phân tích) → ghi `Output Artifacts: none (read-only)`.
-
-## Pipeline Position
+## /generate-bdd — Sinh BDD Feature Files
 
-In một sơ đồ pipeline một dòng, đánh dấu phase của lệnh HIỆN TẠI bằng `◀ bạn ở đây`,
-để người dùng luôn thấy lệnh này nằm ở đâu trong luồng end-to-end:
+→ **Đọc và tuân theo `commands/generate-bdd.md`** với cùng `$ARGUMENTS`.
 
-```
-Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-```
+Command lo: guard PRD approved + Design Spec (approved/độ-tươi/sanity) cho FE/App · Platform Selection web/app/system · System BDD synthesis (tổng hợp web+app, cross-platform conflict) · Version Check drift · proposal tester (chỉ `accepted`) · R1–R10 + C1–C5 + NHÓM grouping · `@trace` header đầy đủ + trace TSV.
 
-Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **phase của nó** trong sơ đồ trên:
+## /generate-tech-docs — Sinh Technical Design Document
 
-| 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` |
-
-Với **lệnh review**, thêm vòng review 3 bước và đánh dấu bước hiện tại, vd:
-`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
-
-**Lệnh xuyên suốt** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
-`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) nằm ngoài pipeline tuyến tính —
-**bỏ hẳn dòng Pipeline** cho các lệnh này (đừng cố nhét chúng vào sơ đồ).
-
-## Gợi ý lệnh tiếp theo
-
-Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
-
-| Lệnh hiện tại           | Gợi ý lệnh tiếp theo                          |
-|-------------------------|-----------------------------------------------|
-| /setup-ai-first         | `/define-product` để bắt đầu feature đầu tiên |
-| /define-product         | `/generate-prd {product-definition-file}`     |
-| /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
-| /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
-| /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
-| /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
-| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |
-| /qc-analyze             | `/qc-plan {UC-ID}` (xử lý các gap blocker 🔴 trước) |
-| /qc-plan                | `/qc-design-test {UC-ID}`                     |
-| /qc-design-test         | `/qc-review {UC-ID}` (review test-case)       |
-| /qc-review (test-case)  | `/qc-run-test {UC-ID}` nếu APPROVED; sửa TC nếu NEEDS_FIX |
-| /qc-run-test            | `/qc-report {UC-ID}` rồi `/qc-review {UC-ID}` (review script) |
-| /qc-review (script)     | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED |
-| /qc-report              | `/validate-traces {UC-ID}` để làm mới Living Docs (qc_status) |
-| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
-| /review-tech-docs       | `/generate-code {feature-file}` nếu APPROVED; sửa doc nếu NEEDS_FIX |
-| /generate-code          | Lần gen đầu → `/review-code {UC-ID}`; gen lại → `/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}` hoặc `/debug {error}`    |
-| /review-code            | `/dev-smoke-test {UC-ID}` hoặc tạo PR            |
-| /dev-smoke-test             | Tạo PR và link tới ticket                  |
-| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; tất cả OK → tạo PR |
-| /fix-bug                | Tạo PR và link tới ticket                  |
-| /debug                  | `/fix-bug {ticket-id}` nếu cần sửa          |
-| /report-bug             | Gửi cho dev (`/fix-bug {BUG-ID}`); nếu thiếu coverage → `/propose-scenario {UC-ID}` |
-| /propose-scenario       | Báo PO/Dev review proposal trong `feedback/bdd-proposals/` |
-| /learn                  | Tiếp tục làm việc — lesson áp dụng ở lệnh kế tiếp |
-| /sync                   | `/validate-traces` để xem độ phủ đầy đủ; xử lý mọi `📥 tester feedback` được nêu |
-| /update-framework       | Review `git diff .agent/`, commit; `/sync` để đồng bộ nội dung dự án |
-
-Định dạng footer như sau:
-```
----
-Status   : {badge}
-{khối Output Artifacts}
-Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-           (lệnh review) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
-Next     : {lệnh gợi ý kèm ví dụ tham số}
-```
-*(Bỏ dòng `Pipeline` cho các lệnh xuyên suốt liệt kê ở trên.)*
-
-
----
-
-## /generate-tech-docs — Generate Technical Design Document
-
-### Gate
-
-Kiểm tra chất lượng BDD (đọc file .feature, verify scenario well-formed).
-Nếu chất lượng < 80%, dừng và report: "BDD quality insufficient. Fix these issues first: [list]"
-
-### Generate
-
-Ghi `specs/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md`:
-
-```markdown
-# Technical Design — {UC-ID}: {Feature}
-
-**Domain**: {domain}
-**Date**: {date}
-**Spec**: specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature
-
-## §1. Overview
-{Brief description of what this UC implements}
-
-## §2. API Endpoints
-
-| Method | Path | Auth/Role | Request Body | Response |
-|--------|------|-----------|--------------|----------|
-| GET    | /v1/{resource} | {role} | — | {ResponseDTO} |
-| POST   | /v1/{resource} | {role} | {RequestDTO} | {ResponseDTO} |
-
-## §3. Data Model
-
-{Entity diagram or table structure}
-
-Key entities:
-- `{Entity}`: {description, key fields}
-
-## §4. Service Flow
-
-Sequence for each UC:
-```
-{Client} → Controller → {Facade} → {Service} → {Repository}
-                              ↓
-                    {OtherService} (if cross-service)
-```
-
-## §5. Business Rules Implementation
-
-| BR-ID | Rule | Implementation approach |
-|-------|------|------------------------|
-| BR-1 | {rule} | {how to implement} |
-
-## §6. Error Handling
-
-| Scenario | Exception | HTTP Status |
-|----------|-----------|-------------|
-| {resource} not found | {NotFoundException} | 404 |
-| Validation failure | {ValidationException} | 400 |
-| Unauthorized | {AuthException} | 403 |
-
-## §7. Database Changes
-
-{Migration script or schema changes needed}
-
-## §8. Caching Strategy
-
-{Which data to cache, TTL, invalidation triggers — or "N/A"}
-
-## §9. Cross-Service Dependencies
-
-{List external service calls, event producers/consumers}
-```
-
-Hướng dẫn: "SA/Lead nên review và approve trước khi chạy /generate-code."
-
-# Report Footer — Định dạng output chuẩn cho mọi lệnh
-
-Mọi report của lệnh phải kết thúc bằng section footer chuẩn này.
-
-## Status Badge
-
-Chọn một theo kết quả:
-- `✅ Complete` — mọi bước thành công, không có vấn đề
-- `❌ Failed` — lệnh không hoàn thành được do lỗi chặn
-- `⚠️ Warnings` — hoàn thành nhưng có vấn đề không chặn, nên review lại
-
-## Output Artifacts
-
-Liệt kê mọi file được tạo hoặc sửa bởi lệnh này:
-```
-Output Artifacts:
-  {created|updated} {file-path} ({mô tả ngắn})
-  {created|updated} {file-path} ({mô tả ngắn})
-```
-
-Nếu không ghi file nào (vd: lệnh review hoặc phân tích) → ghi `Output Artifacts: none (read-only)`.
-
-## Pipeline Position
-
-In một sơ đồ pipeline một dòng, đánh dấu phase của lệnh HIỆN TẠI bằng `◀ bạn ở đây`,
-để người dùng luôn thấy lệnh này nằm ở đâu trong luồng end-to-end:
-
-```
-Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-```
-
-Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **phase của nó** trong sơ đồ trên:
-
-| 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` |
-
-Với **lệnh review**, thêm vòng review 3 bước và đánh dấu bước hiện tại, vd:
-`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
-
-**Lệnh xuyên suốt** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
-`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) nằm ngoài pipeline tuyến tính —
-**bỏ hẳn dòng Pipeline** cho các lệnh này (đừng cố nhét chúng vào sơ đồ).
-
-## Gợi ý lệnh tiếp theo
-
-Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
-
-| Lệnh hiện tại           | Gợi ý lệnh tiếp theo                          |
-|-------------------------|-----------------------------------------------|
-| /setup-ai-first         | `/define-product` để bắt đầu feature đầu tiên |
-| /define-product         | `/generate-prd {product-definition-file}`     |
-| /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
-| /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
-| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
-| /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
-| /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
-| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |
-| /qc-analyze             | `/qc-plan {UC-ID}` (xử lý các gap blocker 🔴 trước) |
-| /qc-plan                | `/qc-design-test {UC-ID}`                     |
-| /qc-design-test         | `/qc-review {UC-ID}` (review test-case)       |
-| /qc-review (test-case)  | `/qc-run-test {UC-ID}` nếu APPROVED; sửa TC nếu NEEDS_FIX |
-| /qc-run-test            | `/qc-report {UC-ID}` rồi `/qc-review {UC-ID}` (review script) |
-| /qc-review (script)     | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED |
-| /qc-report              | `/validate-traces {UC-ID}` để làm mới Living Docs (qc_status) |
-| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
-| /review-tech-docs       | `/generate-code {feature-file}` nếu APPROVED; sửa doc nếu NEEDS_FIX |
-| /generate-code          | Lần gen đầu → `/review-code {UC-ID}`; gen lại → `/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}` hoặc `/debug {error}`    |
-| /review-code            | `/dev-smoke-test {UC-ID}` hoặc tạo PR            |
-| /dev-smoke-test             | Tạo PR và link tới ticket                  |
-| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; tất cả OK → tạo PR |
-| /fix-bug                | Tạo PR và link tới ticket                  |
-| /debug                  | `/fix-bug {ticket-id}` nếu cần sửa          |
-| /report-bug             | Gửi cho dev (`/fix-bug {BUG-ID}`); nếu thiếu coverage → `/propose-scenario {UC-ID}` |
-| /propose-scenario       | Báo PO/Dev review proposal trong `feedback/bdd-proposals/` |
-| /learn                  | Tiếp tục làm việc — lesson áp dụng ở lệnh kế tiếp |
-| /sync                   | `/validate-traces` để xem độ phủ đầy đủ; xử lý mọi `📥 tester feedback` được nêu |
-| /update-framework       | Review `git diff .agent/`, commit; `/sync` để đồng bộ nội dung dự án |
-
-Định dạng footer như sau:
-```
----
-Status   : {badge}
-{khối Output Artifacts}
-Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
-           (lệnh review) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
-Next     : {lệnh gợi ý kèm ví dụ tham số}
-```
-*(Bỏ dòng `Pipeline` cho các lệnh xuyên suốt liệt kê ở trên.)*
+→ **Đọc và tuân theo `commands/generate-tech-docs.md`** với cùng `$ARGUMENTS`.
 
+Command lo: platform-aware (BE = API contract · FE/App = client design GATED trên System BDD + BE contract) · §2b Test Selectors · brownfield reverse-document · review-tech-docs T1–T7 (T7 sign-off) sau đó.

package/skills/spec/SKILL.tmpl

@@ -4,171 +4,16 @@ description: Sinh file BDD .feature từ một PRD đã duyệt, hoặc sinh tà
 
 # Spec Skills — BDD & Technical Design
 
-Skill này xử lý hai lệnh: `/generate-bdd` để tạo file BDD feature, và `/generate-tech-docs` để tạo tài liệu technical design.
+Skill này xử lý `/generate-bdd` và `/generate-tech-docs`. Để **không lệch schema/gate**, skill KHÔNG nhân bản — mỗi lệnh thực thi **y hệt** command tương ứng.
 
----
-
-## /generate-bdd — Generate BDD Feature Files
-
-### Gate
-
-<!-- Directory: specs/*/*/*.md (file PRD ở gốc feature folder) -->
-{{include:steps/gate.md}}
-
-Cũng verify: Kiểm tra PRD `Status` là `approved` (không phải `draft`).
-- Nếu `draft`: cảnh báo "PRD vẫn đang draft. Vẫn tiếp tục? Findings từ /refine-prd có thể chưa được xử lý."
-
-### UC Decomposition
-
-Với mỗi Use Case trong PRD, suy ra scenario. Trình bày outline:
-
-```
-{DOMAIN}-UC1: {Name}
-  SC1: Happy path — {client/role type} — {success scenario}
-  SC2: Happy path — {other client/role type} (if applicable)
-  SC3: Validation error — {invalid input}
-  SC4: Not found / resource missing
-  BRs covered: BR-1, BR-2
-
-{DOMAIN}-UC2: {Name}
-  ...
-```
-
-**CHECKPOINT** — Hỏi: "Outline này đúng chưa? Có scenario nào còn thiếu không?"
-Chờ xác nhận trước khi sinh file.
-
-### Generate
-
-Với mỗi UC, ghi `specs/{domain}/{prd-slug}/bdd/{UC-ID}-{slug}.feature`:
-
-```gherkin
-# @trace.source=specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md
-# @trace.uc={UC-ID}
-Feature: {UC Name}
-
-  Background:
-    Given the system is running
-    And a {persona} is authenticated
-
-  Scenario: SC1 — {Happy path description}
-    Given {precondition}
-    When {action}
-    Then {expected outcome}
-    And {secondary outcome if any}
-
-  Scenario: SC2 — {Another happy path}
-    Given {precondition}
-    When {action}
-    Then {expected outcome}
-
-  Scenario: SC3 — Validation error
-    Given {precondition}
-    When {invalid action}
-    Then the system returns a validation error
-    And the error message mentions "{field}"
-
-  Scenario: SC4 — Resource not found
-    Given no {resource} exists with id {id}
-    When {action}
-    Then the system returns a not-found error
-```
-
-### Quality Check
-
-Sau khi sinh, tự đánh giá:
-- [ ] Mỗi acceptance criteria từ PRD có ít nhất một scenario
-- [ ] Mỗi business rule được phủ bởi ít nhất một scenario
-- [ ] Có error scenario (validation, not-found, unauthorized)
-- [ ] Scenario atomic (một behavior mỗi scenario)
-- [ ] Không có chi tiết implementation trong feature file (không SQL, không tên class)
-
-### Output
-
-```
-/generate-bdd Complete — {domain}
-
-Files created:
-  ✅ specs/{domain}/{prd-slug}/bdd/{UC-ID}-{slug}.feature ({N} scenarios)
-  ...
-
-Quality: {score}%
-```
-
-{{include:steps/report-footer.md}}
-
----
-
-## /generate-tech-docs — Generate Technical Design Document
-
-### Gate
-
-Kiểm tra chất lượng BDD (đọc file .feature, verify scenario well-formed).
-Nếu chất lượng < 80%, dừng và report: "BDD quality insufficient. Fix these issues first: [list]"
-
-### Generate
-
-Ghi `specs/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design.md`:
-
-```markdown
-# Technical Design — {UC-ID}: {Feature}
-
-**Domain**: {domain}
-**Date**: {date}
-**Spec**: specs/{domain}/{prd-slug}/bdd/{UC-ID}.feature
-
-## §1. Overview
-{Brief description of what this UC implements}
-
-## §2. API Endpoints
-
-| Method | Path | Auth/Role | Request Body | Response |
-|--------|------|-----------|--------------|----------|
-| GET    | /v1/{resource} | {role} | — | {ResponseDTO} |
-| POST   | /v1/{resource} | {role} | {RequestDTO} | {ResponseDTO} |
-
-## §3. Data Model
-
-{Entity diagram or table structure}
-
-Key entities:
-- `{Entity}`: {description, key fields}
-
-## §4. Service Flow
-
-Sequence for each UC:
-```
-{Client} → Controller → {Facade} → {Service} → {Repository}
-                              ↓
-                    {OtherService} (if cross-service)
-```
-
-## §5. Business Rules Implementation
-
-| BR-ID | Rule | Implementation approach |
-|-------|------|------------------------|
-| BR-1 | {rule} | {how to implement} |
-
-## §6. Error Handling
-
-| Scenario | Exception | HTTP Status |
-|----------|-----------|-------------|
-| {resource} not found | {NotFoundException} | 404 |
-| Validation failure | {ValidationException} | 400 |
-| Unauthorized | {AuthException} | 403 |
-
-## §7. Database Changes
-
-{Migration script or schema changes needed}
-
-## §8. Caching Strategy
+## /generate-bdd — Sinh BDD Feature Files
 
-{Which data to cache, TTL, invalidation triggers — or "N/A"}
+→ **Đọc và tuân theo `commands/generate-bdd.md`** với cùng `$ARGUMENTS`.
 
-## §9. Cross-Service Dependencies
+Command lo: guard PRD approved + Design Spec (approved/độ-tươi/sanity) cho FE/App · Platform Selection web/app/system · System BDD synthesis (tổng hợp web+app, cross-platform conflict) · Version Check drift · proposal tester (chỉ `accepted`) · R1–R10 + C1–C5 + NHÓM grouping · `@trace` header đầy đủ + trace TSV.
 
-{List external service calls, event producers/consumers}
-```
+## /generate-tech-docs — Sinh Technical Design Document
 
-Hướng dẫn: "SA/Lead nên review và approve trước khi chạy /generate-code."
+→ **Đọc và tuân theo `commands/generate-tech-docs.md`** với cùng `$ARGUMENTS`.
 
-{{include:steps/report-footer.md}}
+Command lo: platform-aware (BE = API contract · FE/App = client design GATED trên System BDD + BE contract) · §2b Test Selectors · brownfield reverse-document · review-tech-docs T1–T7 (T7 sign-off) sau đó.