# /update-framework — Cập nhật Spec-Driven Docs 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 @edupia-tutor/spec-driven-docs@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 @edupia-tutor/spec-driven-docs --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 @edupia-tutor/spec-driven-docs 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 @edupia-tutor/spec-driven-docs@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
```