@edupia-tutor/spec-driven-docs 0.14.0

package/commands/update-framework.tmpl

@@ -0,0 +1,151 @@
+# /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
+
+{{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
+```