evnict-kit 0.2.1

package/templates/content/workflows/evnict-kit-feature-large.md

@@ -0,0 +1,393 @@
+---
+description: Phát triển feature lớn — spec → clarify → plan → TDD implement → archive wiki. Dùng khi feature cần code cả BE, FE, Database.
+---
+
+# Feature Large
+**Command:** `/evnict-kit:feature-large`
+
+## Khi nào dùng
+- Feature mới cần cả Backend + Frontend + Database
+- Độ phức tạp cao, cần spec rõ ràng trước khi code
+- Ước lượng > 1 ngày làm việc
+
+## Input
+- Mô tả feature bằng ngôn ngữ tự nhiên (tiếng Việt hoặc tiếng Anh)
+- VD: `/evnict-kit:feature-large Thêm chức năng ký số hàng loạt cho các hồ sơ đã duyệt`
+
+---
+
+## Phase 0: Brainstorm (Socratic)
+TRƯỚC KHI sinh spec, Agent PHẢI áp dụng skill `evnict-kit-brainstorm`:
+1. Đọc mô tả thô của user.
+2. Xác định yêu cầu cần cả BE và FE không.
+3. Hỏi user tối đa 5 câu hỏi để clarify scope, alternatives, constraints.
+4. Chốt Design Brief.
+5. CHỜ user approve mới chuyển sang Phase 1.
+
+---
+
+## Phase 1: Specify + Clarify
+
+### Bước 0: Detect project context
+1. Kiểm tra project hiện tại là BE hay FE:
+   - Có pom.xml/build.gradle → Backend
+   - Có angular.json/package.json+react → Frontend
+2. Đọc `.evnict/config.yaml` → liệt kê TẤT CẢ repos
+3. Nếu feature cần cả BE+FE:
+   - Spec PHẢI bao gồm cả BE và FE sections
+   - Plan PHẢI sinh tasks cho CẢ BE và FE
+   - Tasks BE đánh prefix `be-`, tasks FE đánh prefix `fe-`
+   - API contract PHẢI được sinh trong plan phase
+4. Thông báo: "Feature sẽ cần handoff sang [FE/BE]. 
+   Sau implement, chạy `/evnict-kit:handoff` để chuyển tasks."
+
+### Bước 1: Thu thập context
+1. Đọc `.evnict/config.yaml` → lấy project name, tech stack, wiki path
+2. **Query wiki** (nếu có) → tìm context liên quan đến chức năng được mô tả:
+   - Đọc index từ `{wiki_path}/processed/`
+   - Tìm theo keyword/domain/tags từ mô tả feature
+   - Nếu tìm được → đưa vào context khi tạo spec
+3. Đọc rules hiện tại trong `.agent/rules/` → nắm conventions dự án
+
+### Bước 2: Sinh spec draft
+Tạo file `.evnict/specs/{feature-slug}/spec.md` theo format:
+
+```markdown
+# Spec: {Feature Name}
+## Generated by /evnict-kit:feature-large
+## Date: {YYYY-MM-DD}
+
+---
+
+## 1. WHAT — Chức năng gì
+{Mô tả chức năng, user story format nếu phù hợp}
+- As a [role], I want to [action], so that [benefit]
+
+## 2. WHY — Tại sao cần
+{Mục đích nghiệp vụ, giá trị mang lại}
+
+## 3. WHO — Ai sử dụng
+| Vai trò | Quyền hạn |
+|---------|-----------|
+| {role}  | {permissions} |
+
+## 4. SCOPE — Phạm vi
+### Bao gồm
+- {in-scope items}
+
+### KHÔNG bao gồm
+- {out-of-scope items}
+
+## 5. BUSINESS RULES
+| Mã | Quy tắc | Ví dụ |
+|----|---------|-------|
+| BR01 | {rule description} | {example} |
+| BR02 | ... | ... |
+
+## 6. LUỒNG NGHIỆP VỤ
+### Luồng chính (Main Flow)
+1. {step 1}
+2. {step 2}
+3. ...
+
+### Luồng ngoại lệ (Exception Flow)
+- Nếu {condition} → {behavior}
+
+## 7. ACCEPTANCE CRITERIA
+- [ ] {criterion 1}
+- [ ] {criterion 2}
+
+## 8. PHẠM VI KỸ THUẬT
+### Backend
+- API endpoints cần tạo: ...
+- Database changes: ...
+- Service logic: ...
+
+### Frontend  
+- Pages/Components cần tạo: ...
+- State management: ...
+- API integration: ...
+
+### Database
+- New tables/columns: ...
+- Migration scripts: ...
+```
+
+### Bước 3: Đặt câu hỏi clarify NGAY TRONG OUTPUT
+Sau khi sinh spec draft, hỏi user TỐI ĐA 3 câu:
+
+```markdown
+## ❓ Câu hỏi cần làm rõ
+
+### Q1: Scope
+{Câu hỏi về phạm vi — feature này bao gồm/không bao gồm gì?}
+Gợi ý: A) ... | B) ... | C) Custom
+
+### Q2: Edge Cases  
+{Câu hỏi về trường hợp ngoại lệ}
+
+### Q3: Constraints
+{Câu hỏi về ràng buộc kỹ thuật/nghiệp vụ}
+```
+
+**Nguyên tắc clarify (theo spec-kit):**
+- Chỉ hỏi khi choice ẢNH HƯỞNG LỚN đến scope/security/UX
+- Có nhiều cách hiểu hợp lý nhưng kết quả khác nhau
+- Không có default hợp lý
+- Giới hạn TỐI ĐA 3 câu hỏi — các vấn đề nhỏ → tự quyết định, ghi vào Assumptions
+
+### Bước 4: User trả lời → Update spec → Confirm
+
+---
+
+## Phase 2: Plan + Task Breakdown
+
+**Trigger:** `/evnict-kit:plan` (chờ User xác nhận trả lời hết Câu hỏi làm rõ ở Phase 1)
+
+### Bước 1: Sinh plan files
+Sau khi spec confirmed, tạo cấu trúc:
+
+```
+.evnict/specs/{feature-slug}/
+├── spec.md              ← Đã confirm ở Phase 1
+├── plan.md              ← Tổng plan (sinh ở bước này)
+├── tasks/
+│   ├── 01-db-migration.md
+│   ├── 02-be-repository.md
+│   ├── 03-be-service.md
+│   ├── 04-be-controller.md
+│   ├── 05-fe-service.md
+│   ├── 06-fe-component.md
+│   └── 07-fe-page.md
+└── contracts/
+    └── api-contract.yaml
+```
+
+### Bước 2: Nội dung plan.md
+
+```markdown
+# Plan: {Feature Name}
+## Tổng quan
+- Estimated: {X} subtasks, ~{Y} phút
+- BE tasks: {N}
+- FE tasks: {M}
+- DB tasks: {K}
+
+## Thứ tự thực hiện
+1. DB Migration (PHẢI xong trước)
+2. BE: Repository → Service → Controller (tuần tự)
+3. FE: Service → Component → Page (tuần tự, SAU KHI BE xong API)
+
+## Dependencies
+- FE tasks PHẢI chờ BE hoàn thành API → đọc contract từ contracts/api-contract.yaml
+- BE tasks PHẢI chờ DB migration xong
+```
+
+### Bước 3: Nội dung mỗi task file
+
+> **CHI TIẾT:** Xem template đầy đủ trong command `/evnict-kit:plan` — Bước 4.
+> Mỗi task file PHẢI ≥ 100 dòng, bao gồm 8 sections:
+> Mục tiêu, Business Context, Files list, Implementation Guide (code patterns từ file mẫu thật),
+> Test Cases (≥ 3), Acceptance Criteria, Dependencies, Estimated.
+
+```markdown
+# Task 01: DB Migration — {description}
+## 1. Mục tiêu
+{3-5 câu mô tả cụ thể}
+
+## 2. Business Context
+- BR{XX}: {rule liên quan}
+
+## 3. Files cần tạo/sửa
+| File | Action | Mô tả |
+|------|--------|-------|
+| database/migrations/V{date}_{seq}__{desc}.sql | CREATE | Migration UP |
+| database/migrations/V{date}_{seq}__{desc}_ROLLBACK.sql | CREATE | Rollback |
+
+## 4. Implementation Guide
+### Conventions: Rule 03 → Migration naming convention
+### Code Pattern: (trích từ migration mẫu trong project)
+
+## 5. Test Cases (TDD)
+| # | Test | Input | Expected | Type |
+|---|------|-------|----------|------|
+| 1 | Migration UP thành công | run script | Table tồn tại | Integration |
+| 2 | Columns đúng type | describe table | Match schema | Integration |
+| 3 | Rollback thành công | run rollback | Table xóa | Integration |
+
+## 6. Acceptance Criteria
+- [ ] {specific criteria}
+
+## 7. Dependencies
+- Requires: none
+- Blocks: Task 02 (BE Repository)
+
+## 8. Estimated: 3 phút
+```
+
+### Bước 4: API Contract (cho FE↔BE coordination)
+
+```yaml
+# contracts/api-contract.yaml
+feature: {feature-name}
+generated: {date}
+endpoints:
+  - method: POST
+    path: /api/{module}/{action}
+    description: {mô tả}
+    request:
+      body:
+        fieldName: { type: string, required: true, maxLength: 100 }
+    response:
+      200:
+        schema: ResponseData
+        data:
+          id: { type: number }
+      400:
+        schema: ResponseData
+        error: { message: string }
+```
+
+### Bước 5: User review plan → Confirm trước khi implement
+
+---
+
+## Phase 3: Implement (TDD per subtask)
+
+**Trigger:** `/evnict-kit:implement` (sau khi plan đã confirm)
+
+### Pre-conditions
+- Plan đã được user approve
+- Working tree clean (`git status`)
+
+### Bước 1: Tạo feature branch
+```bash
+git checkout -b feature/{feature-slug}
+```
+
+### Bước 2: Với MỖI task file, thực hiện TDD cycle
+
+> **MANDATORY:** Sau mỗi task → STOP-AND-ASK (xem implement workflow).
+> Agent KHÔNG ĐƯỢC tự chuyển sang task tiếp mà không hỏi user.
+
+```
+┌─────────────────────────────────────────────┐
+│  Đọc task spec (tasks/01-xxx.md)            │
+│       ↓                                      │
+│  [RED] Viết test TRƯỚC → test FAIL          │
+│       ↓                                      │
+│  [GREEN] Code TỐI THIỂU để test PASS       │
+│       ↓                                      │
+│  Verify: lint pass + build OK               │
+│       ↓                                      │
+│  [REFACTOR] Cải thiện (test vẫn PASS)       │
+│       ↓                                      │
+│  Commit: feat({module}): {task} [task-{N}]  │
+│       ↓                                      │
+│  Cập nhật handoff status                     │
+│       ↓                                      │
+│  ══ STOP-AND-ASK ══ (6 options A-F)         │
+│  Chờ user approve trước khi tiếp tục        │
+│       ↓                                      │
+│  → Task tiếp theo (chỉ khi user chọn A/F)  │
+└─────────────────────────────────────────────┘
+```
+
+### Bước 3: 3-Strike Rule (QĐ-TTPM Mục 8.7)
+Nếu test fail > 3 lần cho cùng 1 đoạn code:
+1. **DỪNG** phiên AI
+2. Báo user: "Task {N} gặp vấn đề, cần phân tích thủ công"
+3. KHÔNG tiếp tục implement
+
+### Bước 4: FE↔BE Coordination
+Khi BE agent xong API:
+1. Ghi API contract vào `.evnict/handoff/contracts/{feature}-api.yaml`
+2. Cập nhật `.evnict/handoff/be-status.md`:
+   ```
+   status: done
+   completed_tasks: ["task-01", "task-02", "task-03", "task-04"]
+   api_contract: handoff/contracts/{feature}-api.yaml
+   last_updated: {timestamp}
+   ```
+3. FE agent đọc contract → implement FE tasks
+
+### Bước 5: Final verify
+```bash
+# Tất cả test pass
+./mvnw test          # hoặc ng test --watch=false
+# Lint pass
+./mvnw spotless:check  # hoặc ng lint
+# Build OK
+./mvnw compile       # hoặc ng build
+```
+
+---
+
+## Phase 4: Archive + Wiki
+
+**Trigger:** `/evnict-kit:wiki-archive-feature` (sau khi implement xong, user đã review)
+
+### Bước 1: Tự tóm tắt feature
+Đọc:
+- `.evnict/specs/{feature}/spec.md`
+- `git log --oneline` trên feature branch
+- Files changed (`git diff --stat main..HEAD`)
+
+### Bước 2: Push vào wiki
+Sinh file markdown:
+```markdown
+---
+title: "{feature_name}"
+domain: "{module}"
+type: feature
+date: {YYYY-MM-DD}
+tags: [{auto-detected tags}]
+related_specs: [".evnict/specs/{feature}/spec.md"]
+---
+
+## Tóm tắt
+{AI-generated summary — 3-5 câu}
+
+## API mới
+{list endpoints added/changed}
+
+## Database changes
+{list migrations}
+
+## Files thay đổi chính
+{key files changed}
+
+## Lessons learned
+{AI-detected issues và cách giải quyết}
+```
+
+Copy vào `{wiki_path}/raw/notes/{domain}-{slug}.md`
+
+### Bước 3: Trigger ingest
+```bash
+cd {wiki_path} && npm run ingest
+```
+⚠️ Nếu ingest chưa setup → nhắc user chạy `/evnict-kit:init-wiki`
+
+### Bước 4: Archive spec
+Copy `.evnict/specs/{feature}/` → `docs/specs/{feature}/`
+
+### Bước 5: Tạo tài liệu đặc tả (QĐ-TTPM Mục 8.9)
+Nếu thay đổi > 20 dòng code → tạo `docs/postmortem/{feature}-{date}.md`:
+| # | Nội dung | Chi tiết |
+|---|----------|----------|
+| 1 | Nhiệm vụ | Task giao cho Agent |
+| 2 | Công cụ | Tool + model + config |
+| 3 | Prompt chính | Prompts quan trọng (đã clean sensitive) |
+| 4 | Thay đổi | Files changed + tóm tắt |
+| 5 | Kiểm tra | Tests, lint, security scan |
+| 6 | Vấn đề | Issues + lessons learned |
+| 7 | Commit ref | Hash các commit liên quan |
+
+### Bước 6: Confirm
+```
+✅ Wiki updated: {wiki_path}/raw/notes/{file}
+✅ Spec archived: docs/specs/{feature}/
+✅ Postmortem: docs/postmortem/{feature}-{date}.md
+✅ Ingest triggered
+```

