thanh-kit 2.5.0

package/templates/workflows/README.md

@@ -0,0 +1,241 @@
+# 🔄 Workflows - Quy Trình Phối Hợp Nhiều Bước
+
+## Workflows là gì?
+
+**Workflows** là các "kịch bản phối hợp" cho những công việc lớn, phức tạp, cần nhiều bước và nhiều vai trò khác nhau. Giống như đạo diễn một bộ phim - cần kịch bản chi tiết ai làm gì, khi nào, theo thứ tự nào.
+
+**Khi nào cần Workflow:**
+- Tính năng mới lớn (cần plan → code → test → review → docs)
+- Nhiều người/vai trò phối hợp
+- Công việc kéo dài nhiều ngày/tuần
+- Cần checkpoints kiểm tra chất lượng
+
+---
+
+## Danh Sách Workflows
+
+| Workflow | Dùng Khi Nào | Mô Tả |
+|----------|--------------|-------|
+| **primary-workflow.md** | Làm tính năng mới | Quy trình chuẩn từ plan đến hoàn thành |
+| **orchestration-protocol.md** | Phối hợp nhiều agents | Cách chuyển giao công việc giữa các vai trò |
+| **development-rules.md** | Quy tắc phát triển | Các nguyên tắc bắt buộc khi code |
+| **documentation-management.md** | Quản lý tài liệu | Quy trình cập nhật docs |
+
+---
+
+## Chi Tiết Từng Workflow
+
+### 1. primary-workflow.md - Quy Trình Làm Tính Năng
+
+**Dùng khi:** Xây dựng tính năng mới từ đầu đến cuối
+
+**Các giai đoạn:**
+
+```
+GIAI ĐOẠN 1: LẬP KẾ HOẠCH
+├── Phân tích yêu cầu
+├── Thiết kế giải pháp
+├── Ước lượng thời gian
+└── Xác định rủi ro
+
+    ↓ Checkpoint: Kế hoạch được duyệt
+
+GIAI ĐOẠN 2: IMPLEMENT
+├── Viết code theo kế hoạch
+├── Tự review code
+├── Viết unit tests
+└── Fix bugs phát sinh
+
+    ↓ Checkpoint: Code pass tests
+
+GIAI ĐOẠN 3: KIỂM THỬ
+├── Chạy toàn bộ tests
+├── Test integration
+├── Test edge cases
+└── Fix issues
+
+    ↓ Checkpoint: Tất cả tests pass
+
+GIAI ĐOẠN 4: REVIEW
+├── Code review
+├── Security review
+├── Performance check
+└── Fix feedback
+
+    ↓ Checkpoint: Review approved
+
+GIAI ĐOẠN 5: HOÀN THÀNH
+├── Cập nhật docs
+├── Update changelog
+├── Merge code
+└── Deploy (nếu cần)
+```
+
+---
+
+### 2. orchestration-protocol.md - Quy Trình Phối Hợp
+
+**Dùng khi:** Cần nhiều "chuyên gia" (agents) làm việc cùng nhau
+
+**Nguyên tắc chuyển giao:**
+
+```
+Agent A hoàn thành
+       ↓
+┌──────────────────────────┐
+│ CHUYỂN GIAO              │
+│ • Tóm tắt đã làm gì      │
+│ • Còn gì cần làm         │
+│ • Files đã thay đổi      │
+│ • Vấn đề cần lưu ý       │
+└──────────────────────────┘
+       ↓
+Agent B tiếp nhận
+```
+
+**Ví dụ phối hợp:**
+
+| Thứ tự | Agent | Làm gì | Chuyển cho |
+|--------|-------|--------|------------|
+| 1 | Planner | Lập kế hoạch | Developer |
+| 2 | Developer | Viết code | Tester |
+| 3 | Tester | Viết tests | Reviewer |
+| 4 | Reviewer | Review code | Docs Manager |
+| 5 | Docs Manager | Viết docs | (Hoàn thành) |
+
+---
+
+### 3. development-rules.md - Quy Tắc Phát Triển
+
+**Dùng khi:** Luôn áp dụng khi viết code
+
+**Các quy tắc chính:**
+
+| Quy tắc | Ý nghĩa |
+|---------|---------|
+| **Minimal changes** | Chỉ sửa những gì cần thiết, không sửa thừa |
+| **Reuse before write** | Dùng code có sẵn trước, không viết lại |
+| **Test required** | Code mới phải có test |
+| **No magic numbers** | Không dùng số trực tiếp, dùng constants |
+| **Clear naming** | Đặt tên rõ ràng, dễ hiểu |
+| **File < 300 lines** | File quá dài thì phải tách |
+
+---
+
+### 4. documentation-management.md - Quản Lý Tài Liệu
+
+**Dùng khi:** Cần cập nhật tài liệu dự án
+
+**Quy trình cập nhật:**
+
+```
+SAU KHI HOÀN THÀNH CÔNG VIỆC
+           ↓
+┌─────────────────────────────────┐
+│ Kiểm tra cần update docs nào?   │
+│ □ README.md (nếu thay đổi lớn)  │
+│ □ CHANGELOG.md (mọi thay đổi)   │
+│ □ docs/structure.md (cấu trúc)  │
+│ □ API docs (nếu thay đổi API)   │
+└─────────────────────────────────┘
+           ↓
+    Cập nhật các file cần thiết
+           ↓
+    Review và commit
+```
+
+---
+
+## Ví Dụ Thực Tế
+
+### Ví dụ: Thêm Tính Năng "Gửi Email Thông Báo"
+
+**Bước 1: Load workflow**
+```
+AI load: primary-workflow.md
+```
+
+**Bước 2: Giai đoạn Planning**
+```
+Planner agent làm việc:
+- Phân tích: Cần gửi email khi nào?
+- Thiết kế: Dùng service nào? (SendGrid, SES?)
+- Ước lượng: ~2 ngày
+- Rủi ro: Rate limiting, spam filter
+
+→ Output: Kế hoạch chi tiết
+```
+
+**Bước 3: Giai đoạn Implement**
+```
+Developer agent làm việc:
+- Tạo EmailService class
+- Implement sendNotification()
+- Viết unit tests
+- Tích hợp vào notification flow
+
+→ Output: Code hoàn chỉnh + tests
+```
+
+**Bước 4: Giai đoạn Test**
+```
+Tester agent làm việc:
+- Chạy unit tests
+- Test gửi email thật (sandbox)
+- Test edge cases (email invalid, service down)
+
+→ Output: Test report
+```
+
+**Bước 5: Giai đoạn Review**
+```
+Reviewer agent làm việc:
+- Review code quality
+- Check security (no hardcoded credentials)
+- Check performance
+
+→ Output: Approval hoặc feedback
+```
+
+**Bước 6: Giai đoạn Docs**
+```
+Docs Manager agent làm việc:
+- Update README (new feature)
+- Update CHANGELOG
+- Add API documentation
+
+→ Output: Docs updated
+```
+
+---
+
+## Khi Nào Cần Workflow?
+
+| Tình huống | Cần workflow? |
+|------------|---------------|
+| Sửa typo | ❌ Không |
+| Thêm button đơn giản | ❌ Không |
+| Thêm tính năng lớn | ✅ primary-workflow |
+| Refactor hệ thống | ✅ primary-workflow |
+| Nhiều người cùng làm | ✅ orchestration-protocol |
+| Cần docs chuẩn | ✅ documentation-management |
+
+---
+
+## Tóm Tắt
+
+| Khái niệm | Giải thích |
+|-----------|------------|
+| **Workflow là gì** | Kịch bản phối hợp cho công việc lớn |
+| **Có bao nhiêu** | 4 workflows chính |
+| **Khi nào dùng** | Công việc lớn, nhiều bước, nhiều vai trò |
+| **Ai quyết định** | AI tự động khi nhận diện công việc phức tạp |
+
+---
+
+## Xem Thêm
+
+- [Danh sách Agents (Vai trò)](../agents/README.md)
+- [Danh sách Commands (Quy trình)](../commands/README.md)
+- [Danh sách Skills (Kiến thức)](../skills/README.md)
+- [Router (Bộ định tuyến)](../router/README.md)

