@educa-corp/sdd-framework 0.1.0

package/core/commands/update-framework.md

@@ -0,0 +1,251 @@
+# /update-framework — Cập nhật SDD Framework Framework
+
+Nâng cấp **framework tooling** (`.agent/commands/`, `steps/`, `modules/`, `hooks/`, `rules/`, `templates/`, `skills/`) lên version mới nhất publish trên npm.
+
+> **Không giống `/sync`.**
+> - `/sync` → pull **nội dung dự án** (code/specs submodule) + làm mới Living Docs. Chạy hằng ngày.
+> - `/update-framework` → nâng cấp **chính các file command của framework**. Chạy thỉnh thoảng, khi có version framework mới.
+
+Lệnh này wrap `npx @educa-corp/sdd-framework@latest --init`. Cần network + npm access.
+
+---
+
+## Step 0 — Phát hiện trạng thái hiện tại
+
+1. Đọc `.agent/FRAMEWORK_VERSION` → version đang cài.
+   - Nếu thiếu → dự án này không được cài qua `--init`. Dừng:
+     ```
+     ❌ .agent/FRAMEWORK_VERSION not found.
+        This project was not set up with the framework installer.
+        Run: npx @educa-corp/sdd-framework --init
+     ```
+
+2. Đọc `.agent/project-context.yaml` → trích `setup.mode` (`umbrella` / vắng = single) và `services`.
+
+3. Liệt kê `.agent/modules/` → ghi tên các module đã cài (phải truyền lại khi nâng cấp để chúng cũng update).
+
+In:
+```
+Current framework : v{current}
+Mode              : {umbrella | single-service}
+Installed modules : {list or "none"}
+```
+
+---
+
+## Step 1 — Kiểm tra version mới nhất
+
+Chạy:
+```bash
+npm view @educa-corp/sdd-framework version
+```
+
+So `current` vs `latest`:
+
+| Kết quả | Hành động |
+|--------|--------|
+| Network/registry không tới được | Cảnh báo `⚠️ Could not reach npm registry — check connection.` và dừng |
+| `current == latest` | In `✅ Already up to date (v{current}). Nothing to do.` và dừng |
+| `latest > current` | In `Update available: v{current} → v{latest}` và tiếp tục |
+
+Hỏi: `Proceed with upgrade? (Y/N)` — chờ `Y`.
+
+---
+
+## Step 2 — Umbrella Awareness *(chỉ umbrella mode)*
+
+Nếu `setup.mode == umbrella`, in note này trước khi nâng cấp:
+
+```
+ℹ️ Umbrella mode — framework tooling lives ONLY at this umbrella root.
+   Service submodules contain just .agent/project-context.yaml (config), not
+   command files — they read commands from the umbrella root. No per-service
+   framework update is needed here.
+
+   Exception: if a teammate opens Claude Code directly INSIDE a service repo
+   (outside the umbrella), that repo has its own .agent/ — its owning team runs
+   /update-framework there independently.
+```
+
+---
+
+## Step 3 — Pre-flight Git Check
+
+Chạy `git status --short .agent/ .claude/commands/`.
+
+Nếu có thay đổi chưa commit trong các path đó:
+```
+⚠️ Uncommitted changes in .agent/ or .claude/commands/.
+   The upgrade overwrites framework files. Commit or stash first so you can
+   cleanly review the upgrade diff:
+     git add .agent/ .claude/commands/ && git commit -m "wip"  (or git stash)
+```
+Hỏi có tiếp tục không `(Y/N)`. Mặc định dừng.
+
+---
+
+## Step 4 — Chạy nâng cấp
+
+Dựng module flag từ Step 0 (một `--module {name}` cho mỗi module đã cài), rồi chạy:
+
+```bash
+npx -y @educa-corp/sdd-framework@latest --init {--module X ...}
+```
+
+Cái này **ghi đè** (làm mới về version mới):
+- `.agent/commands/`, `.agent/steps/`, `.agent/hooks/`, `.agent/rules/`, `.agent/templates/`, `.agent/skills/`, `.agent/modules/{installed}/`
+- `.agent/FRAMEWORK_VERSION`
+- `.claude/commands/` shortcuts
+
+Cái này **KHÔNG đụng tới** (nội dung của bạn an toàn):
+- `.agent/project-context.yaml`
+- `CLAUDE.md`
+- `specs/domain-knowledge/` (business-dictionary, core-entities)
+- `.trace/`
+
+Nếu lệnh npx exit khác 0 → in lỗi và dừng với `❌`.
+
+---
+
+## Step 5 — Review Changes
+
+Chạy:
+```bash
+git diff --stat .agent/ .claude/commands/
+```
+
+Tóm tắt cho người dùng:
+- **New commands** — file `.md` giờ có mà trước không
+- **Updated commands** — file có nội dung thay đổi
+- **Removed commands** — file bị xoá trong version mới
+
+Nếu có command mới xuất hiện (vd một slash command mới), nêu rõ để user biết nó giờ đã có.
+
+---
+
+## Output
+
+# Report Footer — Định dạng output chuẩn cho mọi lệnh
+
+Mọi report của lệnh phải kết thúc bằng section footer chuẩn này.
+
+## Status Badge
+
+Chọn một theo kết quả:
+- `✅ Complete` — mọi bước thành công, không có vấn đề
+- `❌ Failed` — lệnh không hoàn thành được do lỗi chặn
+- `⚠️ Warnings` — hoàn thành nhưng có vấn đề không chặn, nên review lại
+
+## Output Artifacts
+
+Liệt kê mọi file được tạo hoặc sửa bởi lệnh này:
+```
+Output Artifacts:
+  {created|updated} {file-path} ({mô tả ngắn})
+  {created|updated} {file-path} ({mô tả ngắn})
+```
+
+Nếu không ghi file nào (vd: lệnh review hoặc phân tích) → ghi `Output Artifacts: none (read-only)`.
+
+## Pipeline Position
+
+In một sơ đồ pipeline một dòng, đánh dấu phase của lệnh HIỆN TẠI bằng `◀ bạn ở đây`,
+để người dùng luôn thấy lệnh này nằm ở đâu trong luồng end-to-end:
+
+```
+Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+```
+
+Tìm lệnh hiện tại trong bảng phase dưới đây và đánh dấu **phase của nó** trong sơ đồ trên:
+
+| Phase | Commands |
+|-------|----------|
+| Discovery | `/define-product` |
+| PRD | `/generate-prd` · `/refine-prd` · `/review-context` (PRD) |
+| Design Spec | `/generate-design-spec` |
+| BDD | `/generate-bdd` · `/review-context` (BDD) |
+| Tech Design | `/generate-tech-docs` · `/map-testids` · `/review-tech-docs` |
+| Code | `/generate-code` · `/review-code` |
+| Dev Self-Check | `/dev-gen-test` · `/dev-run-test` · `/dev-smoke-test` |
+| QC | `/qc-analyze` · `/qc-plan` · `/qc-design-test` · `/qc-review` · `/qc-run-test` · `/qc-report` |
+| Trace Audit | `/validate-traces` |
+
+Với **lệnh review**, thêm vòng review 3 bước và đánh dấu bước hiện tại, vd:
+`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
+
+**Lệnh xuyên suốt** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
+`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) nằm ngoài pipeline tuyến tính —
+**bỏ hẳn dòng Pipeline** cho các lệnh này (đừng cố nhét chúng vào sơ đồ).
+
+## Gợi ý lệnh tiếp theo
+
+Gợi ý lệnh kế tiếp hợp lý theo phase của workflow:
+
+| Lệnh hiện tại           | Gợi ý lệnh tiếp theo                          |
+|-------------------------|-----------------------------------------------|
+| /setup-ai-first         | `/define-product` để bắt đầu feature đầu tiên |
+| /define-product         | `/generate-prd {product-definition-file}`     |
+| /generate-prd           | `/refine-prd {prd-file}` rồi `/review-context {prd-file}` |
+| /refine-prd             | Mở Review Board → cập nhật PRD → `/review-context {prd-file}` |
+| /review-context (PRD)   | Khi 0 critical → PO đặt `Status: approved`, rồi FE/App: `/generate-design-spec {prd-file}` (→ design sign-off → BDD); BE: `/generate-bdd {prd-file}`. Còn critical/NEEDS_FIX → sửa PRD (giữ draft) |
+| /generate-design-spec   | Designer review → xác nhận link Figma → PO + Designer sign-off → `/generate-bdd {prd-file}` |
+| /generate-bdd           | `/review-context {feature-file}` để kiểm tra độ phủ |
+| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` nếu APPROVED; sinh lại nếu NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (xử lý các gap blocker 🔴 trước) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (review test-case)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` nếu APPROVED; sửa TC nếu NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` rồi `/qc-review {UC-ID}` (review script) |
+| /qc-review (script)     | `/qc-report {UC-ID}` rồi tạo PR nếu APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` để làm mới Living Docs (qc_status) |
+| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
+| /review-tech-docs       | `/generate-code {feature-file}` nếu APPROVED; sửa doc nếu NEEDS_FIX |
+| /generate-code          | Lần gen đầu → `/review-code {UC-ID}`; gen lại → `/dev-gen-test {UC-ID}` |
+| /dev-gen-test         | `/dev-run-test {UC-ID}`                          |
+| /dev-run-test (passing)    | `/review-code {UC-ID}`                        |
+| /dev-run-test (failing)    | `/fix-bug {ticket-id}` hoặc `/debug {error}`    |
+| /review-code            | `/dev-smoke-test {UC-ID}` hoặc tạo PR            |
+| /dev-smoke-test             | Tạo PR và link tới ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; tất cả OK → tạo PR |
+| /fix-bug                | Tạo PR và link tới ticket                  |
+| /debug                  | `/fix-bug {ticket-id}` nếu cần sửa          |
+| /report-bug             | Gửi cho dev (`/fix-bug {BUG-ID}`); nếu thiếu coverage → `/propose-scenario {UC-ID}` |
+| /propose-scenario       | Báo PO/Dev review proposal trong `feedback/bdd-proposals/` |
+| /learn                  | Tiếp tục làm việc — lesson áp dụng ở lệnh kế tiếp |
+| /sync                   | `/validate-traces` để xem độ phủ đầy đủ; xử lý mọi `📥 tester feedback` được nêu |
+| /update-framework       | Review `git diff .agent/`, commit; `/sync` để đồng bộ nội dung dự án |
+
+Định dạng footer như sau:
+```
+---
+Status   : {badge}
+{khối Output Artifacts}
+Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+           (lệnh review) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
+Next     : {lệnh gợi ý kèm ví dụ tham số}
+```
+*(Bỏ dòng `Pipeline` cho các lệnh xuyên suốt liệt kê ở trên.)*
+
+
+```
+/update-framework — v{current} → v{latest}
+
+✅ Framework upgraded
+   Updated : {N} command files, {M} step files
+   New     : {list any new commands, e.g. /some-new-command}
+   Removed : {list any removed commands, or "none"}
+
+Your content was preserved:
+   project-context.yaml, CLAUDE.md, domain-knowledge/, .trace/ — untouched
+
+Review & commit:
+   git diff .agent/
+   git add .agent/ .claude/commands/
+   git commit -m "chore: upgrade spec-driven-docs v{current} → v{latest}"
+   {umbrella mode: this is the umbrella root — service submodules need no framework update}
+
+---
+Status : ✅ Complete | ⚠️ Warnings
+Output Artifacts: refreshed .agent/ framework files, .claude/commands/ shortcuts
+Next   : review git diff, then commit | /sync to refresh project content
+```