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

package/commands/refine-prd.md

@@ -175,13 +175,14 @@ If `services` section is present:
 **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.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 
@@ -389,7 +390,9 @@ findings:
   - id: "F001"
     lens: "QA"           # QA | DEV | SA | PO
     severity: "major"    # critical | major | minor
-    section: "§6. Acceptance Criteria"
+    section: "§6. Acceptance Criteria"   # human-readable heading/section label
+    uc_id: "{TICKET-ID}-UC{N}"           # UC this finding belongs to; "" if PRD-global (scope, metrics, problem statement)
+    quote: "{verbatim snippet copied EXACTLY from the PRD at the issue location, ≤120 chars}"
     finding: "{description of gap or issue}"
     suggestion: "{specific actionable improvement}"
     auto_fixable: false  # true = AI applies in --resume; false = human must write decision in note
@@ -402,6 +405,12 @@ summary:
   recommendation: "APPROVED_WITH_MINOR_CHANGES | NEEDS_REVISION | BLOCKED"
 ```
 
+> **Locator fields (`quote` + `uc_id`) — required for Review Board source-jump.**
+> For every finding, copy a short **verbatim** `quote` straight from the PRD at the exact spot the
+> issue occurs — do NOT paraphrase; it is matched against the document to locate the line. Set
+> `uc_id` to the owning Use Case (or `""` for PRD-global findings). These let a reviewer click a
+> finding in the Review Board and jump straight to the precise location in the source PRD.
+
 ## Report
 
 # Report Footer — Standard Command Output Format

package/commands/refine-prd.tmpl

@@ -37,7 +37,9 @@ findings:
   - id: "F001"
     lens: "QA"           # QA | DEV | SA | PO
     severity: "major"    # critical | major | minor
-    section: "§6. Acceptance Criteria"
+    section: "§6. Acceptance Criteria"   # human-readable heading/section label
+    uc_id: "{TICKET-ID}-UC{N}"           # UC this finding belongs to; "" if PRD-global (scope, metrics, problem statement)
+    quote: "{verbatim snippet copied EXACTLY from the PRD at the issue location, ≤120 chars}"
     finding: "{description of gap or issue}"
     suggestion: "{specific actionable improvement}"
     auto_fixable: false  # true = AI applies in --resume; false = human must write decision in note
@@ -50,6 +52,12 @@ summary:
   recommendation: "APPROVED_WITH_MINOR_CHANGES | NEEDS_REVISION | BLOCKED"
 ```
 
+> **Locator fields (`quote` + `uc_id`) — required for Review Board source-jump.**
+> For every finding, copy a short **verbatim** `quote` straight from the PRD at the exact spot the
+> issue occurs — do NOT paraphrase; it is matched against the document to locate the line. Set
+> `uc_id` to the owning Use Case (or `""` for PRD-global findings). These let a reviewer click a
+> finding in the Review Board and jump straight to the precise location in the source PRD.
+
 ## Report
 
 {{include:steps/report-footer.md}}

package/commands/report-bug.md

@@ -184,13 +184,14 @@ If `services` section is present:
 **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.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/commands/review-code.md

@@ -177,13 +177,14 @@ If `services` section is present:
 **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.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/commands/review-context.md

@@ -182,13 +182,14 @@ If `services` section is present:
 **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.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 
@@ -563,6 +564,8 @@ findings:
     check_id: "P1"           # P1-P5 for PRD; B1-B6 for BDD
     severity: "critical"     # critical | major | minor
     section: "{section or scenario ID where issue was found}"
+    uc_id: "{UC-ID this finding belongs to — PRD: the UC heading; BDD: @trace.id; \"\" if global}"
+    quote: "{verbatim snippet copied EXACTLY from the reviewed file at the issue location, ≤120 chars}"
     finding: "{clear description of the issue}"
     suggestion: "{specific actionable fix — AI will apply this in --resume if accepted}"
     auto_fixable: true       # true = AI can apply; false = human must write note in Review Board
@@ -576,6 +579,12 @@ summary:
   recommendation: "APPROVED | NEEDS_REVISION | BLOCKED"
 ```
 
+> **Locator fields (`quote` + `uc_id`) — required for Review Board source-jump.**
+> For every finding, copy a short **verbatim** `quote` straight from the reviewed file at the exact
+> spot the issue occurs — do NOT paraphrase; it is matched against the document to locate the line.
+> Set `uc_id` to the owning Use Case (`@trace.id` for BDD, the UC heading for PRD; `""` if global).
+> These let a reviewer click a finding in the Review Board and jump to the precise source location.
+
 ## Post-Analysis Routing
 
 After running all checks and writing the findings file:

package/commands/review-context.tmpl

@@ -211,6 +211,8 @@ findings:
     check_id: "P1"           # P1-P5 for PRD; B1-B6 for BDD
     severity: "critical"     # critical | major | minor
     section: "{section or scenario ID where issue was found}"
+    uc_id: "{UC-ID this finding belongs to — PRD: the UC heading; BDD: @trace.id; \"\" if global}"
+    quote: "{verbatim snippet copied EXACTLY from the reviewed file at the issue location, ≤120 chars}"
     finding: "{clear description of the issue}"
     suggestion: "{specific actionable fix — AI will apply this in --resume if accepted}"
     auto_fixable: true       # true = AI can apply; false = human must write note in Review Board
@@ -224,6 +226,12 @@ summary:
   recommendation: "APPROVED | NEEDS_REVISION | BLOCKED"
 ```
 