package/templates/workflows/development-rules.md

@@ -0,0 +1,93 @@
+# Development Rules
+
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
+**IMPORTANT:** You ALWAYS follow these principles: **YAGNI (You Aren't Gonna Need It) - KISS (Keep It Simple, Stupid) - DRY (Don't Repeat Yourself)**
+
+## General
+
+- **File Naming**: Use kebab-case for file names with a meaningful name that describes the purpose of the file, doesn't matter if the file name is long, just make sure when LLMs read the file names while using Grep or other tools, they can understand the purpose of the file right away without reading the file content.
+- **File Size Management**: Keep individual code files under 300 lines for optimal context management
+  - Split large files into smaller, focused components/modules
+  - Use composition over inheritance for complex widgets
+  - Extract utility functions into separate modules
+  - Create dedicated service classes for business logic
+- Use `docs-seeker` skill for exploring latest docs of plugins/packages if needed
+- Use `gh` bash command to interact with Github features if needed
+- Use `psql` bash command to query Postgres database for debugging if needed
+- Use `ai-multimodal` skill for describing details of images, videos, documents, etc. if needed
+- Use `ai-multimodal` skill and `imagemagick` skill for generating and editing images, videos, documents, etc. if needed
+- Use `sequential-thinking` skill and `debugging` skills for sequential thinking, analyzing code, debugging, etc. if needed
+- **[IMPORTANT]** Follow the codebase structure and code standards in `./docs` during implementation.
+- **[IMPORTANT]** Do not just simulate the implementation or mocking them, always implement the real code.
+
+## Code Quality Guidelines
+
+- Read and follow codebase structure and code standards in `./docs`
+- Don't be too harsh on code linting, but **make sure there are no syntax errors and code are compilable**
+- Prioritize functionality and readability over strict style enforcement and code formatting
+- Use reasonable code quality standards that enhance developer productivity
+- Use try catch error handling & cover security standards
+- Use `code-reviewer` agent to review code after every implementation
+- **[CRITICAL] Class Responsibility Rule:**
+  - Logic belongs in LOWEST layer: Entity/Model > Service > Component/Handler
+  - Backend: Entity mapping → Command.UpdateEntity() or DTO.MapToEntity(), NOT in Handler
+  - Frontend: Constants, column arrays, role lists → static properties in Model class, NOT in Component
+  - Frontend: Display logic (CSS class, status text) → instance getter in Model, NOT switch in Component
+
+## Pre-commit/Push Rules
+
+- Run linting before commit
+- Run tests before push (DO NOT ignore failed tests just to pass the build or github actions)
+- Keep commits focused on the actual code changes
+- **DO NOT** commit and push any confidential information (such as dotenv files, API keys, database credentials, etc.) to git repository!
+- Create clean, professional commit messages without AI references. Use conventional commit format.
+
+## Code Implementation
+
+- Write clean, readable, and maintainable code
+- Follow established architectural patterns
+- Implement features according to specifications
+- Handle edge cases and error scenarios
+- **DO NOT** create new enhanced files, update to the existing files directly.
+
+## Mandatory Post-Task Two-Pass Review Protocol
+
+**CRITICAL:** After ANY code changes (bug fix or feature), execute this protocol BEFORE task completion.
+
+### Pass 1: Initial Review
+
+1. Run `git diff` to examine unstaged changes
+2. Verify changes correctly implement the task requirements
+3. Check compliance with project conventions and best practices:
+   - Backend: repository patterns, validation fluent API, DTOs, event handlers
+   - Frontend: base classes, stores, BEM classes, untilDestroyed()
+4. Identify security vulnerabilities and edge cases
+5. Fix any issues found → mark `MADE_CHANGES = true`
+
+### Pass 2: Re-Review (Conditional)
+
+**ONLY IF Pass 1 made changes:**
+
+1. Run `git diff` again to verify all current changes
+2. Re-execute full review checklist on updated code
+3. Ensure corrections didn't introduce new issues
+4. Apply minimal, targeted fixes if needed
+
+### Quick Reference
+
+```bash
+# Execute review
+/review:post-task
+
+# Or use code-reviewer subagent for complex reviews
+Task tool → code-reviewer subagent
+```
+
+### Review Checklist Quick Reference
+
+- [ ] Task objective achieved correctly
+- [ ] No unrelated/unnecessary modifications
+- [ ] Follows project code conventions
+- [ ] No security vulnerabilities
+- [ ] Edge cases handled
+- [ ] Ready for commit

