@edupia-tutor/spec-driven-docs 0.14.0

package/commands/generate-spec-manifest.tmpl

@@ -0,0 +1,164 @@
+# /generate-spec-manifest — Generate Spec Manifest for External Agents
+
+Scans all spec files and writes a `spec-manifest.yaml` at the project root.
+This file is for **external agents only** (e.g. tester's agent) — it is not committed to git.
+
+## Gate
+
+{{include:steps/gate.md}}
+
+*Note: For this command, there is no target file — it scans the entire project. Ignore `$ARGUMENTS` unless a domain filter is passed.*
+
+## Context
+
+{{include:steps/context-loader.md}}
+
+---
+
+## Process
+
+### Step 1 — Determine scan roots
+
+Read `project-context.yaml` to determine mode and paths:
+
+**Umbrella mode** (`setup.mode: umbrella`):
+```
+spec_root      = {setup.spec_source}              ← PO's spec submodule
+prd_glob       = {spec_root}/specs/**/prd.md
+pdd_glob       = {spec_root}/specs/product-definition/**/*.md
+services       = {services}                        ← map of domain → paths
+```
+
+**Single-service mode** (no `setup.mode`):
+```
+spec_root      = .
+prd_glob       = {paths.specs_dir}/**/prd.md
+pdd_glob       = {paths.product_definitions_dir}/**/*.md
+services       = { default: { specs_dir: {paths.specs_dir}, tech_docs_dir: {paths.tech_docs_dir} } }
+```
+
+If a domain filter was passed in `$ARGUMENTS` → only scan PRDs matching that domain.
+
+---
+
+### Step 2 — Scan PRD files
+
+For each `.md` file matched by `prd_glob`:
+
+1. Read the file metadata table:
+   - `TICKET-ID` from `| **PRD ID** |`
+   - `domain` from `| **Domain** |`
+   - `status` from `| **Status** |`
+   - `version` from `| **Version** |`
+2. Also read frontmatter `@trace.domain` if present (use this over metadata table domain if both exist)
+3. Record: `{ ticket_id, domain, status, version, prd_path }` — path relative to manifest root
+
+Skip files where `TICKET-ID` cannot be determined.
+
+---
+
+### Step 3 — Match PDD files
+
+For each TICKET-ID found in Step 2:
+
+Search `pdd_glob` for a file whose name contains the TICKET-ID (e.g. `FT-001-*.md`).
+- Found → record `pdd_path` (relative to manifest root)
+- Not found → record `pdd: null`
+
+---
+
+### Step 4 — Match BDD and Tech-Doc files per service
+
+For each TICKET-ID, for each service in `services` map:
+
+**BDD:**
+- Glob `{service.specs_dir}/**/{TICKET-ID}*.feature`
+- Also check files containing `@trace.prd: {TICKET-ID}` in frontmatter if glob returns nothing
+- Found → record path under `bdd.{service_key}`
+- Not found → omit key (do not write `null` for services with no BDD yet)
+
+**Tech-docs:**
+- Glob `{service.tech_docs_dir}/**/{TICKET-ID}*.md`
+- Also check files containing `@trace.prd: {TICKET-ID}` if glob returns nothing
+- Found → record path under `tech_docs.{service_key}`
+- Not found → omit key
+
+All paths relative to manifest root (umbrella root or project root).
+
+---
+
+### Step 5 — Write spec-manifest.yaml
+
+Write to `{manifest_root}/spec-manifest.yaml` (overwrite if exists).
+
+Format:
+
+```yaml
+# Auto-generated by /generate-spec-manifest — DO NOT edit manually
+# To regenerate: /generate-spec-manifest
+# This file is excluded from git — see .gitignore
+
+version: "1.0"
+generated_at: "{YYYY-MM-DD}"
+project_mode: "{umbrella | single}"
+
+features:
+  {TICKET-ID}:
+    domain: {domain}
+    status: {status}
+    prd_version: "{version}"
+    prd: "{prd_path}"
+    pdd: "{pdd_path}"               # omit if null
+    tech_docs:
+      {service_key}: "{path}"       # only include services where file was found
+    bdd:
+      {service_key}: "{path}"       # only include services where file was found
+```
+
+Sort features by TICKET-ID alphabetically.
+Omit `tech_docs` block entirely if no tech-doc found for any service.
+Omit `bdd` block entirely if no BDD found for any service.
+
+---
+
+### Step 6 — Ensure .gitignore
+
+Check `{manifest_root}/.gitignore`:
+- If `spec-manifest.yaml` is already listed → no action
+- If not → append the following to `.gitignore`:
+
+```
+# Auto-generated — do not commit
+spec-manifest.yaml
+```
+
+Print: `✅ spec-manifest.yaml added to .gitignore`
+
+---
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+/generate-spec-manifest Complete
+---
+Status  : ✅ Complete
+Output  : spec-manifest.yaml  ({N} features)
+Mode    : {umbrella | single}
+.gitignore : ✅ spec-manifest.yaml excluded
+
+Summary:
+  {N} PRDs scanned  ({A} approved, {D} draft)
+  {N} PDDs matched
+  {N} BDD files matched  (across {S} services)
+  {N} Tech-doc files matched  (across {S} services)
+
+  ⚠️  {N} PRDs with no matching BDD:
+    - {TICKET-ID} ({domain}) — run /generate-bdd first
+  ⚠️  {N} PRDs with no matching tech-docs:
+    - {TICKET-ID} ({domain}) — run /generate-tech-docs first
+
+Next   : Share spec-manifest.yaml path with tester agent
+         Regenerate anytime: /generate-spec-manifest
+```