evnict-kit 0.2.1

package/templates/workflows/claude/evnict-kit-handoff.md

@@ -0,0 +1,240 @@
+# Handoff
+**Command:** `/evnict-kit:handoff $ARGUMENTS`
+
+$ARGUMENTS chứa mô tả từ user.
+
+## Ý nghĩa và Mục đích
+Trong mô hình nhiều AI Agents làm việc song song trên nhiều Repositories (BE + FE). Khi Backend hoàn thành API, lệnh `handoff` sẽ sinh file bàn giao **ĐẦY ĐỦ** để FE Agent có thể implement mà KHÔNG cần hỏi thêm.
+
+## Khi nào dùng
+- Khi phát triển xong API Endpoints ở Backend → FE cần implement UI
+- Khi hoàn thành DB Migration ở dự án Database riêng → báo Backend
+- Sau khi BE implement xong tất cả tasks của feature
+
+---
+
+## Workflow chi tiết
+
+### Bước 1: Rà soát Công việc
+1. Đọc `.evnict/specs/{feature}/plan.md` → lấy task list
+2. Kiểm tra tất cả BE tasks đã `[x]` hoàn thành chưa
+   - Nếu chưa xong hết → CẢNH BÁO: "Còn {N} BE tasks chưa hoàn thành. Handoff ngay?"
+3. Kiểm tra API Contract `.evnict/handoff/contracts/{feature}-api.yaml`
+   - Nếu chưa có → sinh mới từ code đã implement
+   - Nếu đã có → verify lại với code hiện tại
+
+### Bước 2: Đọc code đã implement → trích xuất context
+Agent PHẢI đọc các files đã tạo trong BE tasks:
+
+1. **Đọc DTOs** → trích fields, types, annotations, JsonProperty
+2. **Đọc Controllers** → trích endpoints, request params, response format
+3. **Đọc Services** → trích business rules, validation logic
+4. **Đọc commit log** → `git log --oneline main..HEAD`
+
+### Bước 3: Append entry vào Handoff Log — PHẢI có 5 SECTIONS
+
+> **QUAN TRỌNG:** KHÔNG tạo file riêng cho mỗi feature. Thay vào đó, APPEND entry mới vào file `.evnict/handoff/handoff.md`.
+> Nếu file chưa tồn tại → tạo mới với header template.
+
+Append entry sau vào `.evnict/handoff/handoff.md`:
+
+```markdown
+---
+
+### [{YYYY-MM-DD}] BE→FE: {Feature Name} — Handoff
+- **Trạng thái:** 🔴 Chờ xử lý
+- **Spec:** `.evnict/specs/{feature}/spec.md`
+
+#### 1. TỔNG QUAN ĐÃ LÀM (Backend)
+**Mô tả:** {3-5 câu tóm tắt những gì BE đã implement}
+
+**Tasks đã hoàn thành:**
+| # | Task | Files | Tests |
+|---|------|-------|-------|
+| 01 | DB Migration | {migration_file} | ✅ |
+| 02 | Repository | {repo_file} ({dto_file}) | ✅ {N}/{N} |
+| 03 | Service | {service_file} | ✅ {N}/{N} |
+| 04 | Controller | {controller_file} ({M} endpoints) | ✅ {N}/{N} |
+
+**Commits:**
+```
+{hash} feat({module}): {description} [task-01]
+{hash} feat({module}): {description} [task-02]
+...
+```
+
+#### 2. API CONTRACT (Chi tiết cho Frontend)
+**File đầy đủ:** `.evnict/handoff/contracts/{feature}-api.yaml`
+
+**Quick Reference:**
+| Method | Path | Mô tả | Auth |
+|--------|------|-------|------|
+| POST | /api/{module}/{action} | {mô tả} | JWT |
+| ... | ... | ... | ... |
+
+**DTO Structure (cho TypeScript interface):**
+```typescript
+// Auto-generated từ {DTOFile.java}
+export interface {EntityName} {
+  ID: number;
+  FIELD_NAME: string;        // @JsonProperty("FIELD_NAME")
+  NULLABLE_FIELD?: string;   // nullable → optional
+  NUMERIC_FIELD: number;
+  DATE_FIELD: string;        // format: yyyy-MM-dd
+  STATUS: number;
+  USER_CR_ID: string;        // audit - server tự set
+  USER_CR_DTIME: string;     // audit - server tự set
+  USER_MDF_ID: string;       // audit - server tự set
+  USER_MDF_DTIME: string;    // audit - server tự set
+}
+```
+
+**Validation Rules (PHẢI sync BE↔FE):**
+| Field | Rule | Error Message (tiếng Việt) |
+|-------|------|---------------------------|
+| {FIELD} | Required | "Vui lòng nhập {field_label}" |
+| {FIELD} | MaxLength({N}) | "{field_label} không quá {N} ký tự" |
+| {FIELD} | <= today | "{field_label} phải <= ngày hiện tại" |
+| {FIELD} | Range(0-23) | "{field_label} phải từ 0-23" |
+| {FIELD} | >= 0 | "{field_label} phải >= 0" |
+
+**Response Format:**
+```json
+// Success
+{ "success": true, "message": "OK", "data": { ... } }
+// Error
+{ "success": false, "message": "Lỗi cụ thể", "data": null }
+// Paginated
+{
+  "success": true,
+  "data": {
+    "content": [{ ... }],
+    "totalElements": 100,
+    "totalPages": 5
+  }
+}
+```
+
+**Request Format chi tiết cho mỗi endpoint:**
+**POST /api/{module}/list**
+```json
+{
+  "FILTER_FIELD": "string",
+  "FROM_DATE": "yyyy-MM-dd",
+  "TO_DATE": "yyyy-MM-dd",
+  "page": 0,
+  "size": 20
+}
+```
+
+**POST /api/{module}/save**
+```json
+{
+  "ID": null,              // null = create, number = update
+  "FIELD_NAME": "value",
+  // ... all required fields
+}
+```
+
+**POST /api/{module}/delete**
+```json
+{
+  "ID": 123
+}
+```
+
+#### 3. YÊU CẦU CHO FRONTEND
+**Tasks cần làm:**
+| # | Task | Mô tả | Priority |
+|---|------|-------|----------|
+| fe-01 | {Module}Service | HTTP service gọi {N} API endpoints | High |
+| fe-02 | {Module}ListComponent | Trang danh sách + filter + pagination | High |
+| fe-03 | {Module}FormComponent | Dialog form thêm/sửa | High |
+| fe-04 | Routing + Menu | Thêm route + menu item | Medium |
+
+**UI Requirements (từ spec):**
+- **Filter bar:** {dropdown1}, {dropdown2}, {date range}
+- **Table:** PrimeNG p-table, sortable, paginator
+- **Form:** PrimeNG dialog, reactive forms, validation sync với BE
+- **Actions:** Thêm (toolbar), Sửa (row button), Xóa (confirm dialog)
+- **Export:** Excel export (nếu có trong spec)
+
+**Dropdowns cần load:**
+| Dropdown | API | Value field | Display field |
+|----------|-----|-------------|---------------|
+| {Dropdown name} | /api/{path} | {VALUE_ID} | {DISPLAY_NAME} |
+
+#### 4. LƯU Ý ĐẶC BIỆT
+- **ResponseData wrapper:** Luôn check `response.success` trước khi dùng `response.data`
+- **Auth:** JWT token tự động gắn bởi HTTP interceptor — FE KHÔNG cần handle
+- **Date format:** Server nhận `yyyy-MM-dd`, display trên FE `dd/MM/yyyy`
+- **Audit fields:** (USER_CR_*, USER_MDF_*) → server tự set, FE KHÔNG cần gửi
+- **Error handling:** Dùng `response.message` để hiển thị toast notification
+- **Pagination:** PrimeNG LazyLoadEvent → map sang {page, size}
+
+#### 5. HƯỚNG DẪN CHẠY
+FE Agent mở project frontend:
+1. Đọc file: `.evnict/handoff/handoff.md` → tìm entry 🔴 Chờ xử lý
+2. Đọc API contract: `.evnict/handoff/contracts/{feature}-api.yaml`
+3. Chạy: `/evnict-kit:implement`
+4. Agent sẽ tự detect FE tasks từ handoff entry và implement
+5. Sau khi xong → update trạng thái entry thành 🟢 Đã xử lý
+
+- **Kết quả xử lý:** _(FE Agent điền sau khi implement xong)_
+```
+
+### Bước 4: Sinh/Update API Contract YAML
+Tạo hoặc cập nhật `.evnict/handoff/contracts/{feature}-api.yaml`:
+- Dựa vào Controllers đã implement
+- Format theo skill `evnict-kit-coordinate`
+
+### Bước 5: Update BE Status
+Cập nhật `.evnict/handoff/be-status.md`:
+```markdown
+# BE Status
+status: done
+feature: {feature-name}
+completed_tasks: ["task-01", "task-02", ...]
+api_contract: handoff/contracts/{feature}-api.yaml
+handoff_entry: handoff/handoff.md (entry [{date}] BE→FE: {feature})
+last_updated: {timestamp}
+```
+
+### Bước 6: Thông báo User
+```
+═══════════════════════════════════════════
+✅ Handoff: {Feature Name} — THÀNH CÔNG
+═══════════════════════════════════════════
+
+📄 Handoff entry: .evnict/handoff/handoff.md (🔴 Chờ xử lý)
+📜 API Contract: .evnict/handoff/contracts/{feature}-api.yaml
+📊 BE Status: .evnict/handoff/be-status.md → DONE
+
+───────────────────────────────────────────
+📋 Nội dung handoff entry:
+  Section 1: Tổng quan — {N} tasks hoàn thành
+  Section 2: API Contract — {M} endpoints
+  Section 3: FE Tasks — {K} tasks cần làm
+  Section 4: Lưu ý đặc biệt
+  Section 5: Hướng dẫn chạy
+
+───────────────────────────────────────────
+🔄 Thao tác tiếp:
+  1. Chuyển sang IDE/workspace của project Frontend
+  2. Mở Agent và paste:
+     "Backend đã Handoff xong feature {feature-name}.
+      Đọc .evnict/handoff/handoff.md
+      để implement FE tasks."
+═══════════════════════════════════════════
+```
+
+---
+
+## Tiêu chí thành công (Definition of Done)
+1. Handoff entry có ĐỦ 5 sections (tổng quan, API contract, FE tasks, lưu ý, hướng dẫn)
+2. Entry được APPEND vào `handoff.md` (không tạo file riêng)
+3. DTO → TypeScript interface mapping chính xác
+4. Validation rules sync table đầy đủ
+5. API Contract YAML file tồn tại và đầy đủ endpoints
+6. BE Status file updated → `status: done`
+7. User nhận được thông báo rõ ràng để chuyển workspace