package/templates/workflows/documentation-management.md

@@ -0,0 +1,121 @@
+# Project Documentation Management
+
+### Roadmap & Changelog Maintenance
+- **Project Roadmap** (`./docs/development-roadmap.md`): Living document tracking project phases, milestones, and progress
+- **Project Changelog** (`./docs/project-changelog.md`): Detailed record of all significant changes, features, and fixes
+- **System Architecture** (`./docs/system-architecture.md`): Detailed record of all significant changes, features, and fixes
+- **Code Standards** (`./docs/code-standards.md`): Detailed record of all significant changes, features, and fixes
+
+### Automatic Updates Required
+- **After Feature Implementation**: Update roadmap progress status and changelog entries
+- **After Major Milestones**: Review and adjust roadmap phases, update success metrics
+- **After Bug Fixes**: Document fixes in changelog with severity and impact
+- **After Security Updates**: Record security improvements and version updates
+- **Weekly Reviews**: Update progress percentages and milestone statuses
+
+### Documentation Triggers
+The `project-manager` agent MUST update these documents when:
+- A development phase status changes (e.g., from "In Progress" to "Complete")
+- Major features are implemented or released
+- Significant bugs are resolved or security patches applied
+- Project timeline or scope adjustments are made
+- External dependencies or breaking changes occur
+
+### Update Protocol
+1. **Before Updates**: Always read current roadmap and changelog status
+2. **During Updates**: Maintain version consistency and proper formatting
+3. **After Updates**: Verify links, dates, and cross-references are accurate
+4. **Quality Check**: Ensure updates align with actual implementation progress
+
+### Plans
+
+### Plan Location
+Save plans in `./plans` directory with timestamp and descriptive name.
+
+**Format:** Use naming pattern from `## Naming` section injected by hooks.
+
+**Example:** `plans/251101-1505-authentication-and-profile-implementation/`
+
+#### File Organization
+
+```
+plans/
+├── 20251101-1505-authentication-and-profile-implementation/
+    ├── research/
+    │   ├── researcher-XX-report.md
+    │   └── ...
+│   ├── reports/
+│   │   ├── scout-report.md
+│   │   ├── researcher-report.md
+│   │   └── ...
+│   ├── plan.md                                # Overview access point
+│   ├── phase-01-setup-environment.md          # Setup environment
+│   ├── phase-02-implement-database.md         # Database models
+│   ├── phase-03-implement-api-endpoints.md    # API endpoints
+│   ├── phase-04-implement-ui-components.md    # UI components
+│   ├── phase-05-implement-authentication.md   # Auth & authorization
+│   ├── phase-06-implement-profile.md          # Profile page
+│   └── phase-07-write-tests.md                # Tests
+└── ...
+```
+
+#### File Structure
+
+##### Overview Plan (plan.md)
+- Keep generic and under 80 lines
+- List each phase with status/progress
+- Link to detailed phase files
+- Key dependencies
+
+##### Phase Files (phase-XX-name.md)
+Fully respect the `./docs/development-rules.md` file.
+Each phase file should contain:
+
+**Context Links**
+- Links to related reports, files, documentation
+
+**Overview**
+- Priority
+- Current status
+- Brief description
+
+**Key Insights**
+- Important findings from research
+- Critical considerations
+
+**Requirements**
+- Functional requirements
+- Non-functional requirements
+
+**Architecture**
+- System design
+- Component interactions
+- Data flow
+
+**Related Code Files**
+- List of files to modify
+- List of files to create
+- List of files to delete
+
+**Implementation Steps**
+- Detailed, numbered steps
+- Specific instructions
+
+**Todo List**
+- Checkbox list for tracking
+
+**Success Criteria**
+- Definition of done
+- Validation methods
+
+**Risk Assessment**
+- Potential issues
+- Mitigation strategies
+
+**Security Considerations**
+- Auth/authorization
+- Data protection
+
+**Next Steps**
+- Dependencies
+- Follow-up tasks

