@anhth2/spec-driven-dev-plugin 0.5.0

package/steps/spawn-agent.md

@@ -0,0 +1,123 @@
+# Sub-Agent Orchestration Pattern
+
+Used by heavy commands when the target exceeds the complexity threshold.
+The main session becomes a **lightweight orchestrator** — it only coordinates.
+Each unit of work runs in its own sub-agent with a fresh context window.
+
+---
+
+## Complexity Thresholds
+
+| Signal | Threshold | Action |
+|--------|-----------|--------|
+| UC count in PRD | > 3 UCs | spawn 1 agent per UC |
+| PRD length | > 300 lines | spawn agents regardless of UC count |
+
+If **either** threshold is exceeded → switch to orchestration mode.
+
+---
+
+## Orchestrator Steps (main session)
+
+### Step A — Build slim context
+
+Extract only what sub-agents need — do NOT pass full CLAUDE.md or full business-dictionary:
+
+```json
+{
+  "project_name": "{project.name}",
+  "tech_stack": {
+    "language":       "{tech_stack.language}",
+    "framework":      "{tech_stack.framework}",
+    "build_tool":     "{tech_stack.build_tool}",
+    "test_framework": "{tech_stack.test_framework}",
+    "database":       "{tech_stack.database}",
+    "module":         "{tech_stack.module}"
+  },
+  "conventions": {
+    "build_command":  "{conventions.build_command}",
+    "commit_format":  "{conventions.commit_format}"
+  },
+  "paths": {
+    "specs_dir":     "{paths.specs_dir}",
+    "prd_dir":       "{paths.prd_dir}",
+    "trace_dir":     "{paths.trace_dir}",
+    "tech_docs_dir": "{paths.tech_docs_dir}"
+  },
+  "architecture_summary": "<3-5 bullet points: layer order + key rules only>",
+  "domains": ["{domain1}", "{domain2}"],
+  "banned_terms": ["{term1}", "{term2}"]
+}
+```
+
+### Step B — Extract UC list
+
+Scan the target PRD for `#### {TICKET-ID}-UC{N}:` headings.
+Build list: `[ { uc_id, uc_name, line_start, line_end } ]`
+
+### Step C — Announce plan
+
+```
+High complexity detected — {N} UCs / {L} lines in {prd_file}
+Spawning {N} sub-agents (1 per UC)...
+  Agent 1 → {TICKET-ID}-UC1: {UC name}
+  Agent 2 → {TICKET-ID}-UC2: {UC name}
+  ...
+```
+
+### Step D — Spawn one sub-agent per UC
+
+Build payload and invoke Agent tool for each UC:
+
+```json
+{
+  "_agent_mode": true,
+  "command":      "{generate-bdd | generate-code | generate-tests}",
+  "uc_id":        "{TICKET-ID}-UC{N}",
+  "target_file":  "{absolute path to PRD or feature file}",
+  "uc_section":   { "line_start": {N}, "line_end": {N} },
+  "context":      { "<slim context from Step A>" }
+}
+```
+
+Serialize this JSON and pass as `$ARGUMENTS` when invoking the sub-agent command.
+
+### Step E — Collect and merge results
+
+Each sub-agent returns:
+```json
+{
+  "uc_id":         "{TICKET-ID}-UC{N}",
+  "files_created": ["path/to/file1", "path/to/file2"],
+  "status":        "success | error",
+  "errors":        []
+}
+```
+
+Merge into a single report (follow report-footer.md format).
+If any sub-agent errors → list them clearly and suggest re-run for that UC only.
+
+---
+
+## Sub-Agent Entry Point (called commands)
+
+When `gate.md Step 0` detects `_agent_mode: true`:
+
+1. Parse full payload from `$ARGUMENTS`
+2. **Skip context-loader.md** — use `payload.context` directly
+3. **Scope to `payload.uc_id` only** — do not process other UCs in the file
+4. Read only the PRD section between `payload.uc_section.line_start` and `line_end`
+5. Execute the command's normal logic for this single UC
+6. Return structured result JSON (Step E format above)
+
+---
+
+## Context Window Savings
+
+| Mode | What loads per session |
+|------|------------------------|
+| Single session (≤ 3 UC) | Full context + full PRD + all UCs |
+| Orchestrator | Slim context + UC headings only |
+| Each sub-agent | Slim context + **1 UC section only** |
+
+The larger the PRD, the bigger the saving per sub-agent.

