@educa-corp/sdd-framework 0.1.0

package/core/templates/prd.template.md

@@ -0,0 +1,224 @@
+# {TICKET}-{N} {Feature Name}
+
+<!--
+  Template này được sử dụng bởi workflow /generate-prd.
+  AI Agent sẽ điền các section dựa trên input từ PO.
+  Các placeholder {…} cần được thay thế bằng nội dung thực tế.
+
+  FORMAT CHUẨN: Business Rule = bảng 3 cột
+  ID | Business Rule | Business Logic (KHÔNG tách Business Logic ra khối riêng).
+
+  TERMINOLOGY:
+  - Tuân thủ 100% từ điển project: specs/domain-knowledge/business-dictionary.md
+    (KHÔNG dùng từ điển của project khác). Thay banned term bằng canonical term;
+    nếu phát hiện banned term trong input PO → thay + ghi chú trong "Giả định AI".
+  - Status/Enum values → tham chiếu core-entities.md (Enum Registry).
+
+  CROSS-REFERENCE (BẮT BUỘC): Bất kỳ chỗ nào nhắc đến một tính năng/ticket khác
+    (pre-condition, business rule, giả định, AC, hay bất kỳ section nào) → PHẢI gắn inline link:
+      [TICKET-ID khác](../{prd-slug-khác}/{TICKET-ID-khác}-{prd-slug-khác}.md)
+    Không để TICKET-ID dạng plain text nếu tồn tại file PRD tương ứng. (Mỗi PRD nằm trong feature-package riêng nên link trỏ sang folder anh em `../{prd-slug-khác}/`.)
+    Ngoài ra, ghi rõ quan hệ phụ thuộc trong "Tài liệu tham khảo" ở Appendix.
+
+  NEW TERM DETECTION: Nếu input PO xuất hiện thuật ngữ CHƯA CÓ trong business-dictionary.md
+    và lặp lại ≥ 2 lần → DỪNG lại, hỏi PO confirm trước khi tiếp tục:
+      + Thuật ngữ đó nghĩa gì trong ngữ cảnh hệ thống?
+      + English term chuẩn nên dùng là gì?
+      + Có cần bổ sung vào business-dictionary.md không?
+    Sau khi PO confirm → cập nhật business-dictionary.md (nếu PO đồng ý) rồi mới tiếp tục.
+
+  NUMBERING:
+  - UC ID: {TICKET}-{N}-UC{n}  (n bắt đầu từ 1, tăng theo từng use case)
+  - BR ID: {TICKET}-{N}-UC{n}-BR{m}  (m tăng LIÊN TỤC xuyên suốt PRD, KHÔNG reset mỗi UC)
+-->
+
+---
+
+## Metadata
+
+| Field         | Value                                    |
+|---------------|------------------------------------------|
+| **PRD ID**    | {TICKET}-{N}                             |
+| **Version**   | 1.0                                      |
+| **Status**    | draft                                    |
+| **Author**    | AI-assisted                              |
+| **PO**        | {tên PO}                                 |
+| **Domain**    | {domain}                                 |
+| **Created**   | {date}                                   |
+| **Updated**   | {date}                                   |
+| **Ticket**    | {TICKET}-{N}{ — nếu PO có link tracker thật, thêm bên cạnh: `{TICKET}-{N} ([Jira]({tracker_url}))`} |
+| **API Source** | *(để trống nếu greenfield — chỉ điền `existing` khi PRD bọc một API đã chạy production)* |
+
+---
+
+# Feature
+
+**{Feature Name}**
+
+{Đoạn mô tả tổng quan: feature làm gì, cho ai, giải quyết vấn đề gì — lấy từ product-definition.}
+
+---
+
+# 1. Tổng quan
+
+## a. User Story
+
+- **Là một (As a)** {persona}
+- **Tôi muốn (I want to)** {action}
+- **Để (So that)** {benefit}
+
+## b. Phạm vi
+
+> **Scope = ranh giới, KHÔNG phải đặc tả.** Mỗi mục một dòng ngắn "làm gì / không làm gì". Đừng nhét **cơ chế** (retry/timeout/nhánh lỗi → BR/BL) hay **định nghĩa thuật ngữ** (vd "điểm khởi tạo = …" → Business Definition / business-dictionary) vào đây.
+
+**In Scope**
+- {hạng mục trong phạm vi 1}
+- {hạng mục trong phạm vi 2}
+
+**Out of Scope** *(chỉ thêm khi có ranh giới cần nói rõ)*
+- {hạng mục ngoài phạm vi + lý do / chủ sở hữu}
+
+## c. Phụ thuộc liên service *(mức nghiệp vụ — KHÔNG mô tả API/event/kỹ thuật)*
+
+> Kế thừa từ Product Definition Phase 1 ("Phụ thuộc liên service"). Nếu contract do đối tác phát triển song song (xem `API Source`), ghi phụ thuộc partner vào đây.
+
+- {Cần {dữ liệu/năng lực} từ {feature/team/partner} — vì {lý do nghiệp vụ}} — hoặc "Không có"
+
+---
+
+# 2. Acceptance Criteria
+
+> Mỗi AC kế thừa liên kết "Bắt nguồn từ BR" của Product Definition (Phase 6), remap sang BR ID của PRD. Vì BR ID đã chứa số UC nên ref BR truy ngược được tới đúng UC.
+>
+> **1 AC = 1 tiêu chí NGHIỆM THU (outcome quan sát/kiểm được) + ref BR.** KHÔNG viết cơ chế trong AC (số lần retry, timeout, tên/chủ cờ, nhánh lỗi chi tiết) — cái đó thuộc **BR/BL** ở §3, AC chỉ trỏ tới. Nếu tiêu chí có **nhiều nhánh** → tách **bullet con** (mỗi ý một dòng), đừng dồn thành câu dài. Khi `/refine-prd` làm rõ thêm: chi tiết cơ chế → đẩy sang BR/BL; ở tầng AC thì tách bullet/AC mới — KHÔNG nối mệnh đề vào câu cũ (tránh AC thành "đoạn văn" và trùng BR).
+
+**AC1:** {Tiêu chí nghiệm thu, văn xuôi, kiểm chứng được.} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
+
+**AC2:** {Tiêu chí có nhiều nhánh — tách bullet:} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
+  - {nhánh/điều kiện 1 → kết quả kỳ vọng}
+  - {nhánh/điều kiện 2 → kết quả kỳ vọng}
+
+---
+
+# 3. Use Case
+
+#### {TICKET}-{N}-UC1: {Tên use case}
+
+**Actor:** {actor}
+
+**Description:** {mô tả luồng}
+
+**Pre-condition:**
+- {điều kiện trước 1}
+
+**Post-condition:**
+- {kết quả sau 1}
+
+**AC liên quan:** AC{x}, AC{y}  *(các AC mà UC này thoả — phải đúng bằng tập AC có ref BR trỏ về UC này ở §2)*
+
+**Business Rule**
+
+| ID | Business Rule | Business Logic |
+|----|---------------|----------------|
+| {TICKET}-{N}-UC1-BR1 | {luật ngắn gọn} | - {logic chi tiết, xuống dòng bằng `<br/>`}<br/>- {…} |
+| {TICKET}-{N}-UC1-BR2 | {…} | - {…} |
+
+---
+
+#### {TICKET}-{N}-UC2: {Tên use case}
+
+{lặp cấu trúc UC như trên; BR đánh số tiếp tục BR3, BR4…}
+
+---
+
+# 4. UI/UX Guidelines
+
+## a. User Flow
+
+```mermaid
+flowchart TD
+    START(["{điểm bắt đầu}"]) --> A{"{điểm quyết định}"}
+    A -->|{nhánh}| B["{bước}"]
+```
+
+## b. Wireframe
+
+### Screen 1: {Tên màn}
+
+| Thành phần | Chi tiết |
+|------------|----------|
+| **Screen** | {tên/ngữ cảnh màn} |
+| **Components** | - {thành phần 1}<br/>- {thành phần 2} |
+| **Actions** | - {hành động 1 → kết quả}<br/>- {hành động 2 → kết quả} |
+
+---
+
+### Screen 2: {Tên màn}
+
+{lặp bảng như trên cho từng màn}
+
+---
+
+# Appendix
+
+## Input gốc từ PO
+
+> {Trích nguyên văn input/ghi chú gốc của PO + đường dẫn product-definition nguồn.}
+
+## Tài liệu tham khảo
+
+- [{TICKET liên quan}](../{prd-slug-khác}/{TICKET-ID-khác}-{prd-slug-khác}.md) — {quan hệ: pre-condition / overlapping / related…}
+- BDD: [`./bdd/`](./bdd/)
+- Design spec: [`./design-spec/`](./design-spec/) — không áp dụng với feature thuần backend (không có màn hình)
+- Từ điển nghiệp vụ: [`specs/domain-knowledge/business-dictionary.md`](../../domain-knowledge/business-dictionary.md)
+- Domain knowledge: [`specs/domain-knowledge/{domain}.md`](../../domain-knowledge/{domain}.md)
+
+## Existing API Contract *(CHỈ brownfield — điền khi API Source = existing; greenfield BỎ QUA cả section này)*
+
+<!--
+  Chỉ dùng khi PRD bọc một API đã tồn tại trên hệ thống. PO ghi lại contract để:
+  - /generate-bdd (system) dùng trực tiếp làm input — không cần tổng hợp từ FE/App BDD;
+  - /generate-tech-docs chạy mode reverse-document (mô tả lại as-is, không design mới);
+  - /review-tech-docs bỏ qua cổng T7 cross-team sign-off (contract đã cố định).
+  Nếu greenfield (thiết kế mới) → xoá toàn bộ section này.
+-->
+
+| Method | Path | Auth | Request | Response |
+|--------|------|------|---------|----------|
+| {GET/POST/PUT/DELETE} | {/api/v1/path} | {Bearer / none} | `{ field: type }` | `{ field: type }` |
+
+**Error responses:**
+
+| HTTP Status | Error Code | Khi nào xảy ra |
+|-------------|------------|----------------|
+| {4xx/5xx} | {ERR_CODE} | {condition} |
+
+## Giả định AI
+
+> {Giả định / độ vênh AI phát hiện khi đối chiếu product-definition với domain-knowledge — cần PO review. AI KHÔNG tự hoà giải.}
+
+- **Q1 — [AI DRAFT] {tiêu đề}:** {mô tả độ vênh + nguồn}. **Cần PO chốt {điều gì}.**
+
+_(Nếu không có độ vênh: ghi "Không có — toàn bộ nội dung đã được PO xác nhận qua Product Definition.")_
+
+---
+
+# Change Log
+
+> Hiện tại: **v1.0** ({date}) · Lịch sử đầy đủ → [changelog](./changelog/{TICKET}-{N}-{slug}.changelog.md) *(file kho chỉ tạo khi changelog vượt 5 version)*
+
+<!-- Bảng phẳng, MỘT dòng/version, MỚI NHẤT TRÊN CÙNG. Chỉ giữ tối đa 5 version gần nhất ở đây;
+     cũ hơn → /refine-prd & /review-context tự dồn (rollover) sang file changelog/ ở link trên. -->
+
+| Version | Date | Changes (UC/AC/BR bị ảnh hưởng) |
+|---------|------|---------------------------------|
+| 1.0 | {date} | Bản đầu — sinh từ product-definition. |
+
+---
+
+<!--
+  NEXT STEPS:
+  Khi PRD được approve (status: approved), chạy:
+  /generate-bdd "specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md"
+  để sinh BDD feature specs từ PRD này.
+-->

