@anhth2/spec-driven-dev-plugin 0.7.0 → 0.9.0

package/commands/sync.tmpl

@@ -0,0 +1,345 @@
+# /sync — Sync & Refresh Umbrella Project
+
+One command for both **first-time setup** and **daily update** of an umbrella repo with git submodules.
+Safe to run repeatedly — detects what needs to be done automatically.
+
+**Optional argument:** `/sync [spec-branch]` — branch of the spec submodule to pull (e.g. `/sync develop`). If omitted, the branch is resolved automatically (see Step 0-D).
+
+---
+
+## Step 0 — Pre-flight Checks
+
+**A. Git repo check**
+
+Verify current directory is inside a git repo. If not → stop:
+```
+❌ Not a git repository. Open Claude Code from umbrella root and retry.
+```
+
+**B. Read project config early**
+
+Read `.agent/project-context.yaml` before running any git commands. Extract:
+- `setup.spec_source` → path of the spec submodule (e.g., `"my-project-specs"`)
+- `services` → map of domain → `{path, module, ...}` for each service submodule
+
+This is needed to differentiate spec vs service submodules in Step 1.
+
+If `.agent/project-context.yaml` does not exist → warn and set `spec_source = null`, `services = {}`.
+
+**C. Submodule status scan**
+
+Run `git submodule status --recursive` and classify each entry by its first character:
+
+| Char | Meaning | Action |
+|------|---------|--------|
+| `-` | Not initialized | → **Setup mode** |
+| ` ` | Matches recorded pointer | → OK |
+| `+` | Ahead of recorded pointer (local advance uncommitted) | → warn per submodule |
+| `U` | Merge conflict | → **STOP** |
+
+If **any** entry has `U`:
+```
+❌ Merge conflict in submodule: {path}
+   Resolve manually before running /sync:
+     cd {path} && git status
+```
+
+If **any** entry has `+` (checked-out commit differs from the recorded pointer):
+```
+ℹ️ {path} is ahead of the umbrella's recorded pointer.
+   /sync classifies it in Step 1b — if you're on a branch there, it stays untouched.
+```
+Do not act on `+` here — Step 1b decides the right handling per submodule.
+
+Print detected mode: `Mode: Setup (first-time init)` or `Mode: Update (sync latest)`.
+
+---
+
+## Step 1 — Umbrella Pull
+
+Note the current umbrella branch first (this is what `git pull` updates):
+`git rev-parse --abbrev-ref HEAD` → store as `umbrella_branch` and display it.
+
+```bash
+# 1. Pull latest umbrella (includes updated submodule pointer records)
+git pull
+
+# 2. Sync .gitmodules config into local git config
+#    (needed when new submodules were added since last clone)
+git submodule sync --recursive
+
+# 3. Initialize any NOT-yet-cloned submodules ONLY (the '-' entries from Step 0-C).
+#    Do NOT run a blanket `git submodule update --recursive` — that would detach
+#    a submodule you are actively working in. Per-submodule handling is Step 1b.
+git submodule update --init {paths that were '-' in Step 0-C}
+```
+
+If `git pull` exits non-zero → print the error and stop with `❌`.
+
+---
+
+## Step 1b — Classify & Sync Each Submodule
+
+**The key idea:** `/sync` never imposes a branch on a submodule. It **inspects each submodule's current checkout** and respects it. This is how it knows which submodule you are working in vs which are passive dependencies.
+
+For each submodule (use `git submodule foreach` or iterate the paths), read its state:
+
+```bash
+# Inside each submodule:
+git symbolic-ref --short -q HEAD   # → branch name, or empty/non-zero if DETACHED
+git status --porcelain             # → non-empty means uncommitted local changes
+```
+
+Classify into one of four cases and act accordingly:
+
+| Case | Detected state | Action |
+|------|----------------|--------|
+| **Spec submodule** | `path == spec_source` | Advance to `spec_branch` (Step 1c below) |
+| **Active (on a branch)** | HEAD is a branch, not detached | **Do NOT checkout.** This is where you (or a teammate) are coding. Just `git -C {path} fetch` and report branch + ahead/behind. Leave the working tree exactly as-is. |
+| **Passive (detached, clean)** | Detached HEAD, no local changes | Safe to align to the umbrella's recorded pointer: `git submodule update {path}` |
+| **Dirty (uncommitted changes)** | `git status --porcelain` non-empty | **Never touch.** Warn: `⚠️ {path} has uncommitted changes — skipped. Commit or stash before syncing this submodule.` |
+
+> **Why this matters:** A blanket `git submodule update` checks every submodule out to a **detached HEAD** at the recorded pointer. If you have `feature/FEAT-01` checked out inside `user-service/` and are mid-work, that would silently move you off your branch. Classifying first protects your active work.
+
+---
+
+## Step 1c — Advance Spec Submodule *(only if `spec_source` is configured)*
+
+The spec submodule is the one submodule we deliberately advance to a branch HEAD (PO pushes specs continuously).
+
+**Resolve the spec branch** (now that the submodule is initialized), in priority order:
+
+1. **Command argument** — if `$ARGUMENTS` contains a branch name → use it (one-off override)
+2. **`.gitmodules` config** — `git config -f .gitmodules --get submodule.{spec_source}.branch`. If set → use it (team's committed default)
+3. **Remote default** — else the spec repo's default branch: `git -C {spec_source} rev-parse --abbrev-ref origin/HEAD` (strip the `origin/` prefix)
+
+Store as `spec_branch` + `spec_branch_source` (argument | .gitmodules | remote-default). If it fell through to remote-default with nothing pinned, add this hint to the output:
+```
+ℹ️ Spec submodule branch not pinned in .gitmodules — using remote default '{spec_branch}'.
+   To pin it for the whole team:
+     git config -f .gitmodules submodule.{spec_source}.branch {spec_branch}
+     git add .gitmodules && git commit -m "chore: pin spec submodule branch"
+```
+
+Then check it is safe: if the spec submodule has uncommitted changes → warn and skip (devs should treat specs as read-only). Otherwise use an **explicit checkout** (not bare `--remote`) so the branch is unambiguous:
+
+```bash
+cd {spec_source}
+git fetch origin
+git checkout {spec_branch}        # branch resolved in Step 0-D
+git pull origin {spec_branch}
+cd -                              # back to umbrella root
+```
+
+Print: `Spec submodule {spec_source}: pulled branch '{spec_branch}' (source: {spec_branch_source})`
+
+> **Why not `--remote` for service submodules?** Service submodules are version-locked by the umbrella's recorded pointer — this is intentional so all devs work from the same commit. `--remote` would bypass this lock and create uncommitted pointer drift. The spec submodule is the exception: PO pushes continuously, so we advance it to a branch HEAD — but we do it with an explicit `checkout {spec_branch}` rather than `--remote` so it never silently follows the wrong branch.
+
+If `git pull` or `git submodule update` exits non-zero → print the error and stop with `❌`.
+
+Collect from output:
+- Which submodules changed SHA
+- Which were already up to date
+- The spec submodule's `{old_sha}..{new_sha}` (needed by Step 1d)
+
+---
+
+## Step 1d — Surface Tester Feedback *(new bug reports / scenario proposals)*
+
+Tester `/report-bug` and `/propose-scenario` commit feedback into the spec repo. This step tells PO/Dev what arrived in **this** pull, so they are notified through their normal routine. It covers both audiences:
+
+- **Dev/tester in umbrella** → feedback came in via the spec submodule advance (Step 1c)
+- **PO working directly in the spec repo** → feedback came in via the umbrella/current-repo `git pull` (Step 1)
+
+Pick the repo + range that pulled the feedback:
+- Umbrella with `spec_source` → `REPO={spec_source}`, range = spec submodule `{old_sha}..{new_sha}`
+- Otherwise (running inside the spec repo itself) → `REPO=.`, range = the `git pull` `{old_sha}..{new_sha}` from Step 1
+
+If `feedback/` does not exist in REPO → skip silently.
+
+```bash
+git -C {REPO} diff --name-status {old_sha}..{new_sha} -- feedback/bug-reports/ feedback/bdd-proposals/
+```
+
+For each entry, read its title/summary and report:
+```
+📥 New tester feedback (pulled this sync):
+   Bug reports:
+     BUG-20260608-01  FT-001 — account locks after 6 fails (spec says 5)   [layer: Code]
+   Scenario proposals:
+     FT-001-trailing-spaces.md  → maps to AC2  (pending review)
+```
+
+If none changed → print `📥 Tester feedback: none new this sync`.
+
+If the reader is a PO/Dev, add a one-line nudge:
+`→ Review feedback/ then act: /fix-bug {BUG-ID} · promote proposal into BDD · or update PRD.`
+
+---
+
+## Step 2 — Post-sync State Check
+
+Run `git status --short` and check for modified submodule entries (lines starting with ` M` where the path matches a submodule).
+
+If any submodule pointer changed (typically the spec submodule after `--remote`):
+```
+⚠️ Submodule pointer(s) updated — commit to lock new version into umbrella:
+   git add {spec_source} && git commit -m "chore: sync {spec_source} to latest"
+```
+
+If no changes → `✅ Umbrella state clean — no commit needed`.
+
+---
+
+## Step 3 — Bootstrap Service Configs
+
+*Skip if `services` is empty.*
+
+For each entry in `services[]`:
+
+**A. If `{service.path}/.agent/project-context.yaml` already exists:**
+- Read `conventions.test_command` and `conventions.build_command`
+- Report: `✅ {service.path} — test: {test_command} | build: {build_command}`
+
+**B. If missing — auto-create it:**
+
+1. Determine `module` from umbrella `services[].module` (authoritative). If not set, auto-detect from files in `{service.path}/`:
+
+   | File present | Detected module | test_command | build_command |
+   |---|---|---|---|
+   | `pom.xml` | `java-spring` | `mvn test` | `mvn compile` |
+   | `build.gradle` or `build.gradle.kts` | `java-spring` | `./gradlew test` | `./gradlew build` |
+   | `go.mod` | `golang` | `go test ./...` | `go build ./...` |
+   | `*.csproj` or `*.sln` | `dotnet` | `dotnet test` | `dotnet build` |
+   | `composer.json` | `php-laravel` | `php artisan test` | `composer install` |
+   | `pubspec.yaml` | `flutter` | `flutter test` | `flutter build apk` |
+   | `angular.json` | `angular` | `npx ng test --watch=false` | `npm run build` |
+   | `next.config.*` | `nextjs` | `npx vitest run` | `npm run build` |
+   | `package.json` + `nest-cli.json` | `nestjs` | `npm test` | `npm run build` |
+   | `package.json` (fallback) | `react` | `npx vitest run` | `npm run build` |
+   | `requirements.txt` or `pyproject.toml` | `context-engineering` | `pytest tests/ -v` | `pip install -r requirements.txt` |
+   | *(none matched)* | `unknown` | `{{TEST_COMMAND}}` | `{{BUILD_COMMAND}}` |
+
+2. Create `{service.path}/.agent/` directory if it does not exist.
+
+3. Write `{service.path}/.agent/project-context.yaml`:
+
+   ```yaml
+   # Auto-generated by /sync — review and update as needed
+   tech_stack:
+     language: "{detected or from module}"
+     framework: "{detected or from module}"
+     module: "{module}"
+
+   conventions:
+     test_command: "{test_command}"
+     build_command: "{build_command}"
+
+   paths:
+     trace_dir: ".trace"
+     lessons_file: ".agent/project-lessons.md"   # per-service guardrails (see /learn)
+   ```
+
+4. Report:
+   - If auto-detected: `✅ Created {service.path}/.agent/project-context.yaml (module: {module}, test: {test_command})`
+   - If unknown/placeholder: `⚠️ Created {service.path}/.agent/project-context.yaml — fill in {{TEST_COMMAND}} and {{BUILD_COMMAND}}`
+
+---
+
+## Step 4 — Check `.gitignore`
+
+Check if `.trace/` appears in the umbrella root's `.gitignore` (or `.git/info/exclude`).
+
+If missing:
+```
+⚠️ .trace/ is not in umbrella .gitignore
+   Add it to prevent accidentally committing generated trace artifacts:
+   echo ".trace/" >> .gitignore
+```
+
+---
+
+## Step 5 — Refresh Living Docs *(umbrella mode only)*
+
+*Skip if `services` is empty.*
+
+For each service in `services[]`:
+1. Check if `{service.path}/.trace/` directory exists and contains `.tsv` files
+2. If yes → copy TSVs to `{umbrella_root}/.trace/{service-name}/` (create dir if needed)
+
+After copying all services, write merged `{umbrella_root}/.trace/trace-report.json`:
+- Aggregate data from each service's `.trace/` TSVs
+- Include `"service"` field per scenario row
+- Recalculate summary totals
+
+Print sync result:
+```
+Living Docs → .trace/ synced
+  {service-name}: {N} TSVs
+  trace-report.json: {total} scenarios across {S} services
+```
+
+If no `.trace/` dirs found → `Living Docs: no trace data yet — run /generate-bdd then /generate-code first.`
+
+---
+
+## Step 6 — Refresh Spec Manifest *(if spec_source present)*
+
+*Skip if `setup.spec_source` is absent.*
+
+If `spec-manifest.yaml` exists OR `setup.spec_source` is configured:
+- Re-scan `{spec_source}/specs/prd/**/*.md` files
+- Rebuild `spec-manifest.yaml` mapping TICKET-ID → PRD/BDD/tech-doc paths
+- Print: `spec-manifest.yaml refreshed — {N} features indexed`
+
+---
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+/sync — {Setup | Update}
+
+Git
+  ✅ git pull             — umbrella on branch '{umbrella_branch}'
+  ✅ submodule sync       — .gitmodules config refreshed
+
+Submodules (each handled by its current state)
+  ✅ {spec_source}    [spec]            — pulled branch '{spec_branch}' ({spec_branch_source}) → {new-sha}
+  ✋ user-service     [active]          — on 'feature/FEAT-01' — left untouched, fetched (↓2 behind origin)
+  ✅ order-service    [passive]         — aligned to umbrella pointer {sha}
+  ⚠️ payment-service  [dirty]           — uncommitted changes, skipped (commit/stash first)
+
+Umbrella state
+  ⚠️ Pointer changed: git add {spec_source} && git commit -m "chore: sync specs"
+  (or: ✅ Clean — no commit needed)
+
+Tester feedback (pulled this sync)
+  📥 1 bug report:  BUG-20260608-01 FT-001 [Code]
+     1 proposal:    FT-001-trailing-spaces → AC2 (pending review)
+  (or: 📥 none new this sync)
+  → /fix-bug {BUG-ID} · promote proposal into BDD · or update PRD
+
+Service Configs
+  ✅ user-service    — test: mvn test  | build: mvn compile
+  ✅ order-service   — test: mvn test  | build: mvn compile
+  ⚠️ payment-service — .agent/project-context.yaml missing
+                       → create it so /run-tests works correctly
+
+.gitignore
+  ✅ .trace/ is gitignored
+  (or: ⚠️ Add .trace/ to .gitignore)
+
+Living Docs
+  ✅ .trace/ synced — {N} TSVs across {S} services
+     (run /validate-traces for full coverage report)
+
+Spec Manifest
+  ✅ spec-manifest.yaml — {N} features indexed
+
+---
+Status : ✅ Complete | ⚠️ Warnings
+Output Artifacts: updated .trace/ (umbrella mirror), spec-manifest.yaml
+Next   : /validate-traces (full coverage check) | /generate-code {UC-ID} (start coding)
+```

package/commands/update-framework.md

@@ -0,0 +1,211 @@
+# /update-framework — Update the Spec-Driven Dev 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 @anhth2/spec-driven-dev-plugin@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 @anhth2/spec-driven-dev-plugin --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 @anhth2/spec-driven-dev-plugin 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 @anhth2/spec-driven-dev-plugin@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)`.
+
+## 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 |
+| /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 → `/generate-tests {UC-ID}` |
+| /generate-tests         | `/run-tests {UC-ID}`                          |
+| /run-tests (passing)    | `/review-code {UC-ID}`                        |
+| /run-tests (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/smoke-test {UC-ID}` or create PR            |
+| /smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/generate-tests {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}
+Next   : {suggested command with example arguments}
+```
+
+
+```
+/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-dev 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
+```