package/templates/workflows/claude/evnict-kit-implement.md

@@ -0,0 +1,245 @@
+# Implement
+**Command:** `/evnict-kit:implement $ARGUMENTS`
+
+$ARGUMENTS chứa mô tả từ user.
+
+## Khi nào dùng
+- Sau khi plan đã được user approve (từ feature-large hoặc feature-small)
+- Implement từng task theo thứ tự dependency
+- **MỖI task phải có user approval trước khi chuyển sang task tiếp**
+
+## Input
+- Path đến plan: `.evnict/specs/{feature-slug}/plan.md`
+- Hoặc: `/evnict-kit:implement` (tự detect plan từ current feature)
+
+---
+
+## ═══════════════════════════════════════════
+## QUY TẮC BẮT BUỘC: STOP-AND-ASK
+## ═══════════════════════════════════════════
+
+### Sau MỖI subtask hoàn thành, Agent PHẢI DỪNG và hiển thị:
+
+```
+═══════════════════════════════════════════
+✅ Task {N}/{Total}: {task_name} — HOÀN THÀNH
+═══════════════════════════════════════════
+
+📁 Files tạo/sửa:
+  + src/.../FileA.java (NEW — {X} lines)
+  ~ src/.../FileB.java (MODIFIED — {Y} lines changed)
+
+🧪 Tests: {pass}/{total} passed
+📏 Lint: ✅ passed | ❌ {N} issues
+🔨 Build: ✅ passed | ❌ failed
+📝 Commit: feat({module}): {description} [task-{NN}]
+
+───────────────────────────────────────────
+❓ Bạn muốn làm gì tiếp?
+
+  A) ✅ Approve — chuyển sang Task {N+1}: {next_task_name}
+  B) 👀 Review code — tôi sẽ hiển thị code và chờ feedback
+  C) 🔄 Yêu cầu sửa — mô tả cần sửa gì
+  D) ⏸️ Tạm dừng — lưu progress, tiếp tục sau
+  E) ❌ Hủy task này — rollback commit
+  F) 🚀 Auto-approve — chạy hết tasks còn lại KHÔNG hỏi nữa
+     ⚠️ Chỉ dùng khi đã review 2-3 tasks đầu và tin tưởng pattern
+
+Chọn (A/B/C/D/E/F):
+═══════════════════════════════════════════
+```
+
+### TUYỆT ĐỐI KHÔNG được:
+- ❌ Tự động chạy task tiếp mà không hỏi user
+- ❌ Skip phần hiển thị kết quả (files, tests, lint, build, commit)
+- ❌ Gộp nhiều tasks thành 1 lần chạy
+- ❌ Bỏ qua test/lint/build results trong output
+
+---
+
+### Xử lý từng Option
+
+#### Option A — Approve
+Chuyển sang task tiếp theo. Nếu đây là task cuối → chuyển sang Bước 4: Final Verify.
+
+#### Option B — Review Code
+Agent PHẢI hiển thị code cho mỗi file đã tạo/sửa:
+```
+📄 {FileName.java} ({NEW|MODIFIED}):
+─────────────────────────────
+{Hiển thị toàn bộ code nếu NEW}
+{Hiển thị diff nếu MODIFIED}
+─────────────────────────────
+
+📄 {FileName2.java} ({NEW|MODIFIED}):
+─────────────────────────────
+{Code/Diff}
+─────────────────────────────
+
+Bạn có feedback gì không? (Gõ feedback hoặc "OK" để approve)
+```
+
+Sau khi user gõ "OK" → xử lý như Option A.
+Sau khi user gõ feedback → xử lý như Option C.
+
+#### Option C — Yêu cầu sửa
+1. Đọc feedback của user
+2. Sửa code theo feedback
+3. Chạy lại test → lint → build
+4. Amend commit: `git commit --amend -m "..."`
+5. Hiển thị lại STOP-AND-ASK với kết quả mới
+
+#### Option D — Tạm dừng
+Lưu progress vào `.evnict/specs/{feature}/progress.md`:
+```markdown
+# Progress: {feature}
+## Status: PAUSED
+## Completed: {N}/{Total}
+## Last updated: {timestamp}
+
+### Tasks
+- [x] Task 01: {name} — commit: {hash}
+- [x] Task 02: {name} — commit: {hash}
+- [ ] Task 03: {name} ← NEXT
+- [ ] Task 04: {name}
+- [ ] ...
+
+### Resume
+Chạy: `/evnict-kit:implement`
+Agent sẽ auto-detect progress file và tiếp tục từ Task 03.
+```
+
+Hiển thị:
+```
+⏸️ Progress đã lưu: .evnict/specs/{feature}/progress.md
+   Hoàn thành: {N}/{Total} tasks
+   Task tiếp: {N+1}: {name}
+   Resume: chạy /evnict-kit:implement
+```
+
+#### Option E — Hủy + Rollback
+1. `git revert HEAD` (revert commit cuối)
+2. Xóa files đã tạo trong task này
+3. Cập nhật plan.md — đánh dấu task chưa hoàn thành
+4. Hỏi user: "Muốn thử lại task này hay chuyển sang task khác?"
+
+#### Option F — Auto-approve
+1. Hiển thị cảnh báo:
+```
+⚠️ AUTO-APPROVE MODE
+Tất cả tasks còn lại sẽ chạy liên tục KHÔNG hỏi.
+Agent vẫn DỪNG nếu: test fail, build fail, hoặc 3-strike rule.
+
+Tiếp tục? (Y/N)
+```
+2. Nếu Y → chạy tất cả tasks còn lại, mỗi task vẫn hiển thị kết quả (nhưng không hỏi)
+3. Nếu gặp lỗi (test fail, build fail) → TỰ ĐỘNG quay lại mode STOP-AND-ASK
+4. Sau khi tất cả tasks xong → hiển thị Final Summary (Bước 5)
+
+---
+
+## Pre-conditions
+1. Plan đã được user approve
+2. Working tree clean: `git status`
+3. Feature branch đã tạo
+
+## Bước 1: Đọc Plan + Check Resume
+```bash
+cat .evnict/specs/{feature}/plan.md
+ls .evnict/specs/{feature}/tasks/
+```
+
+### Resume Logic
+Kiểm tra `.evnict/specs/{feature}/progress.md`:
+- **Nếu tồn tại** → Đọc progress, hiển thị:
+  ```
+  📋 Phát hiện progress đã lưu:
+     Hoàn thành: {N}/{Total} tasks
+     Task tiếp: {N+1}: {name}
+  
+  Tiếp tục từ Task {N+1}? (Y/N)
+  ```
+  - Y → skip các tasks đã hoàn thành, bắt đầu từ task tiếp
+  - N → bắt đầu lại từ đầu (xác nhận trước: "Sẽ reset progress. Chắc chắn?")
+- **Nếu không tồn tại** → bắt đầu từ Task 01
+
+Xác định thứ tự thực hiện và dependencies.
+
+## Bước 2: Với MỖI task (theo thứ tự)
+
+### 2a: Đọc task spec
+```bash
+cat .evnict/specs/{feature}/tasks/{NN}-{name}.md
+```
+
+### 2b: TDD Cycle
+Gọi skill `evnict-kit-tdd`:
+1. **[RED]** Viết test → FAIL
+2. **[GREEN]** Code tối thiểu → PASS
+3. **Verify** lint + build
+4. **[REFACTOR]** Cải thiện (test vẫn PASS)
+
+### 2c: Commit
+```bash
+git add .
+git commit -m "feat({module}): {task description} [task-{NN}]"
+```
+
+### 2d: Update task status
+Đánh dấu task hoàn thành trong plan.md.
+
+### 2e: Update handoff (nếu BE→FE)
+Gọi skill `evnict-kit-coordinate` → publish contract khi BE tasks done.
+
+### ══ 2f: MANDATORY STOP — STOP-AND-ASK ══
+**DỪNG ĐÂY.** Hiển thị kết quả và hỏi user (xem format ở đầu file).
+**KHÔNG ĐƯỢC** tự động chuyển sang task tiếp.
+Chỉ chuyển khi user chọn A, hoặc đang ở Auto-approve mode (F).
+
+## Bước 3: 3-Strike Rule
+Test fail > 3 lần cho cùng 1 task → **DỪNG NGAY**.
+- Nếu đang ở Auto-approve mode → TỰ ĐỘNG thoát auto-approve, quay lại STOP-AND-ASK.
+
+## Bước 4: Final Verify
+```bash
+./mvnw test && ./mvnw spotless:check && ./mvnw compile
+```
+
+## Bước 5: Final Summary
+```markdown
+═══════════════════════════════════════════
+✅ IMPLEMENTATION COMPLETE
+═══════════════════════════════════════════
+
+📋 Feature: {feature_name}
+📁 Tasks completed: {N}/{total}
+
+📝 Commits:
+  {hash1} feat({module}): {desc} [task-01]
+  {hash2} feat({module}): {desc} [task-02]
+  ...
+
+🧪 Tests: {total_tests} pass
+🔨 Build: ✅ OK
+📏 Lint: ✅ OK
+
+───────────────────────────────────────────
+❓ Tiếp theo:
+  A) /evnict-kit:review — code review
+  B) /evnict-kit:handoff — chuyển sang FE/BE
+  C) /evnict-kit:archive-wiki — lưu wiki + archive
+═══════════════════════════════════════════
+```
+
+---
+
+## Checklist
+- [ ] Plan confirmed
+- [ ] Resume logic checked (progress.md)
+- [ ] All tasks implemented (TDD)
+- [ ] STOP-AND-ASK enforced sau MỖI task
+- [ ] All tests pass
+- [ ] Build OK
+- [ ] Handoff updated (nếu BE→FE)
+- [ ] No 3-strike violations
+- [ ] Final Summary hiển thị

