@trungtamcongnghedigital/vsaf 1.0.0

package/skills/NTAPP/.agent/skills/NTAPP-ds-bootstrap/steps/step-07-apply.md

@@ -0,0 +1,123 @@
+# Step 7: Apply & Archive
+> ⛔ Đây là step cuối (TERMINAL) — KHÔNG còn step kế, KHÔNG có pointer dẫn sang step tiếp.
+
+## GOAL
+
+Apply approved proposals (từ Step 6) vào `master_token.json` + `components_metadata.json` latest, dual-write archive snapshot, optional W3C export. Append `[APPLY SUMMARY]` vào `bootstrap_report.md`.
+
+## ENTRY CONDITION
+
+Chỉ chạy sau khi DSO đã tick checkboxes trong `bootstrap_report.md` tại Step 6 VÀ reply `'approved'` ở HITL prompt cuối Step 6.
+
+## 1. Load Persona
+
+Adopt role của **Bootstrap Applier** sub-agent tại `../agents/bootstrap-applier.md`. Persona declare: role + decision policies (§4.1 approved set composition, §4.2 validation matrix, §4.3 archive numbering, §4.4 W3C export) + output spec (§5 file list + `[APPLY SUMMARY]` markdown template) + edge cases (§6) + constraints (§7).
+
+## 2. Inputs
+
+- `bootstrap_report.md` (DSO-ticked).
+- `master_token_parts/02_normalized.json` (`preliminary_master_token` + approved proposals).
+- `master_token_parts/03_conflict_resolved.json` (optional, nếu Step 5).
+- `components_metadata_parts/01_discovered.json`.
+- `stack-profile.json` (snapshot vào archive).
+- `_shared/token-format-schema.md`, `component-metadata-schema.md`.
+
+## 3. Pipeline
+
+### Stage 3.1: Re-parse approved decisions
+
+Đọc `bootstrap_report.md`, extract approved checkboxes per section (HIGH/MEDIUM/LOW + conflict decisions + hard validation resolutions). Validate: hard validation fail chưa resolve → STOP per persona §6 message.
+
+### Stage 3.2: Build final master_token
+
+Theo `bootstrap-applier.md` §4.1 approved set composition:
+- Start với `preliminary_master_token` từ `02_normalized.json`.
+- Merge approved MEDIUM/LOW proposals.
+- Merge conflict decisions từ `03_conflict_resolved.json` (nếu Step 5 chạy).
+- Apply hard validation resolutions (vd: darken color values).
+
+### Stage 3.3: Build final components_metadata
+
+- Start với `01_discovered.json`.
+- Strip `discovery_metadata` field (internal-only).
+- Replace `<TODO: DSO fill>` placeholders với DSO inputs từ report (nếu DSO đã fill inline trong report editor).
+- TODO chưa fill → giữ placeholder, mark `metadata.status: "incomplete"` cho component đó.
+
+### Stage 3.4: Validate full structure
+
+Theo persona §4.2 matrix:
+- Token format theo `_shared/token-format-schema.md` — 3-tier, downward-only refs, type inference consistent.
+- Component metadata theo `_shared/component-metadata-schema.md` mục 7 — 2 layers, tokens_used resolve, file_path resolve, no duplicate names.
+
+Fail → STOP, dump `{design_system_root}/_failed_bootstrap.json`. KHÔNG ghi đè latest.
+
+### Stage 3.5: Atomic write latest
+
+Theo U1 + U2 + U4:
+- Tempfile → rename pattern cho cả 2 files.
+- Update `metadata.last_updated` ISO timestamp.
+- Pretty-print 2-space indent, sorted keys (deterministic).
+
+Paths:
+- `{design_system_root}/master_token.json`
+- `{design_system_root}/components_metadata.json`
+
+### Stage 3.5b: Derive `component_catalog.md` (digest cho Stage 3b/4a)
+
+Sinh từ `components_metadata.json` final (KHÔNG nguồn khác — derived artifact, regenerate mỗi khi metadata đổi; `/ntapp-ds-build-component` metadata-registrar cũng regenerate sau mỗi lần apply delta):
+
+```markdown
+# Component Catalog — {project}{ — {ds_id} nếu multi-DS} (derived — DO NOT EDIT; regenerate từ components_metadata.json)
+
+| Component | Category | Intent (≤90 chars) | Variants | Used in (top 3) |
+|---|---|---|---|---|
+| search-input | form | Ô tìm kiếm có debounce + clear | default, compact | merchant-list, tx-history, +3 |
+
+## Recipes (composition patterns quan sát từ code)
+- **filter-bar-row** = search-input + status-dropdown + date-range-picker + search-button — thấy ở: merchant-list, tx-history
+## Layout primitives
+Stack, Cluster, Grid, ... (category `layout-primitive` — xem components_metadata.json §12)
+```
+
+- 1 dòng/component (mọi category trừ layout-primitive — nhóm này gộp 1 dòng liệt kê). Intent cắt ≤90 chars. `Used in` từ `usage.screens` (tên folder cuối, ≤3 + `+N`).
+- Mục đích: **F3 (Stage 4a) và UX3 (Stage 3b) load file NÀY thay vì full `components_metadata.json`** — đủ vocabulary + recipes để author wireframe theo tên component thật, không tốn context. Matcher authoritative ở Stage 4b vẫn dùng full metadata.
+- Atomic write: `{design_system_root}/component_catalog.md`.
+
+### Stage 3.6: Dual-write archive
+
+Per persona §4.3:
+- Tạo `{design_system_root}/archive/_v{N+1}_{timestamp}/` (N = count existing `archive/_v*/` + 1).
+- Copy: `master_token.json`, `components_metadata.json`, `stack-profile.json`, `bootstrap_report.md`.
+- Timestamp collision → suffix `_a`, `_b`, ...
+- Disk full → report success cho latest, cảnh báo archive skip, không exit fail.
+
+### Stage 3.7: Optional W3C export
+
+Nếu DSO chọn `target_format = w3c` tại INITIALIZATION:
+- Convert `master_token.json` qua `_shared/w3c-converter.md` mục 3.
+- Atomic write: `{design_system_root}/master_token.w3c.json`.
+
+### Stage 3.8: Append `[APPLY SUMMARY]`
+
+Append section vào `report_sections[]` theo `bootstrap-applier.md` §5 template. Re-compose `bootstrap_report.md` cuối cùng với apply summary (atomic write). **Multi-DS:** header report ghi thêm dòng `ds_id: {ds_id}` (lấy từ `registry.yaml` entry có root khớp `{design_system_root}`; không có registry → bỏ qua) — audit trail phân biệt report thuộc DS nào.
+
+## 4. Decision Points
+
+- **Hard validation fail chưa resolve** (DSO reply `'approved'` nhưng còn fail) → STOP với hint DSO mở report sửa rồi reply lại.
+- **Token reference unresolved** (component dùng `semantic.color.unknown`) → validation fail. STOP, dump `_failed_bootstrap.json`.
+- **`bootstrap_report.md` parse fail** → STOP với hint DSO restore valid markdown.
+- **Disk full khi write archive** → log warning, vẫn report success cho latest (không exit fail).
+- **TODO placeholder chưa fill** trong components_metadata → giữ placeholder + mark `status: "incomplete"` cho component đó (không block apply).
+
+## 5. Output
+
+- `{design_system_root}/master_token.json` (latest).
+- `{design_system_root}/components_metadata.json` (latest).
+- `{design_system_root}/component_catalog.md` (derived digest — Stage 3.5b).
+- `{design_system_root}/bootstrap_report.md` (final, với `[APPLY SUMMARY]`).
+- `{design_system_root}/archive/_v{N+1}_{timestamp}/` (snapshot).
+- (Optional) `{design_system_root}/master_token.w3c.json` (nếu DSO chọn target format w3c).
+
+## 6. Cross-repo note
+
+Step này write **chỉ** spec repo. Code repo KHÔNG bị động chạm (Universal Rule U3). Sau khi skill chạy xong, DSO commit/push spec repo. Không cần commit code repo cho bootstrap.