package/templates/architecture.template.md

@@ -0,0 +1,113 @@
+# §1. Project Overview
+
+Project    : {{PROJECT_NAME}}
+Language   : {{LANGUAGE}}          # e.g., Java 17 / TypeScript / C# / Go
+Framework  : {{FRAMEWORK}}         # e.g., Spring Boot 3.2 / Angular 17 / .NET 8
+Build      : {{BUILD_COMMAND}}     # e.g., mvn clean install -DskipTests / dotnet build / ng build
+Test       : {{TEST_COMMAND}}      # e.g., mvn test / dotnet test / ng test
+Domains    : {{COMMA_SEPARATED_DOMAINS}}
+
+# §2. Architecture
+
+style: "{{ARCH_STYLE}}"  # e.g., Layered / Clean / Hexagonal / Component-based
+
+layers: "{{LAYER_STACK}}"
+# Examples:
+#   Java/Spring:  Controller → Facade → Service → Repository
+#   .NET Clean:   Presentation → Application → Domain → Infrastructure
+#   Angular:      Component → Service → HTTP Client → Backend API
+#   Go:           Handler → UseCase → Repository → Domain
+
+rules:
+  - "{{ARCH_RULE_1}}"  # e.g., Controllers must not contain business logic
+  - "{{ARCH_RULE_2}}"  # e.g., Services own transaction boundaries
+  - "{{ARCH_RULE_3}}"  # e.g., Repositories must not call services
+
+# Layer dependency direction (inner layers must not depend on outer):
+# {{OUTER_LAYER}} → {{MIDDLE_LAYER}} → {{INNER_LAYER}}
+
+# §3. Coding Standards
+
+naming:
+  classes: "{{CLASS_NAMING}}"        # e.g., PascalCase / PascalCase+Suffix
+  methods: "{{METHOD_NAMING}}"       # e.g., camelCase / PascalCase
+  packages: "{{PACKAGE_NAMING}}"     # e.g., lowercase / lowercase.snake_case
+  files: "{{FILE_NAMING}}"           # e.g., PascalCase.java / kebab-case.ts
+
+patterns:
+  response_wrapper: "{{RESPONSE_WRAPPER}}"  # e.g., ApiResponse<T> / Result<T> / IActionResult
+  mapping: "{{MAPPING_LIBRARY}}"            # e.g., MapStruct / AutoMapper / manual
+  exception_base: "{{BASE_EXCEPTION}}"      # e.g., ResourceNotFoundException / DomainException
+
+forbidden:
+  - "Magic numbers — use named constants"
+  - "Debug print statements in production code"
+  - "{{PROJECT_SPECIFIC_FORBIDDEN_PATTERN}}"
+
+# §4. API Conventions
+
+versioning: "{{API_VERSIONING}}"     # e.g., /v1/ prefix / header-based / query param
+auth: "{{AUTH_MECHANISM}}"           # e.g., JWT Bearer / OAuth2 / API Key
+
+http_status:
+  get_list:    200   # paginated or full list
+  get_single:  200
+  create:      201
+  update:      200
+  delete:      204
+  bad_request: 400
+  unauthorized: 401
+  forbidden:   403
+  not_found:   404
+  server_error: 500
+
+error_response_format: |
+  {
+    "code": "ERROR_CODE",
+    "message": "Human readable message",
+    "details": {}   // optional field-level errors
+  }
+
+# §5. Error Handling
+
+not_found_exception: "{{NOT_FOUND_EXCEPTION_CLASS}}"  # e.g., ResourceNotFoundException
+validation_exception: "{{VALIDATION_EXCEPTION_CLASS}}" # e.g., ValidationException
+domain_exception: "{{DOMAIN_EXCEPTION_CLASS}}"         # e.g., DomainException / BusinessRuleViolationException
+
+global_handler: "{{GLOBAL_EXCEPTION_HANDLER}}"  # e.g., @ControllerAdvice / ExceptionHandlerMiddleware
+
+rules:
+  - "Never swallow exceptions silently"
+  - "Log at error level with full stack trace for 5xx"
+  - "{{PROJECT_SPECIFIC_ERROR_RULE}}"
+
+# §6. Testing Standards
+
+unit_test_framework: "{{UNIT_TEST_FW}}"        # e.g., JUnit 5 + Mockito / xUnit + Moq / Jest
+integration_test_framework: "{{IT_TEST_FW}}"   # e.g., Spring Boot Test / WebApplicationFactory
+
+coverage_targets:
+  unit: "{{UNIT_COVERAGE_PCT}}%"          # e.g., 80%
+  integration: "{{IT_COVERAGE_PCT}}%"     # e.g., key flows covered
+
+naming_pattern: "{{TEST_METHOD_NAMING}}"  # e.g., methodName_whenCondition_shouldExpectation
+
+rules:
+  - "Unit tests mock direct dependencies only"
+  - "Integration tests cover happy path + main error paths"
+  - "Every scenario in .feature must have a corresponding test"
+
+# §7. Git Conventions
+
+branch_feature: "feature/{{TICKET_PREFIX}}-{N}-{slug}"
+branch_fix:     "fix/{{TICKET_PREFIX}}-{N}-{slug}"
+branch_chore:   "chore/{slug}"
+
+commit_feature: "feat({{TICKET_PREFIX}}-{N}): {description}"
+commit_fix:     "fix({{TICKET_PREFIX}}-{N}): {description}"
+commit_chore:   "chore: {description}"
+commit_docs:    "docs: {description}"
+
+pr_title: "{{TICKET_PREFIX}}-{N}: {feature name}"
+pr_requires_review: true
+pr_branch_protection: "{{BASE_BRANCH}}"  # e.g., main / develop

