@trungtamcongnghedigital/vsaf 1.0.0

package/skills/NTAPP/.agent/skills/NTAPP-ux-design/templates/ux-conventions-template.md

@@ -0,0 +1,51 @@
+---
+workflowType: 'ux-conventions'
+---
+
+# UX CONVENTIONS — {{project_name}}
+
+**Scope:** PROJECT SINGLETON — 1 file cho cả project, viết lần đầu khi feature multi-screen-new đầu tiên qua Stage 3b, các feature sau chỉ **delta-update** (thêm pattern mới / sửa khi PRD-NFR đổi). KHÔNG regenerate từ đầu mỗi feature.
+**Consumers:** `feature-design` Stage 4a (F3 tuân §C1-C7 khi vẽ wireframe/control states), QA skills (`ntapp-qa-*` — §C4/§C5 là testable spec cho notification/error), Stage 5 dev.
+**Nguồn canonical:** status enum ↔ Module 0 §7 (R8.2); token/component ↔ Master DS (R8.3); shell/screens ↔ journey spec + WBS.
+
+---
+
+## CHANGE LOG
+
+| Date | Section | A/M/D | Feature trigger | Description |
+|:-----|:--------|:------|:----------------|:------------|
+| {{date}} | All | A | {{feature_name}} | Initial conventions |
+
+---
+
+<!--
+TEMPLATE v1.0 — PROJECT UX CONVENTIONS (tách từ ux-design-spec v3.1 §3/§5/§11-15)
+Đây là artifact SỐNG (living doc): steps 04/06/11/12/13 của /ntapp-ux-design ghi TRỰC TIẾP vào đây
+(bootstrap mode: fill đủ; delta mode: chỉ append/patch section có thay đổi + CHANGE LOG row).
+Ngoại lệ R1 verbatim-injection: file này KHÔNG assemble từ parts — steps ghi thẳng (atomic write).
+-->
+
+## C1. UX PRINCIPLES
+<!-- Step 04 — Agent UX0. Core principles table {# | Principle | Description | Application in project} — min 7 (Progressive Disclosure / Consistency / Error Prevention / Recognition over Recall / Feedback & Visibility / Flexibility & Efficiency / Minimal Input), Application cite UI element/flow cụ thể. + Domain-specific principles (min 4, theo archetype). Enforcement reference: layout-best-practices.md L1-L11 (cite rule ID, không chép). -->
+
+## C2. CONTENT STRATEGY & MICROCOPY
+<!-- Step 06 — Agent UX4. (a) Writing rules table {Rule | Good | Bad} ≥5 — verb-first, ngôi 2, nói rõ hệ quả, không mã lỗi kỹ thuật, guide-to-fix; ví dụ dùng domain terminology thật. (b) Empty/Loading state spec (structured, không ASCII) — component §Master DS canonical. (c) STATUS LABELS: bảng {Display Status | Color token path | Module 0 §7 enum | User Description} — 1-1 mapping enum (R8.2), cover lifecycle theo archetype, color token canonical không hex. -->
+
+## C3. INTERACTION PATTERNS
+<!-- Step 11 — Agent UX0. (a) Form validation timing (inline on-blur / on-submit / cross-section) + error surface spec (inline field + summary panel, token refs). (b) View/Tab/Section transition table — cover đủ state taxonomy journey-spec §2.3 (valid switch / error switch / locked / blocked / optional / rejected), tooltip giải thích dependency cụ thể. (c) Confirmation dialogs table {Action | Has dialog? | Content principle} — universal + archetype-conditional; irreversible → BẮT BUỘC dialog. (d) Keyboard shortcuts table — universal FORM-HEAVY + archetype-conditional, không đè browser default. -->
+
+## C4. NOTIFICATION SYSTEM
+<!-- Step 12 — Agent UX4. (a) Event Notification Matrix {Event | Recipient | Channel | Timing | Title ≤8 words | Detail} — single source of truth, event set theo archetype (không bịa event ngoài workflow), timing cite PRD NFR SLA, detail có entity ref + actionable guidance. (b) 4 standard notification components {Pattern | Component (Master DS canonical) | Trigger | Dismiss}: Loading / Success / Error (kèm guidance + retry) / Info. -->
+
+## C5. ERROR HANDLING & RECOVERY
+<!-- Step 12 — Agent UX0 + UX4. (a) Universal principles ≥6 (never lose input; cause+guidance không raw code; luôn ≥1 action button; localize failure scope; retry limit 2; severe error kèm reference code + timestamp). (b) Error classification {Type | User sees | Severity | Recovery | Applicable archetype} — universal 4 (validation / network 3 sub-state / session expiry / unexpected) + conditional theo archetype. (c) Archetype edge cases (chỉ archetype đã chọn): partial sync fail, duplicate detection, step dependency breakage, auto-save & session recovery, stale data, edit conflict, publish conflict. -->
+
+## C6. RESPONSIVE & ACCESSIBILITY
+<!-- Step 13 — Agent UX0. (a) Breakpoints: POINTER tới master_token.json tokens.breakpoint.* (không embed bảng, không hardcode px). (b) Responsive behavior per critical component (sidebar / section indicator / form / widget grid / data table) × 3 variants (desktop/tablet/mobile), touch target ≥44px. (c) WCAG AA checklist ≥8 mục: labels, tab order, screen-reader text, contrast ≥4.5:1 / ≥3:1, focus indicator, error→field linkage, keyboard nav, ARIA live, skip link, alt text, không color-only. (d) Shell layout blueprint chung (ASCII 1 khung — header/nav/content/action bar) nếu project chưa doc ở đâu khác. -->
+
+## C7. AUDIT LOG UX RULES
+<!-- Step 13 — Agent UX0. Applicable: archetype có persistent entity state (skip TRANSACTIONAL lookup / DASHBOARD read-only). RULES ONLY (screen chi tiết → DD Stage 4a của SCR-AUDITLOG): immutable (không edit/delete), chronological most-recent-first group-by-date, actor = name + role (system action → "System"), human + system actions đều log, pagination load-more. Cite PRD FR audit. -->
+
+---
+
+*Template version: 1.0 (tách từ ux-design-spec v3.1 — §3→C1, §5→C2, §11→C3, §12→C4, §13→C5, §14→C6, §15→C7) | Framework: NTAPP Method*

package/skills/NTAPP/.agent/skills/NTAPP-ux-design/templates/ux-design-spec-template.md

@@ -0,0 +1,134 @@
+---
+stepsCompleted: []
+inputDocuments: []
+workflowType: 'ux-design-spec'
+---
+
+# UX JOURNEY SPECIFICATION — {{project_name}}
+
+<!-- QUY ƯỚC OKF: dòng bắt đầu bằng "okf-id:" ngay dưới mỗi heading H2/H3 là ĐỊNH DANH
+     ỔN ĐỊNH của mục đó trong đồ thị OKF. Đổi tiêu đề thì GIỮ NGUYÊN marker. Xoá marker
+     thì danh tính tụt về slug của tiêu đề, và mọi cạnh trỏ tới mục này sẽ đứt lặng lẽ
+     ngay lần đầu ai đó sửa câu chữ của tiêu đề.
+
+     Tài liệu này đặc biệt cần nó hơn DD/techspec: SỐ MỤC NẰM TRONG TIÊU ĐỀ, nên id hôm
+     nay là `3-1-mo-hinh-phan-lop`. Chèn thêm một §2.5 là mọi mục phía dưới bị đánh số
+     lại và tái sinh dưới id mới. Marker cắt số ra khỏi danh tính.
+
+     Marker phải là DÒNG KHÔNG RỖNG ĐẦU TIÊN dưới heading — bộ đọc dừng ở dòng đó. Đặt
+     sau một comment hướng dẫn là marker không được đọc. -->
+
+**Project:** {{project_name}}
+**Anchor System:** {{anchor_system}}
+**Integrated Systems:** {{integrated_systems}}
+**Version:** 1.0
+**Date:** {{date}}
+**Author:** {{user_name}}
+**Conventions:** xem [ux_conventions.md](./ux_conventions.md) — mọi pattern tương tác / notification / error / responsive / content áp cho spec này định nghĩa Ở ĐÓ (singleton project-wide), KHÔNG lặp lại ở đây.
+
+---
+
+## CHANGE LOG
+
+| Date | Section | A/M/D | Description | Version |
+|:-----|:--------|:------|:------------|:--------|
+| {{date}} | All | A | Initial UX journey specification | 1.0 |
+
+---
+
+<!--
+TEMPLATE v4.0 — SLIM JOURNEY SPEC
+Tài liệu này chỉ giữ phần KHÔNG stage nào khác own được: thiết kế CROSS-SCREEN
+(archetype, IA/navigation, journey flows) + PRD traceability.
+
+KHÔNG chứa (đã tách/loại từ v4.0):
+- Per-screen Screen Spec chi tiết → owner DUY NHẤT là feature-design Stage 4a §2 (DD wireframe).
+  Journey node ở đây chỉ 1 dòng purpose + key states (đủ để 4a kế thừa intent, không đủ để drift).
+- §17 Screen & Widget Inventory → SSoT là project_wbs.md (gate feature-design check WBS trực tiếp).
+- Personas chi tiết → `ux_sketch.md` §Personas nếu có (Stage 1, optional) / PRD §User Stories nếu không; ở đây chỉ reference + actor lock từ HLD §3.1.1.
+- Conventions (§3/§5/§11-15 cũ) → ux_conventions.md (project singleton, delta-update).
+
+Mỗi section dưới có generation comment trỏ step file. Agent PHẢI đọc step file trước khi fill.
+-->
+
+## 1. EXECUTIVE SUMMARY
+<!-- okf-id: executive-summary -->
+
+### 1.1. Context & Vision
+<!-- okf-id: context-vision -->
+<!-- Step 02 — Agent UX2. Output: ≤2 đoạn — bối cảnh feature (hệ thống/quy trình hiện tại + pain chính, quantified nếu PRD có số) + 1 câu UX vision. KHÔNG bảng hiện trạng dài — chi tiết đã có trong PRD, cite thay vì chép. -->
+
+### 1.2. Design Goals
+<!-- okf-id: design-goals -->
+<!-- Step 02 — Agent UX2. Output: table {Goal | Measurement} — min 3 goals, measurement quantified, trace PRD success criteria. -->
+
+### 1.3. Personas (reference)
+<!-- okf-id: personas -->
+<!-- Step 02 — Agent UX2. Output: 1 dòng/role: {Persona name — role} → pointer `ux_sketch.md §Personas` (nếu có sketch) hoặc PRD user stories. Actor list LOCK theo HLD §3.1.1 (R8.1/R10) — chỉ liệt kê actor có trong HLD. KHÔNG viết lại persona table chi tiết. -->
+
+---
+
+## 2. WORKFLOW ARCHETYPE & INFORMATION MODEL
+<!-- okf-id: workflow-archetype-info-model -->
+
+### 2.1. Workflow Archetype
+<!-- okf-id: workflow-archetype -->
+<!-- Step 08 — Agent UX3 + UX0. Output: chọn 1 archetype (MAKER_CHECKER / WIZARD / DASHBOARD / TRANSACTIONAL / CONTENT_MGMT / OTHER) + 1-2 câu justification cite PRD primary user story. Hybrid (2 archetype song song) → split 2 spec, KHÔNG mix. OTHER → mô tả pattern inline ≤5 dòng. -->
+
+### 2.2. Primary Entity & Composition Model
+<!-- okf-id: primary-entity-composition -->
+<!-- Step 08 — Agent UX3. Output: entity theo BUSINESS term + composition model (SINGLE / SECTIONED / LINEAR_STEPS / REFERENCE) + ASCII diagram sub-section/step + data-flow direction (nếu ≠ SINGLE). Mark Required/Optional + điều kiện kích hoạt. -->
+
+### 2.3. Section Status & Data Propagation
+<!-- okf-id: section-status-propagation -->
+<!-- Step 08 — Agent UX3. Applicable: composition ≠ SINGLE. Output: (a) state taxonomy (universal Empty/In-progress/Complete/Error + archetype-conditional Locked/Rejected/Blocked/Draft/Published) — mỗi state: icon + color token path + 1 dòng business meaning; (b) bảng cross-section propagation {Source | Field | → Target | Field | Type | Timing | Conflict Policy} nếu có data dependency. Indicator pattern chi tiết + transition behavior → ux_conventions.md §C3. -->
+
+---
+
+## 3. INFORMATION ARCHITECTURE & NAVIGATION
+<!-- okf-id: ia-navigation -->
+
+### 3.1. Navigation Principle & Tree
+<!-- okf-id: navigation-principle-tree -->
+<!-- Step 07 — Agent UX3. Output: nav model (Action/System/Entity-Based/Hybrid) + ASCII navigation tree. BROWNFIELD (đã có ux_design trước / app đang chạy): chỉ vẽ DELTA — node mới + node neo (cha/anh em) đánh dấu (existing), KHÔNG vẽ lại toàn tree. Mỗi leaf node mới ↔ 1 SCR-* trong project_wbs.md (frontend-app module) — WBS là SSoT ID, UX không tự đặt. Annotate role-restricted. -->
+
+### 3.2. Shell Placement
+<!-- okf-id: shell-placement -->
+<!-- Step 07 — Agent UX3. Output: screens mới đặt vào shell layout NÀO (reference shell đã có trong ux_conventions.md §C6-shell hoặc mô tả 1 khung ASCII nếu project chưa có shell doc). Region checklist per archetype giữ ở step file — chỉ emit kết luận. -->
+
+---
+
+## 4. USER JOURNEYS
+<!-- okf-id: user-journeys -->
+
+<!-- QUY TẮC CHUNG §4 (Step 09 + 10): mỗi journey = (a) Mermaid flowchart TD + (b) JOURNEY SCREEN TABLE.
+KHÔNG Screen Spec block per screen (đã bỏ từ v4.0 — chi tiết regions/components/states per screen là việc
+của feature-design Stage 4a; nguồn ở đây chỉ khoá INTENT + STATE bắt buộc để 4a kế thừa).
+
+Journey Screen Table format (R2 fidelity — đủ 5 cột, không thêm không bớt):
+| Screen (SCR-* từ WBS) | Purpose (1 dòng) | Key states (bắt buộc UI phải có) | Entry ← / Exit → | Conventions refs (§C-x áp dụng) |
+
+L5/L6/L9 self-audit (journey/IA level, warn-only) ghi 1 dòng cuối mỗi journey. -->
+
+### 4.1. Primary Journey — {{primary_role_name}}
+<!-- okf-id: primary-journey -->
+<!-- Step 09 — Agent UX0. Mermaid: verb sequence + end states theo archetype §2.1 (mapping table ở step-09). Cover happy path + major branches; không vẽ branch ngoài archetype. + Journey Screen Table. -->
+
+### 4.2. Secondary Journey — {{secondary_role_name}}
+<!-- okf-id: secondary-journey -->
+<!-- Step 10 — Agent UX0. Applicable: ≥2 role non-overlapping trên cùng entity (single-role → SKIP, không placeholder). Mermaid + Journey Screen Table. Decision feedback loop về primary thể hiện bằng node trong Mermaid + hàng trong table (KHÔNG spec màn chi tiết). -->
+
+### 4.3. Additional Role Journeys
+<!-- okf-id: additional-role-journeys -->
+<!-- Step 10 — Agent UX0. Applicable: ≥3 role. 1 sub-section per role: Role Context (1-2 dòng vì sao tách) + Mermaid + Journey Screen Table. Skip role không có user story trong PRD. -->
+
+---
+
+## 5. PRD → UX MAPPING
+<!-- okf-id: prd-ux-mapping -->
+
+<!-- Step 14 — Agent UX2. Output: bảng closure {PRD Requirement | UX Solution | Section (§ ở đây / §C-x conventions / DD Stage 4a)}. 100% FR+BR+NFR xuất hiện, 0 hàng trống, solution cụ thể. NFR/BR thuộc pattern chung → map sang ux_conventions.md §C-x. Requirement chưa có solution → 🔴 GAP + báo cáo. -->
+
+---
+
+*Template version: 4.0 (slim journey spec — per-screen Screen Specs → feature-design Stage 4a; §17 inventory → project_wbs.md; personas → ux-sketch nếu có / PRD fallback, actor lock HLD; conventions → ux_conventions.md) | Framework: NTAPP Method*

package/skills/NTAPP/.agent/skills/NTAPP-ux-design/workflow.md

@@ -0,0 +1,139 @@
+# WORKFLOW: NTAPP UX DESIGN (Stage 3b — Journey Spec + Project Conventions)
+
+Luồng công việc này điều phối **NTAPP UX Design Squad** (4 agents) để tạo **2 artifact tách vai**:
+
+1. **`ux_design.md` — UX Journey Specification** (per-feature-batch, slim): phần cross-screen KHÔNG stage nào khác own — archetype + information model, IA/navigation delta, journey flows (Mermaid + journey screen table), PRD mapping. **KHÔNG chứa per-screen Screen Spec** (owner duy nhất: `feature-design` Stage 4a), **KHÔNG chứa §17 inventory** (SSoT: `project_wbs.md`), **KHÔNG chứa personas chi tiết** (§1.3 chỉ reference — actor lock HLD §3.1.1; chi tiết `ux_sketch.md` nếu có / PRD §User Stories nếu không).
+2. **`ux_conventions.md` — Project UX Conventions** (PROJECT SINGLETON, living doc): principles, content strategy + status labels, interaction patterns, notification matrix, error handling, responsive/a11y, audit-log rules. Viết đủ lần đầu (bootstrap mode), các feature sau chỉ **delta-update**.
+
+Skill chạy ở **Stage 3b** sau slice-planning (Stage 2b), TRƯỚC vòng per-slice — gate applicability ở step-01 §2.0 (SSoT).
+
+---
+
+## WORKFLOW ARCHITECTURE — Progressive disclosure
+
+- File này giữ KHUNG điều phối (bản đồ + cổng + rule). Chi tiết thực thi nằm TRONG từng step file.
+- ⛔ Đọc ĐÚNG MỘT step mỗi lần. Hoàn tất step hiện tại (gồm mọi PAUSE / user-confirm) RỒI mới đọc step kế qua pointer `**Next:**` ở cuối step đó. KHÔNG đọc trước nhiều step. State chuyển tiếp qua part files trong `{intermediate_folder}` (journey spec) hoặc ghi trực tiếp `ux_conventions.md` (conventions — ngoại lệ R1 khai báo trong iron_rules), không qua việc giữ instruction trong context.
+
+---
+
+## INITIALIZATION
+
+### Config resolution (paths)
+
+Skill này tuân theo cùng cascade 3-layer như các NTAPP skill khác (xem chi tiết trong `NTAPP-architecture-design/workflow.md` Step 0):
+
+- **Layer 1** — `{project-root}/_bmad/bmm/config.yaml`: cung cấp default `planning_artifacts`, `stage_1_discovery`, `stage_2_architecture`, `project_knowledge`, `output_folder`, `document_output_language`.
+- **Layer 2** — `{project-root}/.bmm-config.yaml` section `ntapp-ux-design:`: override `planning_artifacts` cho UX (mặc định `{project-root}/NTAPP-output/Stage_3_Specs/ux/`).
+- **Layer 3** — Interactive fallback nếu cả 2 layer đều miss biến cần.
+
+Biến runtime sau cascade:
+
+| Biến | Nguồn | Dùng cho |
+|:---|:---|:---|
+| `planning_artifacts` | Layer 1/2/3 | OUTPUT — chứa `ux_design.md` + `ux_conventions.md` + parts + archive (vd: `NTAPP-output/Stage_3_Specs/ux/`) |
+| `intermediate_folder` | Derived = `{planning_artifacts}/ux_design_parts/` | OUTPUT — part files của journey spec (flat) |
+| `stage_1_discovery` | Layer 1 | INPUT — nơi đọc PRD/Epics (vd: `NTAPP-output/Stage_1_Discovery/`) |
+| `stage_2_architecture` | Layer 1 | INPUT — nơi đọc HLD/Module 0 + `project_wbs.md` |
+| `design_system_path` | Layer 1 `design_system_root` (thống nhất key với mọi skill khác; fallback legacy `output_folder` + `/design-system/`) hoặc Layer 2 `bmad.design_system_root` | INPUT — **family root**. Multi-DS (`registry.yaml` tồn tại): resolve theo `_shared/ds-resolution.md` **nhánh C** — feature trải screen trên nhiều DS → load `component_catalog.md` của MỌI DS liên quan (resolve từng SCR-*/WGT-* qua **thẻ `repo:` ở Cluster Header WBS** — primary, WBS đã required ở step-01 — rồi `id_prefixes`/`modules`), label vocabulary theo `ds_id` (vd "`DataTable` *(web-admin)*"); screen không resolve được → vocabulary chung + WARN, KHÔNG STOP (catalog là recommended). Legacy: 1 catalog như cũ. Dùng cho `component_catalog.md` (digest — KHÔNG load full metadata), `_reference/` visual notes, `master_token.json` chỉ khi cần verify token path |
+| `ux_sketch_path` | Derived = `{stage_1_discovery}/ux_sketch/ux_sketch.md` | INPUT (optional) — personas + rough IA seed |
+| `project_knowledge` | Layer 1 | INPUT — domain docs (vd: `docs/`) |
+
+### Paths & Storage
+
+```
+{planning_artifacts}/
+├── ux_design.md                          (journey spec — canonical, overwrite latest per feature-batch)
+├── ux_conventions.md                     (PROJECT SINGLETON — living doc, delta-update, steps ghi trực tiếp)
+├── ux_design_parts/                      (intermediate parts của journey spec — flat)
+│   ├── ux2_executive_summary_part.md     (Step 02 → §1)
+│   ├── ux3_ia_part.md                    (Step 07 → §3)
+│   ├── ux3_modular_part.md               (Step 08 → §2)
+│   ├── ux0_journeys_part.md              (Step 09-10 → §4)
+│   └── ux2_traceability_part.md          (Step 14 → §5)
+│
+└── archive/
+    ├── ux_design_v{N}.md                 (versioned snapshot journey spec)
+    └── ux_conventions_v{N}.md            (versioned snapshot conventions — chỉ khi có delta)
+```
+
+**Quy tắc:**
+- `ux_design.md` (journey spec): assembly từ 5 part files bằng Verbatim Injection (R1) ở Step 14.
+- `ux_conventions.md`: steps 04/06/11/12/13 ghi TRỰC TIẾP (atomic write, U-rule) — bootstrap mode fill đủ C1-C7; delta mode chỉ patch section thay đổi + CHANGE LOG row. Đây là ngoại lệ R1 có khai báo.
+- `{planning_artifacts}` resolved từ config, KHÔNG hardcode.
+
+---
+
+## PIPELINE MAP (neo thường trực — 1 dòng/step, KHÔNG chi tiết)
+
+| Layer | # | Step file | Agent | Target | Output |
+|:--|:--|:--|:--|:--|:--|
+| A | 01 | steps/step-01-init-discovery.md | UX0 | — | scaffold 2 file + briefing + conventions mode (bootstrap/delta) |
+| A | 02 | steps/step-02-executive-summary.md | UX2 | ux_design §1 | ux2_executive_summary_part.md |
+| A | 04 | steps/step-04-ux-principles.md | UX0 | ux_conventions §C1 | direct write (skip nếu delta-mode không đổi) |
+| A | 06 | steps/step-06-content-strategy.md | UX4 | ux_conventions §C2 | direct write (status labels 1-1 Module 0 §7) |
+| B | 07 | steps/step-07-information-architecture.md | UX3 | ux_design §3 | ux3_ia_part.md (IA delta — brownfield chỉ vẽ node mới) |
+| B | 08 | steps/step-08-information-hierarchy.md | UX3 | ux_design §2 | ux3_modular_part.md (archetype + info model) |
+| C | 09 | steps/step-09-primary-journey.md | UX0 | ux_design §4.1 | ux0_journeys_part.md (Mermaid + journey screen table) |
+| C | 10 | steps/step-10-secondary-journeys.md | UX0 | ux_design §4.2-4.3 | append ux0_journeys_part.md |
+| D | 11 | steps/step-11-interaction-patterns.md | UX0 | ux_conventions §C3 | direct write |
+| D | 12 | steps/step-12-notification-error.md | UX0+UX4 | ux_conventions §C4-C5 | direct write |
+| E | 13 | steps/step-13-responsive-accessibility.md | UX0 | ux_conventions §C6-C7 | direct write |
+| E | 14 | steps/step-14-traceability-assembly.md | UX0+UX2 | ux_design §5 + assembly | ux2_traceability_part.md + Final Assembly + archive |
+
+Chuỗi: **01 → 02 → 04 → 06 → 07 → 08 → 09 → 10 → 11 → 12 → 13 → 14 (TERMINAL)**.
+*(Step 03 personas + step 05 design-system đã RETIRED từ v4.0 — §1.3 chỉ reference personas: actor lock HLD §3.1.1 (bắt buộc) + chi tiết ux-sketch (optional) / PRD fallback; DS vocabulary đi qua `component_catalog.md` digest, không cần section riêng.)*
+
+**Delta mode (conventions đã tồn tại):** steps 04/06/11/12/13 chỉ chạy khi feature mới introduce pattern chưa có / thay đổi pattern cũ (check ở đầu mỗi step — không đổi → log "no conventions delta" + đi tiếp). Journey spec (02/07/08/09/10/14) luôn chạy đủ cho feature mới.
+
+Cổng người-dùng: **step-01 §2.0** (Applicability Gate — có thể SKIP toàn skill) + **step-01 §2.4** (xác nhận pre-flight + inheritance) + **step-08** (conditional — xác nhận scope split nếu PRD chứa 2 archetype). step-14 là step cuối → bàn giao.
+
+### Đội ngũ Agent (UX Design Squad)
+
+| Agent | Vai trò | Persona BMAD | Chuyên môn | Steps phụ trách |
+|:------|:--------|:-------------|:-----------|:----------------|
+| **UX0** | UX Lead & Orchestrator | Sally (bmad-agent-ux-designer) | Journey mapping, interaction design, conventions, final assembly | 01, 04, 09, 10, 11, 13, 14 |
+| **UX2** | PM Liaison | John (bmad-agent-pm) | PRD context, goals, traceability audit | 02, 14 |
+| **UX3** | IA & System Architect | Winston (bmad-agent-architect) | Information architecture, archetype, module integration | 07, 08 |
+| **UX4** | Content Strategist | Paige (bmad-agent-tech-writer) | Microcopy, status labels, notification copy, error messaging | 06, 12 |
+
+*(UX1 Research — Mary — retired cùng step 03: Stage 3b không author personas — §1.3 reference theo actor lock HLD §3.1.1, chi tiết từ ux-sketch nếu có / PRD nếu không.)*
+
+---
+
+## GLOBAL RULES (bất biến — áp dụng mọi step)
+
+### Nguyên tắc Sắt (Iron Rules)
+
+Workflow này tuân thủ 10 quy tắc bất biến (R1–R10) định nghĩa trong [principles/iron_rules.md](./principles/iron_rules.md):
+
+| # | Tóm tắt | Áp dụng chính ở Step |
+|:--|:--|:--|
+| R1 | Verbatim Injection (journey spec; conventions = ngoại lệ khai báo — direct write) | 14 |
+| R2 | Zero-Summarization (kèm Journey Screen Table fidelity) | 14, 09-10 |
+| R3 | Zero-Fabrication (PRD + HLD + Module 0 §7 + Master DS + WBS) | toàn bộ |
+| R4 | Traceability (PRD → §5) | 14 |
+| R5 | Consistency (token / component / status / actor naming) | 04, 06, 09-13 |
+| R6 | Quality Gates | 01, 09-10, 14 |
+| R7 | Stopping Errors | 01, 14 |
+| R8 | Contract Lock (HLD + Module 0 §7 + Master DS + WBS read-only) | 01, 07 |
+| R9 | Missing Input Handling | 01 |
+| R10 | Inheritance Compliance (PRD / HLD / Module 0 §7 / Master DS / WBS / UX Sketch optional) | 01, 14 |
+
+Khi step file cite "tuân thủ Rx" — đọc iron_rules.md để biết chi tiết, KHÔNG tự suy diễn.
+
+### Quy chuẩn tài liệu
+
+- **Templates:** `./templates/ux-design-spec-template.md` (journey spec v4.0) + `./templates/ux-conventions-template.md` (conventions v1.0)
+- **Ngôn ngữ tài liệu:** `{document_output_language}` (từ config)
+- **Trọng tâm:**
+  - **Đúng vai (Separation):** journey spec = cross-screen intent; per-screen chi tiết là việc Stage 4a. Không spec 2 nơi.
+  - **Tính truy ngược (Traceability):** Mọi quyết định UX → PRD requirement (§5) hoặc conventions §C-x.
+  - **Tính nhất quán (Consistency):** status label ↔ Module 0 §7; component vocabulary ↔ `component_catalog.md`; screen ID ↔ WBS.
+
+---
+
+## LAUNCH
+
+Bắt đầu pipeline ở Layer A. Step-01 tự canh **Applicability Gate (§2.0)** — nếu feature không thoả gate multi-screen-new thì step-01 sẽ SKIP và DỪNG skill ngay (không sinh artifact).
+
+**Next:** Read fully and follow `./steps/step-01-init-discovery.md`

package/skills/NTAPP/.agent/skills/NTAPP-ux-sketch/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: ntapp-ux-sketch
+description: 'Tạo bản phác thảo UX nhẹ (Personas + Rough IA + Primary Journey + Screen Intent Table) sau khi có PRD/Epics nhưng trước khi triển khai HLD, kèm preview HTML HI-FI review được trực tiếp trong lavish (click element → comment → agent sửa). Dùng để forcing function chi tiết hóa business intent, inform HLD design, và giảm rework downstream cho Master UX Spec. Sử dụng khi người dùng nói "phác thảo UX", "ux sketch", "early UX exploration", "draft UX trước HLD".'
+---
+
+# NTAPP UX Sketch Skill (Stage 1 sub-step)
+
+This skill provides a **lightweight UX sketch workflow** to produce a rough UX document — Personas + Rough IA + Primary User Journey — **after PRD/Epics but BEFORE HLD design**, plus a **hi-fi HTML preview** of the journey that PM/BA/PO review by annotating elements directly in lavish.
+
+## Purpose
+
+3 outcomes:
+
+- **Forcing function:** PM/BA + UX Designer phải chi tiết hóa user interaction (gõ gì, thấy gì, click gì) — không né bằng prose tổng quát.
+- **Inform HLD design:** Tech Lead xem sketch trước khi design module / container / state machine → sát flow user thực.
+- **Reduce downstream rework:** Journey Spec (`/ntapp-ux-design`) Stage 3b inherit sketch làm seed cho §1.3 Persona references + §3 IA delta + §4.1 Primary Journey — chỉ expand, không rewrite. (Sketch optional — thiếu sketch thì 3b fallback PRD, không block.)
+
+## Output
+
+**1 sketch document** `ux_sketch.md` với 5 sections + **1 preview hi-fi retained** (`previews/{feature_slug}_ux_sketch_preview.html`):
+
+| § | Section | Mô tả |
+|:--|:--|:--|
+| §1 | Executive Brief | Anchor system + primary user goals (1 đoạn) |
+| §2 | Rough Personas | 2-3 personas — name, role, top 3 pain points + top 3 goals |
+| §3 | Rough IA | Top-level navigation tree + integration points với existing systems (đặc biệt cần cho brownfield) |
+| §4 | Primary Journey | 1-2 luồng chính: Mermaid sequence + Screen Intent Table (Screen / Role / Content blocks / CTA / Branch / Trace) + Preview Index |
+| §5 | Open Questions for HLD | Câu hỏi technical cho Tech Lead trả lời ở Stage 2 |
+
+Preview mặc định **hi-fi** — render bằng component thật (Tailwind/DaisyUI) skin bằng `master_token.json` của Master DS nếu project đã bootstrap Stage 0; mỗi frame mang `id` + `data-*` để annotation của reviewer map thẳng về ô tương ứng trong Screen Intent Table. Hạ về wireframe grayscale bằng `sketch_preview: lofi`, tắt bằng `off`.
+
+## Squad
+
+| Agent | Vai trò | BMAD Persona |
+|:--|:--|:--|
+| **UXS0** | UX Sketch Lead & Orchestrator | Sally (`bmad-agent-ux-designer`) |
+| **UXS1** | Research Analyst | Mary (`bmad-agent-analyst`) |
+
+## Stage placement
+
+Sub-step cuối Stage 1 — sau khi PRD + Epics approve, trước khi trigger Stage 2 Architecture.
+
+## Relationship với `/ntapp-ux-design`
+
+```
+PRD/Epics → ux_sketch.md (Stage 1) → HLD/Module 0 (Stage 2) → ux_design.md (Stage 3b)
+                ↓                                                    ↑
+                └──── inherited as seed cho §1.3 + §3 + §4.1 ────────┘
+```
+
+Sketch là **optional upstream**. Nếu không chạy sketch, ux-design vẫn generate from scratch.
+
+## Instructions
+
+Read fully and follow: `./workflow.md`

package/skills/NTAPP/.agent/skills/NTAPP-ux-sketch/bmad-skill-manifest.yaml

@@ -0,0 +1,9 @@
+type: skill
+name: ntapp-ux-sketch
+displayName: UX Sketch (Stage 1 sub-step)
+title: Lightweight UX Sketch Workflow
+icon: "✏️"
+capabilities: "rough personas, rough information architecture, primary user journey (Mermaid + screen intent table), hi-fi HTML preview reviewable in lavish (annotate element → agent fixes), open questions for HLD, brownfield integration mapping"
+role: UX Sketch Squad Orchestration
+identity: "Lightweight 2-agent workflow (UXS0 Sally + UXS1 Mary) chạy sau PRD/Epics nhưng trước HLD design. Output là rough sketch (5 sections) làm forcing function business intent + inform HLD design + reduce rework cho Master UX Spec ở Stage 3b. Subset relaxed của full /ntapp-ux-design."
+module: bmm

package/skills/NTAPP/.agent/skills/NTAPP-ux-sketch/principles/iron_rules.md

@@ -0,0 +1,127 @@
+# IRON RULES — Quy tắc bất biến của workflow NTAPP UX Sketch (Stage 1 sub-step)
+
+> File này là **nguồn sự thật duy nhất** cho các nguyên tắc bất biến của workflow UX Sketch.
+> Đây là **subset relaxed** của iron_rules cho `/ntapp-ux-design` (Stage 3b) — vì sketch chạy trước khi có HLD/Module 0/Master DS, không thể enforce những lock đó.
+> Mọi step file PHẢI tham chiếu file này thay vì tự lặp lại nội dung.
+
+---
+
+## R1. VERBATIM INJECTION (Bơm dữ liệu nguyên văn)
+
+Khi hợp nhất `uxs*_part.md` thành tài liệu Master Sketch (Step 06), **TUYỆT ĐỐI KHÔNG** thực hiện thao tác "Merge" truyền thống bằng cách đọc toàn bộ và viết lại bản tóm tắt.
+
+**Tuân thủ:** Bơm dữ liệu thô từ các Part đơn lẻ vào các vị trí giữ chỗ trong Template `ux-sketch-template.md`.
+
+---
+
+## R2. ZERO-SUMMARIZATION (Cấm tóm tắt) — RELAXED cho screen intent
+
+Mọi Screen Intent Table, Mermaid Diagram, bảng (Persona, IA tree) từ part file **PHẢI được giữ nguyên 100%** dung lượng khi đi vào Master Sketch.
+
+**Screen Fidelity sub-clause — RELAXED so với full ux-design:**
+- Bố cục diễn đạt bằng **Screen Intent Table** (Screen / Role / Content blocks / Primary CTA / Branch / Trace) — KHÔNG vẽ ASCII wireframe, KHÔNG cần layout grid chính xác.
+- Nội dung KHÔNG bắt buộc phải là content thực — placeholder OK miễn đại diện đúng kiểu data của nghiệp vụ.
+- KHÔNG cần component mapping (Stage 4b own quyền chốt component/token).
+- Vẫn cần đủ: screen identifier + content blocks + CTA + branch + trace.
+
+**Preview Fidelity sub-clause:** preview HTML ở Step 05 render **hi-fi** (skin bằng token Master DS nếu đã bootstrap) để reviewer annotate chính xác. Hi-fi là fidelity của **bản render**, KHÔNG phải commitment về design: preview không phải SSoT, không phải visual đã DS-approve, và không sinh/không sửa token. `ux_sketch.md` + parts vẫn canonical — feedback sửa vào part rồi re-render, KHÔNG sửa tay HTML.
+
+**Vi phạm điển hình:** Cắt ngắn persona table; gộp 2 screen thành 1 row; bỏ Mermaid diagram khi assemble; sửa trực tiếp preview HTML rồi để part file lệch.
+
+---
+
+## R3. ZERO-FABRICATION / ZERO-HALLUCINATION (Cấm bịa)
+
+Chỉ sử dụng thông tin từ các nguồn đã xác nhận. Sketch CHỈ có 1 nguồn primary:
+
+| Nguồn | Path | UX Sketch dùng cho |
+|:--|:--|:--|
+| **PRD/Epics** (primary) | `{stage_1_discovery}/prd*.md` + `epics*.md` | Toàn bộ — actors, FR/BR, user stories |
+| **Project domain docs** (optional) | `{project_knowledge}/` | Bối cảnh brownfield — existing systems để integrate, terminology |
+
+**KHÔNG có HLD/Module 0/Master DS để reference** ở Stage này — đó là lý do sketch là "rough", không phải full spec.
+
+Khi thiếu thông tin (vd persona pain point chưa rõ trong PRD) → đánh dấu `[TBD - cần PM/BA confirm]`. **TUYỆT ĐỐI không bịa**.
+
+---
+
+## R4. TRACEABILITY (Traceability cơ bản)
+
+- Mỗi persona §2 phải tương ứng với ≥ 1 actor trong PRD.
+- Mỗi journey step §4 phải reference ≥ 1 Epic ID hoặc Story ID từ Epics document.
+- Mỗi Open Question §5 phải gắn với 1 ambiguity cụ thể trong PRD/Epics — không câu hỏi chung chung.
+
+**Lưu ý:** Sketch KHÔNG cần PRD→UX closure mapping (§16) như full ux-design — đó là việc của Stage 3b.
+
+---
+
+## R6. QUALITY GATES — RELAXED
+
+| Gate | Sau step | Owner | Hành động khi FAIL |
+|---|---|---|---|
+| Pre-flight Input Audit | 01 | UXS0 | DỪNG, escalate user xác nhận PRD/Epics tồn tại |
+| Validation Gate | 05 | UXS0 + User | Loop back step tương ứng để sửa nếu PM/BA/PO không approve |
+
+KHÔNG có Token↔Wireframe Sync, Component Coverage, Quantitative Audit, PRD→UX Closure như full ux-design — vì sketch không có DS coverage hoặc closure requirement.
+
+---
+
+## R7. STOPPING ERRORS
+
+Dừng pipeline ngay và báo cáo nếu phát hiện:
+
+1. PRD hoặc Epics **không tồn tại** hoặc rỗng → broken inheritance.
+2. PRD có actors mơ hồ (chỉ "user" generic, không phân biệt role) → personas §2 không thể derive → cần PM/BA refine PRD trước.
+3. Epics không có user story format ("As a X, I want Y, so that Z") → journey §4 không thể derive Epic/Story trace → cần BA refine Epics trước.
+
+---
+
+## R9. MISSING INPUT HANDLING
+
+Nếu input file (PRD, Epics) không tồn tại hoặc không readable:
+
+- DỪNG ngay, **KHÔNG generate placeholder content** thay thế.
+- Báo user explicit: "File `X` tại path `Y` không tìm thấy. Vui lòng cung cấp đường dẫn hoặc xác nhận file."
+- Chỉ tiếp tục sau khi user confirm file tồn tại + readable.
+
+**Phân biệt Required vs Recommended:**
+- **PRD + Epics:** Required. Thiếu → DỪNG.
+- **Project knowledge docs:** Recommended cho brownfield. Thiếu → WARN, sketch §3 Rough IA sẽ thiếu integration points với existing systems → đánh dấu rõ "không có domain docs, cần SA reconcile ở Stage 2".
+
+**KHÔNG list HLD/Module 0/Master DS** — vì những file này CHƯA tồn tại ở Stage 1.
+
+---
+
+## R10. INHERITANCE COMPLIANCE — Partial
+
+UX Sketch chỉ kế thừa từ 1 nguồn:
+
+- **PRD/Epics inheritance:** Mọi actor, FR, BR, user story trong PRD/Epics phải có representation trong sketch (persona, journey step, IA item).
+
+KHÔNG có HLD/Module 0/Master DS upstream để inherit ở Stage này.
+
+**Vi phạm điển hình:**
+- §2 Personas có "Approver" nhưng PRD chỉ có "Operator" — bịa actor → SAI.
+- §4 Journey có step không trace về Epic/Story nào → SAI.
+- §3 Rough IA có module "Reporting" nhưng PRD không nhắc reporting → SAI.
+
+---
+
+## Note: Quan hệ với `/ntapp-ux-design` Iron Rules (Stage 3b)
+
+Sketch's iron_rules là subset relaxed của full ux-design:
+
+| Rule | Sketch | Full ux-design |
+|:--|:--|:--|
+| R1 Verbatim | ✓ | ✓ |
+| R2 Zero-Sum | ✓ relaxed (Screen Intent Table + preview hi-fi) | ✓ strict wireframe |
+| R3 Zero-Fab | ✓ (PRD only) | ✓ (PRD + HLD + Module 0 + Master DS) |
+| R4 Traceability | ✓ basic | ✓ full §16 closure |
+| R5 Consistency | ✗ | ✓ token/component naming |
+| R6 Quality Gates | ✓ 2 gates | ✓ 6 gates |
+| R7 Stopping | ✓ 3 errors | ✓ 7 errors |
+| R8 Contract Lock | ✗ | ✓ HLD + Module 0 §7 + Master DS |
+| R9 Missing Input | ✓ | ✓ |
+| R10 Inheritance | ✓ partial (PRD only) | ✓ full (PRD + HLD + Module 0 §7 + Master DS) |
+
+→ Sketch deliberately weaker để chạy được ở Stage 1 khi upstream chưa có. Master UX Spec ở Stage 3b sẽ ENFORCE 10/10 rules — sketch chỉ là seed.

package/skills/NTAPP/.agent/skills/NTAPP-ux-sketch/steps/step-01-init.md

@@ -0,0 +1,88 @@
+# STEP 01: INPUT DISCOVERY & SCAFFOLD
+
+> **Thực hiện bởi:** Agent UXS0 (UX Sketch Lead — Sally)
+> **Tuân thủ:** [iron_rules.md](../principles/iron_rules.md) — emphasize **R3, R7, R9**.
+
+## 1. Mục tiêu
+
+Thu thập PRD + Epics, xác nhận phạm vi, khởi tạo tài liệu Master Sketch + parts dir + briefing cho UXS1.
+
+## 2. Chỉ thị thực thi
+
+### 2.1. Pre-flight Input Audit (R7 + R9)
+
+**Path resolution:** Trước khi search, load config cascade (workflow.md §5.1) để resolve `{stage_1_discovery}`, `{planning_artifacts}`, `{project_knowledge}`.
+
+Tìm và verify:
+
+| Tài liệu | Bắt buộc? | Đường dẫn | Action khi miss |
+|:--|:--|:--|:--|
+| **PRD** | ✅ Required | `{stage_1_discovery}/prd*.md` | DỪNG (R7 #1) |
+| **Epics/Stories** | ✅ Required | `{stage_1_discovery}/epics*.md` | DỪNG (R7 #1) |
+| **Project knowledge** | Recommended | `{project_knowledge}/` | WARN — sketch §3 thiếu integration points |
+
+**Validate format:**
+- PRD có actors phân biệt rõ (không chỉ "user" generic)? Nếu không → R7 #2, escalate PM/BA refine.
+- Epics có user story format ("As a X, I want Y, so that Z")? Nếu không → R7 #3, escalate BA refine.
+
+### 2.1b. Pre-resolve preview design source (cho Step 05)
+
+Preview hi-fi ở [step-05](./step-05-validation.md) §3.1b cần biết skin bằng gì — resolve NGAY ở đây để báo user cùng lúc xác nhận phạm vi, không để phát hiện thiếu DS giữa gate:
+
+1. Đọc `sketch_preview` (default `lavish` = hi-fi) + `sketch_preview_theme` (default `corporate`) từ `.bmm-config.yaml` block `ntapp-ux-sketch:`. Value `off` → bỏ qua mục này.
+2. Resolve DS root theo `{design_system_root}/_shared/ds-resolution.md` **nhánh F** (cosmetic, read-only, KHÔNG BAO GIỜ STOP) → check `{ds_root}/master_token.json` + `{ds_root}/_reference/` có tồn tại.
+3. Ghi lại kết quả (dùng ở §2.2 mục 6): `master_token.json` có → *"preview skin bằng Master DS `{ds_id}`"*; không có → *"preview dùng theme placeholder `{sketch_preview_theme}` — chạy `/ntapp-ds-bootstrap` (Stage 0) trước nếu muốn preview mang đúng identity product"*.
+
+### 2.2. Xác nhận phạm vi với User
+
+Trình bày:
+1. **Tài liệu tìm được:** Liệt kê file + tóm tắt 1 dòng.
+2. **Anchor system:** Hệ thống chính (từ PRD).
+3. **Existing systems** (nếu brownfield): list từ project knowledge / PRD.
+4. **Vai trò người dùng:** Danh sách sơ bộ từ PRD.
+5. **Primary user goals:** Top 3 từ PRD.
+6. **Preview design source** (kết quả §2.1b): fidelity đang dùng (`hi-fi` / `lofi` / `off`) + skin lấy từ đâu.
+
+**CHỜ USER XÁC NHẬN** trước khi tiếp tục.
+
+### 2.3. Khởi tạo Master Sketch
+
+1. Đọc template: `../templates/ux-sketch-template.md`
+2. Điền các biến cơ bản:
+   - `{{project_name}}`, `{{anchor_system}}`, `{{date}}`, `{{user_name}}`
+3. Lưu file Master tại: `{planning_artifacts}/ux_sketch.md`
+4. Tạo thư mục parts: `{planning_artifacts}/ux_sketch_parts/` (= `{intermediate_folder}`)
+5. Cập nhật frontmatter:
+   ```yaml
+   stepsCompleted: [step-01-init]
+   inputDocuments: [path/to/prd.md, path/to/epics.md]
+   ```
+
+### 2.4. Draft §1 Executive Brief
+
+UXS0 tự viết §1 Executive Brief (3-5 câu) trực tiếp vào Master scaffold:
+- Anchor system
+- Top 3 primary user goals (từ PRD)
+- Business outcomes expected (1 đoạn)
+
+Trace mỗi goal về PRD §X.
+
+### 2.5. Briefing cho UXS1
+
+Tạo bản tóm tắt ngắn truyền cho UXS1 ở Step 02:
+- Tên dự án + anchor system
+- Danh sách actors từ PRD §X
+- Top pain points đã hint trong PRD problem statement
+- Đường dẫn PRD + Epics
+
+## 3. Đầu ra yêu cầu
+
+- [ ] PRD + Epics đã verify exist + có cấu trúc đúng (R7 pass)
+- [ ] Preview design source đã resolve (§2.1b) — `sketch_preview` + DS root / theme placeholder
+- [ ] Master Sketch khởi tạo (header + change log + frontmatter + §1 Executive Brief draft)
+- [ ] `ux_sketch_parts/` đã tạo
+- [ ] Briefing cho UXS1 chuẩn bị xong
+- [ ] User xác nhận phạm vi
+
+## NEXT
+[step-02-rough-personas.md](./step-02-rough-personas.md)