package/skills/NTAPP/.agent/skills/NTAPP-ds-bootstrap/workflow.md

@@ -0,0 +1,147 @@
+# Workflow: NTAPP DS Bootstrap
+
+**Goal:** Khởi tạo Master Design System cho FE repo từ code reality + best-practices baseline + (optional) external tokens.
+
+---
+
+## WORKFLOW ARCHITECTURE — Progressive disclosure
+
+- File này giữ KHUNG điều phối (bản đồ + rule + cổng). 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 HITL/PAUSE) 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 artifact file + `report_sections[]`, không qua việc giữ instruction trong context.
+
+---
+
+## INITIALIZATION
+
+> **⚠️ Cross-repo direction:** Skill chạy **trong code repo** (cwd có `package.json`); READ source từ code repo, WRITE Master DS metadata về spec repo. Yêu cầu **multi-root workspace** mở cả 2 repo. Xem [Manual_phase_1.md mục 8](../../docs/Process/Manual_phase_1.md) — Multi-repo setup. Direction guard chi tiết: §U3.
+
+### Inputs (DSO cung cấp khi gõ `/ntapp-ds-bootstrap`)
+- (Optional) **External tokens path** — file NTAPP v1 hoặc W3C JSON nếu DSO muốn 3-way diff với code reality. Không nhắc → skip Step 5.
+- (Optional) **Mode override** — `overhaul` / `regenerate full DS` → discard latest, snapshot vào `archive/` trước rồi rebuild. Default: incremental (reuse `stack-profile.json` nếu có).
+- (Optional) **Target format** — `ntapp` (default) hoặc `w3c` để export thêm `master_token.w3c.json` ở Step 7.
+- (Optional) **Re-parse flag** — `--refresh-library-api` để rerun parser bỏ qua cache (xem Step 1b).
+
+Input còn lại được hỏi tại HITL gates (Step 1 reuse stack-profile, Step 1b parse-fail HITL, Step 6 auto-approve HIGH).
+
+### Context Loading
+Load `.bmm-config.yaml` ở **code repo root** — extract:
+- `bmad.spec_repo_root` — relative/absolute path tới spec repo.
+- `bmad.design_system_root` — resolved path tới **DS root của repo này** (default `{spec_repo_root}/NTAPP-output/design-system`). Project multi-DS (nhiều FE repo → nhiều DS): giá trị trỏ `{family_root}/{ds_id}` — thủ tục chuẩn `_shared/ds-resolution.md` **nhánh A** + `_shared/ds-registry-schema.md`.
+- `bmad.code_repo_root` — root của code repo. Default = cwd (auto-detect nếu cwd có `package.json`).
+- Block `stack` (manual override) + `ds-bootstrap` (rules config).
+
+Load shared schemas (READ từ spec repo):
+- `{design_system_root}/_shared/best-practices.md`, `stack-profile-schema.md`, `token-format-schema.md`, `component-metadata-schema.md`, `library-api-schema.md`, `pattern-matcher.md`, `w3c-converter.md`.
+- **Multi-DS:** `_shared/` LUÔN ở family root — `{design_system_root}/_shared/` không tồn tại (DS namespaced `{family}/{ds_id}`) → đọc `{design_system_root}/../_shared/` (quy tắc fallback cơ học, áp cho mọi ref `_shared/*` trong skill).
+
+### Pre-conditions (pre-flight)
+
+**Pre-flight 1 — Cwd phải là code repo:** verify `{code_repo_root}/package.json` tồn tại. Nếu cwd = spec repo (vd: thấy `NTAPP-output/design-system/` ngay tại cwd, không có `package.json`) → STOP: *"Skill scan code stack từ code repo, phải chạy trong code repo. Mở multi-root workspace, switch sang code repo, chạy lại."*
+
+**Pre-flight 2 — Spec repo accessible:** verify `{spec_repo_root}` exist + writable.
+
+**Pre-flight 2b — DS identity (multi-DS guard):** nếu `{design_system_root}/registry.yaml` tồn tại → config đang trỏ **family root** của project multi-DS, KHÔNG phải DS root của repo. *Ngoại lệ hợp lệ duy nhất:* registry có system `root: "."` mà `code_repo` khớp repo hiện tại (DS legacy in-place) → tiếp tục. Ngược lại → STOP: *"`bmad.design_system_root` đang trỏ family root (có `registry.yaml`). Sửa `.bmm-config.yaml` code repo trỏ vào DS root của repo: {liệt kê `{ds_id} → {family}/{root}` từ registry}. Repo chưa có DS trong registry → chạy lại và chọn nhánh 'Tạo DS mới' ở Step 1."*
+
+**Pre-flight 3 — Shared schemas tồn tại:** mỗi file trong Context Loading list phải resolve. Thiếu → STOP: *"Spec repo thiếu shared schema `{path}`. Verify spec repo state hoặc clone lại."*
+
+**Pre-flight 4 — External tokens path (nếu DSO cung cấp):** file tồn tại + parse-able JSON. Fail → báo DSO sửa path/format trước khi tiếp tục.
+
+**Pre-flight 5 — `node_modules` (nếu Step 1b sẽ chạy):** `ui_library.name ∉ {none, shadcn}` và `node_modules/{lib}` không tồn tại → STOP: *"Lib `{name}` cần parse nhưng `node_modules/{lib}` không có. Chạy `npm install` (hoặc tương đương) trước."* (Library-api-parser cũng có cùng check; pre-flight chỉ fail-fast.)
+
+---
+
+## PIPELINE MAP (neo thường trực — 1 dòng/step, KHÔNG chi tiết)
+
+| # | Step file | Persona | Output | Skip / branch |
+|---|---|---|---|---|
+| 1 | steps/step-01-stack-detect.md | stack-detector | stack-profile.json | skip nếu `stack-profile.json` đã có VÀ DSO confirm reuse |
+| 1b | steps/step-01b-library-api-parse.md | library-api-parser | library_apis/{lib}@{ver}/*.json | skip nếu `ui_library.name ∈ {none, shadcn}` |
+| 2 | steps/step-02-extract.md | raw-style-extractor | master_token_parts/01_raw_extracted.json | — |
+| 3 | steps/step-03-discover.md | component-discoverer | components_metadata_parts/01_discovered.json (+ usage, recipes, inferred intents) | — |
+| 3b | steps/step-03b-visual-reference.md | (procedural, DSO tương tác) | _reference/pages/*.png + _reference/visual-notes.md | skip nếu greenfield / config off / không có nguồn render |
+| 4 | steps/step-04-normalize.md | normalizer | master_token_parts/02_normalized.json | branch: external tokens → 5, else → 6 |
+| 5 | steps/step-05-conflict-resolve.md | conflict-resolver | master_token_parts/03_conflict_resolved.json | gated: chỉ chạy nếu DSO cung cấp external tokens |
+| 6 | steps/step-06-human-approval.md | (compose report + HITL) | bootstrap_report.md | [GATE] DSO `'approved'`; optional auto-approve HIGH qua config |
+| 7 | steps/step-07-apply.md | bootstrap-applier | master_token.json + components_metadata.json + archive | TERMINAL; chỉ chạy sau khi DSO `'approved'` ở Step 6 |
+
+Chuỗi: **1 → 1b → 2 → 3 → 3b → 4 → [branch: external tokens? → 5] → 6 → [GATE: DSO approval] → 7**.
+Một cổng người-dùng bắt buộc: **HITL approval ở Step 6** (nằm trong step-06, trước khi sang step-07).
+
+---
+
+## GLOBAL RULES — UNIVERSAL SUB-AGENT RULES (bất biến — áp dụng mọi step)
+
+Mọi persona/sub-agent của skill này tuân thủ các convention sau (declared **ONCE** ở đây, persona không lặp lại):
+
+### U1. Atomic file write
+Mọi write filesystem (master_token.json, components_metadata.json, stack-profile.json, library_apis/*, master_token_parts/*, components_metadata_parts/*, bootstrap_report.md, archive contents, optional W3C export) PHẢI dùng pattern **tempfile → fsync → rename**. Không append-write, không partial write.
+
+### U2. Path resolution
+- File trong **code repo**: path relative tới `{code_repo_root}` (vd: `src/app/lib/components/button/button.component.ts`). KHÔNG absolute, KHÔNG prefix.
+- File trong **spec repo**: path relative tới `{design_system_root}` (vd: `master_token_parts/01_raw_extracted.json`).
+- Lý do relative: portability cross-machine (dev clone code repo paths khác nhau).
+
+### U3. Cross-repo direction guard
+Bootstrap là uni-directional: **READ-only code repo, WRITE-only spec repo**.
+
+- KHÔNG modify source trong `{code_repo_root}/...` (không edit `package.json`, không edit style/component files, không sửa `node_modules/`).
+- Mọi resolve target path phải check: write path bắt đầu bằng `{code_repo_root}/...` → STOP *"Bootstrap không write code repo. Target `{path}` sai. Verify `bmad.design_system_root` config."* Read path bắt đầu bằng `{design_system_root}/...` cho source-of-truth files → OK (vd: shared schemas, previous run output).
+
+### U4. Deterministic output
+Same `(code state, config, external file)` → same output. Áp dụng:
+- JSON pretty-print: 2-space indent, sorted keys alphabetical.
+- Array stable ordering (sort tokens alphabetical TRONG tier, components alphabetical, raw values sort theo `occurrences` descending rồi alphabetical tie-break, dedup theo value).
+- Timestamps chỉ trong metadata fields định trước (`generated_at`, `last_updated`), không scatter trong body.
+
+### U5. Conservative inference (no fabrication)
+Khi không đủ confidence, sub-agent KHÔNG đoán. Behaviors:
+- Mark `<TODO: DSO fill>` placeholder cho field không infer được.
+- Flag `confidence: LOW` + suggest DSO override qua `.bmm-config.yaml`.
+- Library parser fail: mark `unknown` type + ghi note, KHÔNG fabricate prop.
+- Edge cases handle theo persona §6, KHÔNG silent-skip.
+
+### U6. Confidence levels (single canonical)
+| Level | Định nghĩa |
+|---|---|
+| **HIGH** | ≥2 nguồn confirm (vd: manifest + sample file), hoặc deviation rõ ràng + fix tự nhiên |
+| **MEDIUM** | 1 nguồn confirm, others ambiguous, hoặc pattern conflict cần DSO chọn |
+| **LOW** | Heuristic-only, opinion-based, hoặc fabrication risk → bắt buộc DSO override |
+
+Field confidence < HIGH → flag console + suggest override.
+
+---
+
+## FAIL CONDITIONS
+
+Mọi STOP condition document tại DECISION POINTS của step tương ứng (step-01 đến step-07). workflow.md không liệt kê tránh drift. Generic categories:
+
+- **Pre-flight fail** — missing manifest, multi-framework conflict, spec repo unreachable, schema missing, `node_modules` thiếu.
+- **External file invalid** — parse fail hoặc format không support.
+- **Validation fail không resolve** — hard validation fail (WCAG) còn sau Step 6 → bắt buộc DSO resolve.
+- **U3 guard violation** — sub-agent attempt write code repo.
+
+## OUTPUTS
+
+Tất cả output ghi về **spec repo** (`{design_system_root}/...`). Code repo KHÔNG bị skill ghi vào (chỉ READ scan):
+
+- `{design_system_root}/master_token.json` (latest)
+- `{design_system_root}/components_metadata.json` (latest — kèm `usage` per component + top-level `recipes[]`)
+- `{design_system_root}/component_catalog.md` (derived digest — consumer: Stage 3b/4a vocabulary)
+- `{design_system_root}/_reference/` (visual reference — screenshots + visual-notes.md; optional, Step 3b)
+- `{design_system_root}/stack-profile.json`
+- `{design_system_root}/bootstrap_report.md`
+- `{design_system_root}/master_token_parts/` (intermediate)
+- `{design_system_root}/components_metadata_parts/` (intermediate)
+- `{design_system_root}/library_apis/{lib}@{ver}/*.json` (Step 1b)
+- `{design_system_root}/archive/_v{N}_{timestamp}/` (snapshot sau DSO `'approved'`)
+- (Optional) `{design_system_root}/master_token.w3c.json` (target format `w3c`)
+
+> **Commit:** sau khi skill chạy xong, DSO commit/push spec repo. Code repo không bị động chạm — không cần commit code repo cho bootstrap.
+
+---
+
+## LAUNCH
+
+Chạy pre-flight ở INITIALIZATION. Pass → vào pipeline bắt đầu Step 1.
+
+**Next:** Read fully and follow `./steps/step-01-stack-detect.md`

package/skills/NTAPP/.agent/skills/NTAPP-ds-build-component/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: ntapp-ds-build-component
+description: 'Apply một delta proposal (NEW/MODIFIED tokens & components) vào codebase: scaffold component mới (bao gồm layout-primitive adapters theo stack-profile.layout_library), patch component cũ, update master_token canonical (spec repo) + export runtime token file (code repo, theo stack-profile), dual-write archive. Hard gate TRONG Stage 4b — chạy SAU /ntapp-ui-generation khi proposed_ds_updates.md (cho `screen_id` / `widget_id`) có [NEW] non-empty, trước khi merge feature code.'
+---
+
+# NTAPP DS Build Component Skill
+
+Consumer của contract `_shared/proposal-schema.md`. Producer thường là Stage 4b Agent 1 (`/ntapp-ui-generation`), hoặc dev viết tay (manual mode).
+
+**Scope:** FE-only — chỉ xử lý delta từ `screen_id` / `widget_id`. BE `feature_id` không có Master DS delta, skill skip.
+
+6-step pipeline: validate proposal → warning gate → apply tokens (master_token.json, spec repo) → **export runtime tokens (code repo, theo stack-profile format)** → apply components (NEW trước, MODIFIED sau; layout-primitive components dispatch qua adapter theo `stack-profile.layout_library.strategy` — native/utility/generated/raw) → archive + report.
+
+## Workflow
+
+Theo instructions trong [workflow.md](./workflow.md).

package/skills/NTAPP/.agent/skills/NTAPP-ds-build-component/agents/component-patcher.md

@@ -0,0 +1,103 @@
+# PERSONA: COMPONENT PATCHER (sub-agent)
+
+## 1. System Role
+
+Bạn là **Component Patcher** sub-agent của `/ntapp-ds-build-component`. Nhiệm vụ: với mỗi MODIFIED component trong routing object, edit existing file in-place — apply chính xác change_type được Agent 1 specify, detect breaking change, log diff.
+
+**Tôn chỉ:** Surgical edit. KHÔNG rewrite file. KHÔNG refactor ngoài scope. Mỗi `change_type` map tới một edit operation cụ thể.
+
+## 2. Inputs
+
+- Routing object: `components_to_patch` (sorted alphabetical)
+- `stack-profile.json` (để biết file extensions + parser)
+- `master_token.json` (đã updated — để verify new tokens_used exist)
+- `components_metadata.json` (current — để biết file_path)
+- Existing component files (read mode)
+
+## 3. Execution Responsibilities
+
+Agent thực hiện 4 trách nhiệm sau, áp dụng theo decision policies §4 + constraint §6 và output spec §5. **Pipeline ordering, locate procedure, edit operation guidelines, multi-file transactional rollback** đều ở `../steps/step-04-apply-components.md` §5:
+
+- **Locate file** — đọc `components_metadata.json[name].stack_specific.{fw}.file_path`, resolve theo U2, apply U3 (spec-repo guard) + U5 (drift check).
+- **Apply theo `change_type`** — dispatch theo bảng §4.1.
+- **Breaking change detection** — taxonomy §4.2; mismatch declaration → STOP (Universal Rule U5).
+- **Multi-file transactional edit** — touch class + template + style + module + story atomic-or-rollback.
+
+## 4. Decision Policies
+
+### 4.1 `change_type` → edit operation table
+
+| change_type | Operation |
+|---|---|
+| `add_input` | Insert `@Input()` (Angular) hoặc Props field (React) — tại vị trí cuối block inputs hiện có. |
+| `remove_input` | Remove decorator + field. Breaking change. |
+| `add_output` | Insert `@Output() new = new EventEmitter<T>()` (Angular) hoặc handler prop (React). |
+| `remove_output` | Remove. Breaking. |
+| `add_variant` | Update union type `'a' \| 'b'` → `'a' \| 'b' \| 'c'`. Add SCSS class block cho variant mới. |
+| `remove_variant` | Update union, remove SCSS block. Breaking. |
+| `change_token` | Replace token reference trong style file (vd: `var(--color-primary)` → `var(--color-danger)`). Verify new token exist post token-applier. |
+| `add_state` | Insert state field/enum value. |
+| `change_accessibility` | Update `role`, `aria-*` attrs trong template. |
+| `add_dependency` | Update module imports + dependencies array (Angular module hoặc package.json). |
+
+`change_type` ngoài list → STOP `"unknown change_type"`.
+
+### 4.2 Breaking change taxonomy
+
+Theo `_shared/proposal-schema.md`:
+
+Breaking nếu:
+- remove_input / remove_output / remove_variant
+- change_token với type mismatch (color → spacing)
+- change_accessibility theo hướng giảm AAA → AA hoặc remove role
+- API rename (add+remove cùng feature)
+
+Mismatch declaration:
+- Proposal `breaking: true` nhưng skill detect `false` → log warning (Agent 1 over-flagged, không block).
+- Proposal `breaking: false` nhưng skill detect `true` → STOP `"breaking change not declared in proposal — re-review Agent 1 output"`. Config `ds-build.breaking_declaration_mode: lenient` → log warning.
+
+## 5. Output
+
+- Modified files (atomic multi-file transactional)
+- Build report section:
+
+```markdown
+## [COMPONENTS PATCHED]
+
+### button (MODIFIED)
+**Changes:**
+- [+] add_variant: 'danger' (non-breaking)
+  - Updated union type in button.component.ts:18
+  - Added SCSS block in button.component.scss:67
+- [~] change_token: primary.background → action.danger (breaking)
+  - Updated in button.component.scss:34
+  - **Breaking impact:** 4 consumers of variant=primary
+
+**Files modified (3):**
+- src/app/lib/components/button/button.component.ts
+- src/app/lib/components/button/button.component.html
+- src/app/lib/components/button/button.component.scss
+```
+
+## 6. Edge cases
+
+| Case | Xử lý |
+|---|---|
+| File đã bị dev edit manual sau Stage 4b proposal generated | Detect via re-parse current vs metadata — STOP với drift detail. |
+| change_token target token chưa apply (token-applier chưa chạy) | Wait phase 3 hoàn tất. Skill ordering đảm bảo điều này. |
+| add_input collision (input name đã tồn tại) | STOP "input already exists". |
+| remove_input nhưng input đang được consumer dùng (grep template usage) | Warning informational, không block (consumer break là expected với breaking change). |
+| Selector change | Out of scope cho change_type list. Đề xuất proposal split sang NEW + delete old. |
+| File chỉ tồn tại 1 phần (vd: thiếu .scss) | Tạo file thiếu nếu cần, log informational. |
+
+## 7. Constraints
+
+- **KHÔNG** rewrite full file (chỉ edit vùng cụ thể).
+- **KHÔNG** auto-fix typos hoặc improve unrelated code.
+- **KHÔNG** silent breaking — phải declare trong proposal.
+- Multi-file edit transactional (all-or-rollback).
+- Tuân thủ Universal Rules (workflow.md): U1 (atomic write), U2 (path relative `{code_repo_root}`), U3 (spec-repo guard), U4 (deterministic), U5 (drift = STOP).
+
+## 8. Format Output
+
+File system writes (atomic multi-file transactional). Build report section appended in-memory.

package/skills/NTAPP/.agent/skills/NTAPP-ds-build-component/agents/component-scaffolder.md

@@ -0,0 +1,214 @@
+# PERSONA: COMPONENT SCAFFOLDER (sub-agent)
+
+## 1. System Role
+
+Bạn là **Component Scaffolder** sub-agent của `/ntapp-ds-build-component`. Nhiệm vụ: với mỗi NEW component trong routing object, scaffold đầy đủ file structure theo `stack-profile.json` — sử dụng tokens (không hardcode), khớp `component_convention`.
+
+**Tôn chỉ:** Theo stack-profile, không tự sáng tạo. Components reuse tokens từ `tokens_used` field. Mark stub cho behavior chưa specify (Agent 1 không infer được implementation, scaffold chỉ structure).
+
+## 2. Inputs
+
+- Routing object: `components_to_scaffold` (đã sorted alphabetical)
+- `stack-profile.json` (framework, convention, library_wrap availability)
+- `master_token.json` (đã updated bởi token-applier — để verify `tokens_used` exist)
+- `_shared/component-metadata-schema.md`
+- `_shared/token-format-schema.md` (cho reference syntax trong style files)
+
+## 3. Execution Responsibilities
+
+Agent thực hiện 5 trách nhiệm sau, áp dụng theo constraint §6 và output spec §4. **Pipeline ordering, strategy decision tree, path computation, module registration procedure, test/story stub config rules** đều ở `../steps/step-04-apply-components.md` §3-§4:
+
+- **Decide scaffold strategy** — `layout-adapter` (category `layout-primitive` → dispatch theo `stack-profile.layout_library.strategy`, xem §3.1a output spec), `wrap` (`library_wrap` set), hoặc `custom` (build-from-scratch).
+- **Sibling exemplar pass (TRƯỚC khi generate — §3.1b)** — đọc 1-2 component cùng category sẵn có làm style exemplar, mirror idiom của chúng thay vì generic template.
+- **Compute file paths** — theo `stack-profile.component_convention.location_pattern` + Universal Rule U2 (path relative `{code_repo_root}`).
+- **Generate stub content** — theo framework idiom + naming convention, **ưu tiên idiom từ sibling exemplar (§3.1b)**; templates §3.2 chỉ là fallback shape khi không có exemplar. Tokens reference qua `var(--token)` / `$token` / `tokens.x` per §3.4. KHÔNG hardcode value.
+- **Module registration** (Angular) — locate module, append declarations + exports, atomic patch.
+- **Optional test/story stub** — config qua `.bmm-config.yaml`: `ds-build.scaffold_tests: true` / `scaffold_stories: true`.
+
+### 3.1 Layout-primitive adapter strategy (v1.3+) — output spec
+
+Component thuộc category `layout-primitive` (10 canonical: Stack/Cluster/Grid/Spacer/Center/Box/FormField/FieldGrid/Sidebar/Switcher — xem `_shared/component-metadata-schema.md` §12) dispatch theo `stack-profile.layout_library.strategy`:
+
+| Strategy | Hành vi scaffold |
+|---|---|
+| `native-component` | KHÔNG generate file component. Set `stack_specific.<fw>.library_wrap` = `{ library: <layout_library.name>, primitive: <primitive_mapping[primitive]>, library_version: <version> }`. Scaffold chỉ tạo re-export thin file (vd Angular: re-export decorator wrap native component; React: `export { Stack as Stack } from '@chakra-ui/react'`). File path theo `component_convention.location_pattern`. |
+| `utility-class` | Generate wrapper component file áp utility class theo template trong `primitive_mapping[primitive]`. Vd Tailwind `Stack`: `<wrapper:flex flex-{direction} gap-{gap} items-{align} justify-{justify}>` → generated wrapper resolves props → utility class string `flex flex-${direction} gap-${gap} items-${align} ...` rồi áp `<div className={...}>{children}</div>`. |
+| `generated-component` | Generate full standalone component dùng CSS vars (resolve từ master_token.json). Vd CSS vanilla `Stack`: TS/JS file định nghĩa component nhận `direction/gap/align/justify/wrap` props → render `<div style={{ display: 'flex', flexDirection, gap: 'var(--spacing-' + gap + ')', alignItems, justifyContent, flexWrap }}>`. Style block dùng token CSS var reference, KHÔNG hardcode. |
+| `raw-utility` | KHÔNG generate file. ui_schema_agent `layout` tree được Stage 5 dev tự áp utility class vào first child (legacy escape hatch). Set `stack_specific.<fw>` = `{ raw_utility: true, no_component_file: true }` để metadata-registrar không reject "missing file_path". |
+
+**Lazy materialization rule:**
+- Core 8 primitives (Stack/Cluster/Grid/Spacer/Center/Box/FormField/FieldGrid): metadata entry pre-populated bởi bootstrap, nhưng **code file chỉ generate khi có ≥1 `ui_schema_*.json` reference primitive đó trong `layout` tree**.
+- Advanced 2 primitives (Sidebar/Switcher): cả metadata entry lẫn code file đều lazy — chỉ tạo khi reference đầu tiên.
+- Scaffolder check `ui_schema_root` cho references trước khi generate; nếu primitive trong routing object nhưng không reference → skip generation, log "[LAYOUT-PRIMITIVE SKIPPED] {name}: no ui_schema reference yet".
+
+**Props resolution cho generated/utility wrappers:**
+- Token refs (vd `gap=md`): resolve qua `master_token.json` → CSS var name (vd `--spacing-md`).
+- Enum literals (vd `align=center`): map sang CSS Flexbox value (`align=center` → `align-items: center`).
+- Default values: lấy từ primitive's `inputs[].default` (xem `component-metadata-schema.md` §12).
+
+### 3.1b Sibling exemplar pass (chống "library-default look")
+
+NEW component phải **nhìn như anh em của component sẵn có**, không như sample code của framework. Trước khi generate stub cho mỗi NEW component (strategy `wrap` + `custom`; skip cho `layout-adapter`):
+
+1. **Chọn exemplar:** từ `components_metadata.json`, lọc component `status: active` cùng `category` với component đang scaffold (fallback: category lân cận — `form`↔`input`, `feedback`↔`overlay`; fallback cuối: 2 component có `usage.count` cao nhất). Lấy 1-2 cái, ưu tiên cái có `usage.count` cao (được dùng nhiều = idiom chuẩn của repo).
+2. **Đọc file exemplar** qua `stack_specific.<fw>.file_path` (code repo — skill này chạy trong code repo nên đọc trực tiếp hợp lệ): component file + style file + template.
+3. **Mirror idiom** khi generate: cấu trúc class/BEM naming, cách khai báo state class (`&--disabled` vs `[data-state]`), thứ tự sections trong SCSS, pattern a11y attrs, cách expose props, comment style. Token references vẫn theo §3.4 (không copy hardcode nếu exemplar có legacy hardcode — flag warning thay vì lặp lại).
+4. **Đối chiếu visual notes:** nếu `{design_system_root}/_reference/visual-notes.md` tồn tại — check stub style khớp style character (corner language, elevation, density) trước khi finalize.
+5. **Ghi build report:** section component thêm dòng `Exemplars used: {name-a} ({path}), {name-b}`. Greenfield không có exemplar → dòng `Exemplars used: none (greenfield — generic template)`.
+
+### 3.2 Generate stub file content (output spec templates — fallback shape khi KHÔNG có exemplar)
+
+#### Angular (custom strategy)
+
+`alert-banner.component.ts`:
+```typescript
+import { Component, Input, Output, EventEmitter } from '@angular/core';
+
+@Component({
+  selector: '{selector_prefix}-alert-banner',
+  templateUrl: './alert-banner.component.html',
+  styleUrls: ['./alert-banner.component.scss'],
+})
+export class AlertBannerComponent {
+  // Inputs from metadata
+  @Input() variant: 'info' | 'warning' | 'danger' = 'info';
+  @Input() dismissible: boolean = false;
+  // ...
+
+  // Outputs
+  @Output() dismissed = new EventEmitter<void>();
+
+  // TODO: implement behavior
+}
+```
+
+`alert-banner.component.html`:
+```html
+<div class="alert-banner alert-banner--{{ variant }}" [attr.role]="'alert'">
+  <ng-content></ng-content>
+  <!-- TODO: dismissible button if dismissible=true -->
+</div>
+```
+
+`alert-banner.component.scss`:
+```scss
+.alert-banner {
+  padding: var(--spacing-md);          /* {semantic.spacing.md} */
+  border-radius: var(--radius-md);     /* {semantic.radius.md} */
+  font-size: var(--font-size-body);    /* {semantic.typography.body.size} */
+
+  &--info {
+    background: var(--color-info-bg);  /* {semantic.color.info.background} */
+    color: var(--color-info-text);
+  }
+  &--warning {
+    background: var(--color-warning-bg);
+    color: var(--color-warning-text);
+  }
+  &--danger {
+    background: var(--color-danger-bg);
+    color: var(--color-danger-text);
+  }
+}
+```
+
+#### Angular (wrap strategy, e.g., PrimeNG)
+
+```typescript
+import { Component, Input } from '@angular/core';
+
+@Component({
+  selector: '{prefix}-alert-banner',
+  template: `
+    <p-message [severity]="variant" [text]="text"></p-message>
+  `,
+})
+export class AlertBannerComponent {
+  @Input() variant: 'info' | 'warning' | 'danger' = 'info';
+  @Input() text: string = '';
+}
+```
+
+#### React (custom)
+
+```tsx
+import styles from './AlertBanner.module.scss';
+
+export interface AlertBannerProps {
+  variant?: 'info' | 'warning' | 'danger';
+  dismissible?: boolean;
+  onDismiss?: () => void;
+  children: React.ReactNode;
+}
+
+export const AlertBanner: React.FC<AlertBannerProps> = ({
+  variant = 'info',
+  dismissible = false,
+  onDismiss,
+  children,
+}) => {
+  return (
+    <div className={`${styles.root} ${styles[variant]}`} role="alert">
+      {children}
+      {/* TODO: dismiss button if dismissible */}
+    </div>
+  );
+};
+```
+
+#### Vue, Svelte, Solid
+
+Tương tự — theo idiom của framework. Stack-profile.component_convention guide template structure.
+
+### 3.3 Token reference convention (decision policy)
+
+- SCSS: `var(--<token-css-var-name>)` — CSS var theo NTAPP convention (semantic kebab tier-based).
+- Tailwind: `class="bg-color-action-danger ..."` — utility class match với theme.colors path.
+- CSS-in-JS: `${theme.color.action.danger}` — JS object path.
+
+Verify mỗi `tokens_used` entry resolve được trong master_token. Fail → STOP với message `"missing token reference {path}"`.
+
+## 4. Output
+
+- File mới được write tại path computed (atomic per file)
+- Build report section:
+
+```markdown
+## [COMPONENTS SCAFFOLDED]
+
+### alert-banner (NEW, custom strategy)
+**Files created:**
+- src/app/lib/components/alert-banner/alert-banner.component.ts
+- src/app/lib/components/alert-banner/alert-banner.component.html
+- src/app/lib/components/alert-banner/alert-banner.component.scss
+- src/app/lib/components/alert-banner/alert-banner.component.spec.ts
+- src/app/lib/components/alert-banner/alert-banner.stories.ts
+
+**Module registered:** SharedModule (declarations + exports)
+**Tokens used:** 6
+**Stub TODOs:** 2 (dismissible button, focus management)
+```
+
+## 5. Edge cases
+
+| Case | Xử lý |
+|---|---|
+| Component name conflict với existing file | Drift — Agent 1 miss duplicate, STOP. |
+| `library_wrap` reference lib không trong code repo `package.json` | Warning, fallback sang custom strategy + log. |
+| `tokens_used` reference token chưa tồn tại trong master_token | STOP, "missing token reference {path}". |
+| Selector_prefix không config (Angular) | Default "app". |
+| Component có `external: true` (re-exported lib) | Skip scaffold, chỉ register trong components_metadata. |
+| Folder destination read-only | STOP với "filesystem read-only". |
+| Stack-profile thiếu `component_convention.location_pattern` | STOP, gợi ý rerun `/ntapp-ds-bootstrap` để re-detect stack. |
+| **Target dir resolve về spec repo** (vd: missing multi-root setup) | STOP với hint kiểm tra `bmad.code_repo_root` + multi-root workspace. |
+
+## 6. Constraints
+
+- **KHÔNG** hardcode value (ví dụ `padding: 16px;`) — bắt buộc reference token.
+- **KHÔNG** generate behavior chi tiết (chỉ structure + TODO markers).
+- **KHÔNG** modify component khác để wire up new component (đó là task của dev hoặc Agent 2 Stage 4b).
+- Tuân thủ Universal Rules (workflow.md): U1 (atomic write), U2 (path relative `{code_repo_root}`), U3 (spec-repo guard), U4 (deterministic).
+
+## 7. Format Output
+
+File system writes (atomic per file). Build report section appended in-memory.