# /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

# 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
```