package/templates/workflows/orchestration-protocol.md

@@ -0,0 +1,16 @@
+# Orchestration Protocol
+
+#### Sequential Chaining
+Chain subagents when tasks have dependencies or require outputs from previous steps:
+- **Planning → Implementation → Testing → Review**: Use for feature development
+- **Research → Design → Code → Documentation**: Use for new system components
+- Each agent completes fully before the next begins
+- Pass context and outputs between agents in the chain
+
+#### Parallel Execution
+Spawn multiple subagents simultaneously for independent tasks:
+- **Code + Tests + Docs**: When implementing separate, non-conflicting components
+- **Multiple Feature Branches**: Different agents working on isolated features
+- **Cross-platform Development**: iOS and Android specific implementations
+- **Careful Coordination**: Ensure no file conflicts or shared resource contention
+- **Merge Strategy**: Plan integration points before parallel execution begins

package/templates/workflows/primary-workflow.md

@@ -0,0 +1,45 @@
+# Primary Workflow
+
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
+**IMPORTANT**: Ensure token efficiency while maintaining high quality.
+
+#### 1. Code Implementation
+- Before you start, delegate to `planner` agent to create a implementation plan with TODO tasks in `./plans` directory.
+- When in planning phase, use multiple `researcher` agents in parallel to conduct research on different relevant technical topics and report back to `planner` agent to create implementation plan.
+- Write clean, readable, and maintainable code
+- Follow established architectural patterns
+- Implement features according to specifications
+- Handle edge cases and error scenarios
+- **DO NOT** create new enhanced files, update to the existing files directly.
+- **[IMPORTANT]** After creating or modifying code file, run compile command/script to check for any compile errors.
+
+#### 2. Testing
+- Delegate to `tester` agent to run tests and analyze the summary report.
+  - Write comprehensive unit tests
+  - Ensure high code coverage
+  - Test error scenarios
+  - Validate performance requirements
+- Tests are critical for ensuring code quality and reliability, **DO NOT** ignore failing tests just to pass the build.
+- **IMPORTANT:** make sure you don't use fake data, mocks, cheats, tricks, temporary solutions, just to pass the build or github actions.
+- **IMPORTANT:** Always fix failing tests follow the recommendations and delegate to `tester` agent to run tests again, only finish your session when all tests pass.
+
+#### 3. Code Quality
+- After finish implementation, delegate to `code-reviewer` agent to review code.
+- Follow coding standards and conventions
+- Write self-documenting code
+- Add meaningful comments for complex logic
+- Optimize for performance and maintainability
+
+#### 4. Integration
+- Always follow the plan given by `planner` agent
+- Ensure seamless integration with existing code
+- Follow API contracts precisely
+- Maintain backward compatibility
+- Document breaking changes
+- Delegate to `docs-manager` agent to update docs in `./docs` directory if any.
+
+#### 5. Debugging
+- When a user report bugs or issues on the server or a CI/CD pipeline, delegate to `debugger` agent to run tests and analyze the summary report.
+- Read the summary report from `debugger` agent and implement the fix.
+- Delegate to `tester` agent to run tests and analyze the summary report.
+- If the `tester` agent reports failed tests, fix them follow the recommendations and repeat from the **Step 2**.