@educa-corp/sdd-framework 0.1.0

package/commands/update-framework.tmpl

@@ -0,0 +1,151 @@
+# /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
+
+{{include:steps/report-footer.md}}
+
+```
+/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
+```