package/core/templates/product-definition.template.md

@@ -0,0 +1,188 @@
+# {TICKET-ID} Product Definition — {Feature Name}
+
+<!--
+  Template này được dùng bởi workflow /define-product.
+  AI Agent điền từng section qua Q&A theo từng phase với PO.
+  Output là input có cấu trúc cho /generate-prd.
+
+  QUY TẮC:
+  - Mỗi section tương ứng với 1 phase trong workflow
+  - Section chưa đủ → giữ placeholder, KHÔNG được sang phase tiếp theo
+  - Trạng thái xác nhận của PO được ghi trong mỗi section
+-->
+
+---
+
+## Metadata
+
+| Field              | Value                          |
+|--------------------|--------------------------------|
+| **Ticket**         | {TICKET-ID}                    |
+| **Feature**        | {tên tính năng}                |
+| **Domain**         | {domain}                       |
+| **PO**             | {tên PO}                       |
+| **Created**        | {YYYY-MM-DD}                   |
+| **Status**         | in-progress / completed        |
+| **Completed Phase**| {số phase hoàn thành gần nhất} |
+
+---
+
+## Phase 0: Đồng bộ tri thức (Knowledge Sync)
+
+> ⚙️ AI tự thu thập — đây là **bối cảnh hệ thống**, KHÔNG phải yêu cầu nghiệp vụ do PO viết. Mục đích: chuẩn hoá thuật ngữ và nhận biết phần đã có để tái sử dụng. Không cần input từ PO.
+
+### Khái niệm / dữ liệu nghiệp vụ liên quan
+- {Khái niệm 1} — {mô tả ngắn}
+- {Khái niệm 2} — {mô tả ngắn}
+
+### Phần hệ thống / feature liên quan
+- {Phần 1}
+- {Phần 2}
+
+### Rule / Logic có sẵn
+- {Rule/logic từ các PRD có sẵn hoặc domain knowledge}
+
+### Chuẩn hoá thuật ngữ
+| Thuật ngữ trong input PO | Thuật ngữ chuẩn (business-dictionary) |
+|--------------------------|---------------------------------------|
+| {thuật ngữ gốc}          | {thuật ngữ chuẩn}                     |
+
+---
+
+## Phase 1: Định nghĩa tính năng (Feature Definition)
+
+> ✅ PO xác nhận: {Có/Không}
+
+### Bối cảnh (Context)
+{Bối cảnh nghiệp vụ dẫn đến tính năng này}
+
+### Tuyên bố vấn đề (Problem Statement)
+{Vấn đề cần giải quyết}
+
+### Mục tiêu (Goal)
+{Mục tiêu của tính năng}
+
+### Actor
+| Actor    | Vai trò            | Chính/Phụ |
+|----------|--------------------|-----------|
+| {Actor}  | {mô tả vai trò}    | Primary   |
+
+### Phạm vi (In Scope)
+- {Chức năng 1}
+- {Chức năng 2}
+
+### Ngoài phạm vi (Out of Scope)
+- {Hạng mục KHÔNG làm trong ticket này — kèm lý do / để dành pha sau}
+
+### User Story
+- **Là một (As a)** {vai trò}
+- **Tôi muốn (I want to)** {mục tiêu}
+- **Để (So that)** {giá trị nghiệp vụ}
+
+### Phụ thuộc liên service *(mức nghiệp vụ)*
+
+> Feature này cần **dữ liệu/năng lực** gì từ feature/team khác — KHÔNG mô tả API/event/callback (đó là kỹ thuật, thuộc Tech-docs).
+
+- {Cần {dữ liệu/năng lực} từ {feature/team} — vì {lý do nghiệp vụ}} — hoặc "Không có"
+
+---
+
+## Phase 2: Định nghĩa User Flow
+
+> ✅ PO xác nhận: {Có/Không}
+
+### Điểm vào (Entry Point)
+{Người dùng bắt đầu tương tác với tính năng như thế nào}
+
+### Các bước của Flow
+| Bước | Hành động       | Trạng thái/Kết quả nghiệp vụ | Ghi chú    |
+|------|-----------------|------------------------------|------------|
+| 1    | {hành động}     | {trạng thái/kết quả nghiệp vụ} | {ghi chú}  |
+| 2    | {hành động}     | {trạng thái/kết quả nghiệp vụ} | {ghi chú}  |
+
+### Màn hình & thành phần chính
+> Mức nghiệp vụ — nguồn cho Wireframe PRD (§4b) và độ phủ BDD (C.1). KHÔNG pixel/layout/màu.
+
+| Màn hình | Thành phần chính | Hành động → kết quả nghiệp vụ |
+|----------|------------------|-------------------------------|
+| {màn 1}  | {thành phần}     | {hành động → kết quả}         |
+
+### Điểm ra (Exit Point)
+{Kết quả cuối khi flow hoàn thành}
+
+### Edge Cases / Luồng lỗi & ngoại lệ
+> Các kịch bản thất bại nghiệp vụ ngoài happy path — input thiếu, điều kiện không thoả, thao tác đồng thời, phụ thuộc không sẵn sàng.
+- {Kịch bản: khi {điều kiện bất thường} → {kết quả nghiệp vụ kỳ vọng}}
+
+---
+
+## Phase 3: Nhật ký làm rõ (Clarification Log)
+
+> Ghi lại mọi câu hỏi và câu trả lời qua các vòng.
+
+### Vòng {N}
+| # | Nhóm     | Câu hỏi    | PO trả lời |
+|---|----------|------------|------------|
+| 1 | Context  | {câu hỏi}  | {trả lời}  |
+| 2 | Flow     | {câu hỏi}  | {trả lời}  |
+| 3 | Logic    | {câu hỏi}  | {trả lời}  |
+
+### Mục chưa giải quyết
+- {Mục chưa giải quyết — nếu còn tồn đọng, KHÔNG được sang Phase 4}
+
+---
+
+## Phase 4: Business Rules
+
+> ✅ PO xác nhận: {Có/Không}
+
+| Rule ID | Hành động/Trigger   | Quy tắc             | Điều kiện              |
+|---------|---------------------|---------------------|------------------------|
+| BR-1    | {hành động từ flow} | {business rule}     | {điều kiện áp dụng}    |
+| BR-2    | {hành động từ flow} | {business rule}     | {điều kiện áp dụng}    |
+
+---
+
+## Phase 5: Business Logic
+
+> ✅ PO xác nhận: {Có/Không}
+
+| Rule ID | Logic nghiệp vụ (rẽ nhánh / công thức / điều kiện) | Thông báo/kết quả nghiệp vụ khi lỗi |
+|---------|---------------------------------------------------|-------------------------------------|
+| BR-1    | {logic nghiệp vụ khi rule kích hoạt}              | {vd: báo "Số dư không đủ"}           |
+| BR-2    | {logic nghiệp vụ khi rule kích hoạt}              | {…}                                 |
+
+---
+
+## Phase 6: Acceptance Criteria
+
+> ✅ PO xác nhận: {Có/Không}
+
+| AC ID | Mô tả                  | Hành vi kỳ vọng           | Bắt nguồn từ |
+|-------|------------------------|---------------------------|--------------|
+| AC-1  | {mô tả tiêu chí}       | {hành vi kỳ vọng}         | BR-{N}       |
+| AC-2  | {mô tả tiêu chí}       | {hành vi kỳ vọng}         | BR-{N}       |
+
+---
+
+## Phase 7: Báo cáo kiểm chứng (Validation Report)
+
+### Ma trận độ phủ (Coverage Matrix)
+| Hành động Flow | Có Rule? | Có Logic? | Có AC? | Status |
+|----------------|----------|-----------|--------|--------|
+| {Hành động 1}  | ✅/❌    | ✅/❌     | ✅/❌  | OK/GAP |
+
+### Xung đột phát hiện
+- {Mô tả xung đột — hoặc "None"}
+
+### Mục còn thiếu
+- {Rule/AC/logic còn thiếu — hoặc "None"}
+
+---
+
+<!--
+  NEXT STEPS:
+  Khi Product Definition hoàn tất (Status: completed), chạy:
+  /generate-prd {path-to-this-file}
+  để sinh PRD từ Product Definition này.
+-->