package/templates/feature.template

@@ -0,0 +1,259 @@
+# ============================================================
+# BDD Feature Template — KVLoyalty AI Native Pipeline (v2)
+# ============================================================
+# Instructions:
+#   1. Copy this file và rename: {TICKET_ID}-UC{N}-feature-name.feature
+#   2. Điền @trace metadata (required)
+#   3. Khai báo Context của UC (1 lần, đầu file)
+#   4. Tạo/cập nhật dataset YAML cùng domain: specs/features/{domain}.testdata.yaml
+#   5. Viết Scenario — mỗi SC PHẢI có dòng `# Side-effects:` ngay trên
+#   6. Đặt file ở: specs/features/{domain}/
+#   7. Chạy: /generate-code
+# ============================================================
+#
+# RULE VIẾT BDD BẮT BUỘC (xem bdd-writing-guide.md PART A + C):
+#   R1  Given/When/Then Semantics  — Given=state, When=action, Then=outcome (mỗi SC đủ G/W/T)
+#   R2  One Behavior Per Scenario  — 1 SC = 1 behavior; KHÔNG chain When-Then
+#   R3  Ubiquitous Language        — KHÔNG dùng UI selector / API name / tech term
+#   R4  Outside-in Naming          — Tên SC mô tả business outcome, KHÔNG có "click"/"(Case X)"/component name
+#   R5  Declarative over Imperative — Mô tả WHAT (intent business), KHÔNG HOW (UI mechanic)
+#   R6  Observable Outcomes Only   — Then assert outcome quan sát được, KHÔNG UI trung gian/internal state
+#   R7  Key Examples / Concrete    — Dùng concrete values, KHÔNG "hợp lệ" chung chung
+#   R8  Independence               — SC chạy độc lập, KHÔNG phụ thuộc state SC khác
+#   R9  Test Data Completeness     — Data table có đủ field external system để derive expected Then
+#   R10 Scope Boundary Explicit    — Cross-UC reference dùng wording navigation + Note comment
+# PROJECT COMPLIANCE (must-pass, fail review nếu thiếu):
+#   C.1 Wireframe Coverage         — Mọi component/action wireframe có ≥1 SC
+#   C.2 PRD Traceability           — Mọi AC/BR (kèm bullet) map về ≥1 SC
+#   C.3 Business Dictionary        — Dùng đúng term, đề xuất term mới qua DICTIONARY-SUGGESTION
+#   C.4 Banned Terms Compliance    — 0 banned term (auto-grep): SKU/Customer/JS SDK/Cửa hàng/...
+#   C.5 NHÓM Grouping Convention   — Scenarios gom theo CHỦ ĐỀ NGHIỆP VỤ (NHÓM N) — xem §NHÓM GROUPING CONVENTION dưới
+# ============================================================
+
+# --- TRACE METADATA (REQUIRED) ---
+# @trace.id: {TICKET_ID}-UC{N}
+# @trace.title: <Tên tính năng bằng tiếng Việt>
+# @trace.revision: 1
+# @trace.domain: <identity|loyalty|membership|messaging|store-management>
+# @trace.service: <KVLoyalty.Identity|KVLoyalty.Loyalty|...>
+# @trace.status: draft|review|approved
+# @trace.author: <tên tác giả>
+# @trace.created_at: <YYYY-MM-DD>
+# @trace.prd: <TICKET-ID hoặc để trống>
+# @trace.prd_version: <version PRD tại thời điểm viết — để drift-detector so sánh>
+# @trace.business_rules: <{TICKET_ID}-UC{N}-BR{M}, ...>
+# @trace.dataset: <{domain}.testdata.yaml — bắt buộc nếu BDD reference dataset>
+
+# === CONTEXT (áp dụng cho toàn Feature) ===
+# Actor:     <vai trò thực hiện hành động, vd: Consumer, Staff, System>
+# Screens:   <các màn liên quan, vd: Cart → Confirm Order → Order Detail>
+# Entities:  <entity nghiệp vụ, vd: Order, OrderItem, Consumer, Branch>
+# Pre-state: <state chung trước khi vào các scenario>
+
+# === SCOPE ===
+# In:  <những gì UC này cover>
+# Out: <những gì KHÔNG thuộc UC này — link sang UC khác / feature khác (R10)>
+
+# === BUSINESS DEFINITION (MANDATORY) ===
+# Quick reference các thuật ngữ dùng trong feature này. SoT chi tiết: business-dictionary.md
+# Mục đích: reader đọc 1 lần hiểu ngay khái niệm trước khi xem scenarios.
+#
+# <Term 1> (English mapping): <định nghĩa ngắn gọn, vd cấu trúc, scope>
+# <Term 2>: <định nghĩa>
+# ...
+#
+# === Test data convention (R9) ===
+# Khai báo default value khi data table không có cột tương ứng.
+# VD: "SC không khai báo cột customerOrdered → ngầm hiểu customerOrdered = 0 (chưa có khách đặt)"
+# VD: "SC không khai báo cột toggle → ngầm hiểu toggle = Hiện (default Ẩn/Hiện trạng thái)"
+#
+# === Popup/Modal Lifecycle (B.2.4 — bắt buộc nếu feature là popup/modal) ===
+# - Open trigger:   <khi nào popup hiển thị, vd: click menu sidebar>
+# - Close trigger:  <khi nào popup đóng, vd: F5 / click X / ESC / navigate away>
+# - Refresh model:  <data refresh khi nào, vd: mỗi lần open (NO CACHE) / persisted / polling>
+# - State reset:    <state nào reset khi đóng/mở lại, vd: pagination, expand, dropdown selection>
+
+# === DISPLAY LOGIC MATRIX (optional — bắt buộc nếu display logic phụ thuộc ≥2 dimension, B.1.7) ===
+# Enumerate full matrix N×M case + map mỗi case → SC.
+# Tên SC theo pattern: `<cấu trúc>: <outcome>` — KHÔNG dùng "(Case X)" suffix.
+# VD ma trận `{số thuộc tính: 0/1/≥2} × {số đơn vị tính: 0/1/≥2}` = 9 case:
+#
+# | # | Dim1 | Dim2 | Format hiển thị                              | SC   |
+# |---|------|------|----------------------------------------------|------|
+# | 1 | 0    | 0    | `Tên hàng`                                   | SC{} |
+# | 2 | 0    | 1    | `Tên hàng (đơn vị)`                          | SC{} |
+# | ... | ... | ...  | ...                                          | ...  |
+
+# === DICTIONARY REFERENCES (R3 + C.4) ===
+# Liệt kê các term từ business-dictionary.md mà feature này dùng → pointer cho reviewer auto-check.
+# Banned terms (xem business-dictionary.md § Banned Terms) MUST NOT appear: 0 match khi grep.
+#
+# Terms dùng trong feature này:
+# - <Term 1> (xem dictionary line {N})
+# - <Term 2> (xem dictionary line {M})
+# - ...
+
+Feature: <Tên tính năng bằng tiếng Việt>
+  Với vai trò là <vai trò>
+  Tôi muốn <hành động>
+  Để <lợi ích nghiệp vụ>
+
+  # --- DATASET REFERENCE CONVENTION ---
+  # Ưu tiên dùng ALIAS (tiếng Việt) thay vì ID kỹ thuật, để BDD dễ đọc.
+  # Backtick ID chỉ dùng khi cần precision (vd: assertion về mã đơn).
+  #
+  # Ví dụ:
+  #   ✅ Given đơn hàng draft "Đơn COD giao hàng — 2× áo + 1× quần, total 650K"
+  #   ✅ Then đơn được gán mã `ZMA{id}` nhận từ Retail
+  #   ❌ Given đơn hàng draft là `ORD_COD_DRAFT_001`   ← khó đọc, hạn chế
+
+  Background:
+    Given <điều kiện tiên quyết chung — dùng alias từ dataset>
+    # Ví dụ: Given consumer "Khách mới đã cấp quyền Zalo" ở màn "Xác nhận đơn hàng"
+    #        của gian hàng "Cửa hàng Thời Trang (đang kích hoạt)"
+
+  # ============================================================
+  # § NHÓM GROUPING CONVENTION (C.5 — bắt buộc cho mọi feature ≥3 SCs)
+  # ============================================================
+  # Mục đích: organize scenarios theo CHỦ ĐỀ NGHIỆP VỤ để dễ navigate + scope-awareness, KHÔNG
+  # theo phân loại happy/negative/edge (deprecated section markers HAPPY-PATH / NEGATIVE-CASE / EDGE-CASE).
+  #
+  # Quy tắc:
+  #   1. **Gom theo chủ đề business** — mỗi NHÓM = 1 business theme (flow / state / behavior subset).
+  #      ✅ NHÓM 1: Khởi tạo gian hàng thành công với dữ liệu mặc định (BR1, BR2)
+  #      ✅ NHÓM 2: Resume khi onboarding bị gián đoạn (BR1 resume)
+  #      ✅ NHÓM 3: Xử lý lỗi khởi tạo (BR3)
+  #      ❌ NHÓM 1: HAPPY-PATH         ← chia theo loại path, không phải chủ đề
+  #      ❌ NHÓM 1: COD scenarios      ← UI feature, không phải business theme
+  #
+  #   2. **Mỗi NHÓM có thể chứa cả @happy + @edge + @negative SCs cùng chủ đề** — KHÔNG tách happy/edge ra 2 NHÓM riêng.
+  #      Ví dụ: NHÓM "Xử lý lỗi khi khởi tạo" chứa SC happy retry + SC edge X close + SC negative no retry.
+  #      Tag taxonomy (@happy/@edge/@cross-system per B.2.3) áp dụng ở SC level — KHÔNG ở NHÓM level.
+  #
+  #   3. **Format NHÓM header** (3 dòng comment box):
+  #         # ==========================================================
+  #         # NHÓM N: <Chủ đề> (<BR refs nếu áp dụng>)
+  #         # ==========================================================
+  #      Indent 2 spaces (cùng level với Background + Scenario).
+  #
+  #   4. **Đánh số NHÓM tuần tự** từ 1 → N. Không skip số. Reorder NHÓM được — KHÔNG ảnh hưởng SC IDs.
+  #
+  #   5. **SC trong NHÓM KHÔNG cần theo thứ tự ID** — VD NHÓM 2 có thể chứa SC8, SC4, SC11 nếu cùng chủ đề.
+  #      SC IDs tuần tự theo lifecycle (skill §3.4), KHÔNG theo NHÓM ordering.
+  #
+  #   6. **Khi nào skip NHÓM**: feature có <3 SCs → có thể bỏ NHÓM headers (không value to organize so few).
+  #      Đơn giản đặt SCs nối tiếp sau Background. Feature ≥3 SCs → BẮT BUỘC NHÓM.
+  #
+  # Pattern thường gặp (gợi ý theme — tuỳ chỉnh per UC):
+  #   - "Khởi tạo / Lưu thành công — các tổ hợp data hợp lệ" (gom happy + alternative)
+  #   - "Validation / Chặn lưu khi không hợp lệ" (gom negative + edge validation)
+  #   - "Xử lý lỗi — API fail / system error" (gom negative + recovery)
+  #   - "Hủy thay đổi / Đóng modal không lưu" (gom edge UX)
+  #   - "Hành vi popup / dialog — multi-select / persist / boundary" (gom edge UX behavior)
+  #   - "Hiệu ứng cross-system / Consumer view" (gom @cross-system SCs)
+  #   - "Idempotency & Concurrency" (gom edge concurrency)
+  #   - "State transition / Recovery completion" (gom @cross-UC behavior chains)
+  #
+  # Ví dụ NHÓM structure cho UC có 9 SCs (LOYAL-32-UC1 reference):
+  #   NHÓM 1: Lưu cấu hình thành công — các tổ hợp PTTT hợp lệ (BR1, BR2)    → SC1, SC2, SC3, SC4
+  #   NHÓM 2: Chặn lưu khi cấu hình không hợp lệ (BR1, BR2) + lỗi hệ thống   → SC5, SC6, SC7
+  #   NHÓM 3: Hủy thay đổi — đóng Modal không lưu                            → SC8
+  #   NHÓM 4: Initial State — Modal phản ánh cấu hình hiện tại               → SC10
+
+  # ==========================================================
+  # NHÓM 1: <Chủ đề business 1> (<BR refs nếu cần>)
+  # ==========================================================
+
+  # Side-effects: <liệt kê NGẮN GỌN các hậu quả Then phải verify — 1 dòng>
+  # @trace.scenario: {TICKET_ID}-UC{N}-SC1
+  # @trace.sc_version: 1.0
+  # @trace.business_rules: {TICKET_ID}-UC{N}-BR{M}
+  @happy
+
+  Scenario: <Mô tả luồng chính — dùng động từ CHÍNH XÁC (tạo/nhận/gán/đồng bộ)>
+    Given <state đầu vào — dùng alias từ dataset, vd: "Đơn COD giao hàng — 2× áo + 1× quần">
+    When <hành động duy nhất>
+    Then <kết quả chính — dùng backtick ID khi cần precision, vd: mã `ZMA{id}`>
+      And <side-effect 1 đã khai báo ở header>
+      And <side-effect 2 đã khai báo ở header>
+      # ... đủ với danh sách Side-effects ở trên (Rule R2)
+
+  # Side-effects: <...>
+  # @trace.scenario: {TICKET_ID}-UC{N}-SC2
+  # @trace.sc_version: 1.0
+  # @trace.business_rules: {TICKET_ID}-UC{N}-BR{M}
+  @happy @alternative
+
+  Scenario: <Cùng chủ đề NHÓM 1 nhưng path khác — vd enum value khác (Rule R4 enum symmetry)>
+    Given <state đầu vào>
+    When <hành động>
+    Then <kết quả>
+
+  # ==========================================================
+  # NHÓM 2: <Chủ đề business 2 — VD: Xử lý lỗi / Validation> (<BR refs>)
+  # ==========================================================
+
+  # Side-effects: <...>
+  # @trace.scenario: {TICKET_ID}-UC{N}-SC3
+  # @trace.sc_version: 1.0
+  # @trace.business_rules: {TICKET_ID}-UC{N}-BR{M}
+  @edge
+
+  Scenario: <Tình huống biên / lỗi cùng chủ đề NHÓM 2>
+    Given <state đầu vào>
+    When <hành động>
+    Then <xử lý lỗi mong đợi>
+
+  # ==========================================================
+  # NHÓM 3: <Chủ đề business 3 — VD: Cross-system / Hiệu ứng downstream> (<BR refs>)
+  # ==========================================================
+
+  # Side-effects: <...>
+  # @trace.scenario: {TICKET_ID}-UC{N}-SC4
+  # @trace.sc_version: 1.0
+  # @trace.business_rules: {TICKET_ID}-UC{N}-BR{M}
+  @happy @cross-system
+
+  Scenario: <Scenario span ≥2 service hoặc hiệu ứng đồng bộ cross-UC>
+    Given <state đầu vào>
+    When <hành động>
+    Then <kết quả tại service A>
+      And <kết quả đồng bộ sang service B>
+
+# === TECHNICAL HINTS (optional, giúp AI gen code chính xác hơn) ===
+# Dependencies: <UC/service phụ thuộc, vd: LOYAL-28 upstream>
+# Entities: <Entity1, Entity2>
+# Events: <EventName> (publish to <topic>)
+# Cache: <cache invalidation notes>
+# Validation: <validation rules>
+
+# === PRD COVERAGE (C.1 + C.2 — wireframe action + AC/BR checklist) ===
+# AC mapping:
+#   AC1 (...) → SC1, SC2
+#   AC2 (...) → SC3
+# BR mapping (mỗi bullet trong BR PHẢI có ≥1 SC — C.2):
+#   BR1 (...) → SC1
+#   BR2 (...) → SC1, SC2
+# Wireframe mapping (mọi component/action có ≥1 SC — C.1):
+#   Screen "<tên màn>":
+#     [x] Click "<button A>"        → SC1
+#     [x] Click "<button B>"        → SC2
+#     [ ] Click "<" back             → MISSING ← BLOCK MERGE
+# Display Logic Matrix mapping (nếu áp dụng — B.1.7):
+#   Case 1 (...) → SC{N}
+#   Case 2 (...) → SC{N}
+# User Flow: <path name> → SC1, SC2, SC3
+
+# === BUSINESS RULES ===
+# {TICKET_ID}-UC{N}-BR1: <mô tả rule>
+# {TICKET_ID}-UC{N}-BR2: <mô tả rule>
+
+# === PRE-MERGE CHECKLIST (auto-verify) ===
+# - [ ] Mọi SC có Side-effects + @trace.scenario + @trace.sc_version + @trace.ac + @trace.business_rules
+# - [ ] Coverage Matrix có 0 dòng `[ ]` MISSING (C.1)
+# - [ ] Mọi AC/BR (kèm từng bullet) map về ≥1 SC (C.2)
+# - [ ] CI grep banned terms = 0 match (C.4) — xem business-dictionary.md § Banned Terms
+# - [ ] Nếu là popup/modal: Popup/Modal Lifecycle khai báo trong BUSINESS DEFINITION (B.2.4)
+# - [ ] Nếu display logic ≥2 dimension: Display Logic Matrix enumerated (B.1.7)
+# - [ ] Feature ≥3 SCs có NHÓM grouping theo chủ đề business (C.5) — KHÔNG dùng section markers cũ HAPPY-PATH/NEGATIVE-CASE/EDGE-CASE
+# - [ ] /review-context score ≥90 (project gate)

