@edupia-tutor/spec-driven-docs 0.14.0

package/core/commands/update-framework.md

@@ -0,0 +1,251 @@
+# /update-framework — Update the Spec-Driven Docs Framework
+
+Upgrades the **framework tooling** (`.agent/commands/`, `steps/`, `modules/`, `hooks/`, `rules/`, `templates/`, `skills/`) to the latest published version from npm.
+
+> **Not the same as `/sync`.**
+> - `/sync` → pulls **project content** (submodule code/specs) + refreshes Living Docs. Run daily.
+> - `/update-framework` → upgrades the **framework command files themselves**. Run occasionally, when a new framework version ships.
+
+This command wraps `npx @edupia-tutor/spec-driven-docs@latest --init`. It requires network + npm access.
+
+---
+
+## Step 0 — Detect Current State
+
+1. Read `.agent/FRAMEWORK_VERSION` → current installed version.
+   - If missing → this project was not installed via `--init`. Stop:
+     ```
+     ❌ .agent/FRAMEWORK_VERSION not found.
+        This project was not set up with the framework installer.
+        Run: npx @edupia-tutor/spec-driven-docs --init
+     ```
+
+2. Read `.agent/project-context.yaml` → extract `setup.mode` (`umbrella` / absent = single) and `services`.
+
+3. List `.agent/modules/` → record installed module names (these must be re-passed on upgrade so they update too).
+
+Print:
+```
+Current framework : v{current}
+Mode              : {umbrella | single-service}
+Installed modules : {list or "none"}
+```
+
+---
+
+## Step 1 — Check Latest Version
+
+Run:
+```bash
+npm view @edupia-tutor/spec-driven-docs version
+```
+
+Compare `current` vs `latest`:
+
+| Result | Action |
+|--------|--------|
+| Network/registry unreachable | Warn `⚠️ Could not reach npm registry — check connection.` and stop |
+| `current == latest` | Print `✅ Already up to date (v{current}). Nothing to do.` and stop |
+| `latest > current` | Print `Update available: v{current} → v{latest}` and continue |
+
+Ask: `Proceed with upgrade? (Y/N)` — wait for `Y`.
+
+---
+
+## Step 2 — Umbrella Awareness *(umbrella mode only)*
+
+If `setup.mode == umbrella`, print this note before upgrading:
+
+```
+ℹ️ 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
+
+Run `git status --short .agent/ .claude/commands/`.
+
+If there are uncommitted changes in those paths:
+```
+⚠️ 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)
+```
+Ask whether to continue anyway `(Y/N)`. Default to stopping.
+
+---
+
+## Step 4 — Run the Upgrade
+
+Build the module flags from Step 0 (one `--module {name}` per installed module), then run:
+
+```bash
+npx -y @edupia-tutor/spec-driven-docs@latest --init {--module X ...}
+```
+
+This **overwrites** (refreshes to the new version):
+- `.agent/commands/`, `.agent/steps/`, `.agent/hooks/`, `.agent/rules/`, `.agent/templates/`, `.agent/skills/`, `.agent/modules/{installed}/`
+- `.agent/FRAMEWORK_VERSION`
+- `.claude/commands/` shortcuts
+
+This **does NOT touch** (your content is safe):
+- `.agent/project-context.yaml`
+- `CLAUDE.md`
+- `specs/domain-knowledge/` (business-dictionary, core-entities)
+- `.trace/`
+
+If the npx command exits non-zero → print the error and stop with `❌`.
+
+---
+
+## Step 5 — Review Changes
+
+Run:
+```bash
+git diff --stat .agent/ .claude/commands/
+```
+
+Summarize for the user:
+- **New commands** — `.md` files present now but not before
+- **Updated commands** — files with changed content
+- **Removed commands** — files deleted in the new version
+
+If a new command appeared (e.g. a new slash command), call it out explicitly so the user knows it is now available.
+
+---
+
+## Output
+
+# Report Footer — Standard Command Output Format
+
+Every command report must end with this standard footer section.
+
+## Status Badge
+
+Choose one based on outcome:
+- `✅ Complete` — all steps succeeded, no issues found
+- `❌ Failed` — command could not complete due to a blocking error
+- `⚠️ Warnings` — completed with non-blocking issues that should be reviewed
+
+## Output Artifacts
+
+List every file created or modified by this command:
+```
+Output Artifacts:
+  {created|updated} {file-path} ({brief description})
+  {created|updated} {file-path} ({brief description})
+```
+
+If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
+
+## Pipeline Position
+
+Print a one-line map of the pipeline with the CURRENT command's phase marked `◀ bạn ở đây`,
+so the user always sees where this command sits in the end-to-end flow:
+
+```
+Discovery → PRD → [Design Spec] → BDD → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+```
+
+Find the current command in this phase legend and mark **its** phase in the map above:
+
+| 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` |
+
+For a **review command**, also append the 3-step review loop with the current step marked, e.g.:
+`Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume`.
+
+**Cross-cutting commands** (`/sync`, `/update-framework`, `/fix-bug`, `/debug`, `/learn`,
+`/report-bug`, `/propose-scenario`, `/generate-spec-manifest`) sit outside the linear pipeline —
+**omit the Pipeline line entirely** for these (do not force-fit them onto the map).
+
+## Next Command Suggestion
+
+Suggest the logical next command based on workflow phase:
+
+| Current command         | Suggest next                                  |
+|-------------------------|-----------------------------------------------|
+| /setup-ai-first         | `/define-product` to start your first feature |
+| /define-product         | `/generate-prd {product-definition-file}`     |
+| /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
+| /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
+| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
+| /generate-bdd           | `/review-context {feature-file}` to verify coverage |
+| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /qc-analyze             | `/qc-plan {UC-ID}` (resolve 🔴 blocker gaps first) |
+| /qc-plan                | `/qc-design-test {UC-ID}`                     |
+| /qc-design-test         | `/qc-review {UC-ID}` (test-case review)       |
+| /qc-review (test-case)  | `/qc-run-test {UC-ID}` if APPROVED; fix TCs if NEEDS_FIX |
+| /qc-run-test            | `/qc-report {UC-ID}` then `/qc-review {UC-ID}` (script review) |
+| /qc-review (script)     | `/qc-report {UC-ID}` then create PR if APPROVED |
+| /qc-report              | `/validate-traces {UC-ID}` to refresh Living Docs (qc_status) |
+| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
+| /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
+| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/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}` or `/debug {error}`    |
+| /review-code            | `/dev-smoke-test {UC-ID}` or create PR            |
+| /dev-smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/dev-gen-test {UC-ID}`; all OK → create PR |
+| /fix-bug                | Create PR and link to ticket                  |
+| /debug                  | `/fix-bug {ticket-id}` if fix needed          |
+| /report-bug             | Send to dev (`/fix-bug {BUG-ID}`); if coverage gap → `/propose-scenario {UC-ID}` |
+| /propose-scenario       | Notify PO/Dev to review the proposal in `feedback/bdd-proposals/` |
+| /learn                  | Continue working — lesson applies on next command |
+| /sync                   | `/validate-traces` for full coverage; act on any `📥 tester feedback` surfaced |
+| /update-framework       | Review `git diff .agent/`, commit; `/sync` for project content |
+
+Format the footer as:
+```
+---
+Status   : {badge}
+{Output Artifacts block}
+Pipeline : Discovery → PRD → [BDD ◀ bạn ở đây] → Tech Design → Code → Dev Self-Check → QC → Trace Audit
+           (review cmd) Vòng review: [① phân tích ◀] → ② Review Board → ③ --resume
+Next     : {suggested command with example arguments}
+```
+*(Omit the `Pipeline` line for cross-cutting commands listed above.)*
+
+
+```
+/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
+```