package/templates/workflows/claude/evnict-kit-init-check.md

@@ -0,0 +1,74 @@
+# Init Check — Verify Setup
+**Command:** `/evnict-kit:init-check $ARGUMENTS`
+
+$ARGUMENTS chứa mô tả từ user.
+
+## Mục đích
+Sinh demo code nhỏ để verify rằng rules, conventions, workflows hoạt động đúng.
+
+## Pre-conditions
+- `/evnict-kit:init-rules` đã chạy
+- `/evnict-kit:init-context` đã chạy
+- AGENTS.md tồn tại
+
+---
+
+## Workflow
+
+### Bước 1: Tạo demo branch
+```bash
+git checkout -b demo/init-check
+```
+
+### Bước 2: Backend — Sinh sample API
+Gọi skill `evnict-kit-create-api` tạo API đơn giản:
+- GET /api/demo/health → return status
+- POST /api/demo/echo → echo request body
+
+Verify:
+- [ ] DTO có validation annotations
+- [ ] Service có @Transactional
+- [ ] Controller return ResponseData
+- [ ] Tests viết và pass
+
+### Bước 3: Frontend — Sinh sample component
+Gọi skill `evnict-kit-create-component`:
+- DemoComponent: hiển thị data từ /api/demo/health
+
+Verify:
+- [ ] Component trong shared/
+- [ ] i18n keys
+- [ ] Loading/error states
+- [ ] takeUntil pattern
+
+### Bước 4: Security Check
+Gọi skill `evnict-kit-security-audit` scope=module(demo):
+- Verify no security violations
+
+### Bước 5: Report
+```markdown
+## ✅ Init Check Report
+| Check | Status |
+|-------|--------|
+| Rules loaded | ✅ |
+| Conventions applied | ✅ |
+| Backend demo API | ✅ |
+| Frontend demo component | ✅ |
+| Security scan | ✅ |
+| Tests pass | ✅ |
+| Build OK | ✅ |
+
+## Setup is READY! 🎉
+Next: Xóa demo branch hoặc giữ làm reference.
+```
+
+### Bước 6: Cleanup option
+```bash
+git checkout main
+git branch -D demo/init-check
+```
+
+---
+
+## Output
+Demo code + verification report. User quyết định giữ hoặc xóa demo.

