@anhth2/spec-driven-dev-plugin 0.6.0 → 0.8.0

package/commands/generate-tech-docs.md

@@ -31,7 +31,7 @@ Display and wait for response:
 ```
 ⚙️  MODEL CHECK
 ──────────────────────────────────────────────────────────────────
-  Recommended  : claude-opus-4-5 (or claude-opus-4)
+  Recommended  : claude-opus-4 (or latest Opus model)
   Why needed   : Spec analysis, architecture review, code generation
                  require deep reasoning. Smaller models miss edge cases.
 
@@ -84,7 +84,28 @@ Wait for explicit "Y" or "N" from the user before continuing.
 - "N" → stop and ask what the user wants to change.
 
 
-*Note: For this command, the target in Step 1 is a `.feature` file or UC-ID under `{paths.specs_dir}/`. If quality < 80% (missing BDD rules compliance), halt with feedback.*
+*Note: For this command, the target in Step 1 is a `.feature` file or UC-ID under `{paths.specs_dir}/`.*
+
+**Quality Gate**: Before generating, check the BDD findings file:
+
+1. Look for `{paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml`.
+2. **If file does not exist** → warn and ask:
+   ```
+   ⚠️  /review-context has not been run for this feature file.
+   Recommended: run /review-context {feature-file} first to verify BDD quality.
+   Continue without review? (Y/N)
+   ```
+   - Y → proceed (accept risk)
+   - N → stop; run `/review-context {feature-file}` first
+3. **If file exists** → check for unresolved `status: "pending"` critical findings.
+   If any found → **HALT** and print:
+   ```
+   ❌ Quality Gate Failed — {feature-file}
+   Unresolved critical BDD findings detected.
+   Run: /review-context --fix {feature-file}   ← auto-fix what's possible
+   Then: /review-context --resume {feature-file}  ← apply remaining accepted findings
+   Then re-run: /generate-tech-docs {feature-file}
+   ```
 
 ## Context
 # Context Loader — Load All Project Context
@@ -131,6 +152,7 @@ Read `.agent/project-context.yaml`. Extract and store:
 - `paths.core_entities` → path to core-entities.md
 - `paths.tech_docs_dir` → technical documentation root
 - `paths.trace_dir` → trace state directory
+- `paths.design_spec_dir` → Design Spec documents root (FE/App only)
 
 If `paths` section is absent, use these defaults:
 - `specs_dir` = `specs/bdd`
@@ -140,13 +162,46 @@ If `paths` section is absent, use these defaults:
 - `domain_knowledge_dir` = `specs/domain-knowledge`
 - `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
 - `core_entities` = `specs/domain-knowledge/core-entities.md`
-- `tech_docs_dir` = `tech-docs`
+- `tech_docs_dir` = `specs/tech-docs`
 - `trace_dir` = `.trace`
+- `design_spec_dir` = `specs/design-spec`
 
 If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
 
 ---
 
+## Step 1.5 — [SERVICE ROUTING] Resolve service paths (umbrella mode)
+
+*Skip this step entirely if `setup.mode` is not `"umbrella"` and `services` section is absent from project-context.yaml.*
+
+If `services` section is present:
+
+**1. Detect active domain** (in priority order):
+- Read `@trace.domain` from target file frontmatter (if Gate loaded a target file)
+- Extract from target file path: segment immediately after `prd_dir` base path  
+  *(e.g., `specs/prd/user/FEAT-01.md` → domain = `user`)*
+- If `$ARGUMENTS` contains a path, extract the segment after `prd_dir`
+
+**2. Route to service** — if active domain matches a key in `services`:
+- Override `paths.specs_dir` → `services.{domain}.specs_dir`
+- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir`
+- Store `active_service` = `services.{domain}.path`
+- Store `active_service_module` = `services.{domain}.module`
+- If service has its own `module` → use it as `active_module` (overrides `tech_stack.module`)
+
+**3. Fallback** — if domain not detected or no matching service key:
+- Keep default paths from Step 1
+- Set `active_service = unresolved`
+
+**4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
+- Override `paths.prd_dir` → `{spec_source}/specs/prd`
+- Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
+- Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
+- Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
+
+---
+
 ## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
 
 If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
@@ -217,6 +272,26 @@ If the file does not exist → skip silently.
 
 ---
 
+## Step 6.5 — [PLATFORM] Derive active_module and platform_type
+
+Using `tech_stack.module` loaded in Step 1, derive and store two variables for use by all downstream commands:
+
+```
+active_module = tech_stack.module   (e.g. "java-spring", "react", "flutter")
+```
+
+| `platform_type` | Modules |
+|---|---|
+| `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` |
+| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` |
+| `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
+
+If `tech_stack.module` is blank or not recognized → set `platform_type = "unknown"` and flag as ⚠️ in the Step 7 recap.
+
+These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (generate-tests, debug, fix-bug, smoke-test).
+
+---
+
 ## Step 7 — [RECAP] Working Memory Recap (anti-lost-in-middle)
 
 After loading all context, synthesize and output a compact summary block.
@@ -227,10 +302,12 @@ Output exactly this block:
 ```
 [CTX LOADED]
 Stack     : {language} / {framework} / {database}
+Platform  : {active_module} ({platform_type})
 Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
 Ticket    : {ticket_prefix}-
 Dict      : {loaded — N canonical terms, M banned terms | missing}
 Entities  : {loaded — EntityA, EntityB, EntityC | missing}
+Service   : {active_service} ({active_service_module}) | single-service
 Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
 ```
 
@@ -252,6 +329,38 @@ After completing all steps, you have loaded:
 Proceed to the next step of the calling command.
 
 
+---
+
+## CHECKPOINT — Tech Design Plan
+
+Before generating, scan the feature file for scenario count, referenced BRs, and entities. Display and wait for Y:
+
+```
+Tech Design Plan — {UC-ID}
+──────────────────────────────────────────────────────
+UC       : {UC-ID} — {feature title}
+Service  : {trace.service}
+Module   : {trace.module}
+Scenarios: {N} scenarios
+BDD ver  : {trace.bdd_version}
+Output   : {paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md
+
+Sections to generate:
+  §1 Overview
+  §2 API Endpoints   ({N} endpoints inferred from scenarios)
+  §3 Data Model      ({entities from core-entities.md relevant to this UC})
+  §4 Service Flow
+  §5 Business Rules  ({N} BRs from feature header)
+  §6 Error Handling
+  §7 Database Changes
+  §8 Caching Strategy
+  §9 Cross-Service Dependencies
+──────────────────────────────────────────────────────
+Proceed? (Y/N)
+```
+
+Wait for explicit "Y" before generating.
+
 ---
 
 ## Generate
@@ -264,6 +373,8 @@ Write `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`:
 ---
 @trace.id: {UC-ID}
 @trace.domain: {domain}
+@trace.service: {read @trace.service from the .feature file header}
+@trace.module: {read @trace.module from the .feature file header}
 @trace.prd: {TICKET-ID}
 @trace.bdd_version: {read @trace.bdd_version from the .feature file header}
 @trace.revision: 1
@@ -296,8 +407,6 @@ Write `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`:
 | 1 | {YYYY-MM-DD} | Initial generation from {UC-ID}.feature (BDD v{bdd_version}) |
 ```
 
-SA/Lead should review and approve before running `/generate-code`.
-
 ## Output
 
 # Report Footer — Standard Command Output Format
@@ -328,21 +437,23 @@ 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)   | `/generate-bdd {prd-file}` if APPROVED; fix PRD if NEEDS_FIX |
+| /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          | `/generate-tests {UC-ID}`                     |
+| /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        | `/generate-code {UC-ID}` for gaps             |
+| /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          |
 
@@ -358,5 +469,7 @@ Next   : {suggested command with example arguments}
 ```
 /generate-tech-docs Complete — {UC-ID}
 File: {paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md
-Next: /generate-code {UC-ID}
+Next: /review-tech-docs {paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md
+      ← SA/Lead review required before code generation
+      → after approved: /generate-code {paths.specs_dir}/{domain}/{UC-ID}-{slug}.feature
 ```

package/commands/generate-tech-docs.tmpl

@@ -3,13 +3,66 @@
 ## Gate
 {{include:steps/gate.md}}
 
-*Note: For this command, the target in Step 1 is a `.feature` file or UC-ID under `{paths.specs_dir}/`. If quality < 80% (missing BDD rules compliance), halt with feedback.*
+*Note: For this command, the target in Step 1 is a `.feature` file or UC-ID under `{paths.specs_dir}/`.*
+
+**Quality Gate**: Before generating, check the BDD findings file:
+
+1. Look for `{paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml`.
+2. **If file does not exist** → warn and ask:
+   ```
+   ⚠️  /review-context has not been run for this feature file.
+   Recommended: run /review-context {feature-file} first to verify BDD quality.
+   Continue without review? (Y/N)
+   ```
+   - Y → proceed (accept risk)
+   - N → stop; run `/review-context {feature-file}` first
+3. **If file exists** → check for unresolved `status: "pending"` critical findings.
+   If any found → **HALT** and print:
+   ```
+   ❌ Quality Gate Failed — {feature-file}
+   Unresolved critical BDD findings detected.
+   Run: /review-context --fix {feature-file}   ← auto-fix what's possible
+   Then: /review-context --resume {feature-file}  ← apply remaining accepted findings
+   Then re-run: /generate-tech-docs {feature-file}
+   ```
 
 ## Context
 {{include:steps/context-loader.md}}
 
 ---
 
+## CHECKPOINT — Tech Design Plan
+
+Before generating, scan the feature file for scenario count, referenced BRs, and entities. Display and wait for Y:
+
+```
+Tech Design Plan — {UC-ID}
+──────────────────────────────────────────────────────
+UC       : {UC-ID} — {feature title}
+Service  : {trace.service}
+Module   : {trace.module}
+Scenarios: {N} scenarios
+BDD ver  : {trace.bdd_version}
+Output   : {paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md
+
+Sections to generate:
+  §1 Overview
+  §2 API Endpoints   ({N} endpoints inferred from scenarios)
+  §3 Data Model      ({entities from core-entities.md relevant to this UC})
+  §4 Service Flow
+  §5 Business Rules  ({N} BRs from feature header)
+  §6 Error Handling
+  §7 Database Changes
+  §8 Caching Strategy
+  §9 Cross-Service Dependencies
+──────────────────────────────────────────────────────
+Proceed? (Y/N)
+```
+
+Wait for explicit "Y" before generating.
+
+---
+
 ## Generate
 
 Write `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`:
@@ -20,6 +73,8 @@ Write `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`:
 ---
 @trace.id: {UC-ID}
 @trace.domain: {domain}
+@trace.service: {read @trace.service from the .feature file header}
+@trace.module: {read @trace.module from the .feature file header}
 @trace.prd: {TICKET-ID}
 @trace.bdd_version: {read @trace.bdd_version from the .feature file header}
 @trace.revision: 1
@@ -52,8 +107,6 @@ Write `{paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md`:
 | 1 | {YYYY-MM-DD} | Initial generation from {UC-ID}.feature (BDD v{bdd_version}) |
 ```
 
-SA/Lead should review and approve before running `/generate-code`.
-
 ## Output
 
 {{include:steps/report-footer.md}}
@@ -61,5 +114,7 @@ SA/Lead should review and approve before running `/generate-code`.
 ```
 /generate-tech-docs Complete — {UC-ID}
 File: {paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md
-Next: /generate-code {UC-ID}
+Next: /review-tech-docs {paths.tech_docs_dir}/{domain}/{UC-ID}-tech-design.md
+      ← SA/Lead review required before code generation
+      → after approved: /generate-code {paths.specs_dir}/{domain}/{UC-ID}-{slug}.feature
 ```