package/core/templates/project-context.yaml

@@ -0,0 +1,161 @@
+# =============================================================
+# Project Context — AI-First Spec-Driven Development
+# =============================================================
+# This is the SINGLE SOURCE OF TRUTH for project-specific
+# paths, tools, and routing used by all workflows.
+#
+# Workflows reference this file for WHERE to find things.
+# Workflow steps define WHAT to do (universal best practices).
+# =============================================================
+#
+# HOW AI AGENTS USE THIS FILE:
+# 1. Open this file at the start of any workflow
+# 2. Parse the YAML structure
+# 3. When a workflow says "→ key.subkey", look up that key
+#    and use the resolved value as the actual path
+# 4. All paths are RELATIVE to workspace root
+# 5. For "{domain}", substitute the feature's domain (PRD: row `Domain` in Metadata / folder path; .feature: @trace.domain)
+# =============================================================
+
+project:
+  name: "{{PROJECT_NAME}}"
+  description: "{{PROJECT_DESCRIPTION}}"
+
+# ----- File Paths -----
+# All paths are relative to workspace root.
+paths:
+  # Feature-Package Layout:
+  #   specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md  — PRD document
+  #   specs/{domain}/{prd-slug}/bdd/             — BDD .feature files
+  #   specs/{domain}/{prd-slug}/tech-docs/       — Technical design docs
+  #   specs/{domain}/{prd-slug}/design-spec/     — Design specs (FE/App only)
+  #   .trace/{domain}/{prd-slug}/{UC-ID}.tsv     — Trace state
+  #
+  # specs_dir is the unified root for all spec artifact types (PRD, BDD, tech-docs, design-spec).
+  # prd-slug is derived from the PRD folder path — not a separate config variable.
+  specs_dir: "specs"
+  templates_dir: "specs/templates"
+  feature_template: ".agent/templates/feature.template"   # SoT skeleton .feature (dùng bởi /generate-bdd qua {{include}})
+  bdd_writing_guide: "specs/templates/bdd-writing-guide.md"
+  trace_report: "specs/.trace/trace-report.md"
+
+  # PRD template (PRDs are at specs/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md)
+  prd_template: "specs/templates/prd.template.md"
+  refinement_dir: ".agent/review"
+
+  # QC's OWN analysis/design working docs (qc-analyze/plan/design-test outputs:
+  # REQUIREMENT_ANALYSIS.md, DOC_GAPS.md, TEST_PLAN.md, test-cases/*.Test.md).
+  # One subfolder per UC: {qc_dir}/{UC-ID}/. Default "docs" (the QC team's own
+  # convention), VISIBLE — not hidden under .agent/. NOTE: specs (PRD / .feature /
+  # design-spec) are NOT here — they come from the PO spec submodule (spec_source).
+  qc_dir: "docs"
+
+  # WHERE the qc-* commands LOAD their skills from (qa-analyst / qa-designer / qa-planner
+  # / qa-reviewer / qa-runner + DOC_GAPS.template.md). Default = the framework-bundled
+  # copy at .agent/skills/qc (works standalone). The QC team OWNS these skills in their
+  # canonical repo (ai-automation-qc-base) — point this at that repo/submodule (e.g.
+  # "qc-base/.claude/skills") so the skills evolve INDEPENDENTLY and are NOT overwritten
+  # by framework upgrade (--init / upgrade.sh rewrite only .agent/, never this path).
+  qc_skills_dir: ".agent/skills/qc"
+
+  # Product Definitions
+  product_definitions_dir: "specs/product-definition"
+  product_definition_template: "specs/templates/product-definition.template.md"
+
+  # Domain Knowledge
+  domain_knowledge_dir: "specs/domain-knowledge"
+  business_dictionary: "specs/domain-knowledge/business-dictionary.md"
+  core_entities: "specs/domain-knowledge/core-entities.md"
+
+  # Project Lessons (guardrails accumulated via /learn — loaded by context-loader Step 6.7)
+  # Single-service default below. In umbrella/service mode, set this in each service's
+  # .agent/project-context.yaml to ".agent/project-lessons.md" (resolved per service_root).
+  lessons_file: "specs/domain-knowledge/lessons-learned.md"
+
+  # Tech Docs (BE-authored API contract).
+  # Merged into specs_dir in the feature-package layout:
+  # tech-docs live at specs/{domain}/{prd-slug}/tech-docs/.
+  # In umbrella mode with spec_source set, context-loader auto-routes this to
+  # {spec_source}/specs so FE/App read the contract via the spec submodule.
+  tech_docs_dir: "specs"
+
+  # Design Specs (FE/App platforms only — web, app).
+  # In the feature-package layout, design-specs live at specs/{domain}/{prd-slug}/design-spec/.
+  # This variable is no longer needed as a separate path — derived from specs_dir.
+  # design_spec_dir: "specs/design-spec"   ← removed; use specs_dir instead
+
+  # Trace (internal structure: .trace/{domain}/{prd-slug}/{UC-ID}.tsv)
+  trace_dir: ".trace"
+
+  # Tester / QC feedback (written by /report-bug and /propose-scenario).
+  # These live in the SHARED spec repo so PO/Dev see them on their next /sync.
+  # In umbrella mode, context-loader auto-resolves them under {spec_source}/feedback/.
+  bug_reports_dir: "feedback/bug-reports"
+  bdd_proposals_dir: "feedback/bdd-proposals"
+  # PRD change requests (new requirement found in test, not covered by any AC) —
+  # written by /propose-scenario Case B so the PO can add/extend an AC then re-/generate-bdd.
+  prd_change_requests_dir: "feedback/prd-change-requests"
+
+tech_stack:
+  language: "{{LANGUAGE}}"              # e.g., Java 17 / TypeScript / C# / Go
+  framework: "{{FRAMEWORK}}"           # e.g., Spring Boot 3.2 / Angular 17 / .NET 8
+  build_tool: "{{BUILD_TOOL}}"         # e.g., Maven / npm / dotnet / go
+  test_framework: "{{TEST_FRAMEWORK}}" # e.g., JUnit 5 + Mockito / Jest / xUnit
+  database: "{{DATABASE}}"             # e.g., PostgreSQL / MySQL / MongoDB
+  module: "{{MODULE}}"                 # e.g., java-spring / angular / dotnet / golang / context-engineering
+
+conventions:
+  build_command: "{{BUILD_COMMAND}}"   # e.g., mvn clean install -DskipTests
+  test_command: "{{TEST_COMMAND}}"     # e.g., mvn test
+  service_run: "{{RUN_COMMAND}}"       # e.g., mvn spring-boot:run
+  ticket_prefix: "{{TICKET_PREFIX}}"  # e.g., PROJ / FEAT / UC
+
+domains:
+  - "{{DOMAIN_1}}"
+  # - "{{DOMAIN_2}}"
+
+# ----- Multi-Service / Umbrella Setup -----
+# Fill this section ONLY if this is an UMBRELLA repo that contains multiple
+# service submodules. Leave commented out for single-service projects.
+#
+# setup:
+#   mode: umbrella                            # "umbrella" | "single" (default: single)
+#   spec_source: "{{SPEC_SUBMODULE_PATH}}"   # path to PO spec submodule, e.g. "free-trial-specs"
+#
+# When spec_source is set, context-loader auto-derives (ALL specs live in the spec repo
+# using the feature-package layout; service submodules hold only code):
+#   specs_dir            → {spec_source}/specs                # unified root — PRD/BDD/tech-docs/design-spec
+#   tech_docs_dir        → {spec_source}/specs                # merged into specs_dir
+#   domain_knowledge_dir → {spec_source}/specs/domain-knowledge
+#   trace_dir            → {spec_source}/.trace               # structure: .trace/{domain}/{prd-slug}/{UC-ID}.tsv
+# (You can still override these manually in paths: section below.)
+# With spec_source set, only ONE override is needed instead of four separate dir vars.
+#
+# services:                                   # domain → service submodule routing
+#   {{DOMAIN_1}}:                             # must match the PRD's `Domain` (Metadata row) / folder path segment
+#     path: "{{SERVICE_SUBMODULE_DIR}}"       # relative path to service submodule (code + .trace/)
+#     module: "{{STACK_MODULE}}"              # e.g., java-spring, nextjs, flutter
+#     # NOTE: with spec_source set, BDD + tech-docs are cross-team and live in the spec repo —
+#     # do NOT pin per-service specs_dir / tech_docs_dir here (they would be ignored).
+#     # Per-service specs_dir / tech_docs_dir apply ONLY when there is no spec_source.
+#
+# IMPORTANT — per-service CLAUDE.md:
+#   Each service submodule should have its OWN CLAUDE.md ({path}/CLAUDE.md) defining its
+#   architecture + coding standards for ITS stack. context-loader loads CLAUDE.md in two
+#   layers: root CLAUDE.md (umbrella-wide shared rules) + {service}/CLAUDE.md (overlay,
+#   wins on conflict for architecture/coding-standards). The agent sits at the umbrella
+#   root, so without a service CLAUDE.md, code generation falls back to umbrella defaults
+#   (likely the wrong stack). Generate one per service via /setup-ai-first inside each.
+#   {{DOMAIN_2}}:
+#     path: "{{SERVICE_2_DIR}}"
+#     module: "{{STACK_MODULE}}"
+#     specs_dir: "{{SERVICE_2_DIR}}/specs"
+#     tech_docs_dir: "{{SERVICE_2_DIR}}/specs"
+
+# ----- Architecture -----
+architecture:
+  style: "{{ARCH_STYLE}}"              # e.g., Layered / Clean / Hexagonal
+  layers: "{{LAYER_STACK}}"            # e.g., Controller → Facade → Service → Repository
+  key_rules:
+    - "{{ARCH_RULE_1}}"
+    - "{{ARCH_RULE_2}}"