package/templates/workflows/claude/evnict-kit-init-context.md

@@ -0,0 +1,56 @@
+# Init Context — Sinh AGENTS.md
+**Command:** `/evnict-kit:init-context $ARGUMENTS`
+
+$ARGUMENTS chứa mô tả từ user.
+
+## Mục đích
+Đọc rules đã khởi tạo (RP01-RP07) + scan codebase → sinh file AGENTS.md đầy đủ ở root project.
+
+## Pre-conditions
+- `/evnict-kit:init-rules` đã chạy thành công
+- File `05-evnict-kit-project-conventions.md` đã có nội dung (không còn placeholders)
+
+---
+
+## Workflow
+
+### Bước 1: Thu thập context
+1. Đọc `.evnict/config.yaml` → project info
+2. Đọc `05-evnict-kit-project-conventions.md` → conventions
+3. Đọc `.agent/context/init-summary-*.md` → scan results
+4. Scan codebase: `tree -L 3`, pom.xml/package.json, config files
+
+### Bước 2: Sinh AGENTS.md
+Tạo file AGENTS.md ở root project (400-600 dòng) với sections:
+
+1. **Project Overview** — tên, mô tả, tech stack
+2. **Architecture Diagram** — ASCII art
+3. **Tech Stack Table** — framework, library, version
+4. **Project Structure** — tree view
+5. **Development Commands** — build, test, run
+6. **Coding Conventions Summary** — tóm tắt từ rules
+7. **API Conventions** — endpoint patterns, response format
+8. **Database Conventions** — naming, migration
+9. **Security Rules Summary** — critical rules
+10. **Agent Commands** — available workflows/skills
+11. **Safety Rules** — no push, no secrets, no PII
+12. **Integration Map** — external services
+
+### Bước 3: Validate
+- [ ] File 400-600 dòng
+- [ ] Architecture diagram included
+- [ ] Tech stack complete
+- [ ] Commands accurate
+- [ ] No secrets/IPs
+
+### Bước 4: Confirm
+```
+✅ AGENTS.md created: {line count} lines
+📋 Sections: 12
+🔒 Security: verified (no secrets)
+```
+
+---
+
+## Output
+File `AGENTS.md` ở root project — context file duy nhất cho AI Agent.