+> **Locator fields (`quote` + `uc_id`) — required for Review Board source-jump.**
+> For every finding, copy a short **verbatim** `quote` straight from the reviewed file at the exact
+> spot the issue occurs — do NOT paraphrase; it is matched against the document to locate the line.
+> Set `uc_id` to the owning Use Case (`@trace.id` for BDD, the UC heading for PRD; `""` if global).
+> These let a reviewer click a finding in the Review Board and jump to the precise source location.
+
 ## Post-Analysis Routing
 
 After running all checks and writing the findings file:

package/commands/review-tech-docs.md

@@ -179,13 +179,14 @@ If `services` section is present:
 **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.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 
@@ -554,6 +555,8 @@ findings:
     check_id: "T1"           # T1–T7
     severity: "critical"     # critical | major | minor
     section: "{section heading or component name where issue was found}"
+    uc_id: "{UC-ID}"         # same as top-level uc_id (the UC this tech-doc designs)
+    quote: "{verbatim snippet copied EXACTLY from the tech-doc at the issue location, ≤120 chars}"
     finding: "{clear description of the violation or gap}"
     suggestion: "{specific fix — AI applies this in --resume if accepted}"
     auto_fixable: false      # true = AI can apply; false = human must write decision in note
@@ -568,6 +571,11 @@ summary:
   sign_off_gate: "{blocked — pending: fe_team, app_team, sa | ready}"
 ```
 
+> **Locator fields (`quote` + `uc_id`) — required for Review Board source-jump.**
+> For every finding, copy a short **verbatim** `quote` straight from the tech-doc at the exact spot
+> the issue occurs — do NOT paraphrase; it is matched against the document to locate the line.
+> These let a reviewer click a finding in the Review Board and jump to the precise source location.
+
 ## Report
 
 # Report Footer — Standard Command Output Format
@@ -717,4 +725,5 @@ Sign-off : {✅ All done — status set to approved
 Re-run /review-tech-docs {file} to confirm 0 remaining critical findings.
 Next: {/generate-code {feature-file}  ← only if status = approved
       | Collect pending sign-offs → update @trace.sign_off → re-run /review-tech-docs}
+      → if the tech-doc lives in the shared spec repo: commit + push it to the spec submodule so FE/App `/sync` the updated contract
 ```

package/commands/review-tech-docs.tmpl

@@ -202,6 +202,8 @@ findings:
     check_id: "T1"           # T1–T7
     severity: "critical"     # critical | major | minor
     section: "{section heading or component name where issue was found}"
+    uc_id: "{UC-ID}"         # same as top-level uc_id (the UC this tech-doc designs)
+    quote: "{verbatim snippet copied EXACTLY from the tech-doc at the issue location, ≤120 chars}"
     finding: "{clear description of the violation or gap}"
     suggestion: "{specific fix — AI applies this in --resume if accepted}"
     auto_fixable: false      # true = AI can apply; false = human must write decision in note
@@ -216,6 +218,11 @@ summary:
   sign_off_gate: "{blocked — pending: fe_team, app_team, sa | ready}"
 ```
 
+> **Locator fields (`quote` + `uc_id`) — required for Review Board source-jump.**
+> For every finding, copy a short **verbatim** `quote` straight from the tech-doc at the exact spot
+> the issue occurs — do NOT paraphrase; it is matched against the document to locate the line.
+> These let a reviewer click a finding in the Review Board and jump to the precise source location.
+
 ## Report
 
 {{include:steps/report-footer.md}}
@@ -305,4 +312,5 @@ Sign-off : {✅ All done — status set to approved
 Re-run /review-tech-docs {file} to confirm 0 remaining critical findings.
 Next: {/generate-code {feature-file}  ← only if status = approved
       | Collect pending sign-offs → update @trace.sign_off → re-run /review-tech-docs}
+      → if the tech-doc lives in the shared spec repo: commit + push it to the spec submodule so FE/App `/sync` the updated contract
 ```

package/commands/run-tests.md

@@ -175,13 +175,14 @@ If `services` section is present:
 **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.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/commands/smoke-test.md

@@ -177,13 +177,14 @@ If `services` section is present:
 **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.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/commands/validate-traces.md

@@ -177,13 +177,14 @@ If `services` section is present:
 **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.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/core/FRAMEWORK_VERSION

@@ -1 +1 @@
-0.9.0
+0.9.2

package/core/commands/debug.md

@@ -178,13 +178,14 @@ If `services` section is present:
 **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.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/core/commands/define-product.md

@@ -175,13 +175,14 @@ If `services` section is present:
 **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.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/core/commands/fix-bug.md

