spec-lite 1.1.0 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-lite",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Spec-driven development kit for Claude Code",
   "type": "module",
   "bin": {

package/skills/spec-brownfield-component/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: spec-brownfield-component
+description: Discover components từ code, generate crd.md + cdd.md cho từng component, điền Component Index vào prd.md. Phải chạy /spec-brownfield-init trước.
+---
+
+# spec-brownfield-component
+
+## Overview
+
+Tạo `specs/main/component/{C-XXX}-{component-name}/crd.md` và `cdd.md` cho các components trong brownfield project.
+
+Skill này **tự discover** component boundaries từ code (không dựa vào init), sau đó scan sâu từng component để extract responsibilities, entities, public interface, business rules. Khi hoàn thành, **điền Component Index vào prd.md** và **đề xuất Shared Entities cascade vào domain.md**.
+
+## When to Use
+
+- Sau khi `/spec-brownfield-init` đã chạy và `prd.md` tồn tại
+- Cần generate component artifacts cho brownfield project
+
+## When NOT to Use
+
+- `prd.md` chưa có → chạy `/spec-brownfield-init` trước
+- Greenfield project → component artifacts mọc dần qua cascade từ integrations (`/spec-new`)
+
+---
+
+## Process
+
+### Bước 1: Load context và xác định path
+
+**Path:** Nếu có ARGUMENT là path → dùng làm root. Nếu không → CWD.
+
+**Load:**
+- `specs/main/prd.md` — kiểm tra tồn tại; đọc problem statement và NFRs để hiểu business context
+- `specs/main/domain.md` — đọc Glossary để reuse business terms
+
+Nếu `prd.md` không tồn tại → dừng:
+> `prd.md` chưa có nội dung. Hãy chạy `/spec-brownfield-init` trước.
+
+**Attachments:**
+> Bạn có tài liệu bổ sung nào không? (API docs, architecture diagrams, design docs)
+> Nhập `không` để bỏ qua.
+
+---
+
+### Bước 2: Discover component boundaries
+
+Scan directory structure để tìm component candidates. Thử các patterns sau theo thứ tự:
+
+1. `src/modules/*/` — modular structure (NestJS, v.v.)
+2. `src/*/` — flat module structure (nếu có `service` hoặc `controller` bên trong)
+3. `services/*/` — microservices
+4. `packages/*/` — monorepo packages
+5. `apps/*/` — monorepo apps
+
+Với mỗi candidate directory, xác nhận đây là component bằng cách kiểm tra có ít nhất một trong: `*controller*`, `*service*`, `*repository*`, `*handler*`, `*module*` file bên trong.
+
+Ghi lại cho mỗi component candidate:
+- Directory path
+- File count
+- Patterns detected: controller / service / repository / event publisher / consumer
+
+---
+
+### Bước 3: Confirm component list
+
+Trình bày kết quả discovery cho user confirm:
+
+```
+Tôi phát hiện {N} components từ codebase:
+  [C-001] auth      → src/modules/auth/     (15 files: controller+service+repo)
+  [C-002] user      → src/modules/user/     (12 files: controller+service+repo)
+  [C-003] payment   → src/modules/payment/  (8 files: service+repo)
+  [C-004] notification → src/modules/notification/ (6 files: service+event)
+
+Điều chỉnh nếu cần:
+  - Đổi tên: "C-002 → profile" hoặc nhập tên khác
+  - Bỏ component: "bỏ C-004"
+  - Thêm component: "thêm reporting tại src/reporting/"
+  - Merge: "merge C-001 và C-002 thành auth-user"
+
+Confirm danh sách? [y] hoặc nhập điều chỉnh:
+```
+
+Sau khi confirm, assign C-XXX IDs theo thứ tự tăng dần.
+
+---
+
+### Bước 4: Scan sâu từng component
+
+Với mỗi component, đọc code files bên trong để extract:
+
+**4a. Responsibilities:**
+- Public method names trong service files
+- Class-level comments / JSDoc nếu có
+- Export declarations
+
+**4b. Owned Entities:**
+- Entity / model files trong component directory
+- Decorators: `@Entity()` (TypeORM), Prisma model blocks, `@Schema()` (Mongoose), SQLAlchemy models
+- Migration files gắn với component
+
+**4c. Public Interface:**
+- Controller files: HTTP method + path mỗi endpoint
+- Event publisher: `@EventPattern`, `eventEmitter.emit()`, message queue producers
+- Exported service methods nếu là shared library
+
+**4d. Dependencies:**
+- Import statements referencing other component directories
+- Injectable services từ other modules
+- HTTP client calls đến other services
+
+**4e. Business Rules:**
+- Validation decorators (`@Min`, `@Max`, `@IsEmail`, custom validators)
+- Guard conditions trong service (`if (!user.isActive) throw ...`)
+- Domain events và điều kiện trigger
+- Comments có từ khóa: "must", "should", "only", "never", "không được"
+
+**4f. Internal design (cho cdd.md):**
+- Module structure: list sub-modules / file groups
+- ORM/storage usage: repository pattern, raw queries, cache decorators
+- Internal service/repository interface contracts
+
+---
+
+### Bước 5: Identify cross-component entities
+
+Trong quá trình scan, ghi nhận các entities được **import hoặc reference từ nhiều hơn 1 component** → đây là candidate Shared Entities cho `domain.md`.
+
+Ví dụ: `Order` được dùng trong `payment/` và `inventory/` → candidate Shared Entity, cần xác định owner.
+
+---
+
+### Bước 6: Hỏi clarification — batch
+
+Sau khi scan xong tất cả components, hỏi một lần — tối đa **5 câu tổng cộng**. Ưu tiên những điểm ảnh hưởng đến component boundaries hoặc entity ownership.
+
+```
+Cần làm rõ {N} điểm:
+
+[C-001 auth]
+  Q1. Method `validateToken` được call từ cả auth/ và user/ —
+      đây là public interface hay internal helper?
+      [public / internal / skip]
+
+[cross-component]
+  Q2. Entity `Order` được dùng trong payment/ và inventory/ —
+      component nào sở hữu?
+      [payment / inventory / skip]
+
+Trả lời hoặc "skip all" để đánh dấu NEEDS_CLARIFY hết:
+```
+
+---
+
+### Bước 7: Generate artifacts
+
+Với mỗi component, generate 2 files dùng templates tương ứng:
+
+**`crd.md`** — WHAT (dùng `.claude/templates/main/component/crd-template.md`):
+- Role, Responsibilities, Owned Entities, Public Interface, Business Rules, Domain Events, Dependencies
+
+**`cdd.md`** — HOW (dùng `.claude/templates/main/component/cdd-template.md`):
+- Module structure, Internal data flow, Storage & persistence, Internal interfaces, Technical decisions
+
+**Nguyên tắc:**
+- Mọi phần không detect được → NEEDS_CLARIFY, không bịa
+- Business rules detect được từ code → đánh dấu `(detected from code)`
+- crd.md không chứa internal design; cdd.md không chứa public interface
+
+---
+
+### Bước 8: Cascade Proposals — domain.md
+
+Nếu có Shared Entities được phát hiện ở Bước 5:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+SHARED ENTITIES DETECTED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Các entities sau được dùng bởi nhiều components.
+Đề xuất thêm vào specs/main/domain.md (Shared Entities):
+
+  Entity: Order (Owner: C-003-payment)
+    Dùng bởi: C-003-payment, C-005-inventory
+    Fields detected: id, userId, items[], status, totalAmount
+
+  Entity: User (Owner: C-001-auth)
+    Dùng bởi: C-001-auth, C-002-user, C-004-notification
+    Fields detected: id, email, role, isActive
+
+Apply cascade proposals vào domain.md? [y/n/edit]
+```
+
+Nếu `y` → update `specs/main/domain.md` Shared Entities section.
+Nếu `edit` → hỏi chỉnh sửa từng entity trước khi apply.
+
+---
+
+### Bước 9: Review và save artifacts
+
+```
+Sẽ tạo {N} components ({2N} files):
+  ✓ specs/main/component/C-001-auth/crd.md     (3 NEEDS_CLARIFY)
+  ✓ specs/main/component/C-001-auth/cdd.md     (1 NEEDS_CLARIFY)
+  ✓ specs/main/component/C-002-user/crd.md     (0 NEEDS_CLARIFY)
+  ✓ specs/main/component/C-002-user/cdd.md     (2 NEEDS_CLARIFY)
+  ...
+
+Ghi tất cả? [y] hoặc review từng file trước [r]:
+```
+
+- `y` → ghi tất cả
+- `r` → hiển thị lần lượt từng file, user confirm / skip / edit từng cái
+
+---
+
+### Bước 10: Điền Component Index vào prd.md
+
+Sau khi artifacts đã được ghi, update `specs/main/prd.md` Component Index với danh sách đã confirm:
+
+```
+Sẽ điền Component Index vào prd.md:
+  C-001 | auth         | Xác thực và phân quyền người dùng       | active
+  C-002 | user         | Quản lý thông tin người dùng             | active
+  C-003 | payment      | Xử lý thanh toán và giao dịch            | active
+  C-004 | notification | Gửi thông báo qua email/push             | active
+
+Apply? [y/n]
+```
+
+---
+
+### Bước 11: Summary
+
+```
+✓ Generated {N} components:
+  specs/main/component/C-001-auth/    (crd.md + cdd.md)
+  specs/main/component/C-002-user/    (crd.md + cdd.md)
+  ...
+
+✓ prd.md Component Index: {N} entries đã được điền
+
+{nếu có} ✓ domain.md Shared Entities: {N} entities đã được cascade
+
+NEEDS_CLARIFY summary — {total} items:
+  C-001-auth:  {n} — [business rules, domain events, ...]
+  C-002-user:  {n} — [entity ownership, ...]
+  ...
+
+Bước tiếp theo:
+  /spec-brownfield-feature → discover features, generate frd.md + fdd.md, điền Feature Index
+```
+
+---
+
+## Verification
+
+- [ ] Mỗi component có đủ crd.md + cdd.md
+- [ ] crd.md không chứa internal design (đã ở cdd.md)
+- [ ] cdd.md không chứa public interface (đã ở crd.md)
+- [ ] Mọi entity trong crd.md có đúng 1 owner component (hoặc NEEDS_CLARIFY)
+- [ ] Dependencies chỉ reference C-XXX IDs, không reference file paths
+- [ ] Business rules detect được đánh dấu `(detected from code)`
+- [ ] prd.md Component Index đã được update
+- [ ] Shared Entities đã được cascade vào domain.md (nếu có)
+- [ ] NEEDS_CLARIFY items được list đầy đủ trong summary

package/skills/spec-brownfield-feature/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: spec-brownfield-feature
+description: Discover features từ code, generate frd.md + fdd.md cho từng feature, điền Feature Index vào prd.md. Phải chạy /spec-brownfield-component trước vì fdd.md tham chiếu C-XXX từ Component Index.
+---
+
+# spec-brownfield-feature
+
+## Overview
+
+Tạo `specs/main/feature/{F-XXX}-{feature-name}/frd.md` và `fdd.md` cho các features trong brownfield project.
+
+Skill này **tự discover** features từ routes, use cases, và test files, sau đó scan sâu để extract user stories, AC, và inter-component flows. Khi hoàn thành, **điền Feature Index vào prd.md**.
+
+**Phải chạy sau `/spec-brownfield-component`** vì fdd.md mô tả inter-component interaction và cần tham chiếu C-XXX IDs từ Component Index đã được điền.
+
+## When to Use
+
+- Sau khi `/spec-brownfield-component` đã chạy xong
+- prd.md có Component Index (C-XXX IDs đã có)
+- Cần generate feature artifacts cho brownfield project
+
+## When NOT to Use
+
+- `/spec-brownfield-component` chưa chạy → chạy component skill trước
+- Greenfield project → feature artifacts mọc dần qua cascade từ integrations (`/spec-new`)
+
+---
+
+## Process
+
+### Bước 1: Load context và xác định path
+
+**Path:** Nếu có ARGUMENT là path → dùng làm root. Nếu không → CWD.
+
+**Load:**
+- `specs/main/prd.md` — kiểm tra Component Index đã được điền
+- `specs/main/domain.md` — đọc Glossary và Shared Entities
+- `specs/main/component/*/crd.md` — đọc Public Interface của từng component (để cross-reference trong fdd.md)
+
+**Kiểm tra preconditions:**
+
+Nếu `prd.md` không tồn tại → dừng:
+> `prd.md` chưa có nội dung. Hãy chạy `/spec-brownfield-init` trước.
+
+Nếu `prd.md` Component Index còn trống (không có C-XXX entries) → dừng:
+> Component Index chưa có entries. Hãy chạy `/spec-brownfield-component` trước.
+> fdd.md cần tham chiếu C-XXX để mô tả inter-component flows.
+
+Nếu `specs/main/component/` không có crd.md nào → cảnh báo tương tự và dừng.
+
+**Attachments:**
+> Bạn có tài liệu bổ sung nào không? (user stories, test plans, wireframes, existing specs)
+> Nhập `không` để bỏ qua.
+
+---
+
+### Bước 2: Discover feature boundaries
+
+Scan codebase để tìm feature candidates. Tìm theo thứ tự ưu tiên:
+
+1. **Use case / interactor files**: `*UseCase.{ts,js}`, `*Interactor.{ts,js}`, `*Handler.{ts,js}`, thư mục `application/*/`
+2. **Route groups**: controller files grouped by path prefix (`/auth/*`, `/payment/*`, `/orders/*`)
+3. **Test describe blocks**: `describe('User Registration', ...)`, `describe('Checkout Flow', ...)`
+4. **Page / screen directories**: `pages/{feature}/`, `screens/{feature}/`, `views/{feature}/`
+
+Với mỗi candidate, ghi lại:
+- Entry point file(s)
+- Route paths liên quan
+- Test files có hay không
+- Components được call (từ import statements) → map sang C-XXX IDs
+
+---
+
+### Bước 3: Confirm feature list
+
+```
+Tôi phát hiện {N} features từ codebase:
+  [F-001] user-registration  → RegisterUseCase + POST /auth/register   (5 tests)
+  [F-002] authentication     → POST /auth/login, /auth/refresh          (3 tests)
+  [F-003] checkout-flow      → CheckoutUseCase + /checkout/*            (8 tests)
+  [F-004] order-history      → GET /orders/*                            (no tests)
+
+Điều chỉnh nếu cần:
+  - Đổi tên: "F-003 → place-order"
+  - Bỏ feature: "bỏ F-004"
+  - Thêm feature: "thêm password-reset"
+  - Merge: "merge F-001 và F-002 thành auth-flow"
+
+Confirm danh sách? [y] hoặc nhập điều chỉnh:
+```
+
+Sau khi confirm, assign F-XXX IDs theo thứ tự tăng dần.
+
+---
+
+### Bước 4: Scan sâu từng feature
+
+**4a. User stories — infer từ:**
+- Use case class names và public methods → action descriptions
+- Route names + HTTP methods → "As a user, I want to POST /auth/register..."
+- Test `describe` / `it` blocks → `it('should register a new user', ...)` → user story
+
+Đánh dấu source: `(inferred from routes)` hoặc `(from tests)`.
+
+**4b. Acceptance criteria — extract từ:**
+- Test assertions: `expect(response.status).toBe(201)`, `expect(user.email).toBe(...)`
+- Input validation rules từ DTO / request validators
+- Expected error codes / messages từ error handling code
+
+Nếu không có tests → AC section sẽ là NEEDS_CLARIFY.
+
+**4c. Components consumed — extract từ:**
+- Import statements trong feature's controllers / use cases → map sang C-XXX IDs (đã có từ Component Index)
+- Cross-reference với crd.md Public Interface để confirm
+
+**4d. Inter-component flow cho fdd.md — extract từ:**
+- Call chain trong use case file: `authService → userRepo → notificationService`
+- Event publications và subscriptions trong flow
+- Transaction boundaries nếu explicit (`@Transaction`, `queryRunner`)
+- Retry / timeout config nếu detect được
+
+---
+
+### Bước 5: Hỏi clarification — batch
+
+Sau khi scan xong tất cả, hỏi một lần — tối đa **5 câu tổng cộng**:
+
+```
+Cần làm rõ {N} điểm:
+
+[F-001 user-registration]
+  Q1. Flow này chỉ register bằng email/password, hay còn OAuth nữa?
+      (Tôi detect email/password flow nhưng thấy OAuth client được import)
+      [email/password only / cả hai / skip]
+
+[F-003 checkout-flow]
+  Q2. Sau khi place order, payment được xử lý sync hay async?
+      (Tôi thấy PaymentService được call nhưng không rõ transaction boundary)
+      [sync / async / skip]
+
+Trả lời hoặc "skip all":
+```
+
+---
+
+### Bước 6: Generate artifacts
+
+Với mỗi feature, generate 2 files dùng templates tương ứng:
+
+**`frd.md`** — WHAT (dùng `.claude/templates/main/feature/frd-template.md`):
+- Description và business goal (infer từ feature name + use case, NEEDS_CLARIFY nếu không rõ)
+- User stories (đánh dấu source)
+- Acceptance criteria (extract từ tests nếu có, NEEDS_CLARIFY nếu không)
+- Scope: In scope từ detected routes/actions; Out of scope → NEEDS_CLARIFY
+- Components consumed: list C-XXX từ Component Index
+- Dependencies: feature-to-feature dependencies nếu detect được
+
+**`fdd.md`** — HOW / inter-component (dùng `.claude/templates/main/feature/fdd-template.md`):
+- Inter-component data flow: sequence diagram từ detected call chain (Mermaid hoặc ASCII)
+- Orchestration: retry / timeout / fallback nếu detect được
+- Cross-component invariants: transaction boundaries nếu detect được
+
+**Nguyên tắc:**
+- fdd.md là **file mỏng** — chỉ mô tả tương tác giữa components, không lặp nội dung từ crd.md / cdd.md
+- Mọi phần không detect được → NEEDS_CLARIFY, không bịa
+
+---
+
+### Bước 7: Review và save artifacts
+
+```
+Sẽ tạo {N} features ({2N} files):
+  ✓ specs/main/feature/F-001-user-registration/frd.md  (4 NEEDS_CLARIFY)
+  ✓ specs/main/feature/F-001-user-registration/fdd.md  (2 NEEDS_CLARIFY)
+  ✓ specs/main/feature/F-002-authentication/frd.md     (1 NEEDS_CLARIFY)
+  ✓ specs/main/feature/F-002-authentication/fdd.md     (0 NEEDS_CLARIFY)
+  ...
+
+Ghi tất cả? [y] hoặc review từng file trước [r]:
+```
+
+---
+
+### Bước 8: Điền Feature Index vào prd.md
+
+Sau khi artifacts đã được ghi, update `specs/main/prd.md` Feature Index:
+
+```
+Sẽ điền Feature Index vào prd.md:
+  F-001 | user-registration | Đăng ký tài khoản mới qua email/password | Must | TODO
+  F-002 | authentication    | Đăng nhập và refresh token               | Must | TODO
+  F-003 | checkout-flow     | Đặt hàng và thanh toán                   | Must | TODO
+  F-004 | order-history     | Xem lịch sử đơn hàng                     | Should | TODO
+
+Apply? [y/n]
+```
+
+---
+
+### Bước 9: Summary
+
+```
+✓ Generated {N} features:
+  specs/main/feature/F-001-user-registration/  (frd.md + fdd.md)
+  specs/main/feature/F-002-authentication/     (frd.md + fdd.md)
+  ...
+
+✓ prd.md Feature Index: {N} entries đã được điền
+
+NEEDS_CLARIFY summary — {total} items:
+  F-001: {n} — [business goal, out of scope, AC, ...]
+  F-002: {n} — [...]
+  ...
+
+Brownfield init hoàn tất! Main artifacts:
+  specs/main/
+  ├── prd.md           (Component Index: {N} | Feature Index: {N})
+  ├── domain.md        (Glossary: {N} terms | Shared Entities: {N})
+  ├── sad.md
+  ├── component/       ({N} components, mỗi cái có crd.md + cdd.md)
+  └── feature/         ({N} features, mỗi cái có frd.md + fdd.md)
+
+Để bắt đầu implement, dùng /spec-new để tạo integration đầu tiên.
+grep "NEEDS_CLARIFY" để tìm và fill in khi có thêm context.
+```
+
+---
+
+## Verification
+
+- [ ] Chạy sau `/spec-brownfield-component` — Component Index đã có entries
+- [ ] Mỗi feature có đủ frd.md + fdd.md
+- [ ] frd.md có ít nhất 1 user story hoặc NEEDS_CLARIFY rõ ràng
+- [ ] fdd.md chỉ mô tả inter-component interaction — không lặp nội dung từ crd.md / cdd.md
+- [ ] Components consumed list reference đúng C-XXX IDs từ Component Index
+- [ ] User stories và AC detect được đánh dấu source `(inferred)` hoặc `(from tests)`
+- [ ] Feature không có tests → AC section có NEEDS_CLARIFY rõ ràng
+- [ ] prd.md Feature Index đã được update
+- [ ] NEEDS_CLARIFY items được list đầy đủ trong summary

package/skills/spec-brownfield-init/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: spec-brownfield-init
+description: Khởi tạo main artifacts (prd.md, domain.md, sad.md) cho brownfield project bằng cách scan codebase và interview với pre-filled options. Dùng khi onboarding một project đã chạy vào SDD workflow.
+---
+
+# spec-brownfield-init
+
+## Overview
+
+Tạo `specs/main/prd.md`, `specs/main/domain.md`, và `specs/main/sad.md` cho một project đã tồn tại.
+
+Skill này chỉ tập trung vào **product và architecture level** — những gì có thể extract từ README, docs, config, và kiến trúc tổng thể. Component Index và Feature Index trong prd.md sẽ **để trống** — chúng sẽ được điền bởi `/spec-brownfield-component` và `/spec-brownfield-feature` sau khi scan code chuyên sâu.
+
+Thông tin không thể detect từ code được đánh dấu nhất quán:
+
+```
+**[NEEDS_CLARIFY]** <mô tả điều chưa rõ và câu hỏi cần trả lời>
+```
+
+## When to Use
+
+- Onboarding một brownfield project vào SDD workflow
+- `specs/main/prd.md` chưa có hoặc còn trống
+
+## When NOT to Use
+
+- Greenfield project chưa có code → dùng `/spec-prd` + `/spec-sad`
+- `prd.md` đã có nội dung đầy đủ → dùng `/spec-prd` hoặc `/spec-sad` để update từng phần
+
+---
+
+## Process
+
+### Bước 1: Xác định target path và load attachments
+
+**Path:**
+- Nếu có ARGUMENT là path → đây là root của project cần scan.
+- Nếu không có → mặc định dùng current working directory.
+
+Thông báo: `Sẽ scan: {path}`
+
+**Attachments:**
+Hỏi ngay đầu — không hỏi lại sau:
+
+> Bạn có tài liệu bổ sung nào không? (README, API spec, wiki, ADR, existing docs)
+> Paste nội dung hoặc cung cấp file path. Nhập `không` để bỏ qua.
+
+Load tất cả attachments trước khi scan. Dùng làm context bổ sung trong mọi bước tiếp theo.
+
+---
+
+### Bước 2: Kiểm tra existing specs
+
+Kiểm tra `specs/main/prd.md`, `specs/main/domain.md`, `specs/main/sad.md`:
+
+Nếu một trong ba đã có nội dung thực → cảnh báo:
+
+```
+⚠ File đã có nội dung:
+  - specs/main/prd.md
+  - specs/main/sad.md
+
+Skill này sẽ overwrite các file trên. Tiếp tục? [y/n]
+```
+
+Nếu user chọn `n` → dừng.
+
+---
+
+### Bước 3: Scan codebase
+
+Scan tuần tự. **Không hỏi user trong bước này** — chỉ thu thập thông tin.
+
+**3a. Package & tech stack:**
+Đọc (nếu tồn tại): `package.json`, `yarn.lock`, `pnpm-lock.yaml`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, `build.gradle`, `composer.json`, `Gemfile`, `pubspec.yaml`
+
+Extract: ngôn ngữ, framework chính, major dependencies, build/test scripts.
+
+**3b. README và existing docs:**
+Đọc (nếu tồn tại): `README.md`, `README.*`, `docs/`, `ARCHITECTURE.md`, `DESIGN.md`
+
+Extract: mô tả project, target users được nhắc đến, business context.
+
+**3c. Directory structure — top level:**
+List 1-2 levels từ root — không đọc nội dung file source.
+
+Detect: architecture pattern (monolith / microservices / monorepo). Không cần lấy tên từng module — đó là việc của `/spec-brownfield-component`.
+
+**3d. Auth & middleware:**
+Tìm files liên quan: auth, middleware, interceptor, guard, rate-limit, logging config.
+
+Infer: auth strategy, cross-cutting patterns đang dùng.
+
+**3e. Infrastructure:**
+Đọc (nếu tồn tại): `docker-compose.yml`, `Dockerfile`, `.github/workflows/`, `k8s/`, `terraform/`, `serverless.yml`, `.env.example`
+
+Extract: deployment target, số services (để confirm architecture pattern), số môi trường.
+
+---
+
+### Bước 4: Tóm tắt scan và xác nhận tiếp tục
+
+```
+SCAN RESULTS — {path}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Tech stack:    {e.g. TypeScript / NestJS / PostgreSQL / Redis}
+Architecture:  {e.g. Modular Monolith}
+Auth pattern:  {e.g. JWT Bearer / Session / không detect được}
+Docs loaded:   {list files đọc được}
+
+Tiếp tục với brownfield init? [y/n]
+```
+
+Nếu `n` → dừng.
+
+---
+
+### Bước 5: Interview — prd.md
+
+Hỏi tuần tự từng phần. Mỗi câu hỏi có options pre-filled từ scan. Luôn có `[0] Chưa rõ → NEEDS_CLARIFY`. Khi user chọn `[0]` → đánh dấu và tiếp tục, không dừng lại.
+
+**Phần 1 — Problem Statement:**
+
+```
+❓ Hệ thống này giải quyết vấn đề gì?
+  [1] {Trích từ README: "..."}
+  [2] Nhập mô tả khác
+  [0] Chưa rõ → NEEDS_CLARIFY
+```
+
+**Phần 2 — Target Users:**
+
+```
+❓ Ai là người dùng chính?
+  [1] {Detected từ auth guards / README: e.g. "admin, user, guest"}
+  [2] Nhập personas khác
+  [0] Chưa rõ → NEEDS_CLARIFY
+```
+
+Nếu user chọn [1] → hỏi thêm một câu: "Bạn muốn mô tả thêm mục tiêu / pain point cho từng role không? [y/n]"
+
+**Phần 3 — Scope:**
+
+```
+❓ In scope — những gì hệ thống có:
+  [1] {Infer từ README/docs: "..."}
+  [2] Nhập danh sách khác
+  [0] Chưa rõ → NEEDS_CLARIFY
+
+❓ Out of scope — những gì hệ thống KHÔNG làm:
+  [1] Nhập nội dung
+  [0] Chưa rõ → NEEDS_CLARIFY
+```
+
+**Phần 4 — NFRs:**
+
+```
+❓ Non-Functional Requirements:
+  Detected từ config / code:
+    {e.g. Rate limit: 100 req/min (từ rate-limit config)}
+    {e.g. DB pool: max 10 connections (từ DB config)}
+
+  Có thêm NFR nào không? (performance targets, availability SLA, security compliance, scalability)
+  [1] Dùng detected + nhập thêm nếu có
+  [2] Nhập lại từ đầu
+  [0] Chưa rõ → NEEDS_CLARIFY tất cả
+```
+
+**Phần 5 — Business Constraints:**
+
+```
+❓ Business constraints và assumptions:
+  (deadline, budget, compliance, vendor lock-in, team constraints)
+  [1] Nhập nội dung
+  [0] Chưa rõ → NEEDS_CLARIFY
+```
+
+**Lưu ý:** prd.md sẽ có Component Index và Feature Index **để trống** với placeholder. Chúng sẽ được điền bởi `/spec-brownfield-component` và `/spec-brownfield-feature`.
+
+---
+
+### Bước 6: Tạo domain.md — Glossary
+
+domain.md ở bước này chỉ có **Glossary** — Shared Entities để trống, sẽ được mọc qua cascade proposals từ `/spec-brownfield-component` khi nó phát hiện cross-component entities.
+
+Extract glossary terms từ: README/docs (business terms được nhắc đến), tên các key concepts trong problem statement vừa thu thập.
+
+Hỏi:
+```
+❓ Glossary terms cần define:
+  Tôi nhận diện được các terms sau từ docs:
+    - {term 1}: {định nghĩa inferred hoặc NEEDS_CLARIFY}
+    - {term 2}: {định nghĩa inferred hoặc NEEDS_CLARIFY}
+
+  [1] Dùng list này — có thể thêm/sửa/xóa
+  [2] Nhập danh sách mới
+  [0] Chưa rõ / bỏ qua → để trống, điền sau
+```
+
+---
+
+### Bước 7: Auto-generate — sad.md
+
+Phần lớn auto từ scan. Chỉ hỏi 2 câu.
+
+**7a. Auto-fill từ scan:**
+- Tech stack: từ package files
+- Architecture style: infer từ directory structure top-level + docker-compose
+- Cross-cutting concerns: infer từ middleware / interceptors / guards detected
+- Inter-service communication: infer từ message queue / HTTP client usage
+- Infrastructure: infer từ docker-compose, cloud configs
+
+**7b. Hỏi Guardrails:**
+
+```
+❓ Architectural Guardrails:
+  Dựa trên {stack}, tôi đề xuất:
+    GUARD-001: {rule cụ thể}
+    GUARD-002: {rule cụ thể}
+    ...
+
+  [1] Dùng set này — có thể thêm/bớt
+  [2] Nhập guardrails khác
+  [0] Chưa rõ → NEEDS_CLARIFY tất cả
+```
+
+**7c. Hỏi additional constraints:**
+
+```
+❓ Có architectural decision nào quan trọng chưa detect được không?
+  (patterns bắt buộc dùng, patterns bị cấm, third-party services phải dùng)
+  [1] Nhập thêm
+  [0] Không có thêm
+```
+
+---
+
+### Bước 8: Review drafts
+
+Hiển thị draft từng file lần lượt. Với mỗi file:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+DRAFT: specs/main/{file}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+{nội dung draft}
+
+[NEEDS_CLARIFY trong file này: {count} items]
+
+Confirm? [y] Bỏ qua [n] Chỉnh sửa [e]:
+```
+
+- `y` → ghi file, chuyển sang file tiếp theo
+- `n` → bỏ qua file này
+- `e` → hỏi chỉnh sửa cụ thể, show lại draft, hỏi confirm lần nữa
+
+---
+
+### Bước 9: Save
+
+Tạo `specs/main/` nếu chưa có. Ghi các files đã được confirm.
+
+```
+✓ specs/main/prd.md        (Component Index và Feature Index: placeholder — chưa có)
+✓ specs/main/domain.md     (Glossary: {n} terms | Shared Entities: trống — sẽ mọc qua cascade)
+✓ specs/main/sad.md
+
+NEEDS_CLARIFY summary — {total} items cần làm rõ:
+  prd.md:    {n} — [Problem Statement, Business Constraints, ...]
+  domain.md: {n} — [glossary terms, ...]
+  sad.md:    {n} — [guardrails, ...]
+
+Bước tiếp theo:
+  /spec-brownfield-component → scan code, generate crd.md + cdd.md, điền Component Index
+  /spec-brownfield-feature   → scan code, generate frd.md + fdd.md, điền Feature Index
+  (chạy component trước — feature phụ thuộc vào component)
+```
+
+---
+
+## NEEDS_CLARIFY Convention
+
+Format chuẩn — dùng nhất quán trong tất cả artifacts:
+
+```markdown
+**[NEEDS_CLARIFY]** Mô tả ngắn điều chưa rõ. Câu hỏi cần trả lời để fill in.
+```
+
+---
+
+## Verification
+
+- [ ] Scan results đã được hiển thị và user confirm trước khi interview
+- [ ] Mọi section có ít nhất một trong ba: nội dung thực / pre-filled option / NEEDS_CLARIFY
+- [ ] prd.md có Component Index placeholder (chưa có entries — sẽ điền sau)
+- [ ] prd.md có Feature Index placeholder (chưa có entries — sẽ điền sau)
+- [ ] domain.md có Glossary (ít nhất skeleton) và Shared Entities trống
+- [ ] sad.md có Architectural Guardrails section
+- [ ] NEEDS_CLARIFY items được list đầy đủ trong summary cuối
+- [ ] User đã confirm từng file trước khi ghi