@educa-corp/sdd-framework 0.2.4 → 0.2.6

package/docs/04-reference/commands.md

@@ -0,0 +1,105 @@
+[← Docs Home](../README.md) · [Reference](./)
+
+# Reference · Commands — Bảng đầy đủ (Command Catalog)
+
+> 31 slash command, gom theo phase pipeline. Chi tiết cơ chế từng bước → [Pipeline Steps](../02-concepts/pipeline-steps/).
+
+Mọi lệnh chạy chung một **Gate** (model check → target → context-loader → checkpoint). Xem [Khung chung](../02-concepts/pipeline-steps/README.md#khung-chung-mọi-command-common-gate).
+
+---
+
+## 0 · Setup & Foundation
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/setup-ai-first` | Dự án trống/có code | `.agent/`, `.claude/`, `project-context.yaml`, `CLAUDE.md` | Admin/Lead |
+| `/generate-architecture` | config + tài liệu (`--from`) + code | `architecture.md` (SSOT kiến trúc, theo tier) | SA/Lead |
+
+## 1 · Discovery
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/define-product` | Ý tưởng (+Figma) | `product-definition/*.md` (8 chặng) | PO |
+
+## 2 · Specification (PRD)
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/generate-prd` | product-definition | PRD draft | PO |
+| `/refine-prd` | PRD | Findings 3 lăng kính DEV/SA/PO | PO+SA+Dev |
+| `/review-context` (PRD) | PRD | Findings P0–P5 → `Status: approved` | PO |
+
+## 3 · Design-Spec (chỉ FE/App)
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/generate-design-spec` | PRD approved + Figma | `design-spec/*.md` | PO/PM |
+
+## 4 · BDD
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/generate-bdd` | PRD approved (+design-spec) | `bdd/**/*.feature` | PO |
+| `/review-context` (BDD) | `.feature` | Findings B1–B6 → `@trace.status: approved` | PO/Dev |
+
+## 5 · Tech-Docs
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/generate-tech-docs` | BDD approved + entity catalog | `tech-docs/{TICKET}-tech-design.md` | SA |
+| `/review-tech-docs` | tech-design | Findings đa chiều + ký T7 | SA/Lead |
+
+## 6 · Code
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/generate-code` | `.feature` approved + tech-design | Code + `.trace/*.tsv` | Dev |
+| `/review-code` | Code | Findings (read-only) | Dev/Lead |
+| `/fix-bug` | Bug report | Fix + regression test | Dev |
+| `/map-testids` | UI code | testid map (FE) | Dev |
+| `/debug` | Mô tả lỗi | Phân tích (read-only) | Dev |
+
+## 7 · Dev self-test
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/dev-gen-test` | Code + `.feature` | Bộ self-test | Dev |
+| `/dev-run-test` | Self-test | Kết quả + cột `dev_selftest` | Dev |
+| `/dev-smoke-test` | Service/app đang chạy | Kết quả smoke tại chỗ | Dev |
+
+## 8 · QC Automation
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/qc-analyze` | UC + spec | `REQUIREMENT_ANALYSIS.md`, `DOC_GAPS.md` | QA |
+| `/qc-plan` | Analysis | `TEST_PLAN.md` (rủi ro) | QA |
+| `/qc-design-test` | Plan | `test-cases/*.Test.md` | QA |
+| `/qc-review` | Test case/script | 🛑 Cổng review | QA |
+| `/qc-run-test` | `.Test.md` reviewed | Script Playwright + `qc_status` | QA |
+| `/qc-report` | Kết quả run | Report + evidence + product-gap | QA |
+
+## 9 · Quality & Trace
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/validate-traces` | `.trace/*.tsv` + spec/code/test | Ma trận coverage (read-only) | Dev/QA/Lead |
+| `/generate-spec-manifest` | Specs | Mục lục spec cho agent ngoài | SA/Lead |
+
+## 10 · Feedback & Ops
+
+| Lệnh | Input | Output | Owner |
+|------|-------|--------|-------|
+| `/report-bug` | Lỗi phát hiện | `feedback/bug-reports/` (spec-anchored) | Tester/QC |
+| `/propose-scenario` | Scenario thiếu | `feedback/bdd-proposals/` | Tester/QC |
+| `/learn` | Định hướng lặp lại | `project-lessons.md` | Tất cả |
+| `/sync` | (umbrella) | Pull + submodule + nổi feedback + Living Docs | Lead |
+| `/update-framework` | — | Sync bản npm mới | Lead |
+
+---
+
+## Ký hiệu trạng thái trong report
+
+- 🛑 checkpoint (dừng, chờ `Y`) · 🔒 gate trạng thái (chặn downstream) · ⚪ read-only
+- ⚠️ cảnh báo mềm (không chặn) · ✅ pass · ❌ fail
+
+→ [Trace Schema](trace-schema.md) · [Modules](modules.md) · [Configuration](configuration.md) · [Model Selection](model-selection.md)

package/docs/04-reference/configuration.md

@@ -0,0 +1,94 @@
+[← Reference](./) · [Concepts › Architecture](../02-concepts/architecture.md)
+
+# Reference · Configuration
+
+> Hai file cấu hình chính. `/update-framework` **không** đụng chúng — đây là nội dung của bạn.
+
+---
+
+## 1. `project-context.yaml`
+
+**Single source of truth** cho paths/mode/routing. Nằm ở `.agent/project-context.yaml`, sinh từ `templates/project-context.yaml` qua token substitution khi init. Mọi workflow đọc file này để biết **WHERE** tìm mọi thứ.
+
+### Cấu trúc chính
+
+```yaml
+project:
+  name: "..."
+  description: "..."
+
+paths:
+  specs_dir: "specs"                 # gốc mọi spec artifact
+  trace_dir: ".trace"                # trace state .tsv
+  qc_dir: "docs"                     # working docs của QC
+  qc_skills_dir: ".agent/skills/qc"  # nơi qc-* nạp skill (override sang repo QC riêng)
+  refinement_dir: ".agent/review"    # findings review
+
+setup:
+  mode: single | umbrella
+  spec_source: "..."                 # (umbrella) spec repo dùng chung
+
+services:                            # (multi/umbrella) map domain → service
+  # dạng phẳng: {domain}: { path, module }
+  # dạng map-theo-platform: {domain}: { web: {path,module}, app: {...}, system: {...} }
+
+conventions:
+  build_command: "..."               # lệnh build verify (≤3 retry)
+  test_command: "..."
+
+tech_stack:
+  database: "..."                    # vd PostgreSQL
+```
+
+### Bố cục feature-package (path resolution)
+
+Mọi artifact của một feature nằm chung `specs/{domain}/{prd-slug}/`:
+
+```
+specs/{domain}/{prd-slug}/
+├── {TICKET-ID}-{prd-slug}.md          # PRD (file .md duy nhất ở gốc)
+├── bdd/{web|app|system}/*.feature     # BDD
+├── tech-docs/{TICKET-ID}-tech-design.md
+└── design-spec/{TICKET-ID}*.md        # FE/App
+.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv
+```
+
+- `{domain}` = segment đầu sau `specs_dir`.
+- `{prd-slug}` = segment kế tiếp (folder feature-package) — **không** phải folder cha trực tiếp của file lồng sâu.
+
+---
+
+## 2. `CLAUDE.md` (phân tầng)
+
+Instruction cho AI agent — AI *follow* file này thay vì *invent*.
+
+| Tầng | Nội dung |
+|------|----------|
+| **root** `CLAUDE.md` | Luật chung dự án/umbrella |
+| **overlay** `{service}/CLAUDE.md` | §2 kiến trúc & thứ tự layer & package strategy · §3 coding standards · §5 error handling — **theo stack** |
+
+> Service overlay **thắng** root khi mâu thuẫn. context-loader nạp cả hai, đặt ở **cuối** context (Lost-in-the-Middle: "follow style này").
+
+---
+
+## 3. Single vs Umbrella
+
+| | Single | Umbrella |
+|---|--------|----------|
+| `setup.mode` | `single` | `umbrella` |
+| Spec ở đâu | Cùng repo | **Spec repo dùng chung** (`spec_source`) |
+| Code ở đâu | Cùng repo | Service submodule (chỉ code + tooling) |
+| Trace/feedback/findings | Cùng repo | Trong spec repo (một nơi authoritative) |
+| Đồng bộ | — | `/sync` (pull + submodule + nổi feedback + Living Docs) |
+
+Khi `spec_source` được đặt, **mọi** PRD/BDD/tech-doc/design-spec/`.trace`/`.agent/review`/`feedback` route về spec repo — vì đều là **artifact liên team**.
+
+---
+
+## Không bị ghi đè khi update
+
+`/update-framework` ghi đè `.agent/commands|steps|hooks|rules|templates|skills|modules` nhưng **giữ nguyên**: `CLAUDE.md`, `project-context.yaml`, `domain-knowledge/`, `.trace/`.
+
+---
+
+→ [Architecture › Configuration](../02-concepts/architecture.md#configuration-2-file) · [Modules](modules.md)

package/docs/04-reference/model-selection.md

@@ -0,0 +1,68 @@
+[← Reference](./) · [Concepts › Roles & HITL](../02-concepts/roles-and-hitl.md)
+
+# Reference · Model Selection
+
+> Framework **không ràng buộc model cứng** — chỉ khuyến nghị qua **model check mềm** ở Gate. Giả định LLM đủ năng lực reasoning.
+
+---
+
+## Model check (Gate Bước 0-B)
+
+Các lệnh sinh nội dung & review phức tạp đòi hỏi suy luận mạnh. Ở Gate, framework hiển thị:
+
+```
+⚙️  MODEL CHECK
+  Recommended : claude-opus (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.
+
+  Đang chạy claude-opus?
+    Y — đúng → tiếp tục
+    S — bỏ qua (chấp nhận rủi ro chất lượng thấp hơn)
+    N — dừng, đổi model rồi chạy lại
+```
+
+| Trả lời | Kết quả |
+|---------|---------|
+| **Y** | Tiếp tục |
+| **S** | Tiếp tục, thêm ⚠️ vào report cuối (người dùng chấp nhận rủi ro) |
+| **N** / khác | **Dừng** — đổi sang Opus rồi chạy lại |
+
+> Sub-agent (`_agent_mode`) **bỏ qua** model check — orchestrator đã kiểm tra rồi.
+
+---
+
+## Tại sao khuyến nghị Opus
+
+Rủi ro khi dùng model nhỏ hơn cho các lệnh nặng:
+- Bỏ sót edge case khi phân tích spec.
+- Phân tích spec thiếu sót → findings không đầy đủ.
+- Vi phạm kiến trúc khi sinh code.
+
+Các lệnh **read-only cơ học** (áp findings, resume) có thể bỏ qua model check vì không cần suy luận sâu.
+
+---
+
+## Đổi model trong Claude Code
+
+- Settings → Model → chọn "claude-opus", **hoặc**
+- `/model` → chọn `claude-opus`
+
+---
+
+## Model IDs (tham khảo)
+
+Model Claude mới nhất tại thời điểm viết:
+
+| Model | ID |
+|-------|-----|
+| Opus 4.8 | `claude-opus-4-8` |
+| Sonnet 5 | `claude-sonnet-5` |
+| Haiku 4.5 | `claude-haiku-4-5-20251001` |
+| Fable 5 | `claude-fable-5` |
+
+> Dùng model mạnh nhất (Opus) cho các bước generate/review; các bước cơ học có thể dùng model nhẹ hơn.
+
+---
+
+→ [Roles & HITL](../02-concepts/roles-and-hitl.md) · [Commands](commands.md)

package/docs/04-reference/modules.md

@@ -0,0 +1,74 @@
+[← Reference](./) · [Concepts › Architecture](../02-concepts/architecture.md)
+
+# Reference · Modules — Stack overlay
+
+> Module = overlay tuỳ chọn mở rộng base. Skill **đọc `stack-profile.yaml`** thay vì hardcode → đổi stack chỉ cần thêm module.
+
+---
+
+## Module có sẵn (15)
+
+### Tech stack — Backend
+
+| Module | Stack |
+|--------|-------|
+| `java-spring` | Java + Spring Boot |
+| `dotnet` | .NET / C# |
+| `golang` | Go |
+| `php-laravel` | PHP + Laravel |
+
+### Tech stack — Frontend / Mobile
+
+| Module | Stack |
+|--------|-------|
+| `react` | React |
+| `vue` | Vue |
+| `angular` | Angular |
+| `nextjs` | Next.js |
+| `nuxt` | Nuxt |
+| `react-native` | React Native |
+| `flutter` | Flutter |
+| `android-compose` | Android (Jetpack Compose) |
+| `ios-swiftui` | iOS (SwiftUI) |
+
+### Capability
+
+| Module | Vai trò |
+|--------|---------|
+| `qc-playwright` | QC automation — Python + pytest-playwright + Page Object |
+| `context-engineering` | Hỗ trợ context-loader |
+
+---
+
+## Stack profile contract
+
+Mỗi stack module khai báo qua `stack-profile.yaml`:
+
+| Khoá | Ý nghĩa |
+|------|---------|
+| `artifact_types[]` | Loại artifact stack này sinh |
+| `generation_layers[]` | Thứ tự layer + dependency (vd Controller → Service → Repository) |
+| `build_verify` | Lệnh build để verify (≤3 retry) |
+| `test_types{}` | Các loại test hỗ trợ |
+
+Cộng `module.yaml` khai báo metadata module.
+
+---
+
+## Cài & dùng
+
+```bash
+# Khi init
+npx @educa-corp/sdd-framework --init --module java-spring
+# Multi-service
+npx @educa-corp/sdd-framework --init \
+  --services backend:java-spring,web:react,app:flutter
+```
+
+Module nằm ở `.agent/modules/{name}/`. QC skill có thể trỏ ra repo riêng của team QC qua `paths.qc_skills_dir` để không bị ghi đè khi `/update-framework`.
+
+> Ghi chú: bản hiện tại **không** có module jira/figma/locale tích hợp tự động; framework mặc định **ngôn ngữ Việt**; tham chiếu Jira chỉ là field Ticket trong Metadata PRD.
+
+---
+
+→ [Architecture › Module System](../02-concepts/architecture.md#module-system) · [Configuration](configuration.md)

package/docs/04-reference/trace-schema.md

@@ -0,0 +1,93 @@
+[← Reference](./) · [Concepts › Traceability](../02-concepts/traceability.md)
+
+# Reference · Trace Schema
+
+> Field metadata `@trace.*` và cột file `.tsv`. Giải thích khái niệm → [Traceability](../02-concepts/traceability.md).
+
+---
+
+## Trace tags theo artifact
+
+### BDD scenario (`.feature`)
+
+| Tag | Ý nghĩa |
+|-----|---------|
+| `@trace.id` | UC-ID (vd `UC-02`) |
+| `@trace.scenario` | SC-ID (vd `SC-02.1`) |
+| `@trace.business_rules` | BR liên quan (vd `BR-03`) |
+| `@trace.bdd_version` | Version của `.feature` (phát hiện drift) |
+| `@trace.prd_version` | Version PRD nguồn |
+| `@trace.status` | `draft` / `in-review` / `approved` (gate) |
+| `@trace.platform` | `web` / `app` / `system` |
+| `@trace.domain` | Domain nghiệp vụ |
+
+### Code (boundary only)
+
+| Tag | Ý nghĩa |
+|-----|---------|
+| `@trace.implements` | SC mà method này hiện thực |
+| `@trace.source` | `.feature` nguồn |
+
+> **KHÔNG** lưu version trong code — tránh dual SSOT. Version dò qua `.tsv`.
+
+### Test
+
+| Tag | Ý nghĩa |
+|-----|---------|
+| `@trace.verifies` | SC mà test kiểm chứng (vd `UC-02-SC1`) |
+| `@trace.covers` | Phạm vi phủ |
+
+### Bug fix
+
+| Tag | Ý nghĩa |
+|-----|---------|
+| `@trace.fixes` | Bug/ticket được sửa |
+| `@trace.root_cause` | Nguyên nhân gốc |
+| `@trace.regression` | Test regression thêm vào |
+
+---
+
+## Boundary-only tagging
+
+| ✅ Tag | ❌ Không tag |
+|--------|-------------|
+| Controller · Handler · Middleware · Steps file | Entity · Repository · DTO · Interface · Base class |
+
+Shared code dò qua **import chain** từ boundary → tránh tag explosion.
+
+---
+
+## Trace state — `.tsv`
+
+Đường dẫn: `.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv` (mỗi UC × platform một sổ; trong umbrella nằm ở spec repo).
+
+| Cột | Chủ sở hữu | Ý nghĩa |
+|-----|-----------|---------|
+| `status` | `/generate-code`, `/validate-traces` | OK / GAP / DRIFT / UNTRACKED |
+| `implemented_by` | `/generate-code` | File code hiện thực SC (`—` nếu chưa) |
+| `spec_ver` | spec | Version spec hiện tại |
+| `gen_ver` | `/generate-code` | Version lúc sinh code (`—` nếu chưa) |
+| `test_count` | test | Số test phủ SC |
+| `dev_selftest` | `/dev-run-test` | Smoke của dev (pass/fail/`—`) |
+| `qc_status` | `/qc-run-test`, `/report-bug` | QC chính thức (pass/fail/gap) |
+| `bdd_version` | spec | Version BDD |
+| `last_updated` | nhiều | Mốc cập nhật |
+
+---
+
+## Phân loại coverage (thứ tự ưu tiên)
+
+| # | Trạng thái | Điều kiện |
+|---|-----------|-----------|
+| 1 | **UNTRACKED** | `gen_ver == —` |
+| 2 | **DRIFT** | `implemented_by != —` AND `spec_ver != gen_ver` |
+| 3 | **GAP** | `implemented_by != —` AND (`test_count == —` OR `0`) |
+| 4 | **OK** | `spec_ver == gen_ver` AND `implemented_by != —` AND `test_count > 0` |
+
+`code_coverage = (rows where implemented_by != —) / total_scs`
+
+> DRIFT xét **trước** GAP: code lỗi thời + chưa test + spec drift phải hiện DRIFT (regen) không phải GAP (skip).
+
+---
+
+→ [Traceability](../02-concepts/traceability.md) · [Validate Traces](../02-concepts/pipeline-steps/09-validate-traces.md)

package/docs/README.md

@@ -1,53 +1,42 @@
-# 📚 SDD Framework — Documentation
+# 📚 SDD Framework — Tài liệu (Documentation)
 
-> SDD Framework for Claude Code: Discovery → PRD → Design-Spec → BDD →
-> Code → Dev self-check → QC automation, with traceability and human review gates.
+> **SDD Framework** cho Claude Code — đường ray một chiều đưa đội ngũ đi từ
+> **ý tưởng → PRD → Design-Spec → BDD → Tech-Docs → Code → Dev self-test → QC**,
+> với **gate review của con người** ở mỗi khúc cua và **truy vết (traceability)** đầu-cuối.
 
-Tài liệu được chia theo **vai trò** và **chủ đề**. Bắt đầu ở mục phù hợp với bạn:
+Tài liệu chia theo **mục tiêu người đọc**. Bắt đầu ở đúng mục dành cho bạn:
 
-| Bạn là… | Bắt đầu ở |
-|---------|-----------|
-| Người mới / cài đặt lần đầu | [01 · Getting Started](01-getting-started/) |
-| Product Owner | [Guide · Product Owner](02-guides/product-owner/README.md) |
-| Developer | [Guide · Developer](02-guides/developer/README.md) |
-| QC / Tester (QA) | [Guide · Tester / QA](02-guides/tester/README.md) — gồm cả pipeline QC tự động (`/qc-*`) |
-| Muốn hiểu kiến trúc | [03 · Concepts](03-concepts/) |
-| Vận hành / admin | [04 · Operations](04-operations/) |
-| Tra cứu lệnh | [05 · Reference](05-reference/) |
-| Muốn hiểu một lệnh chạy sao (dễ hiểu) | [06 · Commands (Dễ Hiểu)](06-commands/) |
+| Bạn muốn… | Đọc ở |
+|-----------|-------|
+| Cài đặt & chạy feature đầu tiên | [01 · Getting Started](01-getting-started/) |
+| Hiểu framework: mô hình toàn trình + từng bước | [02 · Concepts](02-concepts/) |
+| Biết **vai trò của tôi** làm gì ở mỗi bước | [03 · Guides theo vai trò](03-guides/) |
+| Tra cứu lệnh, schema, module, config | [04 · Reference](04-reference/) |
 
 ---
 
-## Mục lục
+## Mục lục (Table of Contents)
 
-### 01 · [Getting Started](01-getting-started/)
-- [Installation](01-getting-started/installation.md) — cài framework, prerequisites
-- [Quick Start](01-getting-started/quickstart.md) — chạy feature đầu tiên end-to-end
-- [Core Concepts](01-getting-started/core-concepts.md) — khái niệm trong 5 phút
+### 01 · [Getting Started](01-getting-started/) — *Cài & chạy được*
+- [What is SDD](01-getting-started/what-is-sdd.md) — framework là gì, giải quyết vấn đề gì
+- [Installation](01-getting-started/installation.md) — cài đặt, `npx --init`, chọn module
+- [Quick Start](01-getting-started/quickstart.md) — feature đầu tiên end-to-end
 
-### 02 · [Guides (theo vai trò)](02-guides/)
-- [Product Owner](02-guides/product-owner/README.md) — define-product, PRD, design-spec, review
-- [Developer](02-guides/developer/README.md) — BDD, tech-docs, code, dev self-check
-- [Tester / QA](02-guides/tester/README.md) — spec-manifest, report-bug, propose-scenario, Living Docs, và **chương [QC Automation](02-guides/tester/qc-automation.md)** (pipeline `/qc-*`, `qc_status`)
+### 02 · [Concepts](02-concepts/) — *Hiểu framework*
+- [Overview](02-concepts/overview.md) — mô hình toàn trình + triết lý
+- [Glossary](02-concepts/glossary.md) — thuật ngữ (PRD, BDD, UC, trace, drift, gate, HITL…)
+- [Roles & HITL](02-concepts/roles-and-hitl.md) — ma trận vai trò × pipeline, mật độ checkpoint
+- [Traceability](02-concepts/traceability.md) — trace tags, `.tsv`, drift, `dev_selftest` vs `qc_status`
+- [Architecture](02-concepts/architecture.md) — 3 lớp, context-loader, module
+- ⭐ [**Pipeline Steps**](02-concepts/pipeline-steps/) — **chi tiết từng bước**: input · output · ai làm gì · câu hỏi · cách xử lý
 
-### 03 · [Concepts](03-concepts/)
-- [Architecture](03-concepts/architecture.md) — layers, modules, plug-in system
-- [Pipeline](03-concepts/pipeline.md) — các phase Discovery → QC
-- [Traceability & Living Docs](03-concepts/traceability.md) — trace TSV, dev_selftest vs qc_status
+### 03 · [Guides theo vai trò](03-guides/) — *Tôi làm gì ở mỗi bước*
+- [Product Owner](03-guides/product-owner.md) · [Developer](03-guides/developer.md) · [Architect / SA](03-guides/architect.md) · [Tester / QA](03-guides/tester-qa.md)
 
-### 04 · [Operations](04-operations/)
-- [Sync & Update](04-operations/sync-and-update.md) — `/sync`, `/update-framework`, umbrella
-- [Bug Flow](04-operations/bug-flow.md) — report → fix → verify
-- [Publishing](04-operations/publishing.md) — build + npm publish
-
-### 05 · [Reference](05-reference/)
-- [Commands](05-reference/commands.md) — bảng đầy đủ mọi slash command
-- [Trace Schema](05-reference/trace-schema.md) — cột TSV, trace tags
-- [Modules](05-reference/modules.md) — stack modules (java-spring, react, …, qc-playwright)
-
-### 06 · [Commands (Dễ Hiểu)](06-commands/)
-- Giải thích luồng chạy của **cả 30 slash command** bằng ví von đời thường — mỗi trang một `explain-{command}.md`, gom theo phase pipeline. Xem [mục lục 06](06-commands/README.md).
+### 04 · [Reference](04-reference/) — *Tra cứu*
+- [Commands](04-reference/commands.md) — bảng đầy đủ mọi slash command
+- [Trace Schema](04-reference/trace-schema.md) · [Modules](04-reference/modules.md) · [Configuration](04-reference/configuration.md) · [Model Selection](04-reference/model-selection.md)
 
 ---
 
-*Mỗi file có breadcrumb điều hướng ở đầu. Phiên bản framework mới nhất: xem trên [npm](https://www.npmjs.com/package/@educa-corp/sdd-framework).*
+*Phiên bản framework mới nhất: xem trên [npm](https://www.npmjs.com/package/@educa-corp/sdd-framework) — `npm view @educa-corp/sdd-framework version`.*

package/docs/explain/00-setup-ai-first.md

@@ -0,0 +1,77 @@
+[← Explain Home](README.md) · [Next: /generate-architecture →](00b-generate-architecture.md)
+
+# 00 · `/setup-ai-first` — Khởi tạo framework trong dự án
+
+> **Một câu.** Dựng khung thư mục + config + `CLAUDE.md` + domain-knowledge cho một dự án, thích ứng theo **3 loại dự án** (single / umbrella / PO-spec).
+
+---
+
+## Vấn đề giải quyết
+
+Mọi command sau đều đọc `project-context.yaml` + `CLAUDE.md` + `domain-knowledge/` để biết **đọc/ghi ở đâu, viết theo convention nào**. Không có bước setup → mọi lệnh halt ở gate "required context missing". Đây là bước dựng nền một-lần.
+
+---
+
+## Vị trí & tiền đề
+
+- **Vị trí:** tiền pipeline (trước cả Discovery).
+- **Đặc biệt:** lệnh này **bỏ qua Gate Step 1/2/3** (chưa có file input, chưa có project context) — chỉ chạy Step 0-B (model check). Project root = thư mục hiện tại.
+- **Tiền đề:** một repo git (trống hoặc có code) + Node.js.
+
+---
+
+## Input / Output
+
+**Input:** trả lời Q&A (loại dự án, service/stack, spec submodule path…).
+
+**Output** (tuỳ `project_type`):
+
+| project_type | Tạo gì |
+|--------------|--------|
+| **1 · Single** | `specs/{product-definition,domain-knowledge}/`, `.trace/`, `.agent/review/`, `CLAUDE.md` (đủ §1–§7), `project-context.yaml`, `business-dictionary.md`, `core-entities.md` |
+| **2 · Umbrella** | Chỉ `.trace/` + `.agent/review/` ở umbrella root; `project-context.yaml` mode umbrella với `services` + `spec_source`; **không** tạo `CLAUDE.md` root (không có một stack đơn) |
+| **3 · PO Spec repo** | `specs/{product-definition,domain-knowledge}/`, `feedback/`, `.agent/review/`, `CLAUDE.md` tối thiểu (§1+§7) |
+
+---
+
+## Các bước xử lý (chi tiết)
+
+1. **Precondition check** — nếu đã có `CLAUDE.md` + `project-context.yaml` → hỏi regenerate? (an toàn chạy lại; mỗi bước đề nghị merge/skip).
+2. **Step 0.5 · Loại dự án** — hỏi single / umbrella / PO-spec → lưu `project_type`.
+   - Umbrella hỏi thêm: path spec submodule; một domain trải nhiều platform không? → **FORM A** (`domain:module`) hay **FORM B** (`domain:platform:module`, platform ∈ system/web/app).
+3. **Step 1 · Cấu trúc thư mục** — tạo base dir theo `project_type` (bảng trên). Folder feature-package `specs/{domain}/{prd-slug}/` **không** tạo trước — lệnh generate tự tạo on demand.
+4. **Step 2 · CLAUDE.md** — tạo từ template 7 section (§1 Overview, §2 Architecture, §3 Coding Standards, §4 Traceability, §5 Error Handling, §6 Build&Test, §7 Git). Umbrella bỏ qua; PO-spec chỉ §1+§7.
+5. **Step 3 · project-context.yaml** — copy từ `templates/project-context.yaml`, điền `{{PLACEHOLDER}}`. Umbrella: verify/sửa `services` (path phải khớp tên submodule thật — generator để placeholder `TODO-…`).
+6. **Step 4 · business-dictionary.md** — Canonical Terms / Banned Terms / Enum Registry. *(Umbrella skip — sống trong spec submodule.)*
+7. **Step 5 · core-entities.md** — entity catalog máy-đọc-được (field, invariant, relationship). *(Umbrella skip.)*
+8. **Step 6 · VS Code extension** — khuyến nghị cài "Spec Driven Docs Tools" (Review Board + Living Docs UI).
+9. **Step 7 · Verify** — checklist theo `project_type` (file/folder tồn tại; umbrella check submodule init).
+
+---
+
+## Checkpoint & Gate
+
+- Chỉ có model check (Step 0-B) + xác nhận regenerate nếu đã setup.
+- **Không** gate chặn — nhưng nhắc mạnh: sau setup phải **điền tay** `CLAUDE.md` + `project-context.yaml` + `domain-knowledge/` (AI *follow*, trống thì *đoán*).
+
+---
+
+## Cơ chế đặc biệt
+
+- **3 project types** rẽ nhánh sâu — đặc biệt umbrella FORM A vs FORM B định hình cách `services` được khai báo và routing về sau.
+- **On-demand feature folders** — không scaffold trước `specs/{domain}/{prd-slug}/`, giảm rác.
+- **Umbrella tách spec/code** — spec sống ở `spec_source`; service submodule chỉ code + `.trace/`.
+
+---
+
+## 👓 Góc nhìn tối ưu
+
+- **Điểm ma sát #1: điền tay sau setup.** `CLAUDE.md` + `core-entities.md` để trống là nguyên nhân gốc của "AI sinh sai convention/field". Có thể tối ưu bằng scaffold thông minh hơn (đọc `pom.xml`/`package.json` suy §1, §6) — hiện `/sync` đã làm phần này cho umbrella, single-service thì chưa.
+- **Umbrella `services.path` placeholder `TODO-…`** dễ bị quên sửa → routing hỏng. Đáng thêm một validate cứng.
+- **Trùng lặp checklist verify theo 3 project_type** — nếu thêm project_type mới phải sửa nhiều chỗ.
+
+---
+
+## Kết nối
+
+**Trước:** — (đầu tiên) · **Sau:** [`/define-product`](01-define-product.md) để bắt đầu feature đầu tiên.