@@ -175,13 +175,14 @@ If `services` section is present:
 **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.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/core/commands/generate-bdd.md

@@ -173,13 +173,14 @@ If `services` section is present:
 **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.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/core/commands/generate-code.md

@@ -175,13 +175,14 @@ If `services` section is present:
 **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.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/core/commands/generate-design-spec.md

@@ -175,13 +175,14 @@ If `services` section is present:
 **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.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 

package/core/commands/generate-prd.md

@@ -175,13 +175,14 @@ If `services` section is present:
 **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.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---
 
@@ -450,13 +451,14 @@ Write `{paths.prd_dir}/{domain}/{TICKET-ID}-{slug}.md` using the structure below
 
 ## a. User Story
 
-As a {User role}
-I want to {User goal}
-So that {Business value}
+- **As a** {User role}
+- **I want to** {User goal}
+- **So that** {Business value}
 
 ## b. Scope
 
-In Scope
+**In Scope**
+
 - {Function 1}
 - {Function 2}
 
@@ -464,24 +466,36 @@ In Scope
 
 # 2. Acceptance Criteria
 
-AC1: {Acceptance criterion — testable, observable, no UI details}
-AC2: {Acceptance criterion}
+- **AC1:** {Acceptance criterion — testable, observable, no UI details}
+- **AC2:** {Acceptance criterion}
 
 ---
 
 # 3. Use Case
 
 #### {TICKET-ID}-UC1: {Use Case Name}
-Actor: {User performing the action}
-Description: {Business scenario description — 1 sentence}
-Pre-condition: {Condition that must be true BEFORE use case begins}
-Post-condition: {State / result AFTER use case completes}
 
-Business Rule
-| ID                      | Business Rule                        | Business Logic                            |
-|-------------------------|--------------------------------------|-------------------------------------------|
-| {TICKET-ID}-UC1-BR1     | {Rule — WHAT the system must do}    | - Logic 1<br/>- Logic 2<br/>- Logic 3    |
-| {TICKET-ID}-UC1-BR2     | {Rule}                               | - Logic                                  |
+- **Actor:** {User performing the action}
+- **Description:** {Business scenario description — 1 sentence}
+- **Pre-condition:** {Condition that must be true BEFORE use case begins}
+- **Post-condition:** {State / result AFTER use case completes}
+
+**Business Rule**
+
+| ID | Business Rule |
+|----|---------------|
+| {TICKET-ID}-UC1-BR1 | {Rule — WHAT the system must do} |
+| {TICKET-ID}-UC1-BR2 | {Rule} |
+
+**Business Logic**
+
+**{TICKET-ID}-UC1-BR1:**
+- Logic 1
+- Logic 2
+- Logic 3
+
+**{TICKET-ID}-UC1-BR2:**
+- Logic
 
 ---
 
@@ -503,11 +517,16 @@ flowchart TD
 
 **Screen 1: {Screen Name}**
 
-| Component      | Details                                                         |
-|----------------|-----------------------------------------------------------------|
-| **Screen**     | {Screen name}                                                   |
-| **Components** | - {Component 1}<br/>- {Component 2}<br/>- {Component 3}        |
-| **Actions**    | - {Action 1} → {Result}<br/>- {Action 2} → {Result}           |
+**Screen:** {Screen name}
+
+**Components:**
+- {Component 1}
+- {Component 2}
+- {Component 3}
+
+**Actions:**
+- {Action 1} → {Result}
+- {Action 2} → {Result}
 
 ---
 
@@ -557,6 +576,7 @@ flowchart TD
 - [ ] No banned terms (if dictionary exists)
 - [ ] User Flow includes error path / exception path
 - [ ] Wireframe covers all screens related to Use Cases
+- [ ] **Định dạng (readability)**: User Story / AC / các field của UC (Actor, Description, Pre/Post-condition) viết dạng bullet `- **Label:** …` — mỗi ý MỘT dòng, KHÔNG viết các dòng liền nhau (sẽ bị dồn thành 1 đoạn khi render); có một dòng trống trước và sau mỗi bảng
 
 ## Changelog Section (append at end of PRD)
 

package/core/commands/generate-spec-manifest.md

@@ -180,13 +180,14 @@ If `services` section is present:
 **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.tech_docs_dir` → `{spec_source}/specs/tech-docs` — **only if step 2 did not already route it to a service** (multi-service umbrellas keep per-service tech-docs). This publishes the BE-authored API contract into the shared spec repo so FE/App can read it via the spec submodule at `/generate-code --phase=integration`.
 - 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`
 - Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
 - Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
 
-> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+> **Why under `spec_source`:** PRD, design-spec, domain knowledge, the **API contract (tech-docs)**, and tester feedback are all **cross-team artifacts** — they must live in the **shared spec repo** so every umbrella (FE/App/BE) reads the same source via `/sync`. Tech-docs specifically: BE authors the tech-design (API contract), commits + pushes it into the spec submodule (2-layer commit), and FE/App pull it on their next `/sync` to wire the real API in `/generate-code --phase=integration`. In single-service mode (no `spec_source`), these default under the repo root — still shared, same repo.
 
 ---