spec-lite 1.1.0 → 1.1.2

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,312 @@
+---
+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.
+
+## Templates
+
+Mỗi file output được sinh ra từ template tương ứng — đọc template trước khi điền nội dung:
+
+| Output file | Template |
+| --- | --- |
+| `specs/main/prd.md` | `templates/main/prd-template.md` |
+| `specs/main/domain.md` | `templates/main/domain-template.md` |
+| `specs/main/sad.md` | `templates/main/sad-template.md` |
+
+Giữ nguyên cấu trúc section và frontmatter từ template. Điền nội dung thu thập được từ scan và interview vào đúng vị trí.
+
+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