package/templates/platform-guide.template.md

@@ -0,0 +1,145 @@
+# Platform Guide — {{SERVICE_NAME}}
+
+> This guide provides context that Claude uses when working in THIS service/repository.
+> Keep it concise and factual. Update when the architecture or domain model changes.
+> Reference: CLAUDE.md for project-wide standards. This file covers service-specific context.
+
+---
+
+# §1. Service Overview
+
+**Service name**: {{SERVICE_NAME}}
+**Purpose**: {{ONE_SENTENCE_PURPOSE}}
+**Bounded context**: {{BOUNDED_CONTEXT}}  # e.g., "Owns all order lifecycle logic. Does NOT own payments or inventory."
+**Team**: {{TEAM_NAME}}
+**Repository**: {{REPO_URL}}
+
+Primary responsibilities:
+- {{RESPONSIBILITY_1}}
+- {{RESPONSIBILITY_2}}
+- {{RESPONSIBILITY_3}}
+
+This service does NOT handle:
+- {{OUT_OF_SCOPE_1}}  # e.g., "Payment processing → see payment-service"
+- {{OUT_OF_SCOPE_2}}
+
+---
+
+# §2. Domain Model
+
+Key entities and their relationships:
+
+```
+{{ENTITY_1}} (aggregate root)
+  ├── {{CHILD_ENTITY_1}} (value object / child entity)
+  └── {{CHILD_ENTITY_2}}
+
+{{ENTITY_2}}
+  └── references {{ENTITY_1}} by ID
+```
+
+**{{ENTITY_1}}**:
+- Key fields: {{KEY_FIELDS}}
+- Status lifecycle: {{STATUS_1}} → {{STATUS_2}} → {{STATUS_3}}
+- Business rules: {{KEY_RULE_1}}
+
+**{{ENTITY_2}}**:
+- Key fields: {{KEY_FIELDS}}
+- Relationships: {{RELATIONSHIP_DESCRIPTION}}
+
+---
+
+# §3. Common Patterns
+
+Patterns specific to this service (supplement the project-wide standards in CLAUDE.md):
+
+## {{PATTERN_NAME_1}}
+```
+// When to use: {{USE_CASE}}
+// Example:
+{{CODE_EXAMPLE}}
+```
+
+## {{PATTERN_NAME_2}}
+```
+// When to use: {{USE_CASE}}
+// Example:
+{{CODE_EXAMPLE}}
+```
+
+---
+
+# §4. Integration Points
+
+## Upstream Dependencies (this service calls these)
+
+| Service / System | What we call | Protocol | Auth |
+|------------------|--------------|----------|------|
+| {{UPSTREAM_1}}   | {{WHAT}}     | REST/gRPC/Event | {{AUTH_METHOD}} |
+| {{UPSTREAM_2}}   | {{WHAT}}     | REST/gRPC/Event | {{AUTH_METHOD}} |
+
+## Downstream Consumers (these services call us or consume our events)
+
+| Consumer | What they use | Protocol |
+|----------|---------------|----------|
+| {{DOWNSTREAM_1}} | {{WHAT}} | REST/Event |
+| {{DOWNSTREAM_2}} | {{WHAT}} | REST/Event |
+
+## Events Produced
+
+| Event name | Trigger | Payload summary |
+|------------|---------|-----------------|
+| {{EVENT_1}} | {{WHEN}} | {{PAYLOAD_FIELDS}} |
+| {{EVENT_2}} | {{WHEN}} | {{PAYLOAD_FIELDS}} |
+
+## Events Consumed
+
+| Event name | From service | What we do with it |
+|------------|-------------|-------------------|
+| {{EVENT_1}} | {{SOURCE}} | {{HANDLER_ACTION}} |
+
+---
+
+# §5. Known Constraints
+
+## Performance Constraints
+- {{PERF_CONSTRAINT_1}}  # e.g., "Order list endpoint must respond < 200ms for up to 1000 orders"
+- {{PERF_CONSTRAINT_2}}
+
+## Business Rule Constraints
+- {{BUSINESS_CONSTRAINT_1}}  # e.g., "Cannot cancel an order after it has been shipped"
+- {{BUSINESS_CONSTRAINT_2}}
+
+## External Dependencies
+- {{EXTERNAL_DEP_1}}  # e.g., "Requires inventory-service to be available for order creation"
+- {{EXTERNAL_DEP_2}}
+
+## Known Technical Debt
+- {{TECH_DEBT_1}}  # e.g., "OrderItem.price is duplicated from catalog — sync via nightly job"
+
+---
+
+# §6. Directory Structure
+
+```
+{{SERVICE_ROOT}}/
+├── {{SOURCE_DIR}}/              # Main source code
+│   ├── {{LAYER_1}}/             # e.g., controller/ or handler/
+│   │   └── {{EXAMPLE_FILE}}
+│   ├── {{LAYER_2}}/             # e.g., service/ or usecase/
+│   │   └── {{EXAMPLE_FILE}}
+│   ├── {{LAYER_3}}/             # e.g., repository/ or repo/
+│   │   └── {{EXAMPLE_FILE}}
+│   └── {{LAYER_4}}/             # e.g., model/ or domain/
+│       └── {{EXAMPLE_FILE}}
+├── {{TEST_DIR}}/                # Tests mirroring src structure
+├── specs/                       # BDD feature files
+│   └── bdd/
+│       └── {{DOMAIN}}/
+│           └── {{UC-ID}}-{{slug}}.feature
+└── {{CONFIG_FILE}}              # e.g., application.yaml / appsettings.json
+```
+
+**Key conventions for this repo:**
+- {{CONVENTION_1}}  # e.g., "All DTOs are in the api/ package, not mixed with domain models"
+- {{CONVENTION_2}}  # e.g., "Integration tests are in src/test/java/.../integration/ with @Tag(\"integration\")"