package/templates/content/workflows/evnict-kit-feature-small.md

@@ -0,0 +1,86 @@
+---
+description: Feature nhỏ nhanh — skip spec chi tiết, query wiki → plan ngắn → TDD → archive. Dùng khi feature đơn giản, dưới 1 ngày.
+---
+
+# Feature Small
+**Command:** `/evnict-kit:feature-small`
+
+## Khi nào dùng
+- Feature nhỏ, đơn giản (1 API, 1 component, sửa logic)
+- Không cần spec chi tiết
+- Ước lượng < 1 ngày
+
+## Input
+- Mô tả feature ngắn gọn
+- VD: `/evnict-kit:feature-small Thêm API export danh sách khách hàng ra Excel`
+
+---
+
+## Bước 1: Query wiki
+Tìm context liên quan trong wiki:
+```bash
+grep -rl "{keyword}" {wiki_path}/processed/ --include="*.md"
+```
+Đọc kết quả → áp dụng context.
+
+## Bước 2: Plan ngắn
+Tạo plan trực tiếp (KHÔNG tạo spec file):
+
+```markdown
+## Quick Plan: {feature}
+- Files cần tạo/sửa: {list}
+- Test cases: {list}
+- Dependencies: {list}
+- Estimated: {X} phút
+```
+
+Hỏi user confirm plan trước khi implement.
+
+## Bước 3: Checkpoint
+```bash
+git checkout -b feature/{slug}
+```
+
+## Bước 4: TDD Implement
+Với mỗi file:
+1. [RED] Viết test → FAIL
+2. [GREEN] Code tối thiểu → PASS
+3. Verify: `./mvnw test` + `./mvnw compile`
+4. Commit: `feat({module}): {description}`
+
+3-Strike Rule vẫn áp dụng.
+
+## Bước 5: Final verify
+```bash
+./mvnw test && ./mvnw spotless:check && ./mvnw compile
+# hoặc
+ng test --watch=false && ng lint && ng build
+```
+
+## Bước 6: Archive (optional)
+Nếu thay đổi > 20 dòng → push wiki + tạo postmortem.
+Nếu < 20 dòng → skip, chỉ commit.
+
+## Bước cuối: Wiki
+Gợi ý user:
+```
+💡 Feature hoàn thành. Thêm tri thức vào wiki?
+A) Có — chạy `/evnict-kit:wiki-archive-feature` (nạp đầy đủ)
+B) Nhanh — tôi tóm tắt ngắn gọn → push wiki
+C) Không — skip
+```
+- Nếu A → chạy `/evnict-kit:wiki-archive-feature`
+- Nếu B → gọi skill `evnict-kit-wiki` action=push → auto-ingest
+- Nếu C → skip
+
+---
+
+## Checklist hoàn thành
+- [ ] Wiki queried
+- [ ] Plan confirmed
+- [ ] Checkpoint created
+- [ ] TDD implemented
+- [ ] All tests pass
+- [ ] Build OK
+- [ ] Committed
+- [ ] Wiki updated (